2 * This file is part of DisOrder.
3 * Copyright (C) 2010 Richard Kettlewell
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.
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.
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/>.
18 #ifndef CLIENT_STUBS_H
19 #define CLIENT_STUBS_H
21 /** @brief Adopt a track
23 * Makes the calling user owner of a randomly picked track.
26 * @return 0 on success, non-0 on error
28 int disorder_adopt(disorder_client
*c
, const char *id
);
30 /** @brief Create a user
32 * Create a new user. Requires the 'admin' right. Email addresses etc must be filled in in separate commands.
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
39 int disorder_adduser(disorder_client
*c
, const char *user
, const char *password
, const char *rights
);
41 /** @brief Confirm registration
43 * The confirmation string must have been created with 'register'. The username is returned so the caller knows who they are.
45 * @param confirmation Confirmation string
46 * @return 0 on success, non-0 on error
48 int disorder_confirm(disorder_client
*c
, const char *confirmation
);
49 /** @brief Log in with a cookie
51 * The cookie must have been created with 'make-cookie'. The username is returned so the caller knows who they are.
53 * @param cookie Cookie string
54 * @return 0 on success, non-0 on error
56 int disorder_cookie(disorder_client
*c
, const char *cookie
);
57 /** @brief Delete user
59 * Requires the 'admin' right.
61 * @param user User to delete
62 * @return 0 on success, non-0 on error
64 int disorder_deluser(disorder_client
*c
, const char *user
);
66 /** @brief Disable play
68 * Play will stop at the end of the current track, if one is playing. Requires the 'global prefs' right.
70 * @return 0 on success, non-0 on error
72 int disorder_disable(disorder_client
*c
);
74 /** @brief Set a user property
76 * With the 'admin' right you can do anything. Otherwise you need the 'userinfo' right and can only set 'email' and 'password'.
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
83 int disorder_edituser(disorder_client
*c
, const char *username
, const char *property
, const char *value
);
85 /** @brief Enable play
87 * Requires the 'global prefs' right.
89 * @return 0 on success, non-0 on error
91 int disorder_enable(disorder_client
*c
);
93 /** @brief Detect whether play is enabled
97 * @param enabledp 1 if play is enabled and 0 otherwise
98 * @return 0 on success, non-0 on error
100 int disorder_enabled(disorder_client
*c
, int *enabledp
);
102 /** @brief Test whether a track exists
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
110 int disorder_exists(disorder_client
*c
, const char *track
, int *existsp
);
112 /** @brief Get a track preference
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.
116 * @param track Track name
117 * @param pref Preference name
118 * @param valuep Preference value
119 * @return 0 on success, non-0 on error
121 int disorder_get(disorder_client
*c
, const char *track
, const char *pref
, char **valuep
);
123 /** @brief Get a global preference
125 * If the preference does exist not then a null value is returned.
127 * @param pref Global preference name
128 * @param valuep Preference value
129 * @return 0 on success, non-0 on error
131 int disorder_get_global(disorder_client
*c
, const char *pref
, char **valuep
);
133 /** @brief Create a login cookie for this user
135 * The cookie may be redeemed via the 'cookie' command
137 * @param cookiep Newly created cookie
138 * @return 0 on success, non-0 on error
140 int disorder_make_cookie(disorder_client
*c
, char **cookiep
);
142 /** @brief Do nothing
144 * Used as a keepalive. No authentication required.
146 * @return 0 on success, non-0 on error
148 int disorder_nop(disorder_client
*c
);
150 /** @brief Get a track name part
152 * If the name part cannot be constructed an empty string is returned.
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
160 int disorder_part(disorder_client
*c
, const char *track
, const char *context
, const char *part
, char **partp
);
162 /** @brief Pause the currently playing track
164 * Requires the 'pause' right.
166 * @return 0 on success, non-0 on error
168 int disorder_pause(disorder_client
*c
);
170 /** @brief Delete a playlist
172 * Requires the 'play' right and permission to modify the playlist.
174 * @param playlist Playlist to delete
175 * @return 0 on success, non-0 on error
177 int disorder_playlist_delete(disorder_client
*c
, const char *playlist
);
179 /** @brief Lock a playlist
181 * Requires the 'play' right and permission to modify the playlist. A given connection may lock at most one playlist.
183 * @param playlist Playlist to delete
184 * @return 0 on success, non-0 on error
186 int disorder_playlist_lock(disorder_client
*c
, const char *playlist
);
188 /** @brief Get a playlist's sharing status
190 * Requires the 'read' right and permission to read the playlist.
192 * @param playlist Playlist to read
193 * @param sharep Sharing status ("public", "private" or "shared")
194 * @return 0 on success, non-0 on error
196 int disorder_playlist_get_share(disorder_client
*c
, const char *playlist
, char **sharep
);
198 /** @brief Set a playlist's sharing status
200 * Requires the 'play' right and permission to modify the playlist.
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
206 int disorder_playlist_set_share(disorder_client
*c
, const char *playlist
, const char *share
);
208 /** @brief Unlock the locked playlist playlist
210 * The playlist to unlock is implicit in the connection.
212 * @return 0 on success, non-0 on error
214 int disorder_playlist_unlock(disorder_client
*c
);
216 /** @brief Disable random play
218 * Requires the 'global prefs' right.
220 * @return 0 on success, non-0 on error
222 int disorder_random_disable(disorder_client
*c
);
224 /** @brief Enable random play
226 * Requires the 'global prefs' right.
228 * @return 0 on success, non-0 on error
230 int disorder_random_enable(disorder_client
*c
);
232 /** @brief Detect whether random play is enabled
234 * Random play counts as enabled even if play is disabled.
236 * @param enabledp 1 if random play is enabled and 0 otherwise
237 * @return 0 on success, non-0 on error
239 int disorder_random_enabled(disorder_client
*c
, int *enabledp
);
241 /** @brief Re-read configuraiton file.
243 * Requires the 'admin' right.
245 * @return 0 on success, non-0 on error
247 int disorder_reconfigure(disorder_client
*c
);
249 /** @brief Register a new user
251 * Requires the 'register' right which is usually only available to the 'guest' user. Redeem the confirmation string via 'confirm' to complete registration.
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
259 int disorder_register(disorder_client
*c
, const char *username
, const char *password
, const char *email
, char **confirmationp
);
261 /** @brief Send a password reminder.
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.
265 * @param username User to remind
266 * @return 0 on success, non-0 on error
268 int disorder_reminder(disorder_client
*c
, const char *username
);
270 /** @brief Remove a track form the queue.
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.
275 * @return 0 on success, non-0 on error
277 int disorder_remove(disorder_client
*c
, const char *id
);
279 /** @brief Rescan all collections for new or obsolete tracks.
281 * Requires the 'rescan' right.
283 * @return 0 on success, non-0 on error
285 int disorder_rescan(disorder_client
*c
);
287 /** @brief Resolve a track name
289 * Converts aliases to non-alias track names
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
295 int disorder_resolve(disorder_client
*c
, const char *track
, char **resolvedp
);
297 /** @brief Resume the currently playing track
299 * Requires the 'pause' right.
301 * @return 0 on success, non-0 on error
303 int disorder_resume(disorder_client
*c
);
305 /** @brief Revoke a cookie.
307 * It will not subsequently be possible to log in with the cookie.
309 * @return 0 on success, non-0 on error
311 int disorder_revoke(disorder_client
*c
);
313 /** @brief Terminate the playing track.
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.
317 * @param id Track ID (optional)
318 * @return 0 on success, non-0 on error
320 int disorder_scratch(disorder_client
*c
, const char *id
);
322 /** @brief Delete a scheduled event.
324 * Users can always delete their own scheduled events; with the admin right you can delete any event.
326 * @param event ID of event to delete
327 * @return 0 on success, non-0 on error
329 int disorder_schedule_del(disorder_client
*c
, const char *event
);
331 /** @brief Set a track preference
333 * Requires the 'prefs' right.
335 * @param track Track name
336 * @param pref Preference name
337 * @param value New value
338 * @return 0 on success, non-0 on error
340 int disorder_set(disorder_client
*c
, const char *track
, const char *pref
, const char *value
);
342 /** @brief Set a global preference
344 * Requires the 'global prefs' right.
346 * @param pref Preference name
347 * @param value New value
348 * @return 0 on success, non-0 on error
350 int disorder_set_global(disorder_client
*c
, const char *pref
, const char *value
);
352 /** @brief Unset a track preference
354 * Requires the 'prefs' right.
356 * @param track Track name
357 * @param pref Preference name
358 * @return 0 on success, non-0 on error
360 int disorder_unset(disorder_client
*c
, const char *track
, const char *pref
);
362 /** @brief Set a global preference
364 * Requires the 'global prefs' right.
366 * @param pref Preference name
367 * @return 0 on success, non-0 on error
369 int disorder_unset_global(disorder_client
*c
, const char *pref
);
371 /** @brief Get a user property.
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.
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
380 int disorder_userinfo(disorder_client
*c
, const char *username
, const char *property
, char **valuep
);
382 /** @brief Get the server version
386 * @param versionp Server version string
387 * @return 0 on success, non-0 on error
389 int disorder_version(disorder_client
*c
, char **versionp
);