mm.h

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