Commit | Line | Data |
---|---|---|
7788b7c7 RK |
1 | /* |
2 | * This file is part of DisOrder. | |
3 | * Copyright (C) 2010 Richard Kettlewell | |
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 3 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 | |
16 | * along with this program. If not, see <http://www.gnu.org/licenses/>. | |
17 | */ | |
18 | #ifndef CLIENT_STUBS_H | |
19 | #define CLIENT_STUBS_H | |
20 | ||
21 | /** @brief Adopt a track | |
22 | * | |
23 | * Makes the calling user owner of a randomly picked track. | |
24 | * | |
25 | * @param id Track ID | |
26 | * @return 0 on success, non-0 on error | |
27 | */ | |
28 | int disorder_adopt(disorder_client *c, const char *id); | |
29 | ||
30 | /** @brief Create a user | |
31 | * | |
32 | * Create a new user. Requires the 'admin' right. Email addresses etc must be filled in in separate commands. | |
33 | * | |
34 | * @param user New username | |
35 | * @param password Initial password | |
36 | * @param rights Initial rights (optional) | |
37 | * @return 0 on success, non-0 on error | |
38 | */ | |
39 | int disorder_adduser(disorder_client *c, const char *user, const char *password, const char *rights); | |
40 | ||
41 | /** @brief Confirm registration | |
42 | * | |
43 | * The confirmation string must have been created with 'register'. The username is returned so the caller knows who they are. | |
44 | * | |
45 | * @param confirmation Confirmation string | |
46 | * @return 0 on success, non-0 on error | |
47 | */ | |
48 | int disorder_confirm(disorder_client *c, const char *confirmation); | |
49 | /** @brief Log in with a cookie | |
50 | * | |
51 | * The cookie must have been created with 'make-cookie'. The username is returned so the caller knows who they are. | |
52 | * | |
53 | * @param cookie Cookie string | |
54 | * @return 0 on success, non-0 on error | |
55 | */ | |
56 | int disorder_cookie(disorder_client *c, const char *cookie); | |
57 | /** @brief Delete user | |
58 | * | |
59 | * Requires the 'admin' right. | |
60 | * | |
61 | * @param user User to delete | |
62 | * @return 0 on success, non-0 on error | |
63 | */ | |
64 | int disorder_deluser(disorder_client *c, const char *user); | |
65 | ||
66 | /** @brief Disable play | |
67 | * | |
68 | * Play will stop at the end of the current track, if one is playing. Requires the 'global prefs' right. | |
69 | * | |
70 | * @return 0 on success, non-0 on error | |
71 | */ | |
72 | int disorder_disable(disorder_client *c); | |
73 | ||
74 | /** @brief Set a user property | |
75 | * | |
76 | * With the 'admin' right you can do anything. Otherwise you need the 'userinfo' right and can only set 'email' and 'password'. | |
77 | * | |
78 | * @param username User to modify | |
79 | * @param property Property name | |
80 | * @param value New property value | |
81 | * @return 0 on success, non-0 on error | |
82 | */ | |
83 | int disorder_edituser(disorder_client *c, const char *username, const char *property, const char *value); | |
84 | ||
85 | /** @brief Enable play | |
86 | * | |
87 | * Requires the 'global prefs' right. | |
88 | * | |
89 | * @return 0 on success, non-0 on error | |
90 | */ | |
91 | int disorder_enable(disorder_client *c); | |
92 | ||
93 | /** @brief Detect whether play is enabled | |
94 | * | |
95 | * | |
96 | * | |
97 | * @param enabledp 1 if play is enabled and 0 otherwise | |
98 | * @return 0 on success, non-0 on error | |
99 | */ | |
100 | int disorder_enabled(disorder_client *c, int *enabledp); | |
101 | ||
102 | /** @brief Test whether a track exists | |
103 | * | |
104 | * | |
105 | * | |
106 | * @param track Track name | |
107 | * @param existsp 1 if the track exists and 0 otherwise | |
108 | * @return 0 on success, non-0 on error | |
109 | */ | |
110 | int disorder_exists(disorder_client *c, const char *track, int *existsp); | |
111 | ||
112 | /** @brief Get a track preference | |
113 | * | |
114 | * If the track does not exist that is an error. If the track exists but the preference does not then a null value is returned. | |
115 | * | |
116 | * @param track Track name | |
117 | * @param pref Preference name | |
118 | * @param valuep Preference value | |
119 | * @return 0 on success, non-0 on error | |
120 | */ | |
121 | int disorder_get(disorder_client *c, const char *track, const char *pref, char **valuep); | |
122 | ||
123 | /** @brief Get a global preference | |
124 | * | |
125 | * If the preference does exist not then a null value is returned. | |
126 | * | |
127 | * @param pref Global preference name | |
128 | * @param valuep Preference value | |
129 | * @return 0 on success, non-0 on error | |
130 | */ | |
131 | int disorder_get_global(disorder_client *c, const char *pref, char **valuep); | |
132 | ||
133 | /** @brief Create a login cookie for this user | |
134 | * | |
135 | * The cookie may be redeemed via the 'cookie' command | |
136 | * | |
137 | * @param cookiep Newly created cookie | |
138 | * @return 0 on success, non-0 on error | |
139 | */ | |
140 | int disorder_make_cookie(disorder_client *c, char **cookiep); | |
141 | ||
142 | /** @brief Do nothing | |
143 | * | |
144 | * Used as a keepalive. No authentication required. | |
145 | * | |
146 | * @return 0 on success, non-0 on error | |
147 | */ | |
148 | int disorder_nop(disorder_client *c); | |
149 | ||
150 | /** @brief Get a track name part | |
151 | * | |
152 | * If the name part cannot be constructed an empty string is returned. | |
153 | * | |
154 | * @param track Track name | |
155 | * @param context Context ("sort" or "display") | |
156 | * @param part Name part ("artist", "album" or "title") | |
157 | * @param partp Value of name part | |
158 | * @return 0 on success, non-0 on error | |
159 | */ | |
160 | int disorder_part(disorder_client *c, const char *track, const char *context, const char *part, char **partp); | |
161 | ||
162 | /** @brief Pause the currently playing track | |
163 | * | |
164 | * Requires the 'pause' right. | |
165 | * | |
166 | * @return 0 on success, non-0 on error | |
167 | */ | |
168 | int disorder_pause(disorder_client *c); | |
169 | ||
170 | /** @brief Delete a playlist | |
171 | * | |
172 | * Requires the 'play' right and permission to modify the playlist. | |
173 | * | |
174 | * @param playlist Playlist to delete | |
175 | * @return 0 on success, non-0 on error | |
176 | */ | |
177 | int disorder_playlist_delete(disorder_client *c, const char *playlist); | |
178 | ||
179 | /** @brief Lock a playlist | |
180 | * | |
181 | * Requires the 'play' right and permission to modify the playlist. A given connection may lock at most one playlist. | |
182 | * | |
183 | * @param playlist Playlist to delete | |
184 | * @return 0 on success, non-0 on error | |
185 | */ | |
186 | int disorder_playlist_lock(disorder_client *c, const char *playlist); | |
187 | ||
188 | /** @brief Get a playlist's sharing status | |
189 | * | |
190 | * Requires the 'read' right and permission to read the playlist. | |
191 | * | |
192 | * @param playlist Playlist to read | |
193 | * @param sharep Sharing status ("public", "private" or "shared") | |
194 | * @return 0 on success, non-0 on error | |
195 | */ | |
196 | int disorder_playlist_get_share(disorder_client *c, const char *playlist, char **sharep); | |
197 | ||
198 | /** @brief Set a playlist's sharing status | |
199 | * | |
200 | * Requires the 'play' right and permission to modify the playlist. | |
201 | * | |
202 | * @param playlist Playlist to modify | |
203 | * @param share New sharing status ("public", "private" or "shared") | |
204 | * @return 0 on success, non-0 on error | |
205 | */ | |
206 | int disorder_playlist_set_share(disorder_client *c, const char *playlist, const char *share); | |
207 | ||
208 | /** @brief Unlock the locked playlist playlist | |
209 | * | |
210 | * The playlist to unlock is implicit in the connection. | |
211 | * | |
212 | * @return 0 on success, non-0 on error | |
213 | */ | |
214 | int disorder_playlist_unlock(disorder_client *c); | |
215 | ||
216 | /** @brief Disable random play | |
217 | * | |
218 | * Requires the 'global prefs' right. | |
219 | * | |
220 | * @return 0 on success, non-0 on error | |
221 | */ | |
222 | int disorder_random_disable(disorder_client *c); | |
223 | ||
224 | /** @brief Enable random play | |
225 | * | |
226 | * Requires the 'global prefs' right. | |
227 | * | |
228 | * @return 0 on success, non-0 on error | |
229 | */ | |
230 | int disorder_random_enable(disorder_client *c); | |
231 | ||
232 | /** @brief Detect whether random play is enabled | |
233 | * | |
234 | * Random play counts as enabled even if play is disabled. | |
235 | * | |
236 | * @param enabledp 1 if random play is enabled and 0 otherwise | |
237 | * @return 0 on success, non-0 on error | |
238 | */ | |
239 | int disorder_random_enabled(disorder_client *c, int *enabledp); | |
240 | ||
241 | /** @brief Re-read configuraiton file. | |
242 | * | |
243 | * Requires the 'admin' right. | |
244 | * | |
245 | * @return 0 on success, non-0 on error | |
246 | */ | |
247 | int disorder_reconfigure(disorder_client *c); | |
248 | ||
249 | /** @brief Register a new user | |
250 | * | |
251 | * Requires the 'register' right which is usually only available to the 'guest' user. Redeem the confirmation string via 'confirm' to complete registration. | |
252 | * | |
253 | * @param username Requested new username | |
254 | * @param password Requested initial password | |
255 | * @param email New user's email address | |
256 | * @param confirmationp Confirmation string | |
257 | * @return 0 on success, non-0 on error | |
258 | */ | |
259 | int disorder_register(disorder_client *c, const char *username, const char *password, const char *email, char **confirmationp); | |
260 | ||
261 | /** @brief Send a password reminder. | |
262 | * | |
263 | * If the user has no valid email address, or no password, or a reminder has been sent too recently, then no reminder will be sent. | |
264 | * | |
265 | * @param username User to remind | |
266 | * @return 0 on success, non-0 on error | |
267 | */ | |
268 | int disorder_reminder(disorder_client *c, const char *username); | |
269 | ||
270 | /** @brief Remove a track form the queue. | |
271 | * | |
272 | * Requires one of the 'remove mine', 'remove random' or 'remove any' rights depending on how the track came to be added to the queue. | |
273 | * | |
274 | * @param id Track ID | |
275 | * @return 0 on success, non-0 on error | |
276 | */ | |
277 | int disorder_remove(disorder_client *c, const char *id); | |
278 | ||
279 | /** @brief Rescan all collections for new or obsolete tracks. | |
280 | * | |
281 | * Requires the 'rescan' right. | |
282 | * | |
283 | * @return 0 on success, non-0 on error | |
284 | */ | |
285 | int disorder_rescan(disorder_client *c); | |
286 | ||
287 | /** @brief Resolve a track name | |
288 | * | |
289 | * Converts aliases to non-alias track names | |
290 | * | |
291 | * @param track Track name (might be an alias) | |
292 | * @param resolvedp Resolve track name (definitely not an alias) | |
293 | * @return 0 on success, non-0 on error | |
294 | */ | |
295 | int disorder_resolve(disorder_client *c, const char *track, char **resolvedp); | |
296 | ||
297 | /** @brief Resume the currently playing track | |
298 | * | |
299 | * Requires the 'pause' right. | |
300 | * | |
301 | * @return 0 on success, non-0 on error | |
302 | */ | |
303 | int disorder_resume(disorder_client *c); | |
304 | ||
305 | /** @brief Revoke a cookie. | |
306 | * | |
307 | * It will not subsequently be possible to log in with the cookie. | |
308 | * | |
309 | * @return 0 on success, non-0 on error | |
310 | */ | |
311 | int disorder_revoke(disorder_client *c); | |
312 | ||
313 | /** @brief Terminate the playing track. | |
314 | * | |
315 | * Requires one of the 'scratch mine', 'scratch random' or 'scratch any' rights depending on how the track came to be added to the queue. | |
316 | * | |
317 | * @param id Track ID (optional) | |
318 | * @return 0 on success, non-0 on error | |
319 | */ | |
320 | int disorder_scratch(disorder_client *c, const char *id); | |
321 | ||
322 | /** @brief Delete a scheduled event. | |
323 | * | |
324 | * Users can always delete their own scheduled events; with the admin right you can delete any event. | |
325 | * | |
326 | * @param event ID of event to delete | |
327 | * @return 0 on success, non-0 on error | |
328 | */ | |
329 | int disorder_schedule_del(disorder_client *c, const char *event); | |
330 | ||
331 | /** @brief Set a track preference | |
332 | * | |
333 | * Requires the 'prefs' right. | |
334 | * | |
335 | * @param track Track name | |
336 | * @param pref Preference name | |
337 | * @param value New value | |
338 | * @return 0 on success, non-0 on error | |
339 | */ | |
340 | int disorder_set(disorder_client *c, const char *track, const char *pref, const char *value); | |
341 | ||
342 | /** @brief Set a global preference | |
343 | * | |
344 | * Requires the 'global prefs' right. | |
345 | * | |
346 | * @param pref Preference name | |
347 | * @param value New value | |
348 | * @return 0 on success, non-0 on error | |
349 | */ | |
350 | int disorder_set_global(disorder_client *c, const char *pref, const char *value); | |
351 | ||
352 | /** @brief Unset a track preference | |
353 | * | |
354 | * Requires the 'prefs' right. | |
355 | * | |
356 | * @param track Track name | |
357 | * @param pref Preference name | |
358 | * @return 0 on success, non-0 on error | |
359 | */ | |
360 | int disorder_unset(disorder_client *c, const char *track, const char *pref); | |
361 | ||
362 | /** @brief Set a global preference | |
363 | * | |
364 | * Requires the 'global prefs' right. | |
365 | * | |
366 | * @param pref Preference name | |
367 | * @return 0 on success, non-0 on error | |
368 | */ | |
369 | int disorder_unset_global(disorder_client *c, const char *pref); | |
370 | ||
371 | /** @brief Get a user property. | |
372 | * | |
373 | * If the user does not exist an error is returned, if the user exists but the property does not then a null value is returned. | |
374 | * | |
375 | * @param username User to read | |
376 | * @param property Property to read | |
377 | * @param valuep Value of property | |
378 | * @return 0 on success, non-0 on error | |
379 | */ | |
380 | int disorder_userinfo(disorder_client *c, const char *username, const char *property, char **valuep); | |
381 | ||
382 | /** @brief Get the server version | |
383 | * | |
384 | * | |
385 | * | |
386 | * @param versionp Server version string | |
387 | * @return 0 on success, non-0 on error | |
388 | */ | |
389 | int disorder_version(disorder_client *c, char **versionp); | |
390 | ||
391 | #endif |