git.maemo.org Git - lms/blob - lightmediascanner/src/lib/lightmediascanner.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  * @mainpage
  23  *
  24  * The architecture is based on 2 processes that cooperate, the first is
  25  * the driver, that controls the behavior of the worker/slave process,
  26  * that does the hard work. This slave process is meant to make the
  27  * software more robust since some parser libraries and even
  28  * user-provided media is not reliable, so if for some reason the worker
  29  * process freezes, it's killed and then restarted with the next item.
  30  *
  31  * User API is quite simple, with means to add new charsets to be tried
  32  * and new parsers to handle media. The most important functions are (see
  33  * lightmediascanner.h):
  34  *
  35  *   - int lms_process(lms_t *lms, const char *top_path)
  36  *   - int lms_check(lms_t *lms, const char *top_path)
  37  *
  38  * @note The whole library follows libC standard of "0 (zero) means success",
  39  * unless explicitly stated (usually boolean queries where no error is
  40  * possible/interesting).
  41  *
  42  * The first will walk all the files and children directories of
  43  * top_path, check if files are handled by some parser and if they're,
  44  * they'll be parsed and registered in the data base.
  45  *
  46  * The second will get all already registered media in data base that is
  47  * located at top_path and see if they're still up to date, deleted or
  48  * changed. If they were deleted, a flag is set on data base with current
  49  * time, so it can be expired at some point. If they were marked as
  50  * deleted, but are not present again, check if the state is still valid
  51  * (mtime, size), so we can avoid re-parse of removable media. If the
  52  * file was present and is still present, just check if its properties
  53  * (mtime, size) are still the same, if not trigger re-parse.
  54  *
  55  * Parsers are handled as shared object plugins, they can be added
  56  * without modification to the core, see the plugins API later in this
  57  * document. Since the core have no control over plugins, they can
  58  * register data as they want, but since some utilities are provided, we
  59  * expect that the given data base tables are used:
  60  *
  61  *   - @b files: known files.
  62  *      - id: identification inside LMS/DB.
  63  *      - path: file path.
  64  *      - mtime: modification time, in seconds from UNIX epoch.
  65  *      - dtime: modification time, in seconds from UNIX epoch.
  66  *      - size: in bytes.
  67  *   - @b audios: audio files.
  68  *      - id: same as files.id
  69  *      - title: audio title.
  70  *      - album_id: same as audio_albums.id.
  71  *      - genre_id: same as audio_genres.id.
  72  *      - trackno: track number.
  73  *      - rating: rating.
  74  *      - playcnt: play count.
  75  *   - @b audio_artists: audio artists.
  76  *      - id: identification inside LMS/DB.
  77  *      - name: artist name.
  78  *   - @b audio_albums: audio albums.
  79  *      - id: identification inside LMS/DB.
  80  *      - artist_id: same as audio_artists.id.
  81  *      - name: album name.
  82  *   - @b audio_genres: audio genres.
  83  *      - id: identification inside LMS/DB.
  84  *      - name: genre name.
  85  *   - @b playlists: playlists.
  86  *      - id: identification inside LMS/DB.
  87  *      - title: playlists title.
  88  *      - n_entries: number of entries in this playlist.
  89  *   - @b images: image files.
  90  *      - id: identification inside LMS/DB.
  91  *      - title: image title.
  92  *      - artist: image creator or artirst or photographer or ...
  93  *      - date: image taken date or creation date or ...
  94  *      - width: image width.
  95  *      - height: image height.
  96  *      - orientation: image orientation.
  97  *      - gps_lat: GPS latitude.
  98  *      - gps_long: GPS longitude.
  99  *      - gps_alt: GPS altitude.
 100  *   - @b videos: video files.
 101  *      - id: identification inside LMS/DB.
 102  *      - title: video title.
 103  *      - artist: video artist or creator or producer or ...
 104  */
 105
 106
 107 #ifndef _LIGHTMEDIASCANNER_H_
 108 #define _LIGHTMEDIASCANNER_H_ 1
 109
 110 #ifdef API
 111 #undef API
 112 #endif
 113
 114 #ifdef __GNUC__
 115 # if __GNUC__ >= 4
 116 #  define API __attribute__ ((visibility("default")))
 117 #  define GNUC_NULL_TERMINATED __attribute__((__sentinel__))
 118 # else
 119 #  define API
 120 #  define GNUC_NULL_TERMINATED
 121 # endif
 122 # if __GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ >= 96)
 123 #  define GNUC_PURE __attribute__((__pure__))
 124 #  define GNUC_MALLOC __attribute__((__malloc__))
 125 #  define GNUC_CONST __attribute__((__const__))
 126 #  define GNUC_UNUSED __attribute__((__unused__))
 127 # else
 128 #  define GNUC_PURE
 129 #  define GNUC_MALLOC
 130 #  define GNUC_NORETURN
 131 #  define GNUC_CONST
 132 #  define GNUC_UNUSED
 133 # endif
 134 # if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4)
 135 #  define GNUC_WARN_UNUSED_RESULT __attribute__((warn_unused_result))
 136 #  define GNUC_NON_NULL(...) __attribute__((nonnull(__VA_ARGS__)))
 137 # else
 138 #  define GNUC_WARN_UNUSED_RESULT
 139 #  define GNUC_NON_NULL(...)
 140 # endif
 141 #else
 142 #  define API
 143 #  define GNUC_NULL_TERMINATED
 144 #  define GNUC_PURE
 145 #  define GNUC_MALLOC
 146 #  define GNUC_CONST
 147 #  define GNUC_UNUSED
 148 #  define GNUC_WARN_UNUSED_RESULT
 149 #  define GNUC_NON_NULL(...)
 150 #endif
 151
 152 #ifdef __cplusplus
 153 extern "C" {
 154 #endif
 155     /**
 156      * @defgroup LMS_API User-API
 157      *
 158      * Functions for library users.
 159      */
 160
 161     typedef struct lms lms_t;
 162     typedef struct lms_plugin lms_plugin_t;
 163
 164     API lms_t *lms_new(const char *db_path) GNUC_MALLOC GNUC_WARN_UNUSED_RESULT;
 165     API int lms_free(lms_t *lms) GNUC_NON_NULL(1);
 166     API int lms_process(lms_t *lms, const char *top_path) GNUC_NON_NULL(1, 2);
 167     API int lms_check(lms_t *lms, const char *top_path) GNUC_NON_NULL(1, 2);
 168     API void lms_stop_processing(lms_t *lms) GNUC_NON_NULL(1);
 169     API const char *lms_get_db_path(const lms_t *lms) GNUC_NON_NULL(1);
 170     API int lms_is_processing(const lms_t *lms) GNUC_PURE GNUC_NON_NULL(1);
 171     API int lms_get_slave_timeout(const lms_t *lms) GNUC_NON_NULL(1);
 172     API void lms_set_slave_timeout(lms_t *lms, int ms) GNUC_NON_NULL(1);
 173     API unsigned int lms_get_commit_interval(const lms_t *lms) GNUC_NON_NULL(1);
 174     API void lms_set_commit_interval(lms_t *lms, unsigned int transactions) GNUC_NON_NULL(1);
 175
 176     API lms_plugin_t *lms_parser_add(lms_t *lms, const char *so_path) GNUC_NON_NULL(1, 2);
 177     API lms_plugin_t *lms_parser_find_and_add(lms_t *lms, const char *name) GNUC_NON_NULL(1, 2);
 178     API int lms_parser_del(lms_t *lms, lms_plugin_t *handle) GNUC_NON_NULL(1, 2);
 179
 180     API int lms_charset_add(lms_t *lms, const char *charset) GNUC_NON_NULL(1, 2);
 181     API int lms_charset_del(lms_t *lms, const char *charset) GNUC_NON_NULL(1, 2);
 182
 183 #ifdef __cplusplus
 184 }
 185 #endif
 186 #endif /* _LIGHTMEDIASCANNER_H_ */