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

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