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