This repository has been archived by the owner on May 2, 2023. It is now read-only.
forked from akezeke/spotyxbmc
-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathapi.h
executable file
·2285 lines (2001 loc) · 73.4 KB
/
api.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/*
* Copyright (c) 2006-2010 Spotify Ltd
*
* The terms of use for this and related files can be read in
* the associated LICENSE file, usually stored in share/doc/libspotify/LICENSE.
*/
/**
* @file api.h Public API for libspotify
*
* @note All input strings are expected to be in UTF-8
* @note All output strings are in UTF-8.
*
* @note All usernames are valid XMPP nodeprep identifiers:
* http://tools.ietf.org/html/rfc3920#appendix-A
* If you need to store user data, we strongly advise you
* to use the canonical form of the username.
*/
#ifndef PUBLIC_API_H
#define PUBLIC_API_H
#ifdef __cplusplus
extern "C" {
#endif
#ifndef SP_CALLCONV
#ifdef _WIN32
#define SP_CALLCONV __stdcall
#else
#define SP_CALLCONV
#endif
#endif
#ifndef SP_LIBEXPORT
#ifdef _WIN32
#define SP_LIBEXPORT(x) x __stdcall
#else
#define SP_LIBEXPORT(x) x
#endif
#endif
/* Includes */
#include <stddef.h>
/* General types */
#if !defined(__cplusplus) && !defined(__bool_true_false_are_defined)
typedef unsigned char bool;
#endif
typedef unsigned char s_byte;
/**
* @defgroup types Spotify types & structs
*
* @{
*/
typedef struct sp_session sp_session; ///< Representation of a session
typedef struct sp_track sp_track; ///< A track handle
typedef struct sp_album sp_album; ///< An album handle
typedef struct sp_artist sp_artist; ///< An artist handle
typedef struct sp_artistbrowse sp_artistbrowse; ///< A handle to an artist browse result
typedef struct sp_albumbrowse sp_albumbrowse; ///< A handle to an album browse result
typedef struct sp_toplistbrowse sp_toplistbrowse; ///< A handle to a toplist browse result
typedef struct sp_search sp_search; ///< A handle to a search result
typedef struct sp_link sp_link; ///< A handle to the libspotify internal representation of a URI
typedef struct sp_image sp_image; ///< A handle to an image
typedef struct sp_user sp_user; ///< A handle to a user
typedef struct sp_playlist sp_playlist; ///< A playlist handle
typedef struct sp_playlistcontainer sp_playlistcontainer; ///< A playlist container (playlist containing other playlists) handle
/** @} */
/**
* @defgroup error Error Handling
*
* All functions in libspotify use the same set of error codes. Most of them return
* an error code, and let the result of the operation be stored in an out-parameter.
*
* @{
*/
/**
* Error codes returned by various functions
*/
typedef enum sp_error {
SP_ERROR_OK = 0, ///< No errors encountered
SP_ERROR_BAD_API_VERSION = 1, ///< The library version targeted does not match the one you claim you support
SP_ERROR_API_INITIALIZATION_FAILED = 2, ///< Initialization of library failed - are cache locations etc. valid?
SP_ERROR_TRACK_NOT_PLAYABLE = 3, ///< The track specified for playing cannot be played
SP_ERROR_RESOURCE_NOT_LOADED = 4, ///< One or several of the supplied resources is not yet loaded
SP_ERROR_BAD_APPLICATION_KEY = 5, ///< The application key is invalid
SP_ERROR_BAD_USERNAME_OR_PASSWORD = 6, ///< Login failed because of bad username and/or password
SP_ERROR_USER_BANNED = 7, ///< The specified username is banned
SP_ERROR_UNABLE_TO_CONTACT_SERVER = 8, ///< Cannot connect to the Spotify backend system
SP_ERROR_CLIENT_TOO_OLD = 9, ///< Client is too old, library will need to be updated
SP_ERROR_OTHER_PERMANENT = 10, ///< Some other error occured, and it is permanent (e.g. trying to relogin will not help)
SP_ERROR_BAD_USER_AGENT = 11, ///< The user agent string is invalid or too long
SP_ERROR_MISSING_CALLBACK = 12, ///< No valid callback registered to handle events
SP_ERROR_INVALID_INDATA = 13, ///< Input data was either missing or invalid
SP_ERROR_INDEX_OUT_OF_RANGE = 14, ///< Index out of range
SP_ERROR_USER_NEEDS_PREMIUM = 15, ///< The specified user needs a premium account
SP_ERROR_OTHER_TRANSIENT = 16, ///< A transient error occured.
SP_ERROR_IS_LOADING = 17, ///< The resource is currently loading
SP_ERROR_NO_STREAM_AVAILABLE = 18, ///< Could not find any suitable stream to play
} sp_error;
/**
* Convert a numeric libspotify error code to a text string
*
* @param[in] error The error code to lookup
*/
SP_LIBEXPORT(const char*) sp_error_message(sp_error error);
/** @} */
/**
* @defgroup session Session handling
*
* The concept of a session is fundamental for all communication with the Spotify ecosystem - it is the
* object responsible for communicating with the Spotify service. You will need to instantiate a
* session that then can be used to request artist information, perform searches etc.
*
* @{
*/
/**
* Current version of the application interface, that is, the API described by this file.
*
* This value should be set in the sp_session_config struct passed to sp_session_init().
*
* If an (upgraded) library is no longer compatible with this version the error #SP_ERROR_BAD_API_VERSION will be
* returned from sp_session_init(). Future versions of the library will provide you with some kind of mechanism
* to request an updated version of the library.
*/
#define SPOTIFY_API_VERSION 4
/**
* Describes the current state of the connection
*/
typedef enum sp_connectionstate {
SP_CONNECTION_STATE_LOGGED_OUT = 0, ///< User not yet logged in
SP_CONNECTION_STATE_LOGGED_IN = 1, ///< Logged in against a Spotify access point
SP_CONNECTION_STATE_DISCONNECTED = 2, ///< Was logged in, but has now been disconnected
SP_CONNECTION_STATE_UNDEFINED = 3, ///< The connection state is undefined
} sp_connectionstate;
/**
* Sample type descriptor
*/
typedef enum sp_sampletype {
SP_SAMPLETYPE_INT16_NATIVE_ENDIAN = 0, ///< 16-bit signed integer samples
} sp_sampletype;
/**
* Audio format descriptor
*/
typedef struct sp_audioformat {
sp_sampletype sample_type; ///< Sample type enum,
int sample_rate; ///< Audio sample rate, in samples per second.
int channels; ///< Number of channels. Currently 1 or 2.
} sp_audioformat;
/**
* Bitrate definitions for music streaming
*/
typedef enum sp_bitrate {
SP_BITRATE_160k = 0,
SP_BITRATE_320k = 1,
} sp_bitrate;
/**
* Session callbacks
*
* Registered when you create a session.
* If some callbacks should not be of interest, set them to NULL.
*/
typedef struct sp_session_callbacks {
/**
* Called when login has been processed and was successful
*
* @param[in] session Session
* @param[in] error Error code ::sp_error
*/
void (SP_CALLCONV *logged_in)(sp_session *session, sp_error error);
/**
* Called when logout has been processed. Either called explicitly
* if you initialize a logout operation, or implicitly if there
* is a permanent connection error
*
* @param[in] session Session
*/
void (SP_CALLCONV *logged_out)(sp_session *session);
/**
* Called whenever metadata has been updated
*
* If you have metadata cached outside of libspotify, you should purge
* your caches and fetch new versions.
*
* @param[in] session Session
*/
void (SP_CALLCONV *metadata_updated)(sp_session *session);
/**
* Called when there is a connection error, and the library has problems
* reconnecting to the Spotify service. Could be called multiple times (as
* long as the problem is present)
*
*
* @param[in] session Session
* @param[in] error Status code ::sp_error
*/
void (SP_CALLCONV *connection_error)(sp_session *session, sp_error error);
/**
* Called when the access point wants to display a message to the user
*
* In the desktop client, these are shown in a blueish toolbar just below the
* search box.
*
* @param[in] session Session
* @param[in] message String in UTF-8 format.
*/
void (SP_CALLCONV *message_to_user)(sp_session *session, const char *message);
/**
* Called when processing needs to take place on the main thread.
*
* You need to call sp_session_process_events() in the main thread to get
* libspotify to do more work. Failure to do so may cause request timeouts,
* or a lost connection.
*
* @param[in] session Session
*
* @note This function is called from an internal session thread - you need to have proper synchronization!
*/
void (SP_CALLCONV *notify_main_thread)(sp_session *session);
/**
* Called when there is decompressed audio data available.
*
* @param[in] session Session
* @param[in] format Audio format descriptor sp_audioformat
* @param[in] frames Points to raw PCM data as described by \p format
* @param[in] num_frames Number of available samples in \p frames.
* If this is 0, a discontinuity has occured (such as after a seek). The application
* should flush its audio fifos, etc.
*
* @return Number of frames consumed.
* This value can be used to rate limit the output from the library if your
* output buffers are saturated. The library will retry delivery in about 100ms.
*
* @note This function is called from an internal session thread - you need to have proper synchronization!
*
* @note This function must never block. If your output buffers are full you must return 0 to signal
* that the library should retry delivery in a short while.
*/
int (SP_CALLCONV *music_delivery)(sp_session *session, const sp_audioformat *format, const void *frames, int num_frames);
/**
* Music has been paused because only one account may play music at the same time.
*
* @param[in] session Session
*/
void (SP_CALLCONV *play_token_lost)(sp_session *session);
/**
* Logging callback.
*
* @param[in] session Session
* @param[in] data Log data
*/
void (SP_CALLCONV *log_message)(sp_session *session, const char *data);
/**
* End of track.
* Called when the currently played track has reached its end.
*
* @note This function is invoked from the same internal thread
* as the music delivery callback
*
* @param[in] session Session
*/
void (SP_CALLCONV *end_of_track)(sp_session *session);
/**
* Streaming error.
* Called when streaming cannot start or continue
*
* @note This function is invoked from the main thread
*
* @param[in] session Session
* @param[in] errro Error code describing the error
*/
void (SP_CALLCONV *streaming_error)(sp_session *session, sp_error error);
/**
* Called whenever user info has been updated
*
* libspotify will try to resolve the canonical username into displayable usernames
* as soon as a sp_user object is created.
*
* @param[in] session Session
*/
void (SP_CALLCONV *userinfo_updated)(sp_session *session);
} sp_session_callbacks;
/**
* Session config
*/
typedef struct sp_session_config {
int api_version; ///< The version of the Spotify API your application is compiled with. Set to #SPOTIFY_API_VERSION
const char *cache_location; ///< The location where Spotify will write cache files
const char *settings_location; ///< The location where Spotify will write settings files
const void *application_key; ///< Your application key
size_t application_key_size; ///< The size of the application key in bytes
const char *user_agent; ///< "User-Agent" for your application - max 255 characters long
const sp_session_callbacks *callbacks; ///< Delivery callbacks for session events, or NULL if you are not interested in any callbacks (not recommended!)
void *userdata; ///< User supplied data for your application
} sp_session_config;
/**
* Initialize a session. The session returned will be initialized, but you will need
* to log in before you can perform any other operation
*
* In the future, this will be renamed to sp_session_create() and will have a
* corresponding sp_session_release() function.
*
* Here is a snippet from \c spshell.c:
* @dontinclude spshell.c
* @skip config.api_version
* @until }
*
* @param[in] config The configuration to use for the session
* @param[out] sess If successful, a new session - otherwise NULL
*
* @return Error code ::sp_error
*/
SP_LIBEXPORT(sp_error) sp_session_init(const sp_session_config *config, sp_session **sess);
/**
* Logs in the specified username/password combo. This initiates the download in the background.
* A callback is called when login is complete
*
* Here is a snippet from \c spshell.c:
* @dontinclude spshell.c
* @skip sp_session_login
* @until }
*
* @param[in] session Your session object
* @param[in] username The username to log in
* @param[in] password The password for the specified username
*
* @return Result of the operation
*/
SP_LIBEXPORT(sp_error) sp_session_login(sp_session *session, const char *username, const char *password);
/**
* Fetches the currently logged in user
*
* @param[in] session Your session object
*
* @return The logged in user (or NULL if not logged in)
*/
SP_LIBEXPORT(sp_user *) sp_session_user(sp_session *session);
/**
* Logs out the currently logged in user
*
* Always call this before terminating the application and libspotify is currently
* logged in. Otherwise, the settings and cache may be lost.
*
* @param[in] session Your session object
*
* @return Result of the operation
*/
SP_LIBEXPORT(sp_error) sp_session_logout(sp_session *session);
/**
* The connection state of the specified session.
*
* @param[in] session Your session object
*
* @return The connection state - see the sp_connectionstate enum for possible values
*/
SP_LIBEXPORT(sp_connectionstate) sp_session_connectionstate(sp_session *session);
/**
* The userdata associated with the session
*
* @param[in] session Your session object
*
* @return The userdata that was passed in on session creation
*/
SP_LIBEXPORT(void *) sp_session_userdata(sp_session *session);
/**
* Make the specified session process any pending events
*
* @param[in] session Your session object
* @param[out] next_timeout Stores the time (in milliseconds) until you should call this function again
*/
SP_LIBEXPORT(void) sp_session_process_events(sp_session *session, int *next_timeout);
/**
* Loads the specified track
*
* After successfully loading the track, you have the option of running
* sp_session_player_play() directly, or using sp_session_player_seek() first.
* When this call returns, the track will have been loaded, unless an error occurred.
*
* @param[in] session Your session object
* @param[in] track The track to be loaded
*
* @return The result of the operation - see the ::sp_error enum for possible values
*/
SP_LIBEXPORT(sp_error) sp_session_player_load(sp_session *session, sp_track *track);
/**
* Seek to position in the currently loaded track
*
* @param[in] session Your session object
* @param[in] offset Track position, in milliseconds.
*
* @return The result of the operation - see the ::sp_error enum for possible values
*/
SP_LIBEXPORT(sp_error) sp_session_player_seek(sp_session *session, int offset);
/**
* Play or pause the currently loaded track
*
* @param[in] session Your session object
* @param[in] play If set to true, playback will occur. If set to false, the playback will be paused.
*
* @return The result of the operation - see the ::sp_error enum for possible values
*/
SP_LIBEXPORT(sp_error) sp_session_player_play(sp_session *session, bool play);
/**
* Stops the currently playing track
*
* This frees some resources held by libspotify to identify the currently
* playing track.
*
* @param[in] session Your session object
*
*/
SP_LIBEXPORT(void) sp_session_player_unload(sp_session *session);
/**
* Returns the playlist container for the currently logged in user.
*
* @param[in] session Your session object
*
* @return Playlist container object, NULL if not logged in
*/
SP_LIBEXPORT(sp_playlistcontainer *) sp_session_playlistcontainer(sp_session *session);
/**
* Returns the starred list for currently logged in user
*
* @param[in] session Session object
*
* @return A playlist.
* @note You need to release the playlist when you are done with it.
* @see sp_playlist_release()
*/
SP_LIBEXPORT(sp_playlist *) sp_session_starred_create(sp_session *session);
/**
* Set preferred bitrate for music streaming
*
* @param[in] session Session object
* @param[in] bitrate Preferred bitrate, see ::sp_bitrate for possible values
*
*/
SP_LIBEXPORT(void) sp_session_preferred_bitrate(sp_session *session, sp_bitrate bitrate);
/** @} */
/**
* @defgroup link Links (Spotify URIs)
*
* These functions handle links to Spotify entities in a way that allows you to
* not care about the textual representation of the link.
* @{
*/
/**
* Link types
*/
typedef enum {
SP_LINKTYPE_INVALID = 0, ///< Link type not valid - default until the library has parsed the link, or when parsing failed
SP_LINKTYPE_TRACK = 1, ///< Link type is track
SP_LINKTYPE_ALBUM = 2, ///< Link type is album
SP_LINKTYPE_ARTIST = 3, ///< Link type is artist
SP_LINKTYPE_SEARCH = 4, ///< Link type is search
SP_LINKTYPE_PLAYLIST = 5, ///< Link type is playlist
} sp_linktype;
/**
* Create a Spotify link given a string
*
* @param[in] link A string representation of a Spotify link
*
* @return A link representation of the given string representation.
* If the link could not be parsed, this function returns NULL.
*
* @note You need to release the link when you are done with it.
* @see sp_link_type()
* @see sp_link_release()
*/
SP_LIBEXPORT(sp_link *) sp_link_create_from_string(const char *link);
/**
* Generates a link object from a track
*
* @param[in] track A track object
* @param[in] offset Offset in track in ms.
*
* @return A link representing the track
*
* @note You need to release the link when you are done with it.
* @see sp_link_release()
*/
SP_LIBEXPORT(sp_link *) sp_link_create_from_track(sp_track *track, int offset);
/**
* Create a link object from an album
*
* @param[in] album An album object
*
* @return A link representing the album
*
* @note You need to release the link when you are done with it.
* @see sp_link_release()
*/
SP_LIBEXPORT(sp_link *) sp_link_create_from_album(sp_album *album);
/**
* Creates a link object from an artist
*
* @param[in] artist An artist object
*
* @return A link object representing the artist
*
* @note You need to release the link when you are done with it.
* @see sp_link_release()
*/
SP_LIBEXPORT(sp_link *) sp_link_create_from_artist(sp_artist *artist);
/**
* Generate a link object representing the current search
*
* @param[in] search Search object
*
* @return A link representing the search
*
* @note You need to release the link when you are done with it.
* @see sp_link_release()
*/
SP_LIBEXPORT(sp_link *) sp_link_create_from_search(sp_search *search);
/**
* Create a link object representing the given playlist
*
* @param[in] playlist Playlist object
*
* @return A link representing the playlist
*
* @note You need to release the link when you are done with it.
* @see sp_link_release()
*/
SP_LIBEXPORT(sp_link *) sp_link_create_from_playlist(sp_playlist *playlist);
/**
* Create a string representation of the given Spotify link
*
* @param[in] link The Spotify link whose string representation you are interested in
* @param[out] buffer The buffer to hold the string representation of link
* @param[in] buffer_size The max size of the buffer that will hold the string representation
* The resulting string is guaranteed to always be null terminated if
* buffer_size > 0
*
* @return The number of characters in the string representation of the link. If this
* value is greater or equal than \p buffer_size, output was truncated.
*/
SP_LIBEXPORT(int) sp_link_as_string(sp_link *link, char *buffer, int buffer_size);
/**
* The link type of the specified link
*
* @param[in] link The Spotify link whose type you are interested in
*
* @return The link type of the specified link - see the sp_linktype enum for possible values
*/
SP_LIBEXPORT(sp_linktype) sp_link_type(sp_link *link);
/**
* The track representation for the given link
*
* @param[in] link The Spotify link whose track you are interested in
*
* @return The track representation of the given track link
* If the link is not of track type then NULL is returned.
*/
SP_LIBEXPORT(sp_track *) sp_link_as_track(sp_link *link);
/**
* The track and offset into track representation for the given link
*
* @param[in] link The Spotify link whose track you are interested in
* @param[out] offset Pointer to offset into track (in seconds). If the link
* does not contain an offset this will be set to 0.
*
* @return The track representation of the given track link
* If the link is not of track type then NULL is returned.
*/
SP_LIBEXPORT(sp_track *) sp_link_as_track_and_offset(sp_link *link, int *offset);
/**
* The album representation for the given link
*
* @param[in] link The Spotify link whose album you are interested in
*
* @return The album representation of the given album link
* If the link is not of album type then NULL is returned
*/
SP_LIBEXPORT(sp_album *) sp_link_as_album(sp_link *link);
/**
* The artist representation for the given link
*
* @param[in] link The Spotify link whose artist you are interested in
*
* @return The artist representation of the given link
* If the link is not of artist type then NULL is returned
*/
SP_LIBEXPORT(sp_artist *) sp_link_as_artist(sp_link *link);
/**
* Increase the reference count of a link
*
* @param[in] link The link object
*/
SP_LIBEXPORT(void) sp_link_add_ref(sp_link *link);
/**
* Decrease the reference count of a link
*
* @param[in] link The link object
*/
SP_LIBEXPORT(void) sp_link_release(sp_link *link);
/** @} */
/**
* @defgroup track Track subsystem
* @{
*/
/**
* Get load status for the specified track. If the track is not loaded yet,
* all other functions operating on the track return default values.
*
* @param[in] track The track whose load status you are interested in
*
* @return True if track is loaded, otherwise false
*/
SP_LIBEXPORT(bool) sp_track_is_loaded(sp_track *track);
/**
* Return an error code associated with a track. For example if it could not load
*
* @param[in] track The track
*
* @return Error code
*/
SP_LIBEXPORT(sp_error) sp_track_error(sp_track *track);
/**
* Return true if the track is available for playback.
*
* @param[in] track The track
*
* @return True if track is available for playback, otherwise false.
*
* @note The track must be loaded or this function will always return false.
* @see sp_track_is_loaded()
*/
SP_LIBEXPORT(bool) sp_track_is_available(sp_track *track);
/**
* Return true if the track is starred by the currently logged in user.
*
* @param[in] track The track
*
* @return True if track is starred.
*
* @note The track must be loaded or this function will always return false.
* @see sp_track_is_loaded()
*/
SP_LIBEXPORT(bool) sp_track_is_starred(sp_track *track);
/**
* Star/Unstar the specified track
*
* @param[in] session Session
* @param[in] tracks Array of pointer to tracks.
* @param[in] num_tracks Length of \p tracks array
* @param[in] star Starred status of the track
*
*/
SP_LIBEXPORT(void) sp_track_set_starred(sp_session *session, const sp_track **tracks, int num_tracks, bool star);
/**
* The number of artists performing on the specified track
*
* @param[in] track The track whose number of participating artists you are interested in
*
* @return The number of artists performing on the specified track.
* If no metadata is available for the track yet, this function returns 0.
*/
SP_LIBEXPORT(int) sp_track_num_artists(sp_track *track);
/**
* The artist matching the specified index performing on the current track.
*
* @param[in] track The track whose participating artist you are interested in
* @param[in] index The index for the participating artist. Should be in the interval [0, sp_track_num_artists() - 1]
*
* @return The participating artist, or NULL if invalid index
*/
SP_LIBEXPORT(sp_artist *) sp_track_artist(sp_track *track, int index);
/**
* The album of the specified track
*
* @param[in] track A track object
*
* @return The album of the given track. You need to increase the refcount
* if you want to keep the pointer around.
* If no metadata is available for the track yet, this function returns 0.
*/
SP_LIBEXPORT(sp_album *) sp_track_album(sp_track *track);
/**
* The string representation of the specified track's name
*
* @param[in] track A track object
*
* @return The string representation of the specified track's name.
* Returned string is valid as long as the album object stays allocated
* and no longer than the next call to sp_session_process_events()
* If no metadata is available for the track yet, this function returns empty string.
*/
SP_LIBEXPORT(const char *) sp_track_name(sp_track *track);
/**
* The duration, in milliseconds, of the specified track
*
* @param[in] track A track object
*
* @return The duration of the specified track, in milliseconds
* If no metadata is available for the track yet, this function returns 0.
*/
SP_LIBEXPORT(int) sp_track_duration(sp_track *track);
/**
* Returns popularity for track
*
* @param[in] track A track object
*
* @return Popularity in range 0 to 100, 0 if undefined
* If no metadata is available for the track yet, this function returns 0.
*/
SP_LIBEXPORT(int) sp_track_popularity(sp_track *track);
/**
* Returns the disc number for a track
*
* @param[in] track A track object
*
* @return Disc index. Possible values are [1, total number of discs on album]
* This function returns valid data only for tracks appearing in a browse
* artist or browse album result (otherwise returns 0).
*/
SP_LIBEXPORT(int) sp_track_disc(sp_track *track);
/**
* Returns the position of a track on its disc
*
* @param[in] track A track object
*
* @return Track position, starts at 1 (relative the corresponding disc)
* This function returns valid data only for tracks appearing in a browse
* artist or browse album result (otherwise returns 0).
*/
SP_LIBEXPORT(int) sp_track_index(sp_track *track);
/**
* Increase the reference count of a track
*
* @param[in] track The track object
*/
SP_LIBEXPORT(void) sp_track_add_ref(sp_track *track);
/**
* Decrease the reference count of a track
*
* @param[in] track The track object
*/
SP_LIBEXPORT(void) sp_track_release(sp_track *track);
/** @} */
/**
* @defgroup album Album subsystem
* @{
*/
/**
* Album types
*/
typedef enum {
SP_ALBUMTYPE_ALBUM = 0, ///< Normal album
SP_ALBUMTYPE_SINGLE = 1, ///< Single
SP_ALBUMTYPE_COMPILATION = 2, ///< Compilation
SP_ALBUMTYPE_UNKNOWN = 3, ///< Unknown type
} sp_albumtype;
/**
* Check if the album object is populated with data
*
* @param[in] album Album object
* @return True if metadata is present, false if not
*/
SP_LIBEXPORT(bool) sp_album_is_loaded(sp_album *album);
/**
* Return true if the album is available in the current region.
*
* @param[in] album The album
*
* @return True if album is available for playback, otherwise false.
*
* @note The album must be loaded or this function will always return false.
* @see sp_album_is_loaded()
*/
SP_LIBEXPORT(bool) sp_album_is_available(sp_album *album);
/**
* Get the artist associated with the given album
*
* @param[in] album Album object
* @return A reference to the artist. NULL if the metadata has not been loaded yet
*/
SP_LIBEXPORT(sp_artist *) sp_album_artist(sp_album *album);
/**
* Return image ID representing the album's coverart.
*
* @param[in] album Album object
*
* @return ID byte sequence that can be passed to sp_image_create()
* If the album has no image or the metadata for the album is not
* loaded yet, this function returns NULL.
*
* @see sp_image_create
*/
SP_LIBEXPORT(const s_byte *) sp_album_cover(sp_album *album);
/**
* Return name of album
*
* @param[in] album Album object
*
* @return Name of album.
* Returned string is valid as long as the album object stays allocated
* and no longer than the next call to sp_session_process_events()
*/
SP_LIBEXPORT(const char *) sp_album_name(sp_album *album);
/**
* Return release year of specified album
*
* @param[in] album Album object
*
* @return Release year
*/
SP_LIBEXPORT(int) sp_album_year(sp_album *album);
/**
* Return type of specified album
*
* @param[in] album Album object
*
* @return sp_albumtype
*/
SP_LIBEXPORT(sp_albumtype) sp_album_type(sp_album *album);
/**
* Increase the reference count of an album
*
* @param[in] album The album object
*/
SP_LIBEXPORT(void) sp_album_add_ref(sp_album *album);
/**
* Decrease the reference count of an album
*
* @param[in] album The album object
*/
SP_LIBEXPORT(void) sp_album_release(sp_album *album);
/** @} */
/**
* @defgroup artist Artist subsystem
* @{
*/
/**
* Return name of artist
*
* @param[in] artist Artist object
*
* @return Name of artist.
* Returned string is valid as long as the artist object stays allocated
* and no longer than the next call to sp_session_process_events()
*/
SP_LIBEXPORT(const char *) sp_artist_name(sp_artist *artist);
/**
* Check if the artist object is populated with data
*
* @param[in] artist An artist object
*
* @return True if metadata is present, false if not
*
*/
SP_LIBEXPORT(bool) sp_artist_is_loaded(sp_artist *artist);
/**
* Increase the reference count of a artist
*
* @param[in] artist The artist object
*/
SP_LIBEXPORT(void) sp_artist_add_ref(sp_artist *artist);
/**
* Decrease the reference count of a artist
*
* @param[in] artist The artist object
*/
SP_LIBEXPORT(void) sp_artist_release(sp_artist *artist);
/** @} */
/**
* @defgroup albumbrowse Album browsing
*
* Browsing adds additional information to what an ::sp_album holds. It retrieves
* copyrights, reviews and tracks of the album.
*
* @{
*/
/**
* The type of a callback used in sp_albumbrowse_create()
*
* When the callback is called, the metadata of all tracks belonging to it will have
* been loaded, so sp_track_is_loaded() will return non-zero. The ::sp_artist of the
* album will also have been fully loaded.
*
* @param[in] result The same pointer returned by sp_albumbrowse_create()