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 mood_method, 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 mood_open(), mood_cleanup_function, 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  * This optional function of a mood_method is used to free any resources
  47  * allocated in mood_open() by the mood_parser. The argument passed is a
  48  * pointer to the mood_method specific data structure that was returned by the
  49  * mood_parser.
  50  *
  51  * \sa mood_parser.
  52  */
  53 typedef void mood_cleanup_function(void *);
  54
  55 /**
  56  * Used for scoring and to determine whether a file is admissible.
  57  */
  58 struct mood_method {
  59         /** The name of the method. */
  60         const char *name;
  61         /** Pointer to the mood parser. */
  62         mood_parser *parser;
  63         /** Pointer to the score function */
  64         mood_score_function *score_function;
  65         /** Optional cleanup function. */
  66         mood_cleanup_function *cleanup;
  67 };
  68
  69 /** The array of available mood methods. */
  70 extern const struct mood_method mood_methods[];