Move mood methods to a separate file.

[paraslash.git] / mm.h

diff --git a/mm.h b/mm.h
new file mode 100644 (file)
index 0000000..c1744dc
--- /dev/null
+++ b/mm.h
@@ -0,0 +1,70 @@
+/*
+ * Copyright (C) 2007-2009 Andre Noll <maan@systemlinux.org>
+ *
+ * Licensed under the GPL v2. For licencing details see COPYING.
+ */
+
+/** \file mm.h Symbols and declarations for mood methods. */
+
+/**
+ * Assign scores according to a mood_method.
+ *
+ * Each mood_method has its own mood_score_function. The first three parameters
+ * passed to that function are informations about the audio file whose score is
+ * to be computed. The data argument depends on the mood method this function
+ * is used for. It usually is the argument given at the end of a mood line.
+ *
+ * Mood score functions must return values between -100 and +100 inclusively.
+ * Boolean score functions should always return either -100 or +100.
+ *
+ * \sa struct mood_method, mood_parser.
+ */
+typedef int mood_score_function(const char *path, const struct afs_info *afsi,
+               const struct afh_info *afhi, const void *data);
+
+/**
+ * Pre-process a mood line.
+ *
+ * The mood_parser of a mood_method is called once at mood open time for each
+ * line of the current mood definition that contains the mood_method's name as
+ * a keyword. The line is passed to the mood_parser as the first argument. The
+ * mood_parser must determine whether the line is syntactically correct and
+ * return a positive value if so and a negative value otherwise.
+ *
+ * Some mood parsers pre-process the data given in the mood line to compute a
+ * structure which depends of the particular mood_method and which is used
+ * later in the mood_score_function of the mood_method. The mood_parser may
+ * store a pointer to its structure via the void** pointer.
+ *
+ * \sa mood_open(), mood_cleanup_function, mood_score_function.
+ */
+typedef int mood_parser(int, char **, void **);
+
+/**
+ * Deallocate resources which were allocated by the mood_parser.
+ *
+ * This optional function of a mood_method is used to free any resources
+ * allocated in mood_open() by the mood_parser. The argument passed is a
+ * pointer to the mood_method specific data structure that was returned by the
+ * mood_parser.
+ *
+ * \sa mood_parser.
+ */
+typedef void mood_cleanup_function(void *);
+
+/**
+ * Used for scoring and to determine whether a file is admissible.
+ */
+struct mood_method {
+       /** The name of the method. */
+       const char *name;
+       /** Pointer to the mood parser. */
+       mood_parser *parser;
+       /** Pointer to the score function */
+       mood_score_function *score_function;
+       /** Optional cleanup function. */
+       mood_cleanup_function *cleanup;
+};
+
+/** The array of available mood methods. */
+extern const struct mood_method mood_methods[];