--- /dev/null
+# Doxyfile 1.5.2
+
+#---------------------------------------------------------------------------
+# Project related configuration options
+#---------------------------------------------------------------------------
+DOXYFILE_ENCODING = UTF-8
+PROJECT_NAME = "Light Media Scanner"
+PROJECT_NUMBER = 0.1
+OUTPUT_DIRECTORY = docs
+CREATE_SUBDIRS = NO
+OUTPUT_LANGUAGE = English
+BRIEF_MEMBER_DESC = YES
+REPEAT_BRIEF = YES
+ABBREVIATE_BRIEF = "The $name class" \
+ "The $name widget" \
+ "The $name file" \
+ is \
+ provides \
+ specifies \
+ contains \
+ represents \
+ a \
+ an \
+ the
+ALWAYS_DETAILED_SEC = NO
+INLINE_INHERITED_MEMB = NO
+FULL_PATH_NAMES = YES
+STRIP_FROM_PATH =
+STRIP_FROM_INC_PATH =
+SHORT_NAMES = NO
+JAVADOC_AUTOBRIEF = NO
+MULTILINE_CPP_IS_BRIEF = NO
+DETAILS_AT_TOP = NO
+INHERIT_DOCS = YES
+SEPARATE_MEMBER_PAGES = NO
+TAB_SIZE = 8
+ALIASES =
+OPTIMIZE_OUTPUT_FOR_C = YES
+OPTIMIZE_OUTPUT_JAVA = NO
+BUILTIN_STL_SUPPORT = NO
+CPP_CLI_SUPPORT = NO
+DISTRIBUTE_GROUP_DOC = NO
+SUBGROUPING = YES
+#---------------------------------------------------------------------------
+# Build related configuration options
+#---------------------------------------------------------------------------
+EXTRACT_ALL = YES
+EXTRACT_PRIVATE = NO
+EXTRACT_STATIC = NO
+EXTRACT_LOCAL_CLASSES = NO
+EXTRACT_LOCAL_METHODS = NO
+HIDE_UNDOC_MEMBERS = NO
+HIDE_UNDOC_CLASSES = NO
+HIDE_FRIEND_COMPOUNDS = NO
+HIDE_IN_BODY_DOCS = NO
+INTERNAL_DOCS = NO
+CASE_SENSE_NAMES = YES
+HIDE_SCOPE_NAMES = NO
+SHOW_INCLUDE_FILES = YES
+INLINE_INFO = YES
+SORT_MEMBER_DOCS = YES
+SORT_BRIEF_DOCS = NO
+SORT_BY_SCOPE_NAME = NO
+GENERATE_TODOLIST = YES
+GENERATE_TESTLIST = YES
+GENERATE_BUGLIST = YES
+GENERATE_DEPRECATEDLIST= YES
+ENABLED_SECTIONS =
+MAX_INITIALIZER_LINES = 30
+SHOW_USED_FILES = YES
+SHOW_DIRECTORIES = NO
+FILE_VERSION_FILTER =
+#---------------------------------------------------------------------------
+# configuration options related to warning and progress messages
+#---------------------------------------------------------------------------
+QUIET = NO
+WARNINGS = YES
+WARN_IF_UNDOCUMENTED = YES
+WARN_IF_DOC_ERROR = YES
+WARN_NO_PARAMDOC = NO
+WARN_FORMAT = "$file:$line: $text"
+WARN_LOGFILE =
+#---------------------------------------------------------------------------
+# configuration options related to the input files
+#---------------------------------------------------------------------------
+INPUT = src/lib
+INPUT_ENCODING = UTF-8
+FILE_PATTERNS = *.c \
+ *.cc \
+ *.cxx \
+ *.cpp \
+ *.c++ \
+ *.d \
+ *.java \
+ *.ii \
+ *.ixx \
+ *.ipp \
+ *.i++ \
+ *.inl \
+ *.h \
+ *.hh \
+ *.hxx \
+ *.hpp \
+ *.h++ \
+ *.idl \
+ *.odl \
+ *.cs \
+ *.php \
+ *.php3 \
+ *.inc \
+ *.m \
+ *.mm \
+ *.dox \
+ *.py \
+ *.C \
+ *.CC \
+ *.C++ \
+ *.II \
+ *.I++ \
+ *.H \
+ *.HH \
+ *.H++ \
+ *.CS \
+ *.PHP \
+ *.PHP3 \
+ *.M \
+ *.MM \
+ *.PY
+RECURSIVE = NO
+EXCLUDE =
+EXCLUDE_SYMLINKS = NO
+EXCLUDE_PATTERNS =
+EXCLUDE_SYMBOLS =
+EXAMPLE_PATH =
+EXAMPLE_PATTERNS = *
+EXAMPLE_RECURSIVE = NO
+IMAGE_PATH =
+INPUT_FILTER =
+FILTER_PATTERNS =
+FILTER_SOURCE_FILES = NO
+#---------------------------------------------------------------------------
+# configuration options related to source browsing
+#---------------------------------------------------------------------------
+SOURCE_BROWSER = YES
+INLINE_SOURCES = NO
+STRIP_CODE_COMMENTS = YES
+REFERENCED_BY_RELATION = YES
+REFERENCES_RELATION = YES
+REFERENCES_LINK_SOURCE = YES
+USE_HTAGS = NO
+VERBATIM_HEADERS = YES
+#---------------------------------------------------------------------------
+# configuration options related to the alphabetical class index
+#---------------------------------------------------------------------------
+ALPHABETICAL_INDEX = YES
+COLS_IN_ALPHA_INDEX = 3
+IGNORE_PREFIX = lms_
+#---------------------------------------------------------------------------
+# configuration options related to the HTML output
+#---------------------------------------------------------------------------
+GENERATE_HTML = YES
+HTML_OUTPUT = html
+HTML_FILE_EXTENSION = .html
+HTML_HEADER =
+HTML_FOOTER =
+HTML_STYLESHEET =
+HTML_ALIGN_MEMBERS = YES
+GENERATE_HTMLHELP = NO
+CHM_FILE =
+HHC_LOCATION =
+GENERATE_CHI = NO
+BINARY_TOC = NO
+TOC_EXPAND = NO
+DISABLE_INDEX = NO
+ENUM_VALUES_PER_LINE = 4
+GENERATE_TREEVIEW = NO
+TREEVIEW_WIDTH = 250
+#---------------------------------------------------------------------------
+# configuration options related to the LaTeX output
+#---------------------------------------------------------------------------
+GENERATE_LATEX = NO
+LATEX_OUTPUT = latex
+LATEX_CMD_NAME = latex
+MAKEINDEX_CMD_NAME = makeindex
+COMPACT_LATEX = NO
+PAPER_TYPE = a4wide
+EXTRA_PACKAGES =
+LATEX_HEADER =
+PDF_HYPERLINKS = NO
+USE_PDFLATEX = NO
+LATEX_BATCHMODE = NO
+LATEX_HIDE_INDICES = NO
+#---------------------------------------------------------------------------
+# configuration options related to the RTF output
+#---------------------------------------------------------------------------
+GENERATE_RTF = NO
+RTF_OUTPUT = rtf
+COMPACT_RTF = NO
+RTF_HYPERLINKS = NO
+RTF_STYLESHEET_FILE =
+RTF_EXTENSIONS_FILE =
+#---------------------------------------------------------------------------
+# configuration options related to the man page output
+#---------------------------------------------------------------------------
+GENERATE_MAN = NO
+MAN_OUTPUT = man
+MAN_EXTENSION = .3
+MAN_LINKS = NO
+#---------------------------------------------------------------------------
+# configuration options related to the XML output
+#---------------------------------------------------------------------------
+GENERATE_XML = NO
+XML_OUTPUT = xml
+XML_SCHEMA =
+XML_DTD =
+XML_PROGRAMLISTING = YES
+#---------------------------------------------------------------------------
+# configuration options for the AutoGen Definitions output
+#---------------------------------------------------------------------------
+GENERATE_AUTOGEN_DEF = NO
+#---------------------------------------------------------------------------
+# configuration options related to the Perl module output
+#---------------------------------------------------------------------------
+GENERATE_PERLMOD = NO
+PERLMOD_LATEX = NO
+PERLMOD_PRETTY = YES
+PERLMOD_MAKEVAR_PREFIX =
+#---------------------------------------------------------------------------
+# Configuration options related to the preprocessor
+#---------------------------------------------------------------------------
+ENABLE_PREPROCESSING = YES
+MACRO_EXPANSION = NO
+EXPAND_ONLY_PREDEF = NO
+SEARCH_INCLUDES = YES
+INCLUDE_PATH =
+INCLUDE_FILE_PATTERNS =
+PREDEFINED =
+EXPAND_AS_DEFINED =
+SKIP_FUNCTION_MACROS = YES
+#---------------------------------------------------------------------------
+# Configuration::additions related to external references
+#---------------------------------------------------------------------------
+TAGFILES =
+GENERATE_TAGFILE =
+ALLEXTERNALS = NO
+EXTERNAL_GROUPS = YES
+PERL_PATH = /usr/bin/perl
+#---------------------------------------------------------------------------
+# Configuration options related to the dot tool
+#---------------------------------------------------------------------------
+CLASS_DIAGRAMS = NO
+MSCGEN_PATH =
+HIDE_UNDOC_RELATIONS = YES
+HAVE_DOT = YES
+CLASS_GRAPH = YES
+COLLABORATION_GRAPH = YES
+GROUP_GRAPHS = YES
+UML_LOOK = YES
+TEMPLATE_RELATIONS = NO
+INCLUDE_GRAPH = YES
+INCLUDED_BY_GRAPH = YES
+CALL_GRAPH = YES
+CALLER_GRAPH = NO
+GRAPHICAL_HIERARCHY = YES
+DIRECTORY_GRAPH = YES
+DOT_IMAGE_FORMAT = png
+DOT_PATH =
+DOTFILE_DIRS =
+DOT_GRAPH_MAX_NODES = 50
+DOT_TRANSPARENT = YES
+DOT_MULTI_TARGETS = NO
+GENERATE_LEGEND = YES
+DOT_CLEANUP = YES
+#---------------------------------------------------------------------------
+# Configuration::additions related to the search engine
+#---------------------------------------------------------------------------
+SEARCHENGINE = NO
/***********************************************************************
* Public API.
***********************************************************************/
+/**
+ * Create new Light Media Scanner instance.
+ *
+ * @param db_path path to database file.
+ * @return allocated data on success or NULL on failure.
+ * @ingroup LMS_API
+ */
lms_t *
lms_new(const char *db_path)
{
return lms;
}
+/**
+ * Free existing Light Media Scanner instance.
+ *
+ * @param lms previously allocated Light Media Scanner instance.
+ *
+ * @return On success 0 is returned.
+ * @ingroup LMS_API
+ */
int
lms_free(lms_t *lms)
{
return 0;
}
+/**
+ * Add parser plugin given it's shared object path.
+ *
+ * @param lms previously allocated Light Media Scanner instance.
+ * @param so_path path to shared object (usable by dlopen(3)).
+ *
+ * @return On success the LMS handle to plugin is returned, NULL on error.
+ * @ingroup LMS_API
+ */
lms_plugin_t *
lms_parser_add(lms_t *lms, const char *so_path)
{
return parser->plugin;
}
+/**
+ * Add parser plugin given it's name.
+ *
+ * This will look at default plugin path by the file named @p name (plus
+ * the required shared object extension).
+ *
+ * @param lms previously allocated Light Media Scanner instance.
+ * @param name plugin name.
+ *
+ * @return On success the LMS handle to plugin is returned, NULL on error.
+ * @ingroup LMS_API
+ */
lms_plugin_t *
lms_parser_find_and_add(lms_t *lms, const char *name)
{
}
}
+/**
+ * Delete previously added parser, making it unavailable for future operations.
+ *
+ * @param lms previously allocated Light Media Scanner instance.
+ *
+ * @return On success 0 is returned.
+ * @ingroup LMS_API
+ */
int
lms_parser_del(lms_t *lms, lms_plugin_t *handle)
{
return -3;
}
+/**
+ * Checks if Light Media Scanner is being used in a processing operation lile
+ * lms_process() or lms_check().
+ *
+ * @param lms previously allocated Light Media Scanner instance.
+ *
+ * @return 1 if it is processing, 0 if it's not, -1 on error.
+ * @ingroup LMS_API
+ */
int
lms_is_processing(const lms_t *lms)
{
return lms->is_processing;
}
+/**
+ * Get the database path given at creation time.
+ *
+ * @param lms previously allocated Light Media Scanner instance.
+ *
+ * @return path to database.
+ * @ingroup LMS_API
+ */
const char *
lms_get_db_path(const lms_t *lms)
{
return lms->db_path;
}
+/**
+ * Get the maximum amount of milliseconds the slave can take to serve one file.
+ *
+ * If a slave takes more than this amount of milliseconds, it will be killed
+ * and the scanner will continue with the next file.
+ *
+ * @param lms previously allocated Light Media Scanner instance.
+ *
+ * @return -1 on error or time in milliseconds otherwise.
+ * @ingroup LMS_API
+ */
int
lms_get_slave_timeout(const lms_t *lms)
{
return lms->slave_timeout;
}
+/**
+ * Set the maximum amount of milliseconds the slave can take to serve one file.
+ *
+ * If a slave takes more than this amount of milliseconds, it will be killed
+ * and the scanner will continue with the next file.
+ *
+ * @param lms previously allocated Light Media Scanner instance.
+ * @param ms time in milliseconds.
+ * @ingroup LMS_API
+ */
void lms_set_slave_timeout(lms_t *lms, int ms)
{
if (!lms) {
lms->slave_timeout = ms;
}
+/**
+ * Get the number of files served between database transactions.
+ *
+ * This is used as an optimization to database access: doing database commits
+ * take some time and can slow things down too much, so you can choose to just
+ * commit after some number of files are processed, this is the commit_interval.
+ *
+ * @param lms previously allocated Light Media Scanner instance.
+ * @return (unsigned int)-1 on error, value otherwise.
+ * @ingroup LMS_API
+ */
unsigned int
lms_get_commit_interval(const lms_t *lms)
{
return lms->commit_interval;
}
+/**
+ * Set the number of files served between database transactions.
+ *
+ * This is used as an optimization to database access: doing database commits
+ * take some time and can slow things down too much, so you can choose to just
+ * commit after @p transactions files are processed.
+ *
+ * @param lms previously allocated Light Media Scanner instance.
+ * @param transactions number of files (transactions) to process between
+ * commits.
+ * @ingroup LMS_API
+ */
void
lms_set_commit_interval(lms_t *lms, unsigned int transactions)
{
lms->commit_interval = transactions;
}
+/**
+ * Register a new charset encoding to be used.
+ *
+ * All database text strings are in UTF-8, so one needs to register new
+ * encodings in order to convert to it.
+ *
+ * @param lms previously allocated Light Media Scanner instance.
+ * @param charset charset name as understood by iconv_open(3).
+ *
+ * @return On success 0 is returned.
+ * @ingroup LMS_API
+ */
int
lms_charset_add(lms_t *lms, const char *charset)
{
return lms_charset_conv_add(lms->cs_conv, charset);
}
+/**
+ * Forget about registered charset encoding.
+ *
+ * All database text strings are in UTF-8, so one needs to register new
+ * encodings in order to convert to it.
+ *
+ * @param lms previously allocated Light Media Scanner instance.
+ * @param charset charset name as understood by iconv_open(3).
+ *
+ * @return On success 0 is returned.
+ * @ingroup LMS_API
+ */
int
lms_charset_del(lms_t *lms, const char *charset)
{
* @author Gustavo Sverzut Barbieri <gustavo.barbieri@openbossa.org>
*/
+/**
+ * @mainpage
+ *
+ * The architecture is based on 2 processes that cooperate, the first is
+ * the driver, that controls the behavior of the worker/slave process,
+ * that does the hard work. This slave process is meant to make the
+ * software more robust since some parser libraries and even
+ * user-provided media is not reliable, so if for some reason the worker
+ * process freezes, it's killed and then restarted with the next item.
+ *
+ * User API is quite simple, with means to add new charsets to be tried
+ * and new parsers to handle media. The most important functions are (see
+ * lightmediascanner.h):
+ *
+ * - int lms_process(lms_t *lms, const char *top_path)
+ * - int lms_check(lms_t *lms, const char *top_path)
+ *
+ * @note The whole library follows libC standard of "0 (zero) means success",
+ * unless explicitly stated (usually boolean queries where no error is
+ * possible/interesting).
+ *
+ * The first will walk all the files and children directories of
+ * top_path, check if files are handled by some parser and if they're,
+ * they'll be parsed and registered in the data base.
+ *
+ * The second will get all already registered media in data base that is
+ * located at top_path and see if they're still up to date, deleted or
+ * changed. If they were deleted, a flag is set on data base with current
+ * time, so it can be expired at some point. If they were marked as
+ * deleted, but are not present again, check if the state is still valid
+ * (mtime, size), so we can avoid re-parse of removable media. If the
+ * file was present and is still present, just check if its properties
+ * (mtime, size) are still the same, if not trigger re-parse.
+ *
+ * Parsers are handled as shared object plugins, they can be added
+ * without modification to the core, see the plugins API later in this
+ * document. Since the core have no control over plugins, they can
+ * register data as they want, but since some utilities are provided, we
+ * expect that the given data base tables are used:
+ *
+ * - @b files: known files.
+ * - id: identification inside LMS/DB.
+ * - path: file path.
+ * - mtime: modification time, in seconds from UNIX epoch.
+ * - dtime: modification time, in seconds from UNIX epoch.
+ * - size: in bytes.
+ * - @b audios: audio files.
+ * - id: same as files.id
+ * - title: audio title.
+ * - album_id: same as audio_albums.id.
+ * - genre_id: same as audio_genres.id.
+ * - trackno: track number.
+ * - rating: rating.
+ * - playcnt: play count.
+ * - @b audio_artists: audio artists.
+ * - id: identification inside LMS/DB.
+ * - name: artist name.
+ * - @b audio_albums: audio albums.
+ * - id: identification inside LMS/DB.
+ * - artist_id: same as audio_artists.id.
+ * - name: album name.
+ * - @b audio_genres: audio genres.
+ * - id: identification inside LMS/DB.
+ * - name: genre name.
+ * - @b playlists: playlists.
+ * - id: identification inside LMS/DB.
+ * - title: playlists title.
+ * - n_entries: number of entries in this playlist.
+ * - @b images: image files.
+ * - id: identification inside LMS/DB.
+ * - title: image title.
+ * - artist: image creator or artirst or photographer or ...
+ * - date: image taken date or creation date or ...
+ * - width: image width.
+ * - height: image height.
+ * - orientation: image orientation.
+ * - gps_lat: GPS latitude.
+ * - gps_long: GPS longitude.
+ * - gps_alt: GPS altitude.
+ * - @b videos: video files.
+ * - id: identification inside LMS/DB.
+ * - title: video title.
+ * - artist: video artist or creator or producer or ...
+ */
+
+
#ifndef _LIGHTMEDIASCANNER_H_
#define _LIGHTMEDIASCANNER_H_ 1
#ifdef __cplusplus
extern "C" {
#endif
+ /**
+ * @defgroup LMS_API User-API
+ *
+ * Functions for library users.
+ */
+
typedef struct lms lms_t;
typedef struct lms_plugin lms_plugin_t;
char **names;
};
+/**
+ * Create a new charset conversion tool.
+ *
+ * Conversion tool will try to convert provided strings to UTF-8, just need
+ * to register known charsets with lms_charset_conv_add() and then call
+ * lms_charset_conv().
+ *
+ * @return newly allocated conversion tool or NULL on error.
+ */
lms_charset_conv_t *
lms_charset_conv_new(void)
{
return NULL;
}
+/**
+ * Free existing charset conversion tool.
+ *
+ * @param lcc existing Light Media Scanner charset conversion.
+ */
void
lms_charset_conv_free(lms_charset_conv_t *lcc)
{
free(lcc);
}
+/**
+ * Register new charset to conversion tool.
+ *
+ * @param lcc existing Light Media Scanner charset conversion.
+ * @param charset charset name as understood by iconv_open(3).
+ *
+ * @return On success 0 is returned.
+ */
int
lms_charset_conv_add(lms_charset_conv_t *lcc, const char *charset)
{
return -1;
}
+/**
+ * Forget about previously registered charset in conversion tool.
+ *
+ * @param lcc existing Light Media Scanner charset conversion.
+ * @param charset charset name.
+ *
+ * @return On success 0 is returned.
+ */
int
lms_charset_conv_del(lms_charset_conv_t *lcc, const char *charset)
{
return 0;
}
+/**
+ * If required, do charset conversion to UTF-8.
+ *
+ * @param lcc existing Light Media Scanner charset conversion.
+ * @param p_str string to be converted.
+ * @param p_len string size.
+ *
+ * @return On success 0 is returned.
+ */
int
lms_charset_conv(lms_charset_conv_t *lcc, char **p_str, unsigned int *p_len)
{
return i;
}
+/**
+ * Check if strings is not UTF-8 and conversion is required.
+ *
+ * @param lcc existing Light Media Scanner charset conversion.
+ * @param str string to be analysed.
+ * @param len string size.
+ *
+ * @return 0 if string is already UTF-8.
+ */
int
lms_charset_conv_check(lms_charset_conv_t *lcc, const char *str, unsigned int len)
{
#ifdef __cplusplus
extern "C" {
#endif
+/**
+ * @defgroup LMS_CHARSET Charset Conversion
+ *
+ * Utilities to convert strings to UTF-8, the charset used in database.
+ * @{
+ */
typedef struct lms_charset_conv lms_charset_conv_t;
API int lms_charset_conv(lms_charset_conv_t *lcc, char **p_str, unsigned int *p_len) GNUC_NON_NULL(1, 2, 3);
API int lms_charset_conv_check(lms_charset_conv_t *lcc, const char *str, unsigned int len) GNUC_NON_NULL(1, 2);
+/**
+ * @}
+ */
#ifdef __cplusplus
}
#endif
return ret;
}
+/**
+ * Check consistency of given directory.
+ *
+ * This will update media in the given directory or its children. If files
+ * are missing, they'll be marked as deleted (dtime is set), if they were
+ * marked as deleted and are now present, they are unmarked (dtime is unset).
+ *
+ * @param lms previously allocated Light Media Scanner instance.
+ * @param top_path top directory to scan.
+ *
+ * @return On success 0 is returned.
+ */
int
lms_check(lms_t *lms, const char *top_path)
{
#ifdef __cplusplus
extern "C" {
#endif
+/**
+ * @defgroup LMS_DB DataBase-API
+ *
+ * Although Light Media Scanner uses SQLite3 and doesn't try to hide it from
+ * plugins/parsers, it does provide some utilities to make development easier
+ * and less error prone.
+ *
+ * @{
+ */
/* Image Records */
struct lms_gps_info {
API int lms_db_playlist_free(lms_db_playlist_t *ldp) GNUC_NON_NULL(1);
API int lms_db_playlist_add(lms_db_playlist_t *ldp, struct lms_playlist_info *info) GNUC_NON_NULL(1, 2);
-
+/**
+ * @}
+ */
#ifdef __cplusplus
}
#undef _DB_T_UPDATE
+/**
+ * Create audio DB access tool.
+ *
+ * Creates or get a reference to tools to access 'audios' table in an
+ * optimized and easy way.
+ *
+ * This is usually called from plugin's @b setup() callback with the @p db
+ * got from @c ctxt.
+ *
+ * @param db database connection.
+ *
+ * @return DB access tool handle.
+ * @ingroup LMS_Plugins
+ */
lms_db_audio_t *
lms_db_audio_new(sqlite3 *db)
{
return lda;
}
+/**
+ * Start audio DB access tool.
+ *
+ * Compile SQL statements and other initialization functions.
+ *
+ * This is usually called from plugin's @b start() callback.
+ *
+ * @param lda handle returned by lms_db_audio_new().
+ *
+ * @return On success 0 is returned.
+ * @ingroup LMS_Plugins
+ */
int
lms_db_audio_start(lms_db_audio_t *lda)
{
return 0;
}
+/**
+ * Free audio DB access tool.
+ *
+ * Unreference and possible free resources allocated to access tool.
+ *
+ * This is usually called from plugin's @b finish() callback.
+ *
+ * @param lda handle returned by lms_db_audio_new().
+ *
+ * @return On success 0 is returned.
+ * @ingroup LMS_Plugins
+ */
int
lms_db_audio_free(lms_db_audio_t *lda)
{
return ret;
}
+/**
+ * Add audio file to DB.
+ *
+ * This is usually called from plugin's @b parse() callback.
+ *
+ * @param lda handle returned by lms_db_audio_new().
+ * @param info audio information to store.
+ *
+ * @return On success 0 is returned.
+ * @ingroup LMS_Plugins
+ */
int
lms_db_audio_add(lms_db_audio_t *lda, struct lms_audio_info *info)
{
_db_table_updater_images);
}
+/**
+ * Create image DB access tool.
+ *
+ * Creates or get a reference to tools to access 'images' table in an
+ * optimized and easy way.
+ *
+ * This is usually called from plugin's @b setup() callback with the @p db
+ * got from @c ctxt.
+ *
+ * @param db database connection.
+ *
+ * @return DB access tool handle.
+ * @ingroup LMS_Plugins
+ */
lms_db_image_t *
lms_db_image_new(sqlite3 *db)
{
return ldi;
}
+/**
+ * Start image DB access tool.
+ *
+ * Compile SQL statements and other initialization functions.
+ *
+ * This is usually called from plugin's @b start() callback.
+ *
+ * @param ldi handle returned by lms_db_image_new().
+ *
+ * @return On success 0 is returned.
+ * @ingroup LMS_Plugins
+ */
int
lms_db_image_start(lms_db_image_t *ldi)
{
return 0;
}
+/**
+ * Free image DB access tool.
+ *
+ * Unreference and possible free resources allocated to access tool.
+ *
+ * This is usually called from plugin's @b finish() callback.
+ *
+ * @param ldi handle returned by lms_db_image_new().
+ *
+ * @return On success 0 is returned.
+ * @ingroup LMS_Plugins
+ */
int
lms_db_image_free(lms_db_image_t *ldi)
{
return ret;
}
+/**
+ * Add image file to DB.
+ *
+ * This is usually called from plugin's @b parse() callback.
+ *
+ * @param ldi handle returned by lms_db_image_new().
+ * @param info image information to store.
+ *
+ * @return On success 0 is returned.
+ * @ingroup LMS_Plugins
+ */
int
lms_db_image_add(lms_db_image_t *ldi, struct lms_image_info *info)
{
_db_table_updater_playlists);
}
+/**
+ * Create playlist DB access tool.
+ *
+ * Creates or get a reference to tools to access 'playlists' table in an
+ * optimized and easy way.
+ *
+ * This is usually called from plugin's @b setup() callback with the @p db
+ * got from @c ctxt.
+ *
+ * @param db database connection.
+ *
+ * @return DB access tool handle.
+ * @ingroup LMS_Plugins
+ */
lms_db_playlist_t *
lms_db_playlist_new(sqlite3 *db)
{
return ldp;
}
+/**
+ * Start playlist DB access tool.
+ *
+ * Compile SQL statements and other initialization functions.
+ *
+ * This is usually called from plugin's @b start() callback.
+ *
+ * @param ldp handle returned by lms_db_playlist_new().
+ *
+ * @return On success 0 is returned.
+ * @ingroup LMS_Plugins
+ */
int
lms_db_playlist_start(lms_db_playlist_t *ldp)
{
return 0;
}
+/**
+ * Free playlist DB access tool.
+ *
+ * Unreference and possible free resources allocated to access tool.
+ *
+ * This is usually called from plugin's @b finish() callback.
+ *
+ * @param ldp handle returned by lms_db_playlist_new().
+ *
+ * @return On success 0 is returned.
+ * @ingroup LMS_Plugins
+ */
int
lms_db_playlist_free(lms_db_playlist_t *ldp)
{
return ret;
}
+/**
+ * Add playlist file to DB.
+ *
+ * This is usually called from plugin's @b parse() callback.
+ *
+ * @param ldp handle returned by lms_db_playlist_new().
+ * @param info playlist information to store.
+ *
+ * @return On success 0 is returned.
+ * @ingroup LMS_Plugins
+ */
int
lms_db_playlist_add(lms_db_playlist_t *ldp, struct lms_playlist_info *info)
{
_db_table_updater_videos);
}
+/**
+ * Create video DB access tool.
+ *
+ * Creates or get a reference to tools to access 'videos' table in an
+ * optimized and easy way.
+ *
+ * This is usually called from plugin's @b setup() callback with the @p db
+ * got from @c ctxt.
+ *
+ * @param db database connection.
+ *
+ * @return DB access tool handle.
+ * @ingroup LMS_Plugins
+ */
lms_db_video_t *
lms_db_video_new(sqlite3 *db)
{
return ldv;
}
+/**
+ * Start video DB access tool.
+ *
+ * Compile SQL statements and other initialization functions.
+ *
+ * This is usually called from plugin's @b start() callback.
+ *
+ * @param ldv handle returned by lms_db_video_new().
+ *
+ * @return On success 0 is returned.
+ * @ingroup LMS_Plugins
+ */
int
lms_db_video_start(lms_db_video_t *ldv)
{
return 0;
}
+/**
+ * Free video DB access tool.
+ *
+ * Unreference and possible free resources allocated to access tool.
+ *
+ * This is usually called from plugin's @b finish() callback.
+ *
+ * @param ldv handle returned by lms_db_video_new().
+ *
+ * @return On success 0 is returned.
+ * @ingroup LMS_Plugins
+ */
int
lms_db_video_free(lms_db_video_t *ldv)
{
return ret;
}
+/**
+ * Add video file to DB.
+ *
+ * This is usually called from plugin's @b parse() callback.
+ *
+ * @param ldv handle returned by lms_db_video_new().
+ * @param info video information to store.
+ *
+ * @return On success 0 is returned.
+ * @ingroup LMS_Plugins
+ */
int
lms_db_video_add(lms_db_video_t *ldv, struct lms_video_info *info)
{
* @author Gustavo Sverzut Barbieri <gustavo.barbieri@openbossa.org>
*/
+/**
+ * @defgroup LMS_Plugin Plugins-API
+ *
+ *
+ * Plugins should implement the following call that provides required
+ * callbacks (see lightmediascanner_plugin.h):
+ *
+ * @code
+ * struct lms_plugin *lms_plugin_open(void)
+ * @endcode
+ *
+ * where:
+ *
+ * @code
+ * struct lms_plugin {
+ * const char *name;
+ * lms_plugin_match_fn_t match;
+ * lms_plugin_parse_fn_t parse;
+ * lms_plugin_close_fn_t close;
+ * lms_plugin_setup_fn_t setup;
+ * lms_plugin_start_fn_t start;
+ * lms_plugin_finish_fn_t finish;
+ * };
+ * @endcode
+ *
+ * Users can add their own data to the end of this data
+ * structure. Callbacks and their meanings are:
+ *
+ * @code
+ * void *match(lms_plugin_t *p,
+ * const char *path,
+ * int len,
+ * int base)
+ * @endcode
+ *
+ * Given the file 'path' of 'len' bytes, with base name starting at
+ * 'base' bytes offset inside 'path', return a match. Non-NULL
+ * values means it matched, and this return will be given to
+ * parse() function so any match-time analysis can be reused.
+ * This function will be used in the slave process.
+ *
+ *
+ * @code
+ * int parse(lms_plugin_t *p,
+ * struct lms_context *ctxt,
+ * const struct lms_file_info *finfo,
+ * void *match)
+ * @endcode
+ *
+ * Given the parsing context 'ctxt' (contains DB connection,
+ * charset conversion pointers and possible more), parse the file
+ * information 'finfo' using the previously matched data
+ * 'match'. This should return 0 on success or other value for
+ * errors. This will be used in the slave process.
+ *
+ *
+ * @code
+ * int close(lms_plugin_t *p)
+ * @endcode
+ *
+ * Closes the plugin returned by lms_plugin_open(), this will run
+ * on the master process.
+ *
+ *
+ * @code
+ * int setup(lms_plugin_t *p, struct lms_context *ctxt)
+ * @endcode
+ *
+ * Prepare parser to be executed. This is the first phase of plugin
+ * initialization on the slave process, it should create database
+ * tables and like, after this function is called, no database
+ * schema changes are allowed!
+ *
+ *
+ * @code
+ * int start(lms_plugin_t *p, struct lms_context *ctxt)
+ * @endcode
+ *
+ * This is the second phase of plugin initialization on the slave
+ * process. At this point, all database tables should exist and
+ * database schema will not be changed anymore, so one can use this
+ * phase to compile SQL statements for future use.
+ *
+ *
+ * @code
+ * int finish(lms_plugin_t *p, struct lms_context *ctxt)
+ * @endcode
+ *
+ * Finishes the plugin on slave process.
+ *
+ *
+ * Although LMS doesn't place any restrictions on what plugins can do and
+ * how they store information, it's good to have standard tables and easy
+ * way to store data on them. For this task we provide
+ * lightmediascanner_db.h with functions to add audios, images, videos,
+ * playlists and possible more. Use should be pretty straightforward, see
+ * existing plugins to see usage examples.
+ *
+ */
+
#ifndef _LIGHTMEDIASCANNER_PLUGIN_H_
#define _LIGHTMEDIASCANNER_PLUGIN_H_ 1
};
struct lms_context {
- sqlite3 *db;
- lms_charset_conv_t *cs_conv;
+ sqlite3 *db; /**< database instance */
+ lms_charset_conv_t *cs_conv; /**< charset conversion tool */
};
typedef void *(*lms_plugin_match_fn_t)(lms_plugin_t *p, const char *path, int len, int base);
typedef int (*lms_plugin_finish_fn_t)(lms_plugin_t *p, struct lms_context *ctxt);
struct lms_plugin {
- const char *name;
- lms_plugin_match_fn_t match;
- lms_plugin_parse_fn_t parse;
- lms_plugin_close_fn_t close;
- lms_plugin_setup_fn_t setup;
- lms_plugin_start_fn_t start;
- lms_plugin_finish_fn_t finish;
+ const char *name; /**< plugin name */
+ lms_plugin_match_fn_t match; /**< check match */
+ lms_plugin_parse_fn_t parse; /**< parse matched file */
+ lms_plugin_close_fn_t close; /**< close plugin */
+ lms_plugin_setup_fn_t setup; /**< setup (1st phase init) */
+ lms_plugin_start_fn_t start; /**< start (2nd phase init) */
+ lms_plugin_finish_fn_t finish; /**< finish plugin */
};
#ifdef __cplusplus
return r;
}
+/**
+ * Process the given directory.
+ *
+ * This will add or update media found in the given directory or its children.
+ *
+ * @param lms previously allocated Light Media Scanner instance.
+ * @param top_path top directory to scan.
+ *
+ * @return On success 0 is returned.
+ */
int
lms_process(lms_t *lms, const char *top_path)
{
#include <ctype.h>
#include <alloca.h>
+/**
+ * Strips string, in place.
+ *
+ * @param str string to be stripped.
+ * @param p_len string length to analyse, also the place where the final size
+ * is stored.
+ */
void
lms_strstrip(char *str, unsigned int *p_len)
{
*str = *p;
}
+/**
+ * Find out which of the given extensions matches the given name.
+ *
+ * @param name string to analyse.
+ * @param name_len string length.
+ * @param exts array of extensions to be checked.
+ * @param exts_len number of items in array @p exts
+ *
+ * @return index in @p exts or -1 if it doesn't match none.
+ */
int
lms_which_extension(const char *name, unsigned int name_len, const struct lms_string_size *exts, unsigned int exts_len) {
int i;