chiark - git - mdw - disorder/blob - lib/client-stubs.h

   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 List files and directories in a directory
  42  *
  43  * See 'files' and 'dirs' for more specific lists.
  44  *
  45  * @param dir Directory to list (optional)
  46  * @param re Regexp that results must match (optional)
  47  * @param filesp List of matching files and directories
  48  * @param nfilesp Number of elements in filesp
  49  * @return 0 on success, non-0 on error
  50  */
  51 int disorder_allfiles(disorder_client *c, const char *dir, const char *re, char ***filesp, int *nfilesp);
  52
  53 /** @brief Confirm registration
  54  *
  55  * The confirmation string must have been created with 'register'.  The username is returned so the caller knows who they are.
  56  *
  57  * @param confirmation Confirmation string
  58  * @return 0 on success, non-0 on error
  59  */
  60 int disorder_confirm(disorder_client *c, const char *confirmation);
  61 /** @brief Log in with a cookie
  62  *
  63  * The cookie must have been created with 'make-cookie'.  The username is returned so the caller knows who they are.
  64  *
  65  * @param cookie Cookie string
  66  * @return 0 on success, non-0 on error
  67  */
  68 int disorder_cookie(disorder_client *c, const char *cookie);
  69 /** @brief Delete user
  70  *
  71  * Requires the 'admin' right.
  72  *
  73  * @param user User to delete
  74  * @return 0 on success, non-0 on error
  75  */
  76 int disorder_deluser(disorder_client *c, const char *user);
  77
  78 /** @brief List directories in a directory
  79  *
  80  *
  81  *
  82  * @param dir Directory to list (optional)
  83  * @param re Regexp that results must match (optional)
  84  * @param filesp List of matching directories
  85  * @param nfilesp Number of elements in filesp
  86  * @return 0 on success, non-0 on error
  87  */
  88 int disorder_dirs(disorder_client *c, const char *dir, const char *re, char ***filesp, int *nfilesp);
  89
  90 /** @brief Disable play
  91  *
  92  * Play will stop at the end of the current track, if one is playing.  Requires the 'global prefs' right.
  93  *
  94  * @return 0 on success, non-0 on error
  95  */
  96 int disorder_disable(disorder_client *c);
  97
  98 /** @brief Set a user property
  99  *
 100  * With the 'admin' right you can do anything.  Otherwise you need the 'userinfo' right and can only set 'email' and 'password'.
 101  *
 102  * @param username User to modify
 103  * @param property Property name
 104  * @param value New property value
 105  * @return 0 on success, non-0 on error
 106  */
 107 int disorder_edituser(disorder_client *c, const char *username, const char *property, const char *value);
 108
 109 /** @brief Enable play
 110  *
 111  * Requires the 'global prefs' right.
 112  *
 113  * @return 0 on success, non-0 on error
 114  */
 115 int disorder_enable(disorder_client *c);
 116
 117 /** @brief Detect whether play is enabled
 118  *
 119  *
 120  *
 121  * @param enabledp 1 if play is enabled and 0 otherwise
 122  * @return 0 on success, non-0 on error
 123  */
 124 int disorder_enabled(disorder_client *c, int *enabledp);
 125
 126 /** @brief Test whether a track exists
 127  *
 128  *
 129  *
 130  * @param track Track name
 131  * @param existsp 1 if the track exists and 0 otherwise
 132  * @return 0 on success, non-0 on error
 133  */
 134 int disorder_exists(disorder_client *c, const char *track, int *existsp);
 135
 136 /** @brief List files in a directory
 137  *
 138  *
 139  *
 140  * @param dir Directory to list (optional)
 141  * @param re Regexp that results must match (optional)
 142  * @param filesp List of matching files
 143  * @param nfilesp Number of elements in filesp
 144  * @return 0 on success, non-0 on error
 145  */
 146 int disorder_files(disorder_client *c, const char *dir, const char *re, char ***filesp, int *nfilesp);
 147
 148 /** @brief Get a track preference
 149  *
 150  * 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.
 151  *
 152  * @param track Track name
 153  * @param pref Preference name
 154  * @param valuep Preference value
 155  * @return 0 on success, non-0 on error
 156  */
 157 int disorder_get(disorder_client *c, const char *track, const char *pref, char **valuep);
 158
 159 /** @brief Get a global preference
 160  *
 161  * If the preference does exist not then a null value is returned.
 162  *
 163  * @param pref Global preference name
 164  * @param valuep Preference value
 165  * @return 0 on success, non-0 on error
 166  */
 167 int disorder_get_global(disorder_client *c, const char *pref, char **valuep);
 168
 169 /** @brief Get a track's length
 170  *
 171  * If the track does not exist an error is returned.
 172  *
 173  * @param track Track name
 174  * @param lengthp Track length in seconds
 175  * @return 0 on success, non-0 on error
 176  */
 177 int disorder_length(disorder_client *c, const char *track, long *lengthp);
 178
 179 /** @brief Create a login cookie for this user
 180  *
 181  * The cookie may be redeemed via the 'cookie' command
 182  *
 183  * @param cookiep Newly created cookie
 184  * @return 0 on success, non-0 on error
 185  */
 186 int disorder_make_cookie(disorder_client *c, char **cookiep);
 187
 188 /** @brief Do nothing
 189  *
 190  * Used as a keepalive.  No authentication required.
 191  *
 192  * @return 0 on success, non-0 on error
 193  */
 194 int disorder_nop(disorder_client *c);
 195
 196 /** @brief Get a track name part
 197  *
 198  * If the name part cannot be constructed an empty string is returned.
 199  *
 200  * @param track Track name
 201  * @param context Context ("sort" or "display")
 202  * @param part Name part ("artist", "album" or "title")
 203  * @param partp Value of name part
 204  * @return 0 on success, non-0 on error
 205  */
 206 int disorder_part(disorder_client *c, const char *track, const char *context, const char *part, char **partp);
 207
 208 /** @brief Pause the currently playing track
 209  *
 210  * Requires the 'pause' right.
 211  *
 212  * @return 0 on success, non-0 on error
 213  */
 214 int disorder_pause(disorder_client *c);
 215
 216 /** @brief Play a track
 217  *
 218  * Requires the 'play' right.
 219  *
 220  * @param track Track to play
 221  * @param idp Queue ID of new track
 222  * @return 0 on success, non-0 on error
 223  */
 224 int disorder_play(disorder_client *c, const char *track, char **idp);
 225
 226 /** @brief Delete a playlist
 227  *
 228  * Requires the 'play' right and permission to modify the playlist.
 229  *
 230  * @param playlist Playlist to delete
 231  * @return 0 on success, non-0 on error
 232  */
 233 int disorder_playlist_delete(disorder_client *c, const char *playlist);
 234
 235 /** @brief List the contents of a playlist
 236  *
 237  * Requires the 'read' right and oermission to read the playlist.
 238  *
 239  * @param playlist Playlist name
 240  * @param tracksp List of tracks in playlist
 241  * @param ntracksp Number of elements in tracksp
 242  * @return 0 on success, non-0 on error
 243  */
 244 int disorder_playlist_get(disorder_client *c, const char *playlist, char ***tracksp, int *ntracksp);
 245
 246 /** @brief Get a playlist's sharing status
 247  *
 248  * Requires the 'read' right and permission to read the playlist.
 249  *
 250  * @param playlist Playlist to read
 251  * @param sharep Sharing status ("public", "private" or "shared")
 252  * @return 0 on success, non-0 on error
 253  */
 254 int disorder_playlist_get_share(disorder_client *c, const char *playlist, char **sharep);
 255
 256 /** @brief Lock a playlist
 257  *
 258  * Requires the 'play' right and permission to modify the playlist.  A given connection may lock at most one playlist.
 259  *
 260  * @param playlist Playlist to delete
 261  * @return 0 on success, non-0 on error
 262  */
 263 int disorder_playlist_lock(disorder_client *c, const char *playlist);
 264
 265 /** @brief Set a playlist's sharing status
 266  *
 267  * Requires the 'play' right and permission to modify the playlist.
 268  *
 269  * @param playlist Playlist to modify
 270  * @param share New sharing status ("public", "private" or "shared")
 271  * @return 0 on success, non-0 on error
 272  */
 273 int disorder_playlist_set_share(disorder_client *c, const char *playlist, const char *share);
 274
 275 /** @brief Unlock the locked playlist playlist
 276  *
 277  * The playlist to unlock is implicit in the connection.
 278  *
 279  * @return 0 on success, non-0 on error
 280  */
 281 int disorder_playlist_unlock(disorder_client *c);
 282
 283 /** @brief List playlists
 284  *
 285  * Requires the 'read' right.  Only playlists that you have permission to read are returned.
 286  *
 287  * @param playlistsp Playlist names
 288  * @param nplaylistsp Number of elements in playlistsp
 289  * @return 0 on success, non-0 on error
 290  */
 291 int disorder_playlists(disorder_client *c, char ***playlistsp, int *nplaylistsp);
 292
 293 /** @brief Disable random play
 294  *
 295  * Requires the 'global prefs' right.
 296  *
 297  * @return 0 on success, non-0 on error
 298  */
 299 int disorder_random_disable(disorder_client *c);
 300
 301 /** @brief Enable random play
 302  *
 303  * Requires the 'global prefs' right.
 304  *
 305  * @return 0 on success, non-0 on error
 306  */
 307 int disorder_random_enable(disorder_client *c);
 308
 309 /** @brief Detect whether random play is enabled
 310  *
 311  * Random play counts as enabled even if play is disabled.
 312  *
 313  * @param enabledp 1 if random play is enabled and 0 otherwise
 314  * @return 0 on success, non-0 on error
 315  */
 316 int disorder_random_enabled(disorder_client *c, int *enabledp);
 317
 318 /** @brief Re-read configuraiton file.
 319  *
 320  * Requires the 'admin' right.
 321  *
 322  * @return 0 on success, non-0 on error
 323  */
 324 int disorder_reconfigure(disorder_client *c);
 325
 326 /** @brief Register a new user
 327  *
 328  * Requires the 'register' right which is usually only available to the 'guest' user.  Redeem the confirmation string via 'confirm' to complete registration.
 329  *
 330  * @param username Requested new username
 331  * @param password Requested initial password
 332  * @param email New user's email address
 333  * @param confirmationp Confirmation string
 334  * @return 0 on success, non-0 on error
 335  */
 336 int disorder_register(disorder_client *c, const char *username, const char *password, const char *email, char **confirmationp);
 337
 338 /** @brief Send a password reminder.
 339  *
 340  * 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.
 341  *
 342  * @param username User to remind
 343  * @return 0 on success, non-0 on error
 344  */
 345 int disorder_reminder(disorder_client *c, const char *username);
 346
 347 /** @brief Remove a track form the queue.
 348  *
 349  * Requires one of the 'remove mine', 'remove random' or 'remove any' rights depending on how the track came to be added to the queue.
 350  *
 351  * @param id Track ID
 352  * @return 0 on success, non-0 on error
 353  */
 354 int disorder_remove(disorder_client *c, const char *id);
 355
 356 /** @brief Rescan all collections for new or obsolete tracks.
 357  *
 358  * Requires the 'rescan' right.
 359  *
 360  * @return 0 on success, non-0 on error
 361  */
 362 int disorder_rescan(disorder_client *c);
 363
 364 /** @brief Resolve a track name
 365  *
 366  * Converts aliases to non-alias track names
 367  *
 368  * @param track Track name (might be an alias)
 369  * @param resolvedp Resolve track name (definitely not an alias)
 370  * @return 0 on success, non-0 on error
 371  */
 372 int disorder_resolve(disorder_client *c, const char *track, char **resolvedp);
 373
 374 /** @brief Resume the currently playing track
 375  *
 376  * Requires the 'pause' right.
 377  *
 378  * @return 0 on success, non-0 on error
 379  */
 380 int disorder_resume(disorder_client *c);
 381
 382 /** @brief Revoke a cookie.
 383  *
 384  * It will not subsequently be possible to log in with the cookie.
 385  *
 386  * @return 0 on success, non-0 on error
 387  */
 388 int disorder_revoke(disorder_client *c);
 389
 390 /** @brief Terminate the playing track.
 391  *
 392  * Requires one of the 'scratch mine', 'scratch random' or 'scratch any' rights depending on how the track came to be added to the queue.
 393  *
 394  * @param id Track ID (optional)
 395  * @return 0 on success, non-0 on error
 396  */
 397 int disorder_scratch(disorder_client *c, const char *id);
 398
 399 /** @brief Delete a scheduled event.
 400  *
 401  * Users can always delete their own scheduled events; with the admin right you can delete any event.
 402  *
 403  * @param event ID of event to delete
 404  * @return 0 on success, non-0 on error
 405  */
 406 int disorder_schedule_del(disorder_client *c, const char *event);
 407
 408 /** @brief List scheduled events
 409  *
 410  * This just lists IDs.  Use 'schedule-get' to retrieve more detail
 411  *
 412  * @param idsp List of event IDs
 413  * @param nidsp Number of elements in idsp
 414  * @return 0 on success, non-0 on error
 415  */
 416 int disorder_schedule_list(disorder_client *c, char ***idsp, int *nidsp);
 417
 418 /** @brief Search for tracks
 419  *
 420  * Terms are either keywords or tags formatted as 'tag:TAG-NAME'.
 421  *
 422  * @param terms List of search terms
 423  * @param tracksp List of matching tracks
 424  * @param ntracksp Number of elements in tracksp
 425  * @return 0 on success, non-0 on error
 426  */
 427 int disorder_search(disorder_client *c, const char *terms, char ***tracksp, int *ntracksp);
 428
 429 /** @brief Set a track preference
 430  *
 431  * Requires the 'prefs' right.
 432  *
 433  * @param track Track name
 434  * @param pref Preference name
 435  * @param value New value
 436  * @return 0 on success, non-0 on error
 437  */
 438 int disorder_set(disorder_client *c, const char *track, const char *pref, const char *value);
 439
 440 /** @brief Set a global preference
 441  *
 442  * Requires the 'global prefs' right.
 443  *
 444  * @param pref Preference name
 445  * @param value New value
 446  * @return 0 on success, non-0 on error
 447  */
 448 int disorder_set_global(disorder_client *c, const char *pref, const char *value);
 449
 450 /** @brief Request server shutdown
 451  *
 452  * Requires the 'admin' right.
 453  *
 454  * @return 0 on success, non-0 on error
 455  */
 456 int disorder_shutdown(disorder_client *c);
 457
 458 /** @brief Get server statistics
 459  *
 460  * The details of what the server reports are not really defined.  The returned strings are intended to be printed out one to a line..
 461  *
 462  * @param statsp List of server information strings.
 463  * @param nstatsp Number of elements in statsp
 464  * @return 0 on success, non-0 on error
 465  */
 466 int disorder_stats(disorder_client *c, char ***statsp, int *nstatsp);
 467
 468 /** @brief Get a list of known tags
 469  *
 470  * Only tags which apply to at least one track are returned.
 471  *
 472  * @param tagsp List of tags
 473  * @param ntagsp Number of elements in tagsp
 474  * @return 0 on success, non-0 on error
 475  */
 476 int disorder_tags(disorder_client *c, char ***tagsp, int *ntagsp);
 477
 478 /** @brief Unset a track preference
 479  *
 480  * Requires the 'prefs' right.
 481  *
 482  * @param track Track name
 483  * @param pref Preference name
 484  * @return 0 on success, non-0 on error
 485  */
 486 int disorder_unset(disorder_client *c, const char *track, const char *pref);
 487
 488 /** @brief Set a global preference
 489  *
 490  * Requires the 'global prefs' right.
 491  *
 492  * @param pref Preference name
 493  * @return 0 on success, non-0 on error
 494  */
 495 int disorder_unset_global(disorder_client *c, const char *pref);
 496
 497 /** @brief Get a user property.
 498  *
 499  * 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.
 500  *
 501  * @param username User to read
 502  * @param property Property to read
 503  * @param valuep Value of property
 504  * @return 0 on success, non-0 on error
 505  */
 506 int disorder_userinfo(disorder_client *c, const char *username, const char *property, char **valuep);
 507
 508 /** @brief Get a list of users
 509  *
 510  *
 511  *
 512  * @param usersp List of users
 513  * @param nusersp Number of elements in usersp
 514  * @return 0 on success, non-0 on error
 515  */
 516 int disorder_users(disorder_client *c, char ***usersp, int *nusersp);
 517
 518 /** @brief Get the server version
 519  *
 520  *
 521  *
 522  * @param versionp Server version string
 523  * @return 0 on success, non-0 on error
 524  */
 525 int disorder_version(disorder_client *c, char **versionp);
 526
 527 #endif