mm.h

   1 /* Copyright (C) 2007 Andre Noll <maan@tuebingen.mpg.de>, see file COPYING. */
   2
   3 /** \file mm.h Symbols and declarations for mood methods. */
   4
   5 /**
   6  * Assign scores according to a mood_method.
   7  *
   8  * Each mood_method has its own mood_score_function. The first three parameters
   9  * passed to that function are informations about the audio file whose score is
  10  * to be computed. The data argument depends on the mood method this function
  11  * is used for. It usually is the argument given at the end of a mood line.
  12  *
  13  * Mood score functions must return values between -100 and +100 inclusively.
  14  * Boolean score functions should always return either -100 or +100.
  15  *
  16  * \sa struct \ref mood_method, \ref mood_parser.
  17  */
  18 typedef int mood_score_function(const char *path, const struct afs_info *afsi,
  19                 const struct afh_info *afhi, const void *data);
  20
  21 /**
  22  * Pre-process a mood line.
  23  *
  24  * The mood_parser of a mood_method is called once at mood open time for each
  25  * line of the current mood definition that contains the mood_method's name as
  26  * a keyword. The line is passed to the mood_parser as the first argument. The
  27  * mood_parser must determine whether the line is syntactically correct and
  28  * return a positive value if so and a negative value otherwise.
  29  *
  30  * Some mood parsers pre-process the data given in the mood line to compute a
  31  * structure which depends of the particular mood_method and which is used
  32  * later in the mood_score_function of the mood_method. The mood_parser may
  33  * store a pointer to its structure via the void** pointer.
  34  *
  35  * \sa \ref mood_cleanup_function, \ref mood_score_function.
  36  */
  37 typedef int mood_parser(int, char **, void **);
  38
  39 /**
  40  * Deallocate resources which were allocated by the mood_parser.
  41  *
  42  * Function to free the resources allocated in \ref mood_method::parser. The
  43  * argument is a pointer to mood method specific data returned by ->parser().
  44  */
  45 typedef void mood_cleanup_function(void *);
  46
  47 /**
  48  * Used for scoring and to determine whether a file is admissible.
  49  */
  50 struct mood_method {
  51         /** The name of the method. */
  52         const char *name;
  53         /** Pointer to the mood parser. */
  54         mood_parser *parser;
  55         /** Pointer to the score function */
  56         mood_score_function *score_function;
  57         /** Optional cleanup function. */
  58         mood_cleanup_function *cleanup;
  59 };
  60
  61 /** The array of available mood methods. */
  62 extern const struct mood_method mood_methods[];