vcs.maemo.org Git - lms/blob - lightmediascanner/src/lib/lightmediascanner_plugin.h

   1 /**
   2  * Copyright (C) 2007 by INdT
   3  *
   4  * This program is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public License
   6  * as published by the Free Software Foundation; either version 2
   7  * of the License, or (at your option) any later version.
   8  *
   9  * This program is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  * GNU General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public License
  15  * along with this program; if not, write to the Free Software
  16  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  17  *
  18  * @author Gustavo Sverzut Barbieri <gustavo.barbieri@openbossa.org>
  19  */
  20
  21 /**
  22  * @defgroup LMS_Plugin Plugins-API
  23  *
  24  *
  25  * Plugins should implement the following call that provides required
  26  * callbacks (see lightmediascanner_plugin.h):
  27  *
  28  * @code
  29  *    struct lms_plugin *lms_plugin_open(void)
  30  * @endcode
  31  *
  32  * where:
  33  *
  34  * @code
  35  *    struct lms_plugin {
  36  *       const char *name;
  37  *       lms_plugin_match_fn_t match;
  38  *       lms_plugin_parse_fn_t parse;
  39  *       lms_plugin_close_fn_t close;
  40  *       lms_plugin_setup_fn_t setup;
  41  *       lms_plugin_start_fn_t start;
  42  *       lms_plugin_finish_fn_t finish;
  43  *    };
  44  * @endcode
  45  *
  46  * Users can add their own data to the end of this data
  47  * structure. Callbacks and their meanings are:
  48  *
  49  * @code
  50  *    void *match(lms_plugin_t *p,
  51  *                const char *path,
  52  *                int len,
  53  *                int base)
  54  * @endcode
  55  *
  56  *       Given the file 'path' of 'len' bytes, with base name starting at
  57  *       'base' bytes offset inside 'path', return a match. Non-NULL
  58  *       values means it matched, and this return will be given to
  59  *       parse() function so any match-time analysis can be reused.
  60  *       This function will be used in the slave process.
  61  *
  62  *
  63  * @code
  64  *    int parse(lms_plugin_t *p,
  65  *              struct lms_context *ctxt,
  66  *              const struct lms_file_info *finfo,
  67  *              void *match)
  68  * @endcode
  69  *
  70  *       Given the parsing context 'ctxt' (contains DB connection,
  71  *       charset conversion pointers and possible more), parse the file
  72  *       information 'finfo' using the previously matched data
  73  *       'match'. This should return 0 on success or other value for
  74  *       errors. This will be used in the slave process.
  75  *
  76  *
  77  * @code
  78  *    int close(lms_plugin_t *p)
  79  * @endcode
  80  *
  81  *       Closes the plugin returned by lms_plugin_open(), this will run
  82  *       on the master process.
  83  *
  84  *
  85  * @code
  86  *    int setup(lms_plugin_t *p, struct lms_context *ctxt)
  87  * @endcode
  88  *
  89  *       Prepare parser to be executed. This is the first phase of plugin
  90  *       initialization on the slave process, it should create database
  91  *       tables and like, after this function is called, no database
  92  *       schema changes are allowed!
  93  *
  94  *
  95  * @code
  96  *    int start(lms_plugin_t *p, struct lms_context *ctxt)
  97  * @endcode
  98  *
  99  *       This is the second phase of plugin initialization on the slave
 100  *       process.  At this point, all database tables should exist and
 101  *       database schema will not be changed anymore, so one can use this
 102  *       phase to compile SQL statements for future use.
 103  *
 104  *
 105  * @code
 106  *    int finish(lms_plugin_t *p, struct lms_context *ctxt)
 107  * @endcode
 108  *
 109  *       Finishes the plugin on slave process.
 110  *
 111  *
 112  * Although LMS doesn't place any restrictions on what plugins can do and
 113  * how they store information, it's good to have standard tables and easy
 114  * way to store data on them. For this task we provide
 115  * lightmediascanner_db.h with functions to add audios, images, videos,
 116  * playlists and possible more. Use should be pretty straightforward, see
 117  * existing plugins to see usage examples.
 118  *
 119  */
 120
 121 #ifndef _LIGHTMEDIASCANNER_PLUGIN_H_
 122 #define _LIGHTMEDIASCANNER_PLUGIN_H_ 1
 123
 124 #include <lightmediascanner.h>
 125 #include <lightmediascanner_charset_conv.h>
 126 #include <sqlite3.h>
 127 #include <sys/types.h>
 128
 129 #ifdef __cplusplus
 130 extern "C" {
 131 #endif
 132
 133     struct lms_file_info {
 134         const char *path; /**< file path */
 135         int path_len; /**< path length */
 136         int base; /**< index of basename inside path */
 137         int64_t id; /**< database id */
 138         time_t mtime; /**< in-disk modification time */
 139         time_t dtime; /**< deletion time */
 140         size_t size; /**< file size in bytes */
 141     };
 142
 143     struct lms_context {
 144         sqlite3 *db; /**< database instance */
 145         lms_charset_conv_t *cs_conv; /**< charset conversion tool */
 146     };
 147
 148     typedef void *(*lms_plugin_match_fn_t)(lms_plugin_t *p, const char *path, int len, int base);
 149     typedef int (*lms_plugin_parse_fn_t)(lms_plugin_t *p, struct lms_context *ctxt, const struct lms_file_info *finfo, void *match);
 150     typedef int (*lms_plugin_close_fn_t)(lms_plugin_t *p);
 151     typedef int (*lms_plugin_setup_fn_t)(lms_plugin_t *p, struct lms_context *ctxt);
 152     typedef int (*lms_plugin_start_fn_t)(lms_plugin_t *p, struct lms_context *ctxt);
 153     typedef int (*lms_plugin_finish_fn_t)(lms_plugin_t *p, struct lms_context *ctxt);
 154
 155     struct lms_plugin {
 156         const char *name; /**< plugin name */
 157         lms_plugin_match_fn_t match; /**< check match */
 158         lms_plugin_parse_fn_t parse; /**< parse matched file */
 159         lms_plugin_close_fn_t close; /**< close plugin */
 160         lms_plugin_setup_fn_t setup; /**< setup (1st phase init) */
 161         lms_plugin_start_fn_t start; /**< start (2nd phase init) */
 162         lms_plugin_finish_fn_t finish; /**< finish plugin */
 163     };
 164
 165 #ifdef __cplusplus
 166 }
 167 #endif
 168 #endif /* _LIGHTMEDIASCANNER_PLUGIN_H_ */