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
|
/*
* Copyright (C) 2003-2009 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).
*/
void
sticker_global_init(const char *path);
/**
* Close the sticker database.
*/
void
sticker_global_finish(void);
/**
* Returns true if the sticker database is configured and available.
*/
bool
sticker_enabled(void);
/**
* Populates a GHashTable with GStrings of sticker keys and values
* from an object's sticker record. The caller must free the returned
* GHashTable with g_hash_list_destroy().
*/
GHashTable *
sticker_list_values(const char *type, const char *uri);
/**
* 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);
/**
* 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(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(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);
#endif
|
