src/sticker.h

   1 /*
   2  * Copyright (C) 2003-2010 The Music Player Daemon Project
   3  * http://www.musicpd.org
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  18  */
  19
  20 /*
  21  * This is the sticker database library.  It is the backend of all the
  22  * sticker code in MPD.
  23  *
  24  * "Stickers" are pieces of information attached to existing MPD
  25  * objects (e.g. song files, directories, albums).  Clients can create
  26  * arbitrary name/value pairs.  MPD itself does not assume any special
  27  * meaning in them.
  28  *
  29  * The goal is to allow clients to share additional (possibly dynamic)
  30  * information about songs, which is neither stored on the client (not
  31  * available to other clients), nor stored in the song files (MPD has
  32  * no write access).
  33  *
  34  * Client developers should create a standard for common sticker
  35  * names, to ensure interoperability.
  36  *
  37  * Examples: song ratings; statistics; deferred tag writes; lyrics;
  38  * ...
  39  *
  40  */
  41
  42 #ifndef STICKER_H
  43 #define STICKER_H
  44
  45 #include <glib.h>
  46
  47 #include <stdbool.h>
  48
  49 struct sticker;
  50
  51 /**
  52  * Opens the sticker database (if path is not NULL).
  53  *
  54  * @param error_r location to store the error occuring, or NULL to
  55  * ignore errors
  56  * @return true on success, false on error
  57  */
  58 bool
  59 sticker_global_init(const char *path, GError **error_r);
  60
  61 /**
  62  * Close the sticker database.
  63  */
  64 void
  65 sticker_global_finish(void);
  66
  67 /**
  68  * Returns true if the sticker database is configured and available.
  69  */
  70 bool
  71 sticker_enabled(void);
  72
  73 /**
  74  * Returns one value from an object's sticker record.  The caller must
  75  * free the return value with g_free().
  76  */
  77 char *
  78 sticker_load_value(const char *type, const char *uri, const char *name);
  79
  80 /**
  81  * Sets a sticker value in the specified object.  Overwrites existing
  82  * values.
  83  */
  84 bool
  85 sticker_store_value(const char *type, const char *uri,
  86                     const char *name, const char *value);
  87
  88 /**
  89  * Deletes a sticker from the database.  All sticker values of the
  90  * specified object are deleted.
  91  */
  92 bool
  93 sticker_delete(const char *type, const char *uri);
  94
  95 /**
  96  * Deletes a sticker value.  Fails if no sticker with this name
  97  * exists.
  98  */
  99 bool
 100 sticker_delete_value(const char *type, const char *uri, const char *name);
 101
 102 /**
 103  * Frees resources held by the sticker object.
 104  *
 105  * @param sticker the sticker object to be freed
 106  */
 107 void
 108 sticker_free(struct sticker *sticker);
 109
 110 /**
 111  * Determines a single value in a sticker.
 112  *
 113  * @param sticker the sticker object
 114  * @param name the name of the sticker
 115  * @return the sticker value, or NULL if none was found
 116  */
 117 const char *
 118 sticker_get_value(const struct sticker *sticker, const char *name);
 119
 120 /**
 121  * Iterates over all sticker items in a sticker.
 122  *
 123  * @param sticker the sticker object
 124  * @param func a callback function
 125  * @param user_data an opaque pointer for the callback function
 126  */
 127 void
 128 sticker_foreach(const struct sticker *sticker,
 129                 void (*func)(const char *name, const char *value,
 130                              gpointer user_data),
 131                 gpointer user_data);
 132
 133 /**
 134  * Loads the sticker for the specified resource.
 135  *
 136  * @param type the resource type, e.g. "song"
 137  * @param uri the URI of the resource, e.g. the song path
 138  * @return a sticker object, or NULL on error or if there is no sticker
 139  */
 140 struct sticker *
 141 sticker_load(const char *type, const char *uri);
 142
 143 /**
 144  * Finds stickers with the specified name below the specified URI.
 145  *
 146  * @param type the resource type, e.g. "song"
 147  * @param base_uri the URI prefix of the resources, or NULL if all
 148  * resources should be searched
 149  * @param name the name of the sticker
 150  * @return true on success (even if no sticker was found), false on
 151  * failure
 152  */
 153 bool
 154 sticker_find(const char *type, const char *base_uri, const char *name,
 155              void (*func)(const char *uri, const char *value,
 156                           gpointer user_data),
 157              gpointer user_data);
 158
 159 #endif