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