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