API Reference eSDK 3.201.430
Main
#include "spotify_embedded.h"
Macros and Constants
Data Structures
Data Structure | Description |
---|---|
SpPlaybackRestrictions | Playback restrictions. |
SpMetadata | Track metadata. |
SpFormat | Mapping of which media formats are supported in which DRM. |
SpZeroConfDeviceAlias | ZeroConf DeviceAlias. |
SpZeroConfVars | ZeroConf variables. |
SpSampleFormat | Sample format of the audio data. |
SpPlaybackCallbacks | Callbacks to be registered with SpRegisterPlaybackCallbacks |
SpDebugCallbacks | Callbacks to be registered with SpRegisterDebugCallbacks |
SpConnectionCallbacks | Callbacks to be registered with SpRegisterConnectionCallbacks |
SpDeviceAlias | Device alias definition. |
SpConfig | Configuration. |
SpDeviceAliasCallbacks | Callbacks to be registered with SpRegisterDeviceAliasCallbacks |
Typedefs
Typedef | Description |
---|---|
SpCallbackError | Callback for reporting errors to the application. |
SpCallbackPlaybackNotify | Callback for notifying the application about playback-related events. |
SpCallbackPlaybackSeek | Callback to notify the application of a change in the playback position. |
SpCallbackPlaybackApplyVolume | Callback to notify the application of a volume change using Spotify Connect. |
SpCallbackConnectionNotify | Callback for notifying the application about events related to the connection to Spotify |
SpCallbackConnectionNewCredentials | Callback for passing a login blob to the application. |
SpCallbackConnectionMessage | Callback for sending a message to the user. |
SpCallbackDebugMessage | Callback for sending debug messages/trace logs. |
SpCallbackSelectedDeviceAliasChanged | Callback for receiving the selected device alias from the backend. |
SpCallbackDeviceAliasesUpdateDone | Callback for knowing when the device alias list has been updated after call to SpSetDeviceAliases |
Enumerations
- SpError
- SpAPIReturnCode
- SpPlaybackBitrate
- SpPlaybackNotification
- SpConnectionNotification
- SpDeviceType
- SpMetadataTrack
- SpConnectivity
- SpContent
- SpMediaType
- SpAudioQuality
- SpDrmFormat
- SpReDeliveryMode
Functions
Function | Description |
---|---|
SpInit | Initialize the library. |
SpFree | Shut down the library. |
SpGetLibraryVersion | Retrieve a version string for the library. |
SpConnectionSetConnectivity | Set the type of network connection of the device. |
SpConnectionGetConnectivity | Get the connectivity that was set with SpConnectionSetConnectivity |
SpConnectionLoginBlob | Log in a user to Spotify using a credentials blob. |
SpConnectionLoginPassword | Log in a user to Spotify using a password. |
SpConnectionLoginOauthToken | Log in a user to Spotify using a Spotify OAuth token. |
SpConnectionLogout | Log the user out of Spotify |
SpConnectionIsLoggedIn | Is the user logged in to Spotify |
SpConnectionGetAckId | Get the last Ack ID. |
SpGetCanonicalUsername | Get the canonical username of the logged in user. |
SpSetDisplayName | Set the display name for the device or application. |
SpSetVolumeSteps | Set the volume steps the device is capable of. |
SpSetDeviceIsGroup | Control if the device represents a group. |
SpEnableConnect | Enable Connect functionality for this device. |
SpDisableConnect | Disable Connect functionality for this device. |
SpGetSelectedDeviceAlias | Return the currently selected device alias. |
SpPumpEvents | Allow the library to perform asynchronous tasks and process events. |
SpRegisterConnectionCallbacks | Register callbacks related to the connection to Spotify |
SpRegisterDebugCallbacks | Register a callback that receives debug messages/trace logs. |
SpRegisterPlaybackCallbacks | Register playback-related callbacks. |
SpGetMetadata | Retrieve metadata for a track in the current track list. |
SpGetMetadataImageURL | Return the HTTP URL to an image file from a spotify:image: URI. |
SpGetPlayerCookie | Obtain player cookie for current playback. |
SpPlaybackPlay | Start or resume playback. |
SpPlaybackPause | Pause playback. |
SpPlaybackSkipToNext | Skip playback to the next track in the track list. |
SpPlaybackSkipToPrev | Skip playback to the previous track in the track list. |
SpPlaybackSeek | Seek to a position within the current track. |
SpPlaybackSeekRelative | Seek a relative amount of time within the current track. |
SpPlaybackGetPosition | Get the current playback position within the track. |
SpPlaybackUpdateVolume | Request a change to the playback volume. |
SpPlaybackGetVolume | Get the playback volume level. |
SpPlaybackIsPlaying | Is the playback status playing or paused. |
SpPlaybackIsAdPlaying | Is the current track an Ad or not. |
SpPlaybackIsShuffled | Is “shuffle” mode enabled. |
SpPlaybackIsRepeated | Is “repeat” mode enabled. |
SpPlaybackGetRepeatMode | Which “repeat” mode is on. |
SpPlaybackIsActiveDevice | Is the device the active playback device. |
SpPlaybackEnableShuffle | Enable or disable “shuffle” mode. |
SpPlaybackEnableRepeat | Enable or disable “repeat” mode. |
SpPlaybackCycleRepeatMode | Cycle through the available repeat modes. |
SpPlaybackSetBitrate | Change the bitrate at which compressed audio data is delivered. |
SpPlaybackSetAvailableToPlay | Allow or disallow the device to start playback. |
SpPlaybackIsAvailableToPlay | Is the device available for playback. |
SpPlaybackSetDeviceInactive | Set the device inactive. |
SpPlaybackIsDeviceControllable | Is the device controllable. |
SpPlaybackSetDeviceControllable | Allow or disallow the device to be controllable. |
SpPlaybackIncreaseUnderrunCount | Increase the underrun counter of the current track. |
SpPlaybackSetBandwidthLimit | Set a limit on the download speed. |
SpPlaybackSetRedeliveryMode | Activates redelivery of audio data on play or resume playback. |
SpPlaybackIsRedeliveryModeActivated | Gets the status of redelivery mode. |
SpZeroConfGetVars | Get variables for ZeroConf, mainly the “getInfo” request. |
SpZeroConfAnnouncePause | Temporarily pause ZeroConf mDNS announcements. |
SpZeroConfAnnounceResume | Resume ZeroConf mDNS announcement after calling SpZeroConfAnnouncePause |
SpConnectionLoginZeroConf | Log in a user to Spotify using a ZeroConf credentials blob. |
SpGetBrandName | |
SpGetModelName | |
SpRegisterDeviceAliasCallbacks | Register callbacks related to device aliases. |
SpSetDeviceAliases | Update the device alias definitions. |
SpRestrictDrmMediaFormats | |
SpRestoreDrmMediaFormats |
Macros and Constants
SP_API_VERSION
#define SP_API_VERSION 77
The version of the API defined in this header file.
See also
SP_RECOMMENDED_MEMORY_BLOCK_SIZE
#define SP_RECOMMENDED_MEMORY_BLOCK_SIZE 1024 * 1024
Minimum recommended size of the buffer SpConfig::memory_block
SP_MAX_BRAND_NAME_LENGTH
#define SP_MAX_BRAND_NAME_LENGTH 32
Maximum length of the brand name string (not counting terminating NULL)
See also
SP_MAX_MODEL_NAME_LENGTH
#define SP_MAX_MODEL_NAME_LENGTH 30
Maximum length of the model name string (not counting terminating NULL)
See also
SP_MAX_PLATFORM_NAME_LENGTH
#define SP_MAX_PLATFORM_NAME_LENGTH 64
Maximum length of the platform_name string (not counting terminating NULL)
See also
SP_MAX_CLIENT_ID_LENGTH
#define SP_MAX_CLIENT_ID_LENGTH 32
Maximum length of the client id string (not counting terminating NULL)
See also
SP_MAX_OS_VERSION_LENGTH
#define SP_MAX_OS_VERSION_LENGTH 64
Maximum length of the os version string (not counting terminating NULL)
See also
SP_MAX_DISPLAY_NAME_LENGTH
#define SP_MAX_DISPLAY_NAME_LENGTH 64
Maximum length of the device display name (not counting terminating NULL)
See also
SP_MAX_UNIQUE_ID_LENGTH
#define SP_MAX_UNIQUE_ID_LENGTH 64
Maximum length of the device's unique ID (not counting terminating NULL)
See also
SP_MAX_USERNAME_LENGTH
#define SP_MAX_USERNAME_LENGTH 64
Maximum length of usernames (not counting terminating NULL)
See also
SP_MAX_DEVICE_ALIASES
#define SP_MAX_DEVICE_ALIASES 8
Maximum number of device aliases that can be configured.
See also
SP_NO_ALIAS_SELECTED
#define SP_NO_ALIAS_SELECTED -1
A value to use for alias_index when aliases are not used.
See also
SP_MAX_METADATA_NAME_LENGTH
#define SP_MAX_METADATA_NAME_LENGTH 255
Maximum length of display names in track metadata (not counting terminating NULL)
See also
Notes:
- It is possible that metadata will be truncated to less than this length. Applications requiring full length metadata should request it from the Spotify web APIs https://developer.spotify.com/documentation/web-api/
SP_MAX_METADATA_URI_LENGTH
#define SP_MAX_METADATA_URI_LENGTH 127
Maximum length of URIs in track metadata (not counting terminating NULL)
See also
SP_MAX_TRACK_UID_LENGTH
#define SP_MAX_TRACK_UID_LENGTH 64
Maximum length of Track UID in track metadata (not counting terminating NULL)
See also
SP_MAX_METADATA_IMAGE_URL_LENGTH
#define SP_MAX_METADATA_IMAGE_URL_LENGTH 255
Maximum length of URLs (not counting terminating NULL)
See also
SP_PLAYER_COOKIE_LENGTH
#define SP_PLAYER_COOKIE_LENGTH 32
Length of player cookie (not counting terminating NULL)
See also
SP_MAX_PLAYBACK_ID_LENGTH
#define SP_MAX_PLAYBACK_ID_LENGTH 32
Maximum length of Playback-Id (not counting terminating NULL)
See also
SP_MAX_PUBLIC_KEY_LENGTH
#define SP_MAX_PUBLIC_KEY_LENGTH 149
Maximum length of the public key used in ZeroConf logins (not counting terminating NULL)
See also
SP_MAX_DEVICE_ID_LENGTH
#define SP_MAX_DEVICE_ID_LENGTH 64
Maximum length of the device ID used for ZeroConf logins (not counting terminating NULL)
See also
SP_MAX_DEVICE_TYPE_LENGTH
#define SP_MAX_DEVICE_TYPE_LENGTH 15
Maximum length of the device type string (not counting terminating NULL)
See also
SP_MAX_VERSION_LENGTH
#define SP_MAX_VERSION_LENGTH 30
Maximum length of the library version string (not counting terminating NULL)
See also
SP_MAX_GROUP_STATUS_LENGTH
#define SP_MAX_GROUP_STATUS_LENGTH 15
Maximum length of the group status string (not counting terminating NULL)
See also
SP_MAX_TOKEN_TYPE_LENGTH
#define SP_MAX_TOKEN_TYPE_LENGTH 30
Maximum length of the token type used for OAuth logins (not counting terminating NULL)
See also
SP_MAX_SCOPE_LENGTH
#define SP_MAX_SCOPE_LENGTH 64
Maximum length of the scope used for OAuth login (not counting terminating NULL)
See also
SP_MAX_CLIENT_KEY_LENGTH
#define SP_MAX_CLIENT_KEY_LENGTH 511
Maximum length of the client key (not counting terminating NULL)
See also
SP_MAX_ZEROCONF_BLOB_LENGTH
#define SP_MAX_ZEROCONF_BLOB_LENGTH 2047
Maximum length of the ZeroConf blob (not counting terminating NULL)
See also
SP_MAX_LOGIN_ID_LENGTH
#define SP_MAX_LOGIN_ID_LENGTH 64
Maximum length of the login ID used for ZeroConf logins (not counting terminating NULL)
See also
SP_MAX_AVAILABILITY_LENGTH
#define SP_MAX_AVAILABILITY_LENGTH 15
Maximum length of the availability string (not counting terminating NULL)
See also
SP_MAX_PARTNER_NAME_LENGTH
#define SP_MAX_PARTNER_NAME_LENGTH 48
Maximum length of the Partner Name (TSP_PARTNER_NAME) (not counting terminating NULL) The longest partner name when this was written was "imagination_technologies_mips" at 29 characters.
SP_MAX_FILENAME_LENGTH
#define SP_MAX_FILENAME_LENGTH 63
Maximum length of filename fields (not counting terminating NULL)
SP_ZEROCONF_DISABLED
#define SP_ZEROCONF_DISABLED 0
Value for SpConfig::zeroconf_serve when disabling built-in ZeroConf stack. Complete ZeroConf stack has to run externally.
See also
SP_ZEROCONF_SERVE
#define SP_ZEROCONF_SERVE 1
Value for SpConfig::zeroconf_serve when activating complete built-in ZeroConf stack (both mDNS and http server).
See also
SP_ZEROCONF_SERVE_HTTP_ONLY
#define SP_ZEROCONF_SERVE_HTTP_ONLY 2
Value for SpConfig::zeroconf_serve when activating built-in ZeroConf http server only while running the ZeroConf mDNS server externally.
See also
SP_ZEROCONF_SERVE_MDNS_ONLY
#define SP_ZEROCONF_SERVE_MDNS_ONLY 3
Value for SpConfig::zeroconf_serve when activating built-in ZeroConf mDNS server only while running the ZeroConf http server externally.
See also
SP_SCOPE_STREAMING
#define SP_SCOPE_STREAMING "streaming"
Value for SpConfig::scope when implementing a basic streaming device.
SP_DEVICE_ALIAS_ATTRIBUTE_GROUP
#define SP_DEVICE_ALIAS_ATTRIBUTE_GROUP 1
Set this bit in the device alias attributes integer (SpDeviceAlias::attributes) to mark a device alias as representing a group.
Notes:
- SpSetDeviceIsGroup also sets group status, but only for the currently selected alias.
SP_GLOBAL_ATTRIBUTE_VOICE
#define SP_GLOBAL_ATTRIBUTE_VOICE 2
Set this bit in the global attributes integer (SpConfig::global_attributes) to mark that this device supports voice.
SP_MAX_SUPPORTED_FORMATS
#define SP_MAX_SUPPORTED_FORMATS 8
See also
SP_PLAYBACK_RESTRICTION_ALREADY_PAUSED
#define SP_PLAYBACK_RESTRICTION_ALREADY_PAUSED 1
The track is already paused.
SP_PLAYBACK_RESTRICTION_NOT_PAUSED
#define SP_PLAYBACK_RESTRICTION_NOT_PAUSED 2
The track is already playing.
SP_PLAYBACK_RESTRICTION_LICENSE_DISALLOW
#define SP_PLAYBACK_RESTRICTION_LICENSE_DISALLOW 4
Licensing rules disallow this action.
SP_PLAYBACK_RESTRICTION_AD_DISALLOW
#define SP_PLAYBACK_RESTRICTION_AD_DISALLOW 8
Action can't be performed while an ad is playing.
SP_PLAYBACK_RESTRICTION_NO_PREV_TRACK
#define SP_PLAYBACK_RESTRICTION_NO_PREV_TRACK 16
There is no track before the current one in the currently playing context.
SP_PLAYBACK_RESTRICTION_NO_NEXT_TRACK
#define SP_PLAYBACK_RESTRICTION_NO_NEXT_TRACK 32
There is no track after the current one in the currently playing context.
SP_PLAYBACK_RESTRICTION_UNKNOWN
#define SP_PLAYBACK_RESTRICTION_UNKNOWN 64
The action is restricted, but no reason is provided.
This means that eSDK has not retrieved the restrictions from the backend yet and therefore the action is not allowed right now. As soon as eSDK retrieves the information, the notification kSpPlaybackNotifyMetadataChanged will be sent, and the application can check the field again.
SP_PLAYBACK_RESTRICTION_ENDLESS_CONTEXT
#define SP_PLAYBACK_RESTRICTION_ENDLESS_CONTEXT 128
The action is restricted for context level reasons.
’
Data Structures
SpPlaybackRestrictions
Return to Main data structures
Playback restrictions.
struct SpPlaybackRestrictions {
uint32_t disallow_pausing_reasons;
uint32_t disallow_resuming_reasons;
uint32_t disallow_seeking_reasons;
uint32_t disallow_peeking_prev_reasons;
uint32_t disallow_peeking_next_reasons;
uint32_t disallow_skipping_prev_reasons;
uint32_t disallow_skipping_next_reasons;
uint32_t disallow_toggling_repeat_context_reasons;
uint32_t disallow_toggling_repeat_track_reasons;
uint32_t disallow_toggling_shuffle_reasons;
};
uint32_t | disallow_pausing_reasons | Bitfield of reasons the pause action is not allowed. |
uint32_t | disallow_resuming_reasons | Bitfield of reasons the resume action is not allowed. |
uint32_t | disallow_seeking_reasons | Bitfield of reasons seeking is not allowed. |
uint32_t | disallow_peeking_prev_reasons | Bitfield of reasons peeking on the previous track is not allowed. |
uint32_t | disallow_peeking_next_reasons | Bitfield of reasons peeking on the next track is not allowed. |
uint32_t | disallow_skipping_prev_reasons | Bitfield of reasons skipping to the previous track is not allowed. |
uint32_t | disallow_skipping_next_reasons | Bitfield of reasons skipping to the next track is not allowed. |
uint32_t | disallow_toggling_repeat_context_reasons | Bitfield of reasons setting repeat context is not allowed. |
uint32_t | disallow_toggling_repeat_track_reasons | Bitfield of reasons setting repeat track is not allowed. |
uint32_t | disallow_toggling_shuffle_reasons | Bitfield of reasons toggling shuffle is not allowed. |
SpMetadata
Return to Main data structures
Track metadata.
See also
struct SpMetadata {
char playback_source;
char playback_source_uri;
char track;
char track_uri;
char artist;
char artist_uri;
char album;
char album_uri;
char album_cover_uri;
char original_track_uri;
uint32_t duration_ms;
int32_t index;
char track_uid;
uint32_t original_index;
uint32_t bitrate;
struct SpPlaybackRestrictions playback_restrictions;
char playback_id;
enum SpContent content_type;
enum SpMediaType media_type;
enum SpAudioQuality audio_quality;
};
char | playback_source | Display name of the playback source. E.g., the name of the playlist from which playback was initiated (UTF-8-encoded) |
|
char | playback_source_uri | Spotify URI of the playback source (in the form "spotify:xxxxxx:xxxxxxx...") |
|
| |||
char | track | Display name of the track (UTF-8-encoded) |
|
char | track_uri | Spotify URI of the track (in the form "spotify:track:xxxxxxx...") |
|
| |||
char | artist | Display name of the artist of the track (UTF-8-encoded) |
|
char | artist_uri | Spotify URI of the artist of the track (in the form "spotify:artist:xxxxxxx...") |
|
| |||
char | album | Display name of the track's album (UTF-8-encoded) |
|
char | album_uri | Spotify URI of the track's album (in the form "spotify:album:xxxxxxx...") |
|
| |||
char | album_cover_uri | Spotify URI of the album's cover art image (in the form "spotify:image:xxxxxxx...") |
|
Use the function SpGetMetadataImageURL to convert this to an HTTP URL to the actual image file. | |||
char | original_track_uri | Spotify URI of the original track before relinking (in the form "spotify:track:xxxxxxx...") |
|
If the track was relinked this field would contain the Spotify URI of the original track before relinking. If track was not relinked this would be equal to the track_uri. This field is helpful to identify whether the track is already in the user collection. Notes:
| |||
uint32_t | duration_ms | Playback duration of the track in milliseconds. |
|
int32_t | index | Index of the track in the currently playing context. |
|
This is the index of the track in the currently playing context (eg. playlist, artist, radio, etc). Since the contents of the underlying context can change, the index is correct from the time when the track is loaded, but may occasionally be out of date if the context is actively changing. Notes:
| |||
char | track_uid | Track UID of the track in the currently playing context. |
|
| |||
uint32_t | original_index | Index of the track in the original (unchanged) playing context. |
|
It's not affected by shuffle logic. | |||
uint32_t | bitrate | The bitrate of the track in kbps. 0 means "unplayable". |
|
struct SpPlaybackRestrictions | playback_restrictions | Restrictions that apply to playback and transitions related to this track. |
|
Restriction reasons are provided as bitfields inside this struct. Each member of this struct represents one individual action that might be restricted, and its value is a combination of the reasons that are currently in effect. A value of zero means that the action is not currently restricted in any way. Notes:
| |||
char | playback_id | Playback-id of this playback of this specific track. |
|
Playback-id uniquely identifies a single playback of a track. If the same track exists twice in a context, each instance will have a unique playback-id. It is valid for only one playback of a track and once the track is played or skipped-over, the playback-id is no longer valid e.g if you skip a track and then come back to it using skip-prev, the playback-id changes. | |||
enum SpContent | content_type | Content type of this track. |
|
| |||
enum SpMediaType | media_type | Media type of this track. |
|
| |||
enum SpAudioQuality | audio_quality | Audio quality of this track. |
|
|
SpFormat
Return to Main data structures
Mapping of which media formats are supported in which DRM.
See also
struct SpFormat {
enum SpDrmFormat drm;
uint64_t media;
};
enum SpDrmFormat | drm | DRM format which the integration supports. |
|
uint64_t | media | Supported media formats for a DRM. |
|
Bitmask of media formats that the integration supports for this DRM format. The list of known media formats is in SpMediaFormat enumeration. Integration needs to fill this bitmask with the formats that it can decode and play. This field is used to determine which media formats will be delivered to the integration. For example, if the integration supports both Spotify ogg/vorbis and mp3, the bitmask would be: Example:
|
SpZeroConfDeviceAlias
Return to Main data structures
ZeroConf DeviceAlias.
This structure contains information about a single device alias, as returned by SpZeroConfGetVars
See also
struct SpZeroConfDeviceAlias {
uint32_t id;
int is_group;
char display_name;
};
uint32_t | id | String to be sent in the "id" field of the alias in the "getInfo" response. |
int | is_group | Boolean (0 = "false", 1 = "true") to be sent in the "isGroup" field of the alias in the "getInfo" response. |
char | display_name | String to be sent in the "name" field of the alias in the "getInfo" response. |
SpZeroConfVars
Return to Main data structures
ZeroConf variables.
This structure contains the fields that the application needs for ZeroConf, mainly what to send in the response to the "getInfo" request. See the ZeroConf manual for more information.
See also
struct SpZeroConfVars {
char public_key;
char device_id;
char remote_name;
char device_type;
char library_version;
int resolver_version;
char group_status;
int webserver_current_port;
char token_type;
char client_id;
char scope;
char availability;
uint32_t product_id;
struct SpZeroConfDeviceAlias aliases;
uint32_t alias_count;
struct SpFormat supported_drm_media_formats;
uint64_t supported_capabilities;
};
char | public_key | String to be sent in the "publicKey" field of the "getInfo" response[*]. |
char | device_id | String to be sent in the "deviceID" field of the "getInfo" response[*]. |
char | remote_name | String to be sent in the "remoteName" field of the "getInfo" response[*]. |
char | device_type | String to be sent in the "deviceType" field of the "getInfo" response[*]. |
char | library_version | String to be sent in the "libraryVersion" field of the "getInfo" response[*]. |
int | resolver_version | Integer to be sent as string in the "resolverVersion" field of the "getInfo" response[*]. |
char | group_status | String to be sent in the "groupStatus" field of the "getInfo" response[*]. |
int | webserver_current_port | Current internal ZeroConf webserver port number. To be used when running an external mDNS server together with an internal webserver. |
char | token_type | String to be sent in the "tokenType" field of the "getInfo" response[*]. |
char | client_id | String to be sent in the "clientID" field of the "getInfo" response[*]. |
char | scope | String to be sent in the "scope" field of the "getInfo" response[*]. |
char | availability | String to be sent in the "availability" field of the "getInfo" response[*]. |
uint32_t | product_id | Integer to be sent in the "productID" field of the "getInfo" response[*]. |
struct SpZeroConfDeviceAlias | aliases | Array of SpZeroConfDeviceAlias to be sent in the "aliases" field of the "getInfo" response[*]. |
uint32_t | alias_count | Number of valid items in aliases array. |
struct SpFormat | supported_drm_media_formats | Array of SpFormat to be sent in the "supported_drm_media_formats" field of the "getInfo" response[*]. |
uint64_t | supported_capabilities | Integer representing a bitmask to be sent in the "supported_capabilities" field of the "getInfo" response[*]. |
SpSampleFormat
Return to Main data structures
Sample format of the audio data.
struct SpSampleFormat {
int channels;
int sample_rate;
};
int | channels | Number of channels (1 = mono, 2 = stereo) |
int | sample_rate | Sample rate in Hz (such as 22050, 44100 or 48000) |
SpPlaybackCallbacks
Return to Main data structures
Callbacks to be registered with SpRegisterPlaybackCallbacks
Any of the pointers may be NULL. See the documentation of the callback typedefs for information about the individual callbacks.
struct SpPlaybackCallbacks {
SpCallbackPlaybackNotify on_notify;
SpCallbackPlaybackSeek on_seek;
SpCallbackPlaybackApplyVolume on_apply_volume;
};
SpCallbackPlaybackNotify | on_notify | Notification callback. |
SpCallbackPlaybackSeek | on_seek | Seek position callback. |
SpCallbackPlaybackApplyVolume | on_apply_volume | Apply volume callback. |
SpDebugCallbacks
Return to Main data structures
Callbacks to be registered with SpRegisterDebugCallbacks
Any of the pointers may be NULL. See the documentation of the callback typedefs for information about the individual callbacks.
struct SpDebugCallbacks {
SpCallbackDebugMessage on_message;
};
SpCallbackDebugMessage | on_message | Debug message callback. |
SpConnectionCallbacks
Return to Main data structures
Callbacks to be registered with SpRegisterConnectionCallbacks
Any of the pointers may be NULL. See the documentation of the callback typedefs for information about the individual callbacks.
struct SpConnectionCallbacks {
SpCallbackConnectionNotify on_notify;
SpCallbackConnectionNewCredentials on_new_credentials;
SpCallbackConnectionMessage on_message;
};
SpCallbackConnectionNotify | on_notify | Notification callback. |
SpCallbackConnectionNewCredentials | on_new_credentials | Credentials blob callback. |
SpCallbackConnectionMessage | on_message | Connection message callback. |
SpDeviceAlias
Return to Main data structures
Device alias definition.
This struct is used to define (optional) device aliases. It's a part of the SpConfig struct which will be passed to SpInit to initialize the eSDK.
struct SpDeviceAlias {
const char *display_name;
uint32_t attributes;
};
const char * | display_name | A UTF-8 encoded display name for an alias of the application/device. |
|
The string will be truncated to at most SP_MAX_DISPLAY_NAME_LENGTH bytes (depending on the UTF-8-encoded characters), not counting the terminating NULL. | |||
uint32_t | attributes | Attributes for this device alias. |
|
Attributes is an unsigned integer interpreted as a bitfield. Different attributes ar OR:ed together and stored in the integer. Example:
|
SpConfig
Return to Main data structures
Configuration.
See also
struct SpConfig {
int api_version;
void *memory_block;
uint32_t memory_block_size;
const char *unique_id;
const char *display_name;
uint32_t global_attributes;
struct SpDeviceAlias device_aliases;
const char *brand_name;
const char *brand_display_name;
const char *model_name;
const char *model_display_name;
const char *platform_name;
const char *client_id;
uint32_t product_id;
const char *scope;
const char *os_version;
enum SpDeviceType device_type;
enum SpPlaybackBitrate max_bitrate;
SpCallbackError error_callback;
void *error_callback_context;
int zeroconf_serve;
const char *host_name;
int zeroconf_port;
int zeroconf_port_range;
struct SpFormat supported_drm_media_formats;
};
int | api_version | The version of the API contained in this header file. Must be set to SP_API_VERSION. |
|
void * | memory_block | Pointer to a memory block to be used by the library. |
|
The block is suggested to be at least SP_RECOMMENDED_MEMORY_BLOCK_SIZE bytes in size. Smaller values are accepted, but may lead to degraded performance, or playback failure. | |||
uint32_t | memory_block_size | Size of the memory_block buffer in bytes. |
|
const char * | unique_id | A NULL-terminated character string that uniquely identifies the device (such as a MAC address) |
|
The string will be truncated to SP_MAX_UNIQUE_ID_LENGTH characters, not counting the terminating NULL. The library may use this to distinguish this device from other Spotify Connect-enabled devices that the users has. On any given device, the ID should not change between calls to SpInit | |||
const char * | display_name | A UTF-8-encoded display name for the application/device. |
|
When using Spotify Connect, this is the name that the Spotify app will use in the UI to refer to this instance of the application/this device. The string will be truncated to at most SP_MAX_DISPLAY_NAME_LENGTH bytes (depending on the UTF-8-encoded characters), not counting the terminating NULL. The display name can be changed later with SpSetDisplayName Notes:
| |||
uint32_t | global_attributes | The global attributes is a bitfield where each attribute is OR:ed together and stored in this integer. |
|
These attributes must be valid for each device alias. Example:
| |||
struct SpDeviceAlias | device_aliases | Device alias definitions. These are optional, if you don't want to define aliases this array must be zeroed. |
|
A user could switch between these aliases by selecting a different alias for playback through the Spotify apps (or by other means where applicable like through voice control), and let an integration perform different audio routing depending on which alias was selected, without disrupting the current session or any ongoing streaming. The array has SP_MAX_DEVICE_ALIASES slots. Any slot which contains NULL as the alias name is ignored. See also Notes:
| |||
const char * | brand_name | A NULL-terminated string containing the brand name of the hardware device (for hardware integrations) |
|
This should be an ASCII string containing only letters, digits, "_" (underscore), "-" (hyphen) and "." (period). SpInit returns kSpErrorInvalidArgument if this is not specified or if the string is longer than SP_MAX_BRAND_NAME_LENGTH characters. | |||
const char * | brand_display_name | A UTF-8-encoded brand name of the hardware device (for hardware integrations). Should be very similar to brand_name. |
|
The string will be truncated to at most SP_MAX_DISPLAY_NAME_LENGTH bytes (depending on the UTF-8-encoded characters), not counting the terminating NULL. | |||
const char * | model_name | A NULL-terminated string containing the model name of the hardware device (for hardware integrations) |
|
This should be an ASCII string containing only letters, digits, "_" (underscore), "-" (hyphen) and "." (period). SpInit returns kSpErrorInvalidArgument if this is not specified or if the string is longer than SP_MAX_MODEL_NAME_LENGTH characters. | |||
const char * | model_display_name | A UTF-8-encoded model name of the hardware device (for hardware integrations) |
|
The string will be truncated to at most SP_MAX_DISPLAY_NAME_LENGTH bytes (depending on the UTF-8-encoded characters), not counting the terminating NULL. | |||
const char * | platform_name | A NULL-terminated string containing the platform identifier. |
|
SpInit returns kSpErrorInvalidArgument if this is invalid or longer than SP_MAX_PLATFORM_NAME_LENGTH characters. | |||
const char * | client_id | A NULL-terminated string containing the client id of the application. |
|
The Client ID identifies the application using Spotify, Register your application here. This can be an ASCII string containing only hexadecimal characters, or NULL SpInit returns kSpErrorInvalidArgument if this is invalid or longer than SP_MAX_CLIENT_ID_LENGTH characters. | |||
uint32_t | product_id | An integer enumerating the product for this partner. |
|
The (Client ID, Product ID) pair will uniquely identify this product in the Spotify backend. That could determine things like license, icons, and other behaviour as needed. | |||
const char * | scope | A NULL-terminated string containing the OAuth scope requested when authenticating with the Spotify backend. |
|
This can be a comma-separated string of Spotify scopes, or NULL (which would mean the default SP_SCOPE_STREAMING = "streaming") SpInit returns kSpErrorInvalidArgument if this is invalid or longer than SP_MAX_SCOPE_LENGTH characters. | |||
const char * | os_version | A NULL-terminated string containing the os version running on the hardware. |
|
This should be an ASCII string containing only printable characters or NULL. SpInit returns kSpErrorInvalidArgument if this is invalid or longer than SP_MAX_OS_VERSION_LENGTH characters. | |||
enum SpDeviceType | device_type | The device type that best describes this product. |
|
This device type will be reported to client applications and might result in a suitable icon being shown, etc. SpInit returns kSpErrorInvalidArgument if this is invalid | |||
enum SpPlaybackBitrate | max_bitrate | The maximum bitrate to use for playback. |
|
Leave as default to use the maximum available bitrate (high). The bitrate may drop automatically to compensate for low network speeds. Use SpSetPlaybackBitrate to change the bitrate. | |||
SpCallbackError | error_callback | Pointer to a callback function that will receive error notifications. |
|
void * | error_callback_context | Application-defined pointer that will be passed unchanged as the context argument to the error_callback callback. |
|
int | zeroconf_serve | Not applicable in this eSDK configuration. |
|
const char * | host_name | Not applicable in this eSDK configuration. |
|
int | zeroconf_port | Not applicable in this eSDK configuration. |
|
int | zeroconf_port_range | Not applicable in this eSDK configuration. |
|
struct SpFormat | supported_drm_media_formats | ||
Mapping of DRM formats and media formats that the integration supports. See also Example:
|
SpDeviceAliasCallbacks
Return to Main data structures
Callbacks to be registered with SpRegisterDeviceAliasCallbacks
Any of the pointers may be NULL. See the documentation of the callback typedefs for information about the individual callbacks.
struct SpDeviceAliasCallbacks {
SpCallbackSelectedDeviceAliasChanged on_selected_device_alias_changed;
SpCallbackDeviceAliasesUpdateDone on_device_aliases_update_done;
};
SpCallbackSelectedDeviceAliasChanged | on_selected_device_alias_changed | Selected device alias updated callback. |
SpCallbackDeviceAliasesUpdateDone | on_device_aliases_update_done | Device alias list updated. |
Typedefs
SpCallbackError()
typedef void(* SpCallbackError)(SpError error, void *context)
Callback for reporting errors to the application.
To register this callback, set the field SpConfig::error_callback when invoking the function SpInit
Parameters
[in] | SpError error | Error code |
[in] | void * context |
Context pointer that was passed when registering the callback |
Notes:
- The application should not block or call API functions that are not allowed in the callback.
SpCallbackPlaybackNotify()
typedef void(* SpCallbackPlaybackNotify)(enum SpPlaybackNotification event, void *context)
Callback for notifying the application about playback-related events.
To register this callback, use the function SpRegisterPlaybackCallbacks
Parameters
[in] | enum SpPlaybackNotification event |
Type of event |
[in] | void * context |
Context pointer that was passed when registering the callback |
Notes:
- The application should not block or call API functions that are not allowed in the callback.
SpCallbackPlaybackSeek()
typedef void(* SpCallbackPlaybackSeek)(uint32_t position_ms, void *context)
Callback to notify the application of a change in the playback position.
To register this callback, use the function SpRegisterPlaybackCallbacks This callback is invoked when SpPlaybackSeek is invoked or when the user seeks to a position within the track using Spotify Connect.
Parameters
[in] | uint32_t position_ms |
New position within the track in milliseconds |
[in] | void * context |
Context pointer that was passed when registering the callback |
Notes:
- The application should not block or call API functions that are not allowed in the callback.
SpCallbackPlaybackApplyVolume()
typedef void(* SpCallbackPlaybackApplyVolume)(uint16_t volume, uint8_t remote, void *context)
Callback to notify the application of a volume change using Spotify Connect.
To register this callback, use the function SpRegisterPlaybackCallbacks This callback is invoked in two cases: When the user changes the playback volume using Spotify Connect. When the application invoked SpPlaybackUpdateVolume In both cases, the application is responsible for applying the new volume to its audio output. The application should never invoke SpPlaybackUpdateVolume from this callback, as this might result in an endless loop.
Parameters
[in] | uint16_t volume | Volume in the range 0 (silence) to 65535 (max volume) |
[in] | uint8_t remote | Set to 1 if the volume was changed using Spotify Connect, 0 otherwise |
[in] | void * context |
Context pointer that was passed when registering the callback |
Notes:
- The application should not block or call API functions that are not allowed in the callback.
SpCallbackConnectionNotify()
typedef void(* SpCallbackConnectionNotify)(enum SpConnectionNotification event, void *context)
Callback for notifying the application about events related to the connection to Spotify
To register this callback, use the function SpRegisterConnectionCallbacks
Parameters
[in] | enum SpConnectionNotification event |
Type of event |
[in] | void * context |
Context pointer that was passed when registering the callback |
Notes:
- The application should not block or call API functions that are not allowed in the callback.
SpCallbackConnectionNewCredentials()
typedef void(* SpCallbackConnectionNewCredentials)(const char *credentials_blob, const char *username, void *context)
Callback for passing a login blob to the application.
To register this callback, use the function SpRegisterConnectionCallbacks The application may save the credentials_blob for subsequent logins using the function SpConnectionLoginBlob The application should also discard any credentials blobs for this user that it received previously, either through this callback or through ZeroConf (see the ZeroConf manual). Note: If credentials_blob is an empty string, the application MUST delete any existing saved credentials for the account, and must not attempt to login again with the empty credentials. This happens when a permanent logout is requested.
Parameters
[in] | const char * credentials_blob |
Credentials to be passed to SpConnectionLoginBlob |
[in] | const char * username |
user name to be passed to SpConnectionLoginBlob |
[in] | void * context |
Context pointer that was passed when registering the callback |
See also
Notes:
- The application should not block or call API functions that are not allowed in the callback.
SpCallbackConnectionMessage()
typedef void(* SpCallbackConnectionMessage)(const char *message, void *context)
Callback for sending a message to the user.
To register this callback, use the function SpRegisterConnectionCallbacks This callback is invoked when Spotify wants to display a message to the user. The message is meant to be displayed to the user as-is and should not be interpreted by the application (the format of the messages may change without notice). If the application does not have a graphical user interface, it can safely ignore this callback.
Parameters
[in] | const char * message |
Message to be displayed to the user. |
[in] | void * context |
Context pointer that was passed when registering the callback |
Notes:
- The application should not block or call API functions that are not allowed in the callback.
SpCallbackDebugMessage()
typedef void(* SpCallbackDebugMessage)(const char *debug_message, void *context)
Callback for sending debug messages/trace logs.
To register this callback, use the function SpRegisterDebugCallbacks In special builds of the library, this callback receives debug messages that the application may write to its logs. The application should not interpret the messages (the format of the messages may change without notice).
Parameters
[in] | const char * debug_message |
Message to be logged |
[in] | void * context |
Context pointer that was passed when registering the callback |
Notes:
- The application should not block or call API functions that are not allowed in the callback.
SpCallbackSelectedDeviceAliasChanged()
typedef void(* SpCallbackSelectedDeviceAliasChanged)(uint32_t alias_index, void *context)
Callback for receiving the selected device alias from the backend.
To register this callback, use the function SpRegisterDeviceAliasCallbacks This callback is invoked whenever the selected device alias is updated. This can happen when, for example, the user selects an alias from Spotify Connect device picker.
Parameters
[in] | uint32_t alias_index |
Index of the device alias which was selected |
[in] | void * context |
Context pointer that was passed when registering the callback |
Notes:
- The application should not block or call API functions that are not allowed in the callback.
SpCallbackDeviceAliasesUpdateDone()
typedef void(* SpCallbackDeviceAliasesUpdateDone)(SpError error_code, void *context)
Callback for knowing when the device alias list has been updated after call to SpSetDeviceAliases
To register this callback, use the function SpRegisterDeviceAliasCallbacks This callback is invoked when the operation started by SpSetDeviceAliases has finished.
Parameters
[in] | SpError error_code | if the update was successful, the value is kSpErrorOk |
[in] | void * context |
Context pointer that was passed when registering the callback |
Notes:
- The application should not block or call API functions that are not allowed in the callback.
Enumerations
SpError
enum SpError {
kSpErrorOk,
kSpErrorFailed,
kSpErrorInitFailed,
kSpErrorWrongAPIVersion,
kSpErrorNullArgument,
kSpErrorInvalidArgument,
kSpErrorUninitialized,
kSpErrorAlreadyInitialized,
kSpErrorLoginBadCredentials,
kSpErrorNeedsPremium,
kSpErrorTravelRestriction,
kSpErrorApplicationBanned,
kSpErrorGeneralLoginError,
kSpErrorUnsupported,
kSpErrorNotActiveDevice,
kSpErrorAPIRateLimited,
kSpErrorReentrancyDetected,
kSpErrorMultiThreadingDetected,
kSpErrorTryAgain,
kSpErrorDuringLogout,
kSpErrorPermanentConnectionError,
kSpErrorEntropyFailure,
kSpErrorZeroConfErrorStart,
kSpErrorZeroConfBadRequest,
kSpErrorZeroConfUnknown,
kSpErrorZeroConfNotImplemented,
kSpErrorZeroConfNotInstalled,
kSpErrorZeroConfNotLoaded,
kSpErrorZeroConfNotAuthorized,
kSpErrorZeroConfCannotLoad,
kSpErrorZeroConfSystemUpdateRequired,
kSpErrorZeroConfSpotifyUpdateRequired,
kSpErrorZeroConfLoginFailed,
kSpErrorZeroConfInvalidPublicKey,
kSpErrorZeroConfMissingAction,
kSpErrorZeroConfInvalidAction,
kSpErrorZeroConfInvalidArguments,
kSpErrorZeroConfNoSpotifySession,
kSpErrorZeroConfSpotifyError,
kSpErrorPlaybackErrorStart,
kSpErrorGeneralPlaybackError,
kSpErrorPlaybackRateLimited,
kSpErrorPlaybackCappingLimitReached,
kSpErrorAdIsPlaying,
kSpErrorCorruptTrack,
kSpErrorContextFailed,
kSpErrorPrefetchItemUnavailable,
kSpAlreadyPrefetching,
kSpStorageReadError,
kSpStorageWriteError,
kSpPrefetchDownloadFailed,
kSpErrorBusy,
kSpErrorUnavailable,
kSpErrorNotAllowed,
kSpErrorNetworkRequired,
kSpErrorNotLoggedIn,
kSpErrorInProgress,
kSpErrorPlaybackInitiation,
kSpErrorPresetFailed,
kSpErrorInvalidRequest,
kSpErrorInvalidTrackId,
kSpErrorIncorrectMsPlayed,
kSpErrorDeviceNotControllable,
kSpErrorPlaybackInitiationTimeout,
kSpErrorGeneralDownloadError,
};
kSpErrorOk | The operation was successful. |
|
kSpErrorFailed | The operation failed due to an unspecified issue. |
|
kSpErrorInitFailed | The library could not be initialized. |
|
| ||
kSpErrorWrongAPIVersion | The library could not be initialized because of an incompatible API version. |
|
When calling SpInit you are required to set the field SpConfig::api_version to SP_API_VERSION. This error indicates that the library that the application is linked against was built for a different SP_API_VERSION. There might be an issue with the include or library paths in the build environment, or the wrong Embedded SDK shared object is loaded at runtime. See also | ||
kSpErrorNullArgument | An unexpected NULL pointer was passed as an argument to a function. |
|
kSpErrorInvalidArgument | An unexpected argument value was passed to a function. |
|
kSpErrorUninitialized | A function was invoked before SpInit or after SpFree was called. |
|
kSpErrorAlreadyInitialized | SpInit was called more than once. |
|
kSpErrorLoginBadCredentials | Login to Spotify failed because of invalid credentials. |
|
| ||
kSpErrorNeedsPremium | The operation requires a Spotify Premium account. |
|
kSpErrorTravelRestriction | The Spotify user is not allowed to log in from this country. |
|
kSpErrorApplicationBanned | The application has been banned by Spotify |
|
This most likely means that the client_id specified in SpConfig::client_id has been denylisted. | ||
kSpErrorGeneralLoginError | An unspecified login error occurred. |
|
In order to help debug the issue, the application should register the callback SpCallbackDebugMessage which receives additional information about the error. | ||
kSpErrorUnsupported | The operation is not supported. |
|
kSpErrorNotActiveDevice | The operation is not supported if the device is not the active playback device. |
|
| ||
kSpErrorAPIRateLimited | The API has been rate-limited. |
|
The API is rate-limited if it is asked to perform too many actions in a short amount of time. | ||
kSpErrorReentrancyDetected | The eSDK API was used from a callback. |
|
This eSDK API function cannot be used from callbacks. | ||
kSpErrorMultiThreadingDetected | The eSDK API was used from multiple threads. |
|
This eSDK API function does not support multi-threading. | ||
kSpErrorTryAgain | The eSDK API cannot be performed right now. |
|
This eSDK API cannot be performed right now, but you are free to retry. | ||
kSpErrorDuringLogout | Logout failed during SpFree call. |
|
kSpErrorPermanentConnectionError | Permanent connection error. eSDK ceased attempts to reconnect. |
|
kSpErrorEntropyFailure | Failed to get cryptographic random data from the platform. |
|
kSpErrorZeroConfErrorStart | Error range reserved for ZeroConf-related errors. |
|
kSpErrorZeroConfBadRequest | ZeroConf Web server problem or critically malformed request. |
|
kSpErrorZeroConfUnknown | Fallback when no other ZeroConf error applies. |
|
kSpErrorZeroConfNotImplemented | ZeroConf device does not implement this feature. |
|
kSpErrorZeroConfNotInstalled | Spotify not installed (where applicable) |
|
kSpErrorZeroConfNotLoaded | Spotify not loaded (where applicable) |
|
kSpErrorZeroConfNotAuthorized | Spotify client not authorized to play. |
|
kSpErrorZeroConfCannotLoad | Spotify cannot be loaded (where applicable) |
|
kSpErrorZeroConfSystemUpdateRequired | Device system needs update (where applicable) |
|
kSpErrorZeroConfSpotifyUpdateRequired | Spotify requires an update. |
|
kSpErrorZeroConfLoginFailed | Spotify returned an error when trying to login. |
|
kSpErrorZeroConfInvalidPublicKey | ZeroConf login failed due to an invalid public key. |
|
kSpErrorZeroConfMissingAction | ZeroConf HTTP request has no action parameter. |
|
kSpErrorZeroConfInvalidAction | ZeroConf HTTP request has an unrecognized action parameter. |
|
kSpErrorZeroConfInvalidArguments | Incorrect or insufficient ZeroConf arguments supplied for requested action. |
|
kSpErrorZeroConfNoSpotifySession | No valid Spotify session for requested Spotify action (where applicable) |
|
kSpErrorZeroConfSpotifyError | A Spotify API call returned an error not covered by other error messages. |
|
kSpErrorPlaybackErrorStart | Error range reserved for playback-related errors. |
|
kSpErrorGeneralPlaybackError | An unspecified playback error occurred. |
|
| ||
kSpErrorPlaybackRateLimited | The application has been rate-limited. |
|
The application is rate-limited if it requests the playback of too many tracks within a given amount of time. | ||
kSpErrorPlaybackCappingLimitReached | The Spotify user has reached a capping limit that is in effect in this country and/or for this track. |
|
kSpErrorAdIsPlaying | Cannot change track while ad is playing. |
|
kSpErrorCorruptTrack | The track is (temporarily) corrupted in the Spotify catalogue. |
|
This track will be skipped because it cannot be downloaded. This is a temporary issue with the Spotify catalogue that will be resolved. The error is for informational purposes only. No action is required. | ||
kSpErrorContextFailed | Unable to read all tracks from the playing context. |
|
Playback of the Spotify context (playlist, album, artist, radio, etc) will stop early because eSDK is unable to retrieve more tracks. This could be caused by temporary communication or server problems, or by the underlying context being removed or shortened during playback (for instance, the user deleted all tracks in the playlist while listening). | ||
kSpErrorPrefetchItemUnavailable | The item that was being prefetched was unavailable, and cannot be fetched. This could be due to an invalid URI, changes in track availability, or geographical limitations. This is a permanent error, and the item should not be tried again. |
|
kSpAlreadyPrefetching | An item is already actively being prefetched. You must stop the current prefetch request to start another one. This error is only relevant for builds with offline storage enabled. |
|
kSpStorageReadError | A permanent error was encountered while reading to a registered file storage callback. This error is only relevant for builds with offline storage enabled. |
|
kSpStorageWriteError | A permanent error was encountered while writing to a registered file storage callback. This error is only relevant for builds with offline storage enabled. |
|
kSpPrefetchDownloadFailed | The prefetched item was not fully downloaded or failed. If error happens prefetch can be retried. This error is only relevant for builds with offline storage enabled. |
|
kSpErrorBusy | The current API call cannot be completed because eSDK is busy. Same API call should be done sometime later with the same arguments. |
|
kSpErrorUnavailable | The current API call cannot be completed because the requested operation is not available at the moment. |
|
kSpErrorNotAllowed | This eSDK API is not allowed due to current license restrictions. |
|
kSpErrorNetworkRequired | The current API call cannot be completed without connection to the Spotify backend. |
|
kSpErrorNotLoggedIn | The current API call cannot be completed without being logged in. |
|
kSpErrorInProgress | Used in callbacks to notify the application that the action is not yet complete. |
|
kSpErrorPlaybackInitiation | Used in SpCallbackError callback to notify the application that playback initiation failed. |
|
kSpErrorPresetFailed | Used in SpCallbackError callback to notify the application that recalling and playing a preset failed. |
|
| ||
kSpErrorInvalidRequest | The queued track was rejected. |
|
This error is the opposite of kSpPlaybackNotifyQueuedTrackAccepted and occurs when a call to SpQueueUri failed. That might happen e.g. when queuing of several tracks was done within a very short time period and therefore was rate-limited. See also | ||
kSpErrorInvalidTrackId | Used in SpCallbackError callback to notify the application that an invalid track_id was used. |
|
kSpErrorIncorrectMsPlayed | Used in SpCallbackError callback to notify the application that an incorrect value for ms_played was reported. |
|
kSpErrorDeviceNotControllable | The operation is not allowed since the device is not controllable. |
|
| ||
kSpErrorPlaybackInitiationTimeout | The playback initiation operation timed out. |
|
kSpErrorGeneralDownloadError | Failed to download the requested track. |
|
|
SpAPIReturnCode
enum SpAPIReturnCode {
kSpAPINoError,
kSpAPITryAgain,
kSpAPIDNSLookupError,
kSpAPIGenericError,
kSpAPINotSupported,
kSpAPIEOF,
kSpAPINotFound,
};
kSpAPINoError | This code should be used when the API call was successful. |
kSpAPITryAgain | This code means operation cannot be performed right now. Same API call should be done sometime later with the same arguments. |
kSpAPIDNSLookupError | Use to notify about any DNS lookup error that cannot be retried. |
kSpAPIGenericError | API call has failed. |
kSpAPINotSupported | Requested feature is not supported by platform. |
kSpAPIEOF | End of file/socket reached. |
kSpAPINotFound | Requested resource does not exist. |
SpPlaybackBitrate
enum SpPlaybackBitrate {
kSpPlaybackBitrateDefault,
kSpPlaybackBitrateLow,
kSpPlaybackBitrateNormal,
};
kSpPlaybackBitrateDefault | Set the bitrate to the default (currently High). |
kSpPlaybackBitrateLow | Set the bitrate to low. Corresponds to e.g. 96 kbit/s ogg/vorbis. |
kSpPlaybackBitrateNormal | Set the bitrate to normal. Corresponds to e.g. 160 kbit/s ogg/vorbis. |
SpPlaybackNotification
enum SpPlaybackNotification {
kSpPlaybackNotifyPlay,
kSpPlaybackNotifyPause,
kSpPlaybackNotifyTrackChanged,
kSpPlaybackNotifyNext,
kSpPlaybackNotifyPrev,
kSpPlaybackNotifyShuffleOn,
kSpPlaybackNotifyShuffleOff,
kSpPlaybackNotifyRepeatOn,
kSpPlaybackNotifyRepeatOff,
kSpPlaybackNotifyBecameActive,
kSpPlaybackNotifyBecameInactive,
kSpPlaybackNotifyAudioDeliveryDone,
kSpPlaybackNotifyContextChanged,
kSpPlaybackNotifyMetadataChanged,
kSpPlaybackNotifyNetworkRequired,
kSpPlaybackNotifyTrackDownloadStalled,
kSpPlaybackNotifyQueuedTrackAccepted,
};
kSpPlaybackNotifyPlay | Playback has started or has resumed. |
|
If the device is the active speaker (according to SpPlaybackIsActiveDevice and it has audio data that was delivered by audio data callback function left in its buffers, the application must resume playing the audio data. If the device is not the active speaker, it means that another device that is being observed has resumed playback. See observing. See also | ||
kSpPlaybackNotifyPause | Playback has been paused. |
|
If the device is the active speaker (according to SpPlaybackIsActiveDevice the application must stop playing audio immediately. If the device is not the active speaker, it means that another device that is being observed has paused. See observing. See also Notes:
| ||
kSpPlaybackNotifyTrackChanged | The current track or its metadata has changed. |
|
This event occurs in several cases: When SpPlayUri is called When SpPlaybackSkipToNext is called When SpPlaybackSkipToPrev is called Once any of the above actions were issued over connect Once a track has progressed naturally It should not happen: on pause and resume on seek in-track bitrate changes for any reason If your application displays metadata of the current track, use SpGetMetadata to reload the metadata when you receive this event. Applications that allow free users to login can check if the current track is an advertisement using SpPlaybackIsAdPlaying This information can be used to change the display or available controls for advertisements. See also Notes:
| ||
kSpPlaybackNotifyNext | Playback has skipped to the next track. |
|
This event occurs when SpPlaybackSkipToNext was invoked or when the user skipped to the next track using Spotify Connect. It does not occur when playback goes to a new track after the previous track has reached the end. See also | ||
kSpPlaybackNotifyPrev | Playback has skipped to the previous track. |
|
| ||
kSpPlaybackNotifyShuffleOn | "Shuffle" was switched on |
|
| ||
kSpPlaybackNotifyShuffleOff | "Shuffle" was switched off |
|
| ||
kSpPlaybackNotifyRepeatOn | "Repeat" was switched on |
|
| ||
kSpPlaybackNotifyRepeatOff | "Repeat" was switched off |
|
| ||
kSpPlaybackNotifyBecameActive | This device has become the active playback device. |
|
This event occurs when the user moves playback to this device using Spotify Connect, or when playback is moved to this device as a side-effect of invoking one of the SpPlayback functions. When this event occurs, it may be a good time to initialize the audio pipeline of the application. You should not unpause when you receive this event wait for kSpPlaybackNotifyPlay See also | ||
kSpPlaybackNotifyBecameInactive | This device is no longer the active playback device. |
|
This event occurs when the user moves playback to a different device using Spotify Connect. When this event occurs, the application must stop producing audio immediately. The application should not take any other action. Specifically, the application must not invoke any of the SpPlayback functions unless requested by some subsequent user interaction. See also | ||
kSpPlaybackNotifyAudioDeliveryDone | The library will not send any more audio data. |
|
This event occurs when the library reaches the end of a playback context and has no more audio to deliver. This occurs, for instance, at the end of a playlist when repeat is disabled. When the application receives this event, it should finish playing out all of its buffered audio. | ||
kSpPlaybackNotifyContextChanged | Playback changed to a different Spotify context. |
|
This event occurs when playback starts or changes to a different context than was playing before, such as a change in album or playlist. This is an informational event that does not require action, but may be used to update the UI display. DeprecatedUse kSpPlaybackNotifyMetadataChanged instead. | ||
kSpPlaybackNotifyMetadataChanged | Metadata is changed. |
|
This event occurs when playback starts or changes to a different context, when a track switch occurs, etc. This is an informational event that does not require action, but should be used to keep the UI display updated with the latest metadata information. Applications that allow free users to login can check if the current track is an advertisement using SpPlaybackIsAdPlaying This information can be used to change the display or available controls for advertisements. | ||
kSpPlaybackNotifyNetworkRequired | Playback is not allowed without network connection. |
|
This event occurs when there has been no connection to Spotify for a period of time. When this event occurs, the application should stop producing audio immediately. The application should not take any other action. If the user takes any action to affect playback, kSpErrorNetworkRequired will be returned. Once network connection is restored (see kSpConnectionNotifyReconnect), the application can resume playback by calling SpPlaybackPlay Playback is not resumed automatically. | ||
kSpPlaybackNotifyTrackDownloadStalled | Download of the current track stalled due to network outage. |
|
This event occurs when the currently playing track has run out of data to play due to network outage. This is an informative event that indicates that there is no more data to play for the current track until network connections are re-established. If network connection is not available within a certain amount of time playback will be automatically paused, this is to prevent startling effects for the user when track playback resumes unexpectedly after a long time period of silence. Once network connection is restored (see kSpConnectionNotifyReconnect), playback should resume automatically (unless kSpPlaybackNotifyPause occurred due to timeout). | ||
kSpPlaybackNotifyQueuedTrackAccepted | The queued track was accepted. |
|
This event occurs when a call to SpQueueUri has been accepted. Normally there is no need to monitor specifically for this as kSpPlaybackNotifyMetadataChanged is enough to detect UI related changes. A distinct use case for this notification is if one wants to queue several tracks within a very short time period where waiting for this notification between each call will help avoid getting rate-limited. See also |
SpConnectionNotification
enum SpConnectionNotification {
kSpConnectionNotifyLoggedIn,
kSpConnectionNotifyLoggedOut,
kSpConnectionNotifyTemporaryError,
kSpConnectionNotifyDisconnect,
kSpConnectionNotifyReconnect,
kSpConnectionNotifyProductTypeChanged,
kSpConnectionNotifyZeroConfVarsChanged,
kSpConnectionNotifyTransmittingData,
};
kSpConnectionNotifyLoggedIn | The user has successfully logged in to Spotify |
|
| ||
kSpConnectionNotifyLoggedOut | The user has been logged out of Spotify |
|
This can occur as a result of invoking SpConnectionLogout or because of a permanent connection error. To log in again, the application must invoke SpConnectionLoginBlob See also Notes:
| ||
kSpConnectionNotifyTemporaryError | A temporary connection error occurred. The library will automatically retry. |
|
A temporary error can be due to lost network connectivity. The library will try to reconnect from time to time. If the application is able to detect that the network has become unavailable (e.g., when the network cable is unplugged), it should call SpConnectionSetConnectivity with kSpConnectivityNone When the network becomes available again, it should invoke SpConnectionSetConnectivity with a value other than kSpConnectivityNone, which will cause the library to try to reconnect immediately. In order to help debug the issue, the application should register the callback SpCallbackDebugMessage which receives additional information about the error. | ||
kSpConnectionNotifyDisconnect | The connection to Spotify has been lost. |
|
The application can use this to indicate a connectivity issue. No other action is necessary. In particular, the application is not supposed to re-login the user. Notes:
| ||
kSpConnectionNotifyReconnect | The connection to Spotify has been (re-)established. |
|
This notification will be sent when the connection to Spotify has been re-established after a prior kSpConnectionNotifyDisconnect or the first time a connection is established to Spotify | ||
kSpConnectionNotifyProductTypeChanged | The connected user account type has changed (became premium, for example). |
|
No action is necessary, but new features may be available if used in conjunction with the Spotify Web API. | ||
kSpConnectionNotifyZeroConfVarsChanged | The SpZeroConfVars has changed. |
|
Retrieve the new values using SpZeroConfGetVars | ||
kSpConnectionNotifyTransmittingData | The eSDK is transmitting data. |
|
This notification is sent every time the eSDK begins sending data. It can be used to trigger integration-specific data transmissions to coincide with the eSDK transmissions, to save energy for wireless applications. Notes:
|
SpDeviceType
enum SpDeviceType {
kSpDeviceTypeComputer,
kSpDeviceTypeTablet,
kSpDeviceTypeSmartphone,
kSpDeviceTypeSpeaker,
kSpDeviceTypeTV,
kSpDeviceTypeAVR,
kSpDeviceTypeSTB,
kSpDeviceTypeAudioDongle,
kSpDeviceTypeGameConsole,
kSpDeviceTypeCastVideo,
kSpDeviceTypeCastAudio,
kSpDeviceTypeAutomobile,
kSpDeviceTypeSmartwatch,
kSpDeviceTypeChromebook,
};
kSpDeviceTypeComputer | Laptop or desktop computer device. |
kSpDeviceTypeTablet | Tablet PC device. |
kSpDeviceTypeSmartphone | Smartphone device. |
kSpDeviceTypeSpeaker | Speaker device. |
kSpDeviceTypeTV | Television device. |
kSpDeviceTypeAVR | Audio/Video receiver device. |
kSpDeviceTypeSTB | Set-Top Box device. |
kSpDeviceTypeAudioDongle | Audio dongle device. |
kSpDeviceTypeGameConsole | Game console device. |
kSpDeviceTypeCastVideo | Chromecast Video. |
kSpDeviceTypeCastAudio | Chromecast Audio. |
kSpDeviceTypeAutomobile | Automobile. |
kSpDeviceTypeSmartwatch | Smartwatch. |
kSpDeviceTypeChromebook | Chromebook. |
SpMetadataTrack
enum SpMetadataTrack {
kSpMetadataTrackBeforePrevious,
kSpMetadataTrackPrevious,
kSpMetadataTrackCurrent,
kSpMetadataTrackNext,
kSpMetadataTrackAfterNext,
};
kSpMetadataTrackBeforePrevious | Index of the before previous track in the track list. |
kSpMetadataTrackPrevious | Index of the previous track in the track list. |
kSpMetadataTrackCurrent | Index of the current track in the track list. |
kSpMetadataTrackNext | Index of the next track in the track list. |
kSpMetadataTrackAfterNext | Index of the after next track in the track list. |
SpConnectivity
enum SpConnectivity {
kSpConnectivityNone,
kSpConnectivityWired,
kSpConnectivityWireless,
kSpConnectivityMobile,
};
kSpConnectivityNone | The device is not connected to the network. |
kSpConnectivityWired | The device is connected to a wired network. |
kSpConnectivityWireless | The device is connected to a wireless network. |
kSpConnectivityMobile | The device uses a mobile data connection. |
SpContent
enum SpContent {
kSpContentUnknown,
kSpContentMusicTrack,
kSpContentShowEpisode,
kSpContentAd,
};
kSpContentUnknown | Unknown content type. |
kSpContentMusicTrack | Music track. |
kSpContentShowEpisode | Podcast show episode. |
kSpContentAd | Advertisement. |
SpMediaType
enum SpMediaType {
kSpMediaTypeAudio,
kSpMediaTypeVideo,
};
kSpMediaTypeAudio | Audio media type. |
kSpMediaTypeVideo | Video media type. |
SpAudioQuality
enum SpAudioQuality {
kSpAudioQualityUnknown,
kSpAudioQualityLow,
kSpAudioQualityNormal,
kSpAudioQualityHigh,
kSpAudioQualityVeryHigh,
};
kSpAudioQualityUnknown | Unknown audio quality. |
kSpAudioQualityLow | Low audio quality. |
kSpAudioQualityNormal | Normal audio quality (e.g. 96 kbps ogg/vorbis) |
kSpAudioQualityHigh | High audio quality (e.g. 160 kbps ogg/vorbis) |
kSpAudioQualityVeryHigh | Very high audio quality (e.g. 320 kbps ogg/vorbis) |
SpDrmFormat
enum SpDrmFormat {
kSpDrmFormatUnknown,
kSpDrmFormatUnencrypted,
kSpDrmFormatFairPlay,
kSpDrmFormatWidevine,
kSpDrmFormatPlayReady,
};
kSpDrmFormatUnknown | Unknown DRM. |
kSpDrmFormatUnencrypted | No DRM, unencrypted. |
kSpDrmFormatFairPlay | FairPlay. |
kSpDrmFormatWidevine | Widevine. |
kSpDrmFormatPlayReady | PlayReady. |
SpReDeliveryMode
enum SpReDeliveryMode {
kSpRedeliveryModeActivated,
kSpRedeliveryModeDeactivated,
};
kSpRedeliveryModeActivated | Redelivery is activated. |
kSpRedeliveryModeDeactivated | Redelivery is deactivated. |
Functions
SpInit()
SpError SpInit(struct SpConfig *conf)
Initialize the library.
Parameters
[in] | struct SpConfig * conf |
Configuration parameters |
Returns
Returns an error code
SpFree()
SpError SpFree(void)
Shut down the library.
If a user is currently logged in, the application should first call SpConnectionLogout and wait for the kSpConnectionNotifyLoggedOut event, otherwise SpFree may take several seconds.
Returns
Returns an error code
SpGetLibraryVersion()
const char * SpGetLibraryVersion(void)
Retrieve a version string for the library.
Returns
Version string
Notes:
- This API can be invoked from a callback.
SpConnectionSetConnectivity()
SpError SpConnectionSetConnectivity(enum SpConnectivity connectivity)
Set the type of network connection of the device.
When the application detects that the device has lost network connection, it should call this function with kSpConnectivityNone When network connection is restored, the application should call this function with one of the other values of SpConnectivity The library will then immediately retry to reconnect to Spotify (rather than waiting for the next retry timeout). The library may use the type of network connection to adapt its streaming and buffering strategies. Currently, however, all types of network connection are treated the same.
Parameters
[in] | enum SpConnectivity connectivity |
Type of connection |
Returns
Returns an error code
SpConnectionGetConnectivity()
enum SpConnectivity SpConnectionGetConnectivity(void)
Get the connectivity that was set with SpConnectionSetConnectivity
The library does not detect the type of network connection by itself. It only updates it if the application calls SpConnectionSetConnectivity If SpConnectionSetConnectivity was never called, the connection defaults to kSpConnectivityWired
Returns
Type of connection
Notes:
- This API can be invoked from a callback.
SpConnectionLoginBlob()
SpError SpConnectionLoginBlob(const char *username, const char *credentials_blob)
Log in a user to Spotify using a credentials blob.
Parameters
[in] | const char * username |
Spotify username. UTF-8 encoded. Must not be longer than SP_MAX_USERNAME_LENGTH bytes (not UTF-8-encoded characters), not counting the terminating NULL. (For users that log in via Facebook, this is an email address.) |
[in] | const char * credentials_blob |
Credentials blob received via ZeroConf or in the callback SpCallbackConnectionNewCredentials Note: if the credentials_blob is an empty string, this function should not be called or it will return kSpErrorFailed |
Returns
Returns an error code
See also
Notes:
- The login is performed asynchronously. The return value only indicates whether the library is able to perform the login attempt. The status of the login will be reported via callbacks:
- The blob can only be used for subsequent logins as long as the value of SpConfig::unique_id does not change. If SpConfig::unique_id has changed since the blob was received, this function returns an error and you will receive a debug message similar to "Parsing ZeroConf blob failed with code -3".
SpConnectionLoginPassword()
SpError SpConnectionLoginPassword(const char *username, const char *password)
Log in a user to Spotify using a password.
Returns kSpErrorGeneralLoginError if a connection is not present. For logging in offline please use SpConnectionLoginBlob Applications must not store the password. Instead, they should implement the callback SpCallbackConnectionNewCredentials and store the credentials blob that they receive for subsequent logins using the function SpConnectionLoginBlob
Parameters
[in] | const char * username |
Spotify username. UTF-8 encoded. Must not be longer than SP_MAX_USERNAME_LENGTH bytes (not UTF-8-encoded characters), not counting the terminating NULL. (For users that log in via Facebook, this is an email address.) |
[in] | const char * password |
Password |
Returns
Returns an error code
See also
Notes:
- The login is performed asynchronously. The return value only indicates whether the library is able to perform the login attempt. The status of the login will be reported via callbacks:
- Spotify Connect-enabled hardware devices must not use this function. Such devices must implement the ZeroConf and use the function SpConnectionLoginBlob instead.
SpConnectionLoginOauthToken()
SpError SpConnectionLoginOauthToken(const char *oauth_token)
Log in a user to Spotify using a Spotify OAuth token.
For subsequent logins the SpCallbackConnectionNewCredentials callback should be implemented and the received credentials blob should be stored and used. (Note that the OAuth access token itself expires after a short time. The credentials blob returned by the callback allows you to re-login even after the token has expired.)
Parameters
[in] | const char * oauth_token |
Spotify OAuth access token with “streaming” scope. See https://developer.spotify.com/documentation/general/guides/authorization-guide/ |
Returns
Returns an error code
See also
Notes:
- The login is performed asynchronously. The return value only indicates whether the library is able to perform the login attempt. The status of the login will be reported via callbacks:
- Spotify Connect-enabled hardware devices that implement the ZeroConf stack must use the function SpConnectionLoginBlob instead.
SpConnectionLogout()
SpError SpConnectionLogout(void)
Log the user out of Spotify
Returns
Returns an error code
See also
Notes:
- The logout is performed asynchronously. The logout is complete when the callback SpCallbackConnectionNotify is called with the event kSpConnectionNotifyLoggedOut
SpConnectionIsLoggedIn()
uint8_t SpConnectionIsLoggedIn(void)
Is the user logged in to Spotify
Returns
1: The user is logged in 0: The user is not logged in
See also
Notes:
- This API can be invoked from a callback.
SpConnectionGetAckId()
const char * SpConnectionGetAckId(void)
Get the last Ack ID.
Notes:
- This function is deprecated and should not be used.
SpGetCanonicalUsername()
const char * SpGetCanonicalUsername(void)
Get the canonical username of the logged in user.
This function returns the canonical username of the logged in user, which is the unique username used for identifying a specific user for things like playlists and the Spotify Web API. This username might differ from the username used to login. A user can login with an e-mail address or non-canonical unicode. This function will return the canonicalized version of the username after a successful login.
Returns
Returns a string containing the username, or NULL if no user is logged in.
Notes:
- The canonical username should not be stored persistently. Always store the username as provided by the user, not the canonicalized version.
- This API can be invoked from a callback.
SpSetDisplayName()
SpError SpSetDisplayName(const char *display_name)
Set the display name for the device or application.
This function can be used to change the display name that was passed to SpInit in the field SpConfig::display_name
Parameters
[in] | const char * display_name |
A UTF-8-encoded display name |
Returns
Returns an error code
Notes:
- The display name is not allowed to be an empty string.
SpSetVolumeSteps()
SpError SpSetVolumeSteps(uint32_t steps)
Set the volume steps the device is capable of.
This function will indicate the number of intermediate steps from min_volume to max_volume that the device supports. If there's no volume control ability it must be set to zero to inform that no volume control is possible at all. The default number of steps if this function is not called is 16.
Parameters
[in] | uint32_t steps |
the number of volume steps the device can support. 0 means no volume steps at all. The max value that is possible to set is 65535. |
Returns
Returns an error code
Notes:
- There's no commitment from the other Connect clients to respect the volume steps. It's important to call this function passing zero if no volume control is possible though.
SpSetDeviceIsGroup()
SpError SpSetDeviceIsGroup(int is_group)
Control if the device represents a group.
A group is a number of devices all playing back the same sound synchronized. Setting this status correctly will allow Spotify clients to display the correct metadata for this device.
Parameters
[in] | int is_group |
0: Indicate that this device is a single stand-alone device. 1: Indicate that this device represents a group. |
Notes:
- If device aliases are used, this function should not be used to set the group status. Instead, SpSetDeviceAliases should be used to update group status individually for each alias.
SpEnableConnect()
SpError SpEnableConnect(void)
Enable Connect functionality for this device.
A device with enabled Connect functionality will show up in other devices' Connect pickers, and will be able to both control them and be controlled. The Spotify embedded library will enable Connect functionality by default
SpDisableConnect()
SpError SpDisableConnect(void)
Disable Connect functionality for this device.
A device that disables Connect will not be able to control playback on other devices, or be controlled by them.
SpGetSelectedDeviceAlias()
int SpGetSelectedDeviceAlias(void)
Return the currently selected device alias.
Returns
The currently selected device alias or SP_NO_ALIAS_SELECTED if no alias is selected.
SpPumpEvents()
SpError SpPumpEvents(void)
Allow the library to perform asynchronous tasks and process events.
Note: The suggested time interval to call this function is 10ms. This function should not be called from a callback. A typical usage pattern looks like this:
Returns
Returns an error code
SpRegisterConnectionCallbacks()
SpError SpRegisterConnectionCallbacks(struct SpConnectionCallbacks *cb, void *context)
Register callbacks related to the connection to Spotify
Parameters
[in] | struct SpConnectionCallbacks * cb |
Structure with pointers to individual callback functions. Any of the pointers in the structure may be NULL. |
[in] | void * context |
Application-defined pointer that will be passed unchanged as the context argument to the callbacks. |
Returns
Returns an error code
SpRegisterDebugCallbacks()
SpError SpRegisterDebugCallbacks(struct SpDebugCallbacks *cb, void *context)
Register a callback that receives debug messages/trace logs.
These callbacks can be registered before SpInit has been called, in order to receive debug logs that occur during initialization.
Parameters
[in] | struct SpDebugCallbacks * cb |
Structure with pointers to individual callback functions. |
[in] | void * context |
Application-defined pointer that will be passed unchanged as the context argument to the callback. |
Returns
Returns an error code
SpRegisterPlaybackCallbacks()
SpError SpRegisterPlaybackCallbacks(struct SpPlaybackCallbacks *cb, void *context)
Register playback-related callbacks.
Parameters
[in] | struct SpPlaybackCallbacks * cb |
Structure with pointers to individual callback functions. Any of the pointers in the structure may be NULL. |
[in] | void * context |
Application-defined pointer that will be passed unchanged as the context argument to the callbacks. |
Returns
Returns an error code
SpGetMetadata()
SpError SpGetMetadata(struct SpMetadata *metadata, int relative_index)
Retrieve metadata for a track in the current track list.
Parameters
[out] | struct SpMetadata * metadata |
Structure to be filled with the metadata for the track |
[in] | int relative_index |
Track index relative to the current track. Some relative indices are defined in the enum SpMetadataTrack |
Returns
Returns an error code. Returns kSpErrorFailed if relative_index is out of range.
Notes:
- This API can be invoked from a callback.
- Be aware that many APIs that change the currently playing context are asynchronous, and the changes will not be immediately reflected in the metadata returned by SpGetMetadata For example, when calling SpPlaybackSkipToNext SpPlaybackEnableShuffle etc., the metadata returned by SpGetMetadata might be unchanged while the command is being processed (which involves network communication). The notification kSpPlaybackNotifyMetadataChanged will be sent as soon as SpGetMetadata would return a different result for any relative_index defined in the enum SpMetadataTrack
SpGetMetadataImageURL()
SpError SpGetMetadataImageURL(const char *image_uri, char *image_url, size_t image_url_size)
Return the HTTP URL to an image file from a spotify:image: URI.
Parameters
[in] | const char * image_uri |
image URI returned in SpMetadata::album_cover_uri |
[out] | char * image_url |
Pointer to a buffer that will be filled with HTTP URL. |
[in] | size_t image_url_size | size of the image_url buffer. SP_MAX_METADATA_IMAGE_URL_LENGTH is the max amount of data that can be returned in image_url. |
Returns
Returns an error code. Returns kSpErrorFailed if the buffer is not big enough.
Notes:
- This API can be invoked from a callback.
SpGetPlayerCookie()
SpError SpGetPlayerCookie(char *player_cookie, size_t player_cookie_size)
Obtain player cookie for current playback.
The obtained player cookie can then be used to get more detailed metadata for current playback from Spotify's backend using Spotify Web API.
Parameters
[out] | char * player_cookie |
Pointer to a buffer where the player cookie will be copied. This buffer will be reset even if there is no player cookie available. |
[in] | size_t player_cookie_size | Size of the player_cookie buffer. Player cookie length is defined SP_PLAYER_COOKIE_LENGTH and the buffer should be at least SP_PLAYER_COOKIE_LENGTH+1 in size. |
Returns
Returns an error code. Returns kSpErrorUnsupported if the build configuration doesn’t support player cookies.
Notes:
- Experimental, subject to change
SpPlaybackPlay()
SpError SpPlaybackPlay(int alias_index)
Start or resume playback.
Parameters
[in] | int alias_index |
The index of the device alias to start playback on. If aliases aren’t used, pass SP_NO_ALIAS_SELECTED. |
Returns
Returns an error code
SpPlaybackPause()
SpError SpPlaybackPause(void)
Pause playback.
If the device is not the active speaker (SpPlaybackIsActiveDevice()), the error code kSpErrorNotActiveDevice is returned.
Returns
Returns an error code
SpPlaybackSkipToNext()
SpError SpPlaybackSkipToNext(void)
Skip playback to the next track in the track list.
If the device is not the active speaker (SpPlaybackIsActiveDevice()), the error code kSpErrorNotActiveDevice is returned.
Returns
Returns an error code
SpPlaybackSkipToPrev()
SpError SpPlaybackSkipToPrev(void)
Skip playback to the previous track in the track list.
If the device is not the active speaker (SpPlaybackIsActiveDevice()), the error code kSpErrorNotActiveDevice is returned.
Returns
Returns an error code
Notes:
- This function will try to skip to the previous track regardless of the current playback position. If the desired behaviour is to only skip to the previous track UNLESS the current playback position is beyond 3 seconds, the following code example is suggested as a base: if(SpPlaybackGetPosition()/1000=3) SpPlaybackSeek(0); else SpPlaybackSkipToPrev
SpPlaybackSeek()
SpError SpPlaybackSeek(uint32_t position_ms)
Seek to a position within the current track.
If the device is not the active speaker (SpPlaybackIsActiveDevice()), the error code kSpErrorNotActiveDevice is returned.
Parameters
[in] | uint32_t position_ms |
Position within the track in milliseconds |
Returns
Returns an error code
SpPlaybackSeekRelative()
SpError SpPlaybackSeekRelative(int32_t time_ms)
Seek a relative amount of time within the current track.
If the device is not the active speaker (SpPlaybackIsActiveDevice()), the error code kSpErrorNotActiveDevice is returned.
Parameters
[in] | int32_t time_ms |
Amount of time to seek within the current track, negative values seek backwards and positive values seek forward. |
Returns
Returns an error code
SpPlaybackGetPosition()
uint32_t SpPlaybackGetPosition(void)
Get the current playback position within the track.
Returns
Playback position in milliseconds
Notes:
- This API can be invoked from a callback.
SpPlaybackUpdateVolume()
SpError SpPlaybackUpdateVolume(uint16_t volume)
Request a change to the playback volume.
It is the application's responsibility to apply the volume change to its audio output. This function merely notifies the library of the volume change, so that the library can inform other Spotify Connect-enabled devices. Calling this function invokes the SpCallbackPlaybackApplyVolume callback, which the application can use to apply the actual volume change.
Parameters
[in] | uint16_t volume | Volume in the range 0 (silence) to 65535 (full volume) |
Returns
Returns an error code
Notes:
- When the library is initialized, it assumes a volume level of 32768 (50% volume). The application must invoke SpPlaybackUpdateVolume at some point after calling SpInit to inform the library of the actual volume level of the device's audio output.
SpPlaybackGetVolume()
uint16_t SpPlaybackGetVolume(void)
Get the playback volume level.
This returns the last volume level that the application set using SpPlaybackUpdateVolume or that was reported to the application using SpCallbackPlaybackApplyVolume
Returns
Volume level in the range 0 (silence) to 65535 (full volume).
Notes:
- This API can be invoked from a callback.
SpPlaybackIsPlaying()
uint8_t SpPlaybackIsPlaying(void)
Is the playback status playing or paused.
Returns
1: Playback status is playing 0: Playback status is paused (or no playback has been started at all)
See also
Notes:
- This API can be invoked from a callback.
- The result of this API is analogous to the playback notifications kSpPlaybackNotifyPlay and kSpPlaybackNotifyPause
SpPlaybackIsAdPlaying()
uint8_t SpPlaybackIsAdPlaying(void)
Is the current track an Ad or not.
Returns
1: The current playing track is an Ad 0: The current playing track is not an Ad.
See also
Notes:
- This API can be invoked from a callback.
SpPlaybackIsShuffled()
uint8_t SpPlaybackIsShuffled(void)
Is "shuffle" mode enabled.
Returns
1: Shuffle is enabled 0: Shuffle is disabled
See also
Notes:
- This API can be invoked from a callback.
SpPlaybackIsRepeated()
uint8_t SpPlaybackIsRepeated(void)
Is "repeat" mode enabled.
Returns
1: Repeat is enabled 0: Repeat is disabled
See also
Notes:
- This API can be invoked from a callback.
SpPlaybackGetRepeatMode()
uint8_t SpPlaybackGetRepeatMode(void)
Which "repeat" mode is on.
Returns
0: Repeat is disabled 1: Repeat Context is enabled 2: Repeat Track is enabled
See also
Notes:
- This API can be invoked from a callback.
SpPlaybackIsActiveDevice()
uint8_t SpPlaybackIsActiveDevice(void)
Is the device the active playback device.
Returns
1: The device is the active playback device 0: Another device is the active playback device
See also
Notes:
- This API can be invoked from a callback.
SpPlaybackEnableShuffle()
SpError SpPlaybackEnableShuffle(uint8_t enable)
Enable or disable "shuffle" mode.
If the device is not the active speaker (SpPlaybackIsActiveDevice()), the error code kSpErrorNotActiveDevice is returned.
Parameters
[in] | uint8_t enable | 1 to enable, 0 to disable |
Returns
Returns an error code
See also
Notes:
- The change to the shuffle mode might not take effect if the API is invoked in the time window between requesting playback of a new context (e.g., by calling SpPlayUri and playback of the new context actually starting.
SpPlaybackEnableRepeat()
SpError SpPlaybackEnableRepeat(uint8_t enable)
Enable or disable "repeat" mode.
If the device is not the active speaker (SpPlaybackIsActiveDevice()), the error code kSpErrorNotActiveDevice is returned.
Parameters
[in] | uint8_t enable | 0 to disable, 1 to Repeat Context, 2 to Repeat Track The Repeat values were previously called Repeat and Repeat-1. |
Returns
Returns an error code
See also
SpPlaybackCycleRepeatMode()
SpError SpPlaybackCycleRepeatMode(void)
Cycle through the available repeat modes.
Cycles through repeat modes (repeat off, repeat context, repeat track) given their current availability. If for example repeat context is enabled and repeat track is disallowed due to restrictions, this API will go directly to repeat off.
Returns
Returns an error code.
SpPlaybackSetBitrate()
SpError SpPlaybackSetBitrate(enum SpPlaybackBitrate bitrate)
Change the bitrate at which compressed audio data is delivered.
This will take effect for the next chunk of audio data that is streamed from the backend. The format or sample rate of the audio data that is received does not change.
Parameters
[in] | enum SpPlaybackBitrate bitrate |
The bitrate to be set |
Returns
Returns an error code
SpPlaybackSetAvailableToPlay()
SpError SpPlaybackSetAvailableToPlay(uint8_t can_play)
Allow or disallow the device to start playback.
On some platforms, there might be certain situations in which playback should be disallowed temporarily. In this case, when the user tries to start playback on the device using the mobile application, the device should be marked as "Unavailable for playback" in the UI.
Parameters
[in] | uint8_t can_play | 2 to allow playback (default), 1 to disallow playback without becoming inactive, the playback will be paused, 0 to disallow playback and become inactive. |
See also
Notes:
- This functionality is reserved for specific integration scenarios. In most cases, when integrating the SDK into a device, this API must not be used. If the device is unable to play (for example, if a firmware upgrade is about to be performed), the application shall log out, shut down the library, and stop announcing the device via the ZeroConf.)
- If the device is currently the active device setting can_play to 0 will cause the notification kSpPlaybackNotifyBecameInactive to be sent. Playback-related APIs (SpPlaybackPlay(), ...) will return an error code. This setting will persist across logout/login.
SpPlaybackIsAvailableToPlay()
uint8_t SpPlaybackIsAvailableToPlay(void)
Is the device available for playback.
Returns
1: The device is available for playback 0: The device cannot accept playback requests nor start playback either.
See also
SpPlaybackSetDeviceInactive()
SpError SpPlaybackSetDeviceInactive(void)
Set the device inactive.
If the device is currently the active device, this function stops the playback if playing, sets the device inactive, and sends the notification kSpPlaybackNotifyBecameInactive If the device is already inactive, the error code kSpErrorNotActiveDevice is returned.
Returns
Returns an error code
See also
Notes:
- The device gets active and starts playing when integration calls SpPlaybackPlay or SpPlayUri
SpPlaybackIsDeviceControllable()
uint8_t SpPlaybackIsDeviceControllable(void)
Is the device controllable.
Returns
1: The device is controllable. 0: The device is not controllable so it cannot accept playback requests nor start playback either.
See also
SpPlaybackSetDeviceControllable()
SpError SpPlaybackSetDeviceControllable(uint8_t is_controllable)
Allow or disallow the device to be controllable.
On some platforms, there might be certain situations in which the control of the playback should be disallowed temporarily. In this case, when the user tries to start playback on the device using the mobile application, the device should be marked as "Unavailable for playback" in the UI.
Parameters
[in] | uint8_t is_controllable | When set to 0, eSDK will pause the playback and won’t accept local and remote playback commands, the device gets grayed off in the picker. Set to 1 to allow device control, eSDK will accept both local and remote playback commands and the device becomes available in the picker. |
Returns
Returns an error code
See also
Notes:
- This functionality is reserved for specific integration scenarios. It can be used to temporarily forbid playback when for example playing cutscenes in video games or taking a phone call while driving a car. This API should not be used if the device is unable to play (for example, if a firmware upgrade is about to be performed), the application shall then instead log out, shut down the library, and stop announcing the device via the ZeroConf.
SpPlaybackIncreaseUnderrunCount()
SpError SpPlaybackIncreaseUnderrunCount(uint32_t count)
Increase the underrun counter of the current track.
If playback underruns have been detected in the current track, use this API to report it to eSDK. This should only be called when there was no data to play at all and there was an audible glitch or gap for the user. It should only be called if audio was expected to be played and there was audio before. For example if eSDK is active and playing, but there is an underrun, report it. If eSDK is active and was requested to play something, but it never started, do not report it. If eSDK is active and playing and user skips, there is an expected gap, so report an underrun only if audio data started being delivered from eSDK and then stopped.
Parameters
[in] | uint32_t count |
A counter of how many underruns happened. More than one could have occurred since the last one. |
Returns
Returns an error code
SpPlaybackSetBandwidthLimit()
SpError SpPlaybackSetBandwidthLimit(uint32_t max_bytes_per_sec)
Set a limit on the download speed.
By calling this function eSDK will attempt to limit how fast it downloads a track. In some use cases it is preferred to not use the full bandwidth. At the beginning of a download eSDK will do a burst download and then try to obey the limit.
Parameters
[in] | uint32_t max_bytes_per_sec |
approximate bandwidth budget for downloads. To use default bandwidth specify 0. |
Returns
Returns an error code
Notes:
- eSDK is not guaranteed to stay strictly below the limit but will not exceed it by much. It is also not guaranteed to use all available bandwidth.
SpPlaybackSetRedeliveryMode()
SpError SpPlaybackSetRedeliveryMode(SpReDeliveryMode mode)
Activates redelivery of audio data on play or resume playback.
This function should be called to activate or deactivate audio redelivery for the next calls to SpPlaybackPlay When the client application can't keep unplayed audio in its playback buffers (for example when audio from some other source was played while Spotify was paused) the eSDK should be notified that redelivery of audio data is needed. The audio data is redelivered from the last playback position reported by the integration with the same precision as seek. eSDK will need to redownload the data that was already delivered to the integration and therefore there will be a penalty of increased data consumption and latencies. Only use this function when unplayed audio is discarded.
Returns
Returns an error code
SpPlaybackIsRedeliveryModeActivated()
SpReDeliveryMode SpPlaybackIsRedeliveryModeActivated(void)
Gets the status of redelivery mode.
When redelivery mode is activated or deactivated through the API SpPlaybackSetRedeliveryMode an internal state is updated to keep track of the redelivery behavior. This API exposes this internal state.
Returns
Returns redelivery mode status: kSpRedeliveryModeActivated or kSpRedeliveryModeDeactivated
SpZeroConfGetVars()
SpError SpZeroConfGetVars(struct SpZeroConfVars *vars)
Get variables for ZeroConf, mainly the "getInfo" request.
The application should use this function to retrieve the data that it should send in the response to the "getInfo" request. See the ZeroConf manual for more information. There are also other fields here that might be needed for ZeroConf.
Parameters
[out] | struct SpZeroConfVars * vars |
Structure to be filled with the variables |
Notes:
- This API can be invoked from a callback.
SpZeroConfAnnouncePause()
SpError SpZeroConfAnnouncePause(void)
Temporarily pause ZeroConf mDNS announcements.
Returns
Returns an error code
Notes:
- This call requires ZeroConf to be started by setting SpConfig::zeroconf_serve when calling SpInit
SpZeroConfAnnounceResume()
SpError SpZeroConfAnnounceResume(void)
Resume ZeroConf mDNS announcement after calling SpZeroConfAnnouncePause
Returns
Returns an error code
Notes:
- This call requires ZeroConf to be started by setting SpConfig::zeroconf_serve when calling SpInit
SpConnectionLoginZeroConf()
SpError SpConnectionLoginZeroConf(const char *username, const char *zero_conf_blob, const char *client_key, const char *login_id, const char *token_type)
Log in a user to Spotify using a ZeroConf credentials blob.
This function logs in with the information that the application receives in the "addUser" ZeroConf request. See the ZeroConf manual.
Parameters
[in] | const char * username |
Spotify username. UTF-8 encoded. Must not be longer than SP_MAX_USERNAME_LENGTH bytes (not UTF-8-encoded characters), not counting the terminating NULL. |
[in] | const char * zero_conf_blob |
Credentials blob from the “blob” field of the request. Must not be longer than SP_MAX_ZEROCONF_BLOB_LENGTH bytes, not counting the terminating NULL. |
[in] | const char * client_key |
Client key from the “clientKey” field of the request. This may be NULL if not supplied in the “addUser” request. Must not be longer than SP_MAX_CLIENT_KEY_LENGTH bytes, not counting the terminating NULL. |
[in] | const char * login_id |
Login ID from the “loginId” field of the request. This may be NULL if not supplied in the “addUser” request. Must not be longer than SP_MAX_LOGIN_ID_LENGTH bytes, not counting the terminating NULL. |
[in] | const char * token_type |
Token type from the “tokenType” field of the request. This may be NULL if not supplied in the “addUser” request. Must not be longer than SP_MAX_TOKEN_TYPE_LENGTH bytes, not counting the terminating NULL. |
Returns
Returns an error code
See also
Notes:
- The login is performed asynchronously. The return value only indicates whether the library is able to perform the login attempt. The status of the login will be reported via callbacks:
SpGetBrandName()
const char * SpGetBrandName(void)
This function can be used to get the brand name. If the field SpConfig::brand_display_name was set at SpInit function returns its value, otherwise it returns what was set in the mandatory field SpConfig::brand_name
Returns
The UTF-8-encoded brand name
Notes:
- This API can be invoked from a callback.
SpGetModelName()
const char * SpGetModelName(void)
This function can be used to get the model name. If the field SpConfig::model_display_name was set at SpInit function returns its value, otherwise it returns what was set in the mandatory field SpConfig::model_name
Returns
The UTF-8-encoded model name
Notes:
- This API can be invoked from a callback.
SpRegisterDeviceAliasCallbacks()
SpError SpRegisterDeviceAliasCallbacks(struct SpDeviceAliasCallbacks *cb, void *context)
Register callbacks related to device aliases.
Parameters
[in] | struct SpDeviceAliasCallbacks * cb |
Structure with pointers to individual callback functions. Any of the pointers in the structure may be NULL. |
[in] | void * context |
Application-defined pointer that will be passed unchanged as the context argument to the callbacks. |
Returns
Returns an error code
SpSetDeviceAliases()
SpError SpSetDeviceAliases(const struct SpDeviceAlias *aliases)
Update the device alias definitions.
Call this whenever the current alias definitions are updated. The id values for the aliases must be unique within the array. aliases Pointer to an array of SpDeviceAlias structs filled in with the new alias names and corresponding attributes. The array size must be of size SP_MAX_DEVICE_ALIASES.
Parameters
[in] | const struct SpDeviceAlias * aliases |
Pointer to an array of SpDeviceAlias structs filled in with the new alias names and corresponding attributes. The array size must be of size SP_MAX_DEVICE_ALIASES. |
SpRestrictDrmMediaFormats()
SpError SpRestrictDrmMediaFormats(const struct SpFormat formats[SP_MAX_SUPPORTED_FORMATS])
Restricts the list of DRM and media formats to a subset of the formats registered in SpInit To lift the restrictions use SpRestoreDrmMediaFormats
See also
SpRestoreDrmMediaFormats()
SpError SpRestoreDrmMediaFormats(void)
Resets the list of DRM formats and media formats to the ones registered in SpInit
See also
Content
#include "spotify_embedded_content.h"
Data Structures
Data Structure | Description |
---|---|
SpContentCallbacks | Callbacks to be registered with SpRegisterContentCallbacks |
Typedefs
Typedef | Description |
---|---|
SpCallbackTrackCacheState | This callback, if set by the client, is called by eSDK to inform how many percent of the particular track are cached. It is measured from the beginning of the track. E.g. if 60 is reported it means that 60% of the track is cached starting from the beginning. |
SpCallbackStorageKeyContentMapping | This callback, if set by the client, is called by eSDK to notify how the storage_key is mapped to particular content being stored. SpContentType is used to specify exact content type. For example: hint being equal to kSpContentTrack means that the descriptor’s representation is spotify:track:[base62]. |
SpCallbackTrackRelinked | This callback, if set by the client, is called by eSDK to notify about the fact that requested track is substituted with another (relinked) one during prefetch/offline process. |
SpCallbackTrackRemoved | This callback, if set by the client, is called by eSDK to notify that the track is removed. |
SpCallbackOnAvailableContainer | Callback for each available container. |
Enumerations
Functions
Function | Description |
---|---|
SpRegisterContentCallbacks |
’
Data Structures
SpContentCallbacks
Return to Content data structures
Callbacks to be registered with SpRegisterContentCallbacks
Any of the pointers may be NULL.
Notes:
- See the documentation of the callback typedefs for information about the individual callbacks.
struct SpContentCallbacks {
SpCallbackTrackCacheState track_state_callback;
SpCallbackStorageKeyContentMapping store_key_map_callback;
SpCallbackTrackRelinked track_relink_callback;
SpCallbackTrackRemoved track_removed_callback;
SpCallbackOnAvailableContainer on_available_container;
};
SpCallbackTrackCacheState | track_state_callback | Track cached state callback. |
|
| |||
SpCallbackStorageKeyContentMapping | store_key_map_callback | Content mapping callback. |
|
| |||
SpCallbackTrackRelinked | track_relink_callback | Notify about track relink during prefetch/offline. |
|
SpCallbackTrackRemoved | track_removed_callback | Notify about track removal. |
|
SpCallbackOnAvailableContainer | on_available_container | Notify about an available container item. |
Typedefs
SpCallbackTrackCacheState()
typedef void(* SpCallbackTrackCacheState)(const char *track_uri, uint32_t percents, void *context)
This callback, if set by the client, is called by eSDK to inform how many percent of the particular track are cached. It is measured from the beginning of the track. E.g. if 60 is reported it means that 60% of the track is cached starting from the beginning.
Parameters
[in] | const char * track_uri |
Track URI which status is reported. |
[in] | uint32_t percents |
How much data is cached in percent. Range: [0 - 100%] |
[in] | void * context |
Context provided in callback register procedure. |
Notes:
- The application should not block or call other API functions in the callback. This callback is called before each track delivery is started.
SpCallbackStorageKeyContentMapping()
typedef void(* SpCallbackStorageKeyContentMapping)(const char *storage_key, const char *descriptor, enum SpContentType hint, void *context)
This callback, if set by the client, is called by eSDK to notify how the storage_key is mapped to particular content being stored. SpContentType is used to specify exact content type. For example: hint being equal to kSpContentTrack means that the descriptor's representation is spotify:track:[base62].
Parameters
[in] | const char * storage_key |
Storage key that was used in Alloc/Read/Write API. |
[in] | const char * descriptor |
Content descriptor. Value depends on hint. |
See also
Notes:
- The application should not block or call other API functions in the callback. This callback is called as soon as possible after Alloc callback of Storage API has been called and succeeds.
SpCallbackTrackRelinked()
typedef void(* SpCallbackTrackRelinked)(const char *original_uri, const char *new_uri, void *context)
This callback, if set by the client, is called by eSDK to notify about the fact that requested track is substituted with another (relinked) one during prefetch/offline process.
Parameters
[in] | const char * original_uri |
Initial URI passed into eSDK PrefetchURI/OfflineURI function calls. |
[in] | const char * new_uri |
URI that is obtained after relink has happened. |
[in] | void * context |
Context provided in callback register procedure. |
SpCallbackTrackRemoved()
typedef void(* SpCallbackTrackRemoved)(const char *track_uri, void *context)
This callback, if set by the client, is called by eSDK to notify that the track is removed.
track_uri URI passed into eSDK PlayURI/PrefetchURI/OfflineURI function calls. context Context provided in callback register procedure.
Parameters
[in] | const char * track_uri |
URI passed into eSDK PlayURI/PrefetchURI/OfflineURI function calls. |
[in] | void * context |
Context provided in callback register procedure. |
SpCallbackOnAvailableContainer()
typedef void(* SpCallbackOnAvailableContainer)(const char *uri, int total, void *context)
Callback for each available container.
Parameters
[in] | const char * uri |
URI of a container |
[in] | int total |
Total number of containers |
[in] | void * context |
Context provided in callback register procedure. |
Notes:
- Experimental, subject of change
Enumerations
SpContentType
Return to Content enumerations
enum SpContentType {
kSpContentTrack,
kSpContentTrackMetadata,
};
kSpContentTrack | Content pointed by descriptor is spotify playable item URI (track or episode) |
kSpContentTrackMetadata | Content pointed by descriptor is spotify playable item URI for which metadata is saved. |
Functions
SpRegisterContentCallbacks()
SpError SpRegisterContentCallbacks(struct SpContentCallbacks *callbacks, void *context)
Parameters
[in] | struct SpContentCallbacks * callbacks |
Structure with pointers to individual callback functions. Any of the pointers in the structure may be NULL. |
[in] | void * context |
Application-defined pointer that will be passed unchanged as the context argument to the callbacks. |
Returns
Returns an error code
Hal
#include "spotify_embedded_hal.h"
Data Structures
Data Structure | Description |
---|---|
SpSockaddr | Struct contains resolved hostname IP address and its family. |
SpDnsHALCallbacks | Callbacks to be registered with SpRegisterDnsHALCallbacks |
SpSocketHandle | Socket handle type. |
SpSocketHALCallbacks | Callbacks to be registered with SpRegisterSocketHALCallbacks |
Typedefs
Typedef | Description |
---|---|
SpCallbackPerformDNSLookup | This callback, if set by the client, is called by eSDK to perform DNS lookups. It should be robust against slow name resolutions (e.g. poor network conditions) by performing lookups asynchronously. Otherwise SpPumpEvents might block for too long and cause audio stutters. See documentation for return value for more recommendations w.r.t. asynchronous implementation. |
SpCallbackSocketCreate | This callback, if set by the client, is called by eSDK to create a socket of a certain type and family. |
SpCallbackSocketSetOption | This callback, if set by the client, is called by eSDK to set specific options on the previously created socket. |
SpCallbackSocketClose | This callback, if set by the client, is called by eSDK to close the previously opened socket. |
SpCallbackSocketBind | This callback, if set by the client, is called by eSDK to bind to the provided socket. |
SpCallbackSocketListen | This callback, if set by the client, is called by eSDK to start listening on the provided socket. This callback has no effect on UDP sockets. |
SpCallbackSocketConnect | This callback, if set by the client, is called by eSDK to connect to the specified address and remote port. |
SpCallbackSocketAccept | This callback, if set by the client, is called by eSDK to accept connection on the provided socket. |
SpCallbackSocketRead | This callback, if set by the client, is called by eSDK to read data from the socket. |
SpCallbackSocketWrite | This callback, if set by the client, is called by eSDK to write data to the socket. |
SpCallbackSocketReadFrom | This callback, if set by the client, is called by eSDK to read data from the socket addressed by the SpSockaddr instance. |
SpCallbackSocketWriteTo | This callback, if set by the client, is called by eSDK to write data to the socket addressed by the SpSockaddr instance. |
SpCallbackSocketError | This callback, if set by the client, is called by eSDK to get the underlying OS error code. |
SpCallbackSocketReadable | This callback, if set by the client, is called by eSDK to figure out if the socket is readable. |
SpCallbackSocketWriteable | This callback, if set by the client, is called by eSDK to figure out if the socket is writable. |
SpCallbackLocalAddresses | This callback, if set by the client, is called by eSDK to get local interface addresses. |
SpCallbackSocketAddress | This callback, if set by the client, is called by eSDK to provide platform defined representation of address that can be used in SpCallbackSocketReadFrom and SpCallbackSocketWriteTo The client is responsible for providing a sufficient lifetime of the returned pointer. |
SpCallbackPump | This callback, if set by the client, is called by eSDK to pump the network layer. |
Enumerations
Functions
Function | Description |
---|---|
SpRegisterDnsHALCallbacks | Register HAL-related callbacks. Should be called right after SpInit |
SpGetDefaultDnsHALCallbacks | Get eSDK’s default DNS callbacks. |
SpRegisterSocketHALCallbacks | Register socket HAL-related callbacks. To remove callbacks, call SpRegisterSocketHALCallbacks with SpSocketHALCallbacks initialized to zeros. |
SpGetDefaultSocketHALCallbacks | Get eSDK’s default socket callbacks. |
’
Data Structures
SpSockaddr
Struct contains resolved hostname IP address and its family.
struct SpSockaddr {
enum SpIPFamily family;
uint8_t addr;
int port;
};
enum SpIPFamily | family | IP protocol family for which lookup is requested. |
uint8_t | addr | Ip address. Network byte order. |
int | port | Contains port value if applicable. Host byte order. |
SpDnsHALCallbacks
Callbacks to be registered with SpRegisterDnsHALCallbacks
Any of the pointers may be NULL. To remove DNS callback at any time call SpRegisterDnsHALCallbacks with SpDnsHALCallbacks::dns_lookup_callback set to NULL.
Notes:
- See the documentation of the callback typedefs for information about the individual callbacks.
struct SpDnsHALCallbacks {
SpCallbackPerformDNSLookup dns_lookup_callback;
};
SpCallbackPerformDNSLookup | dns_lookup_callback | DNS lookup callback. If NULL eSDK will use its internal DNS resolve mechanism. |
SpSocketHandle
Socket handle type.
struct SpSocketHandle {
void *handle;
void *tls;
};
void * | handle | Platform defined socket representation. |
void * | tls | Can be used by the TLS implementation to store connection specific state. |
SpSocketHALCallbacks
Callbacks to be registered with SpRegisterSocketHALCallbacks
Any of the pointers may be NULL. See the documentation of the callback typedefs for information about the individual callbacks.
struct SpSocketHALCallbacks {
SpCallbackSocketCreate socket_create;
SpCallbackSocketSetOption socket_set_option;
SpCallbackSocketClose socket_close;
SpCallbackSocketBind socket_bind;
SpCallbackSocketListen socket_listen;
SpCallbackSocketConnect socket_connect;
SpCallbackSocketAccept socket_accept;
SpCallbackSocketRead socket_read;
SpCallbackSocketWrite socket_write;
SpCallbackSocketReadFrom socket_read_from;
SpCallbackSocketWriteTo socket_write_to;
SpCallbackSocketError socket_error;
SpCallbackSocketReadable socket_readable;
SpCallbackSocketWriteable socket_writable;
SpCallbackLocalAddresses local_addresses;
SpCallbackSocketAddress socket_address;
SpCallbackPump on_pump;
};
SpCallbackSocketCreate | socket_create | Callback to create socket instance. |
SpCallbackSocketSetOption | socket_set_option | Callback to set options on created socket. |
SpCallbackSocketClose | socket_close | Callback to close the socket. |
SpCallbackSocketBind | socket_bind | Callback to bind to socket. |
SpCallbackSocketListen | socket_listen | Callback to start listening the socket. |
SpCallbackSocketConnect | socket_connect | Callback to connect to socket. |
SpCallbackSocketAccept | socket_accept | Callback to accept connection on socket. |
SpCallbackSocketRead | socket_read | Callback to read data from socket. |
SpCallbackSocketWrite | socket_write | Callback to write data to socket. |
SpCallbackSocketReadFrom | socket_read_from | Callback to read data from socket pointed by address. |
SpCallbackSocketWriteTo | socket_write_to | Callback to write data to socket pointed by address. |
SpCallbackSocketError | socket_error | Callback to get OS error on socket. |
SpCallbackSocketReadable | socket_readable | Callback to get readable state on socket. |
SpCallbackSocketWriteable | socket_writable | Callback to get writable state on socket. |
SpCallbackLocalAddresses | local_addresses | Callback to get local interface addresses. |
SpCallbackSocketAddress | socket_address | Callback to platform address representation. |
SpCallbackPump | on_pump | Callback to pump network layer. |
Typedefs
SpCallbackPerformDNSLookup()
typedef enum SpCallbackPerformDNSLookup)(const char *hostname, struct SpSockaddr *sockaddr, void *context)
This callback, if set by the client, is called by eSDK to perform DNS lookups. It should be robust against slow name resolutions (e.g. poor network conditions) by performing lookups asynchronously. Otherwise SpPumpEvents might block for too long and cause audio stutters. See documentation for return value for more recommendations w.r.t. asynchronous implementation.
Parameters
[in] | const char * hostname |
Name to be resolved. |
[out] | struct SpSockaddr * sockaddr |
Pointer to SpSockaddr structure. DNS lookup can result in a single instance of SpSockaddr structure only. If the underlying implementation (getaddrinfo(), getaddrinfo_a() etc) returns multiple addresses (IPv6, IPv4, …) this callback is responsible for choosing the best suitable one. Port value of SpSockaddr is ignored. |
[inout] | void * context |
Context provided in callback register procedure. |
See also
Notes:
- See SpRegisterDnsHALCallbacks for recommendation when it makes sense to provide a custom DNS callback.
- The application should not block or call other API functions in the callback.
SpCallbackSocketCreate()
typedef enum SpCallbackSocketCreate)(enum SpIPFamily family, enum SpSocketType type, enum SpSocketPool pool_id, struct SpSocketHandle **socket, void *context)
This callback, if set by the client, is called by eSDK to create a socket of a certain type and family.
Parameters
[in] | enum SpIPFamily family |
Socket family as specified in SpIPFamily |
[in] | enum SpSocketType type |
Socket type as specified in SpSocketType |
[in] | enum SpSocketPool pool_id |
Socket pool ID to create the new socket from |
[in] | struct SpSocketHandle ** socket |
Pointer to valid SpSocketHandle instance in case of success. Unchanged in case of failure. |
[in] | void * context |
Context provided in callback register procedure. |
Notes:
- The application should not block or call other API functions in the callback.
SpCallbackSocketSetOption()
typedef enum SpCallbackSocketSetOption)(struct SpSocketHandle *socket, enum SpSocketOptions option, void *value, void *context)
This callback, if set by the client, is called by eSDK to set specific options on the previously created socket.
Parameters
[in] | struct SpSocketHandle * socket |
Socket instance to perform action with. |
[in] | enum SpSocketOptions option |
One of SpSocketOptions options. |
[in] | void * value |
Option value. Depends on the particular SpSocketOptions option. |
[in] | void * context |
Context provided in callback register procedure. |
Notes:
- The application should not block or call other API functions in the callback.
SpCallbackSocketClose()
typedef enum SpCallbackSocketClose)(struct SpSocketHandle *socket, void *context)
This callback, if set by the client, is called by eSDK to close the previously opened socket.
Parameters
[in] | struct SpSocketHandle * socket |
Socket instance to perform action with. |
[in] | void * context |
Context provided in callback register procedure. |
Notes:
- The application should not block or call other API functions in the callback.
SpCallbackSocketBind()
typedef enum SpCallbackSocketBind)(struct SpSocketHandle *socket, int *port, void *context)
This callback, if set by the client, is called by eSDK to bind to the provided socket.
Parameters
[in] | struct SpSocketHandle * socket |
Socket instance to perform action with. |
[in] | int * port |
Port which eSDK would listen to (host byte order). If the referenced value is zero, port has to be used to return the actual bound port. |
[in] | void * context |
Context provided in callback register procedure. |
Notes:
- The application should not block or call other API functions in the callback.
SpCallbackSocketListen()
typedef enum SpCallbackSocketListen)(struct SpSocketHandle *socket, int backlog, void *context)
This callback, if set by the client, is called by eSDK to start listening on the provided socket. This callback has no effect on UDP sockets.
Parameters
[in] | struct SpSocketHandle * socket |
Socket instance to perform action with. |
[in] | int backlog |
Parameter defines the maximum length for the queue of pending connections. |
[in] | void * context |
Context provided in callback register procedure. |
Notes:
- The application should not block or call other API functions in the callback.
SpCallbackSocketConnect()
typedef enum SpCallbackSocketConnect)(struct SpSocketHandle *socket, const struct SpSockaddr *addr, void *context)
This callback, if set by the client, is called by eSDK to connect to the specified address and remote port.
Parameters
[in] | struct SpSocketHandle * socket |
Socket instance to perform action with. |
[in] | const struct SpSockaddr * addr |
Address to connect to. |
[in] | void * context |
Context provided in callback register procedure. |
Notes:
- The application should not block or call other API functions in the callback.
SpCallbackSocketAccept()
typedef enum SpCallbackSocketAccept)(struct SpSocketHandle *socket, enum SpSocketPool pool_id, struct SpSocketHandle **out_socket, void *context)
This callback, if set by the client, is called by eSDK to accept connection on the provided socket.
Parameters
[in] | struct SpSocketHandle **out_ socket |
Socket instance to perform action with. |
[in] | enum SpSocketPool pool_id |
Socket pool ID to create the new socket from |
[in] | struct SpSocketHandle ** out_socket |
Socket created by accepting connection. |
[in] | void * context |
Context provided in callback register procedure. |
Notes:
- The application should not block or call other API functions in the callback.
SpCallbackSocketRead()
typedef enum SpCallbackSocketRead)(struct SpSocketHandle *socket, void *data, int data_size, int *bytes_read, void *context)
This callback, if set by the client, is called by eSDK to read data from the socket.
Parameters
[in] | struct SpSocketHandle * socket |
Socket instance to perform action with. |
[in] | void * data |
Buffer to read data into. |
[in] | int data_size |
Amount of requested data to read. |
[in] | int * bytes_read |
Pointer to store how many bytes were actually read. If NULL, the read operation is still performed. Should stay unchanged if the read operation has failed. |
[in] | void * context |
Context provided in callback register procedure. |
Notes:
- The application should not block or call other API functions in the callback.
SpCallbackSocketWrite()
typedef enum SpCallbackSocketWrite)(struct SpSocketHandle *socket, const void *data, int data_size, int *bytes_written, void *context)
This callback, if set by the client, is called by eSDK to write data to the socket.
Parameters
[in] | struct SpSocketHandle * socket |
Socket instance to perform action with. |
[in] | const void * data |
Buffer with data to be written. |
[in] | int data_size |
Amount of data to write. |
[in] | int * bytes_written |
Pointer to store how many bytes were actually written. If NULL, the write operation is still performed. Should stay unchanged if the write operation has failed. |
[in] | void * context |
Context provided in callback register procedure. |
Notes:
- The application should not block or call other API functions in the callback.
SpCallbackSocketReadFrom()
typedef enum SpCallbackSocketReadFrom)(struct SpSocketHandle *socket, void *data, int data_size, const void **addr, int *bytes_read, void *context)
This callback, if set by the client, is called by eSDK to read data from the socket addressed by the SpSockaddr instance.
Parameters
[in] | struct SpSocketHandle * socket |
Socket instance to perform action with. |
[in] | void * data |
Buffer to read data into. |
[in] | int data_size |
Amount of requested data to read. |
[in] | const void ** addr |
Platform defined address representation. See SpCallbackSocketAddress |
[in] | int * bytes_read |
Pointer to store how many bytes were actually read. If NULL, read is still performed. Should stay unchanged if reading has failed. |
[in] | void * context |
Context provided in callback register procedure. |
Notes:
- The application should not block or call other API functions in the callback. This callback should mirror the behavior of recvfrom() for connected/non-connected sockets.
SpCallbackSocketWriteTo()
typedef enum SpCallbackSocketWriteTo)(struct SpSocketHandle *socket, const void *data, int data_size, const void *addr, int *bytes_written, void *context)
This callback, if set by the client, is called by eSDK to write data to the socket addressed by the SpSockaddr instance.
Parameters
[in] | struct SpSocketHandle * socket |
Socket instance to perform action with. |
[in] | const void * data |
Buffer with data to be written. |
[in] | int data_size |
Amount of data to write. |
[in] | const void * addr |
Platform defined address representation. See SpCallbackSocketAddress |
[in] | int * bytes_written |
Pointer to store how many bytes were actually written. If NULL, write is still performed. Should stay unchanged if writing has failed. |
[in] | void * context |
Context provided in callback register procedure. |
Notes:
- The application should not block or call other API functions in the callback. This callback should mirror the behavior of sendto() for connected/non-connected sockets.
SpCallbackSocketError()
typedef int(* SpCallbackSocketError)(struct SpSocketHandle *socket, void *context)
This callback, if set by the client, is called by eSDK to get the underlying OS error code.
Parameters
[in] | struct SpSocketHandle * socket |
Socket instance for which error code is requested. |
[in] | void * context |
Context provided in callback register procedure. |
Notes:
- The application should not block or call other API functions in the callback.
SpCallbackSocketReadable()
typedef int(* SpCallbackSocketReadable)(struct SpSocketHandle *socket, void *context)
This callback, if set by the client, is called by eSDK to figure out if the socket is readable.
Parameters
[in] | struct SpSocketHandle * socket |
Socket instance to perform action with. |
[in] | void * context |
Context provided in callback register procedure. |
Notes:
- The application should not block or call other API functions in the callback.
SpCallbackSocketWriteable()
typedef int(* SpCallbackSocketWriteable)(struct SpSocketHandle *socket, void *context)
This callback, if set by the client, is called by eSDK to figure out if the socket is writable.
Parameters
[in] | struct SpSocketHandle * socket |
Socket instance to perform action with. |
[in] | void * context |
Context provided in callback register procedure. |
Notes:
- The application should not block or call other API functions in the callback.
SpCallbackLocalAddresses()
typedef void(* SpCallbackLocalAddresses)(struct SpSockaddr *addrs, int *num_addrs, void *context)
This callback, if set by the client, is called by eSDK to get local interface addresses.
Parameters
[in] | int *num_ addrs |
Pointer to array of SpSockaddr to store the data. Data in network byte order. |
[in] | int * num_addrs |
eSDK will invoke this callback with a max capacity of the given array. The callback has to set the value to the actual number of returned items. If the client can’t get local interfaces, implementation should fill num_addrs with 0. |
[in] | void * context |
Context provided in callback register procedure. |
Notes:
- The application should not block or call other API functions in the callback.
SpCallbackSocketAddress()
typedef const void *(* SpCallbackSocketAddress)(const struct SpSockaddr *addr, void *context)
This callback, if set by the client, is called by eSDK to provide platform defined representation of address that can be used in SpCallbackSocketReadFrom and SpCallbackSocketWriteTo The client is responsible for providing a sufficient lifetime of the returned pointer.
Parameters
[in] | const struct SpSockaddr * addr |
Address to convert. Network byte order. |
[in] | void * context |
Context provided in callback register procedure. |
Notes:
- The application should not block or call other API functions in the callback.
SpCallbackPump()
typedef enum SpCallbackPump)(unsigned max_wait_ms, void *context)
This callback, if set by the client, is called by eSDK to pump the network layer.
Parameters
[in] | unsigned max_wait_ms | Maximum time to wait in one pump call |
[in] | void * context |
Context provided in callback register procedure. |
Notes:
- The application should not block or call other API functions in the callback.
Enumerations
SpIPFamily
enum SpIPFamily {
kSpIPV4,
kSpIPV6,
};
kSpIPV4 | IP v4 family. |
kSpIPV6 | IP v6 family. |
SpSocketPool
enum SpSocketPool {
kSpSocketPoolGeneral,
kSpSocketPoolZeroConf,
};
kSpSocketPoolGeneral | Sockets used for backend, streaming, etc. |
kSpSocketPoolZeroConf | Sockets used for ZeroConf. |
SpSocketType
enum SpSocketType {
kSpSocketStream,
kSpSocketDgram,
};
kSpSocketStream | Stream socket type. |
kSpSocketDgram | Datagram socket type. |
SpSocketOptions
enum SpSocketOptions {
kSpSocketNonBlocking,
kSpSocketReuseAddr,
kSpSocketReusePort,
kSpSocketMulticastTTL,
kSpSocketMulticastLoop,
kSpSocketMembership,
kSpSocketMcastSendIf,
};
kSpSocketNonBlocking | Nonblocking mode has to be set by the implementation if possible. POSIX analog: TCP_NODELAY. Option is passed as an intptr_t in a range [0, 1]. |
kSpSocketReuseAddr | Reuse address mode has to be set if possible. POSIX analog: SO_REUSEADDR. Option is passed as an intptr_t in a range [0, 1]. |
kSpSocketReusePort | Reuse port mode has to be set if possible. POSIX analog: SO_REUSEPORT. Option is passed an intptr_t in a range [0, 1]. |
kSpSocketMulticastTTL | Multicast TTL has to be set if possible. POSIX analog: IP_MULTICAST_TTL. Option is passed as an intptr_t in a range [0, 255]. |
kSpSocketMulticastLoop | Multicast loop has to be set if possible. POSIX analog: IP_MULTICAST_LOOP. Option is passed as an intptr_t in a range [0, 1]. |
kSpSocketMembership | Set group address if possible. POSIX analog: IP_ADD_MEMBERSHIP. Option is passed as a pointer to SpSockaddr Address is in network byte order. Port field is not applicable. |
kSpSocketMcastSendIf | Set outgoing multicast interface. POSIX analog: IP_MULTICAST_IF. Option is passed as a pointer to SpSockaddr Address is in network byte order. Port field is not applicable. |
Functions
SpRegisterDnsHALCallbacks()
SpError SpRegisterDnsHALCallbacks(struct SpDnsHALCallbacks *callbacks, void *context)
Register HAL-related callbacks. Should be called right after SpInit
Parameters
[in] | struct SpDnsHALCallbacks * callbacks |
Structure with pointers to individual callback functions. Any of the pointers in the structure may be NULL. |
[in] | void * context |
Application-defined pointer that will be passed unchanged as the context argument to the callbacks. |
Returns
Returns an error code.
Notes:
- To remove DNS callback at any time call SpRegisterDnsHALCallbacks with SpDnsHALCallbacks::dns_lookup_callback set to NULL.
- eSDK provides built-in implementation for DNS lookups. For integrations built with glibc = 2.2.3 DNS lookups will be implemented via getaddrinfo_a() and therefore will be done asynchronously. Such integrations have to link libanl (-lanl). Remaining builds will use blocking DNS lookups (e.g. getaddrinfo() for POSIX). Depending on the platform's timeout settings they might cause SpPumpEvents to block for a long time and result in audio stutters. For affected platforms it's recommended to provide an asynchronous implementation instead.
SpGetDefaultDnsHALCallbacks()
SpError SpGetDefaultDnsHALCallbacks(struct SpDnsHALCallbacks *callbacks)
Get eSDK's default DNS callbacks.
Parameters
[in] | struct SpDnsHALCallbacks * callbacks |
SpDnsHALCallbacks struct to be populated with pointers to callback functions |
Returns
Returns an error code.
Notes:
- These callbacks are made available so they may be wrapped by custom DNS functions provided with SpRegisterDnsHALCallbacks
SpRegisterSocketHALCallbacks()
SpError SpRegisterSocketHALCallbacks(struct SpSocketHALCallbacks *callbacks, void *context)
Register socket HAL-related callbacks. To remove callbacks, call SpRegisterSocketHALCallbacks with SpSocketHALCallbacks initialized to zeros.
Parameters
[in] | struct SpSocketHALCallbacks * callbacks |
Structure with pointers to individual callback functions. Either all pointers are NULL or all are valid. |
[in] | void * context |
Application-defined pointer that will be passed unchanged as the context argument to the callbacks. |
Returns
Returns an error code
Notes:
- A call to this function has to be performed before SpInit is called. Calling this function when eSDK is initialized will fail with kSpErrorAlreadyInitialized
SpGetDefaultSocketHALCallbacks()
SpError SpGetDefaultSocketHALCallbacks(struct SpSocketHALCallbacks *callbacks, void **context)
Get eSDK's default socket callbacks.
Parameters
[in] | struct SpSocketHALCallbacks * callbacks |
SpSocketHALCallbacks struct to be populated with pointers to callback functions |
[in] | void ** context |
the default context that is being used. |
Returns
Returns an error code.
Notes:
- These callbacks are made available so they may be wrapped by custom socket functions provided with SpRegisterSocketHALCallbacks
Log
#include "spotify_embedded_log.h"
Macros and Constants
Define | Value |
---|---|
SP_FILE_NAME | FILE |
SP_LOG_DEFAULT_LEVEL | SP_LOG_LEVEL_INFO |
SP_LOG_DEFINE_TRACE_OBJ | struct |
SP_LOG_DECLARE_TRACE_OBJ | extern struct |
SP_LOG_REGISTER_TRACE_OBJ | See macro below |
SP_LOG | See macro below |
SpLogFatal | See macro below |
SpLogError | See macro below |
SpLogWarning | |
SpLogInfo | See macro below |
SpLogDebug | See macro below |
SpLogTrace | See macro below |
Data Structures
Data Structure | Description |
---|---|
SpLogTraceObject | Trace object. |
Enumerations
Functions
Function | Description |
---|---|
SpLogRegisterTraceObject | Register a defined trace object with eSDK. |
SpLog | Output a debug message via eSDK. |
SpLogSetLevel | Control the current logging level. |
SpLogGetLevels | Get registered trace objects and log levels. |
Macros and Constants
SP_FILE_NAME
#define SP_FILE_NAME __FILE__
Preferred macro to log the file name, you might redefine SP_FILE_NAME using basename() or use -ffile-prefix-map.
SP_LOG_DEFAULT_LEVEL
#define SP_LOG_DEFAULT_LEVEL SP_LOG_LEVEL_INFO
Default trace log level.
SP_LOG_DEFINE_TRACE_OBJ
#define SP_LOG_DEFINE_TRACE_OBJ struct
Macro to define a trace object.
obj Name of the trace object
SP_LOG_DECLARE_TRACE_OBJ
#define SP_LOG_DECLARE_TRACE_OBJ extern struct
Macro to declare a previously defined trace object.
obj Name of the trace object
SP_LOG_REGISTER_TRACE_OBJ
#define SP_LOG_REGISTER_TRACE_OBJ SpLogRegisterTraceObject(&trace_obj_##obj)
Macro to register a previously defined trace object.
obj Name of the trace object
SP_LOG
#define SP_LOG do { \
if (trace_obj_##obj.level >= lvl) { \
Macro that outputs a trace message.
obj Trace object name lvl Trace level for the message file Source file name func Calling function name line Line number in the source file
SpLogFatal
#define SpLogFatal SP_LOG(obj, SP_LOG_LEVEL_FATAL, SP_FILE_NAME, __func__, __LINE__, __VA_ARGS__)
Emit trace message with SP_LOG_LEVEL_FATAL.
SpLogError
#define SpLogError SP_LOG(obj, SP_LOG_LEVEL_ERROR, SP_FILE_NAME, __func__, __LINE__, __VA_ARGS__)
Emit trace message with SP_LOG_LEVEL_ERROR.
SpLogWarning
#define SpLogWarning
Emit trace message with SP_LOG_LEVEL_WARNING.
SpLogInfo
#define SpLogInfo SP_LOG(obj, SP_LOG_LEVEL_INFO, SP_FILE_NAME, __func__, __LINE__, __VA_ARGS__)
Emit trace message with SP_LOG_LEVEL_INFO.
SpLogDebug
#define SpLogDebug SP_LOG(obj, SP_LOG_LEVEL_DEBUG, SP_FILE_NAME, __func__, __LINE__, __VA_ARGS__)
Emit trace message with SP_LOG_LEVEL_DEBUG.
SpLogTrace
#define SpLogTrace SP_LOG(obj, SP_LOG_LEVEL_TRACE, SP_FILE_NAME, __func__, __LINE__, __VA_ARGS__)
Emit trace message with SP_LOG_LEVEL_TRACE.
’
Data Structures
SpLogTraceObject
Trace object.
The trace object is an abstraction of a specific trace message category and an associated log level. The level can be changed freely for individual trace objects.
struct SpLogTraceObject {
SpLogLevel level;
const char *name;
};
SpLogLevel | level | The current debug level for this trace object. |
const char * | name | The trace category name describing this trace object. |
Enumerations
SpLogLevel
enum SpLogLevel {
SP_LOG_LEVEL_FATAL,
SP_LOG_LEVEL_ERROR,
SP_LOG_LEVEL_WARNING,
SP_LOG_LEVEL_INFO,
SP_LOG_LEVEL_DEBUG,
SP_LOG_LEVEL_TRACE,
};
SP_LOG_LEVEL_FATAL | Indicates a severe abnormal condition and program termination. |
SP_LOG_LEVEL_ERROR | Indicates an abnormal condition that could result in degraded functionality. |
SP_LOG_LEVEL_WARNING | Indicates a condition that probably has some impact on execution or performance. |
SP_LOG_LEVEL_INFO | Informational message. |
SP_LOG_LEVEL_DEBUG | Debug message. |
SP_LOG_LEVEL_TRACE | Trace message. |
Functions
SpLogRegisterTraceObject()
SpError SpLogRegisterTraceObject(struct SpLogTraceObject *obj)
Register a defined trace object with eSDK.
Parameters
[in] | struct SpLogTraceObject * obj |
Pointer to trace object |
Returns
Return kSpErrorOk on success, or error code on failure.
SpLog()
void SpLog(const struct SpLogTraceObject *obj, SpLogLevel level, const char *file, const char *func, int line, const char *format,...)
Output a debug message via eSDK.
obj Pointer to trace object level The log level associated this this message file The source file from where the call is made, see SP_FILE_NAME. func The function name from where the call is made, typically __func__. line The line number from where the call is made, typically __LINE__. format A printf style format string followed by arguments.
Parameters
[in] | const struct SpLogTraceObject * obj |
Pointer to trace object |
[in] | SpLogLevel level | The log level associated this this message |
[in] | const char * file |
The source file from where the call is made, see SP_FILE_NAME. |
[in] | const char * func |
The function name from where the call is made, typically func. |
[in] | int line |
The line number from where the call is made, typically LINE. |
[in] | const char * format |
A printf style format string followed by arguments. |
SpLogSetLevel()
SpError SpLogSetLevel(const char *category, SpLogLevel level)
Control the current logging level.
Control the logging level for a particular category. If the current configured log level is greater than or equal to the level associated with the message, the log message will be passed to the debug log callback. Each log message is also associated with a category. The category is a string that is included in the log message output. Each individual category has a separate current log level. The log messages produced by the eSDK are formatted as: LEVEL CATEGORY MESSAGE where LEVEL is a single letter indicating the log level (E=Error, I=Info, etc.), CATEGORY is a short string that identifies the log category, for example 'api' and MESSAGE is the actual debug message. As an example, a debug output string with level set to SP_LOG_LEVEL_ERROR (letter "E") and the category "api" could look something like this (the timestamp is not actually part of the debug message from eSDK, but added by the SpCallbackDebugMessage Therefore, the format may not exactly match the example below).
Parameters
[in] | const char * category |
Identifies the log category for which to set the logging level. If NULL is passed in this parameter, the level will be applied to all categories. |
[in] | SpLogLevel level | The log level defined by SpLogLevel |
Returns
Returns an error code if the category is not a valid log category.
SpLogGetLevels()
SpError SpLogGetLevels(char *buffer, int buffer_len)
Get registered trace objects and log levels.
The information about trace objects and levels is represented as a string containing comma separated tuples level:trace obj, e.g. "4:app,4:esdk,4:audio".
Parameters
[in] | char * buffer |
A buffer to copy the string to. |
[in] | int buffer_len |
Length of the buffer |
Returns
Returns an error code if the buffer is not big enough.
Media
#include "spotify_embedded_media.h"
Data Structures
Data Structure | Description |
---|---|
SpStreamInfo | Stream Parameters. |
SpStreamCallbacks | Callbacks to be registered with SpRegisterStreamCallbacks |
Typedefs
Typedef | Description |
---|---|
SpCallbackStreamStart | Callback to provide track details to the application. |
SpCallbackStreamData | Callback for delivering data to the integration. |
SpCallbackStreamEnd | Callback to tell integration that all data was delivered. |
SpCallbackStreamGetPosition | Callback to get the playback position in milliseconds. |
SpCallbackStreamSeekToPosition | Callback to tell the integration to seek to a position. |
SpCallbackStreamFlush | Callback to tell the integration to flush. |
Enumerations
Functions
Function | Description |
---|---|
SpRegisterStreamCallbacks | Register callbacks related to the delivery API. |
SpNotifySeekComplete | API to notify eSDK of the completion of seek operation. |
SpNotifyTrackLength | API to notify eSDK of the track length in milliseconds. |
SpNotifyTrackError | API to notify eSDK of any track errors with last played position. |
SpNotifyStreamPlaybackStarted | Notify eSDK that the first audio sample of the delivery has been played. |
SpNotifyStreamPlaybackContinued | Notify eSDK that the first audio sample after a flush of a delivery has been played. |
SpNotifyStreamPlaybackFinishedNaturally | Notify eSDK that the delivery playback finished by playing the last sample of the delivery. |
SpSetDownloadPosition | API to instruct eSDK to start downloading from a given byte offset. |
’
Data Structures
SpStreamInfo
Return to Media data structures
Stream Parameters.
struct SpStreamInfo {
uint32_t size;
int32_t gain_mdb;
uint32_t start_position_ms;
const char *resource;
};
uint32_t | size | Size of the stream in bytes. If the size is unknown, 0 is used. |
int32_t | gain_mdb | Audio normalization gain (in mdB) to apply to the stream. |
uint32_t | start_position_ms | Reserved for internal use. |
const char * | resource | Reserved for internal use. |
SpStreamCallbacks
Return to Media data structures
Callbacks to be registered with SpRegisterStreamCallbacks
struct SpStreamCallbacks {
SpCallbackStreamStart on_start;
SpCallbackStreamData on_data;
SpCallbackStreamEnd on_end;
SpCallbackStreamGetPosition on_get_position;
SpCallbackStreamSeekToPosition on_seek_position;
SpCallbackStreamFlush on_flush;
};
SpCallbackStreamStart | on_start | Start of delivery callback. |
SpCallbackStreamData | on_data | Data delivery callback. |
SpCallbackStreamEnd | on_end | End of delivery callback. |
SpCallbackStreamGetPosition | on_get_position | Current playback position callback. |
SpCallbackStreamSeekToPosition | on_seek_position | Seek to position callback. |
SpCallbackStreamFlush | on_flush | Flush callback. |
Typedefs
SpCallbackStreamStart()
typedef void(* SpCallbackStreamStart)(unsigned int stream_id, enum SpMediaFormat media_format, enum SpDrmFormat drm_format, const struct SpStreamInfo *stream_info, void *context)
Callback to provide track details to the application.
To register this callback, use the function SpRegisterStreamCallbacks
Parameters
[in] | unsigned int stream_id |
Unique identifier to identify tracks |
[in] | enum SpMediaFormat media_format |
Information about the format of the audio data |
[in] | enum SpDrmFormat drm_format |
Information about the used DRM method |
[in] | const struct SpStreamInfo * stream_info |
Additional information related to the stream |
See also
SpCallbackStreamData()
typedef size_t(* SpCallbackStreamData)(unsigned int stream_id, const void *buf, size_t len, uint32_t offset, void *context)
Callback for delivering data to the integration.
To register this callback, use the function SpRegisterStreamCallbacks This callback is called up to 4 times in a single pump until the integration accepts data less than buffer length or when all data from the download buffer is exhausted.
Parameters
[in] | unsigned int stream_id |
Unique identifier to identify tracks |
[in] | const void * buf |
Block of data (it can be audio or video data) |
[in] | size_t len | Size of the data |
[in] | uint32_t offset |
Byte offset in the data stream (relative to the start) |
[in] | void * context |
Context pointer that was passed when registering the callback |
SpCallbackStreamEnd()
typedef void(* SpCallbackStreamEnd)(unsigned int stream_id, void *context)
Callback to tell integration that all data was delivered.
To register this callback, use the function SpRegisterStreamCallbacks stream_id Unique identifier to identify tracks context Context pointer that was passed when registering the callback
Parameters
[in] | unsigned int stream_id |
Unique identifier to identify tracks |
[in] | void * context |
Context pointer that was passed when registering the callback |
SpCallbackStreamGetPosition()
typedef uint32_t(* SpCallbackStreamGetPosition)(unsigned int stream_id, void *context)
Callback to get the playback position in milliseconds.
To register this callback, use the function SpRegisterStreamCallbacks
Parameters
[in] | unsigned int stream_id |
Unique identifier to identify tracks |
[in] | void * context |
Context pointer that was passed when registering the callback |
SpCallbackStreamSeekToPosition()
typedef void(* SpCallbackStreamSeekToPosition)(unsigned int stream_id, uint32_t position_ms, void *context)
Callback to tell the integration to seek to a position.
To register this callback, use the function SpRegisterStreamCallbacks When receiving this callback, the integration should start to seek to the given position. The integration is expected to call SpSetDownloadPosition to instruct eSDK to start downloading from a byte offset corresponding to the position given in this callback. If the position exceeds the length of the track the integration is expected to seek as close as possible to the end. stream_id Unique identifier to identify tracks position_ms Position in time within the track where to seek to context Context pointer that was passed when registering the callback
Parameters
[in] | unsigned int stream_id |
Unique identifier to identify tracks |
[in] | uint32_t position_ms |
Position in time within the track where to seek to |
[in] | void * context |
Context pointer that was passed when registering the callback |
SpCallbackStreamFlush()
typedef uint32_t(* SpCallbackStreamFlush)(unsigned int *playing_stream_id, void *context)
Callback to tell the integration to flush.
To register this callback, use the function SpRegisterStreamCallbacks When receiving this callback, the integration should forget all queued audio and compressed data.
Parameters
[out] | unsigned int * playing_stream_id |
The delivery of the track which is currently playing. If nothing is playing, zero should be used |
[in] | void * context |
Context pointer that was passed when registering the callback |
Enumerations
SpMediaFormat
enum SpMediaFormat {
kSpMediaFormatSpotifyOggVorbis,
kSpMediaFormatMp3,
kSpMediaFormatMp4AAC,
kSpMediaFormatSpacAAC,
kSpMediaFormatSpotifyManifestId,
};
kSpMediaFormatSpotifyOggVorbis | ogg/vorbis 44.1 kHz stereo audio format with Spotify metadata page |
kSpMediaFormatMp3 | mp3 |
kSpMediaFormatMp4AAC | mp4/aac-lc |
kSpMediaFormatSpacAAC | spac/aac-he-v2 |
kSpMediaFormatSpotifyManifestId | Spotify video manifest id. |
Functions
SpRegisterStreamCallbacks()
SpError SpRegisterStreamCallbacks(struct SpStreamCallbacks *cb, void *context)
Register callbacks related to the delivery API.
Parameters
[in] | struct SpStreamCallbacks * cb |
Structure with pointers to individual callback functions. Any of the pointers in the structure may be NULL. |
[in] | void * context |
Application-defined pointer that will be passed unchanged as the context argument to the callbacks. |
Returns
Returns an error code
SpNotifySeekComplete()
SpError SpNotifySeekComplete(unsigned int stream_id)
API to notify eSDK of the completion of seek operation.
Parameters
[in] | unsigned int stream_id |
Unique identifier to identify tracks |
Returns
Returns an error code
SpNotifyTrackLength()
SpError SpNotifyTrackLength(unsigned int stream_id, uint32_t length_ms)
API to notify eSDK of the track length in milliseconds.
Parameters
[in] | unsigned int stream_id |
Unique identifier to identify tracks |
[in] | uint32_t length_ms |
Position in milliseconds of the track |
Returns
Returns an error code
SpNotifyTrackError()
SpError SpNotifyTrackError(unsigned int stream_id, uint32_t position_ms, const char *reason)
API to notify eSDK of any track errors with last played position.
Parameters
[in] | unsigned int stream_id |
Unique identifier to identify tracks |
[in] | uint32_t position_ms |
Position in milliseconds of the track |
[in] | const char * reason |
The reason for the error |
Returns
Returns an error code
SpNotifyStreamPlaybackStarted()
SpError SpNotifyStreamPlaybackStarted(unsigned int stream_id)
Notify eSDK that the first audio sample of the delivery has been played.
This is used by the eSDK to measure playback latency.
Parameters
[in] | unsigned int stream_id |
Unique identifier to identify tracks |
Returns
Returns an error code. Returns kSpErrorAlreadyInitialized if SpNotifyStreamPlaybackStarted() has already been called for this delivery.
SpNotifyStreamPlaybackContinued()
SpError SpNotifyStreamPlaybackContinued(unsigned int stream_id)
Notify eSDK that the first audio sample after a flush of a delivery has been played.
This is used by the eSDK to measure seek latency.
Parameters
[in] | unsigned int stream_id |
Unique identifier to identify tracks |
Returns
Returns an error code
SpNotifyStreamPlaybackFinishedNaturally()
SpError SpNotifyStreamPlaybackFinishedNaturally(unsigned int stream_id, uint32_t last_pos_ms)
Notify eSDK that the delivery playback finished by playing the last sample of the delivery.
Parameters
[in] | unsigned int stream_id |
Unique identifier to identify tracks |
[in] | uint32_t last_pos_ms |
Position in milliseconds of the track |
Returns
Returns an error code
SpSetDownloadPosition()
SpError SpSetDownloadPosition(unsigned int stream_id, uint32_t byte_offset)
API to instruct eSDK to start downloading from a given byte offset.
Parameters
[in] | unsigned int stream_id |
Unique identifier to identify tracks |
[in] | uint32_t byte_offset |
New download byte offset (relative to the start of the stream) where downloading could continue. |
Returns
Returns an error code
Play
#include "spotify_embedded_play_api.h"
Macros and Constants
Define | Value |
---|---|
SP_NO_INDEX | -1 |
SP_MAX_UUID_LENGTH | 36 |
SP_MAX_SOURCE_TYPE_LENGTH | 63 |
SP_MAX_SOURCE_URI_LENGTH | 511 |
SP_MAX_REFERRER_LENGTH | 16 |
SP_PLAYOPTIONS_INITIALIZER_LOGGING_PARAMS | |
SP_PLAYOPTIONS_INITIALIZER | See macro below |
Data Structures
Data Structure | Description |
---|---|
SpSourceInfo | Metadata for identifying where a playback request originated from. |
SpPlayOptions | PlayOptions passed to SpPlayUriWithOptions Use SP_PLAYOPTIONS_INITIALIZER for initializing with default values. |
Functions
Function | Description |
---|---|
SpPlayUri | Start local playback of the given Spotify URI. |
SpPlayUriWithOptions | Start local playback of the given Spotify URI with additional options. |
SpPlayContextUri | Start local playback of the given Spotify URI with an optional track UID. |
SpQueueUri | Queue a URI. The track will be in queue only after kSpPlaybackNotifyQueuedTrackAccepted event is raised, but for UI purposes one can choose to monitor for kSpPlaybackNotifyMetadataChanged instead. |
SpPlaybackBecomeActiveDevice | Become active without starting to play. |
Macros and Constants
SP_NO_INDEX
#define SP_NO_INDEX -1
Indicates that the index value is not set. Note: Can only be used with eSDK 3.
See also
SP_MAX_UUID_LENGTH
#define SP_MAX_UUID_LENGTH 36
Maximum length of a UUID.
A 128 bit UUID containing 32 hexadecimal digits in five groups separated by hyphens.
SP_MAX_SOURCE_TYPE_LENGTH
#define SP_MAX_SOURCE_TYPE_LENGTH 63
Maximum length of the type of playback source.
See also
SP_MAX_SOURCE_URI_LENGTH
#define SP_MAX_SOURCE_URI_LENGTH 511
Maximum length of the source URIs.
See also
SP_MAX_REFERRER_LENGTH
#define SP_MAX_REFERRER_LENGTH 16
Maximum length of the referrer.
See also
SP_PLAYOPTIONS_INITIALIZER_LOGGING_PARAMS
#define SP_PLAYOPTIONS_INITIALIZER_LOGGING_PARAMS
Internal macro.
See also
SP_PLAYOPTIONS_INITIALIZER
#define SP_PLAYOPTIONS_INITIALIZER { \
/*.from_index =*/
Macro for initialization of struct SpPlayOptions Use it instead of memset() due to the fact that some fields are optional and encoded as non-zero values.
’
Data Structures
SpSourceInfo
Return to Play data structures
Metadata for identifying where a playback request originated from.
See also
struct SpSourceInfo {
char type;
char uri;
char expected_track_uri;
char referrer;
};
char | type | The type of playlist/context/UI view that caused this playback to start. Note: If set, this MUST be one of the following strings (unless told otherwise): |
|
"album" "artist" "playlist" "playlistfolder" "radio" "search" "toplist" "unknown" Please contact Spotify if you have a common play source that is not obviously represented in this list. | |||
char | uri | The URI of the parent container, if there is one. |
|
For example, if the user selects an album from an artist view, the URI passed to SpPlayUri is the album to play, and the URI in this source field should be the URI of the artist. | |||
char | expected_track_uri | The URI of the track that is expected to play. |
|
If the URI to play is a container of multiple tracks (ex: playlist, artist, album), this field can optionally be filled with the track URI that is expected to play. This can be used to adjust the index when the context has changed or when tracks are unavailable. | |||
char | referrer | The view you were in prior to initiating playback. |
|
The acceptable values are: "home" "search" "collection" "browse" (this is for older clients) "radio" (this is for older clients) "other" |
SpPlayOptions
Return to Play data structures
PlayOptions passed to SpPlayUriWithOptions Use SP_PLAYOPTIONS_INITIALIZER for initializing with default values.
Example:
struct SpPlayOptions options= SP_PLAYOPTIONS_INITIALIZER;
struct SpPlayOptions {
int from_index;
const char *from_uid;
int offset_ms;
int shuffle_context;
int repeat_mode;
const struct SpSourceInfo *source_info;
};
int | from_index | Track index in the Context from which playback should start. Use SP_NO_INDEX if no specific index is required. In case of non-shuffled context this will result in the first track of the context being played whereas in shuffled context this will result in a random track being played. |
|
const char * | from_uid | The UID to identify a unique track in the context. |
|
int | offset_ms | The time offset to start playing specified track from. |
|
int | shuffle_context | Set to enable or disable shuffle mode for the requested playback command. |
|
Setting this to 1 means shuffling is enabled, 0 means it is disabled, all remaining values will leave shuffling settings unchanged. Notes:
| |||
int | repeat_mode | Set to enable or disable repeat mode for the requested playback command. |
|
Setting it to 0 disables repeat mode, 1 enables repeat for all tracks in the requested context, 2 enables repeat of a single track. All remaining values will leave repeating settings unchanged. Notes:
| |||
const struct SpSourceInfo * | source_info | Metadata about what user action caused this playback event, and the expected result. |
|
|
Functions
SpPlayUri()
SpError SpPlayUri(const char *uri, int index, int offset_ms, const struct SpSourceInfo *source, int alias_index)
Start local playback of the given Spotify URI.
This call starts playback of a Spotify URI, such as a playlist, album, artist, or track. Valid Spotify URIs can be obtained via the Spotify Web API. Using this call will 'pull' playback from any other Spotify Connect client active on the same account. Note that there may be a lag between the introduction of new URI types and support for playing them with this call.
Parameters
[in] | const char * uri |
URI of resource (ex: spotify:album:6tSdnCBm5HCAjwNxWfUC7m) |
[in] | int alias_ index |
The zero based index of the item to start playing in the resource (for instance, ‘4’ would play the 5th track in a playlist). Set to zero if the resource does not have multiple items. In eSDK 3, this can be set to SP_NO_INDEX if no specific index is required. In case of non-shuffled context this will result in the first track of the context being played whereas in shuffled context this will result in a random track being played. |
[in] | int offset_ms |
The time offset to start playing specified track from. Set to zero to start from the beginning. |
[in] | const struct SpSourceInfo * source |
Metadata about what user action caused this playback event, and the expected result. This information is used to correct behavior when the exact request isn’t possible, and to enable better recommendations and suggestions for users. This field is optional, but MUST be provided whenever possible. Failure to fill in this data accurately will result in a downgraded Spotify experience. |
[in] | int alias_index |
The index of the device alias to start playback on. If aliases aren’t used, pass SP_NO_ALIAS_SELECTED. |
Returns
Returns an error code
See also
SpPlayUriWithOptions()
SpError SpPlayUriWithOptions(const char *uri, const struct SpPlayOptions *opts, int alias_index)
Start local playback of the given Spotify URI with additional options.
Parameters
[in] | const char * uri |
The context URI to play. |
[in] | const struct SpPlayOptions * opts |
The options to apply to the play command. |
[in] | int alias_index |
Device alias index. If aliases aren’t used, pass SP_NO_ALIAS_SELECTED. |
Returns
Returns an error code
SpPlayContextUri()
SpError SpPlayContextUri(const char *uri, const char *from_uid, int offset_ms, const struct SpSourceInfo *source, int alias_index)
Start local playback of the given Spotify URI with an optional track UID.
This call will start playback of any Spotify context URI. In addition, it allows the client to provide a UID to start the playback from a given track in the context. The main difference between UIDs and the field SpSourceInfo::expected_track_uri is that while one track URI can occur more than once in the context, UIDs are unique for each track in it. Valid Spotify URIs can be obtained via the Spotify Web API. Track UIDs are currently available when resolving contexts from a small subset of services. Using this call will 'pull' playback from any other Spotify Connect client active on the same account.
Parameters
[in] | const char * uri |
URI of resource (ex: spotify:album:6tSdnCBm5HCAjwNxWfUC7m) |
[in] | const char * from_uid |
The UID to identify a unique track in the context. |
[in] | int offset_ms |
The time offset to start playing specified track from. Set to zero to start from the beginning. |
[in] | const struct SpSourceInfo * source |
Metadata about what user action caused this playback event, and the expected result. This information is used to correct behavior when the exact request isn’t possible, and to enable better recommendations and suggestions for users. This field is optional, but MUST be provided whenever possible. Failure to fill in this data accurately will result in a downgraded Spotify experience. |
[in] | int alias_index |
The index of the device alias to start playback on. If aliases aren’t used, pass SP_NO_ALIAS_SELECTED. |
Returns
Returns an error code
See also
SpQueueUri()
SpError SpQueueUri(const char *uri)
Queue a URI. The track will be in queue only after kSpPlaybackNotifyQueuedTrackAccepted event is raised, but for UI purposes one can choose to monitor for kSpPlaybackNotifyMetadataChanged instead.
Parameters
[in] | const char * uri |
URI to queue. |
Returns
Returns an error code.
See also
SpPlaybackBecomeActiveDevice()
SpError SpPlaybackBecomeActiveDevice(int alias_index)
Become active without starting to play.
alias_index The index of the device alias that should become active. If aliases aren't used, pass SP_NO_ALIAS_SELECTED. This call makes the device active, without starting to play anything, if playback is paused or no device is active. The device is active after the kSpPlaybackNotifyBecameActive event is received. If another Connect-enabled device was active and playing, it will be interrupted. If the currently active device is playing, this call behaves like SpPlaybackPlay If device aliases are used, this function will switch the selected alias. If the selected alias was changed during playback, the playback will continue uninterrupted with the new alias.
Parameters
[in] | int alias_index |
The index of the device alias that should become active. If aliases aren’t used, pass SP_NO_ALIAS_SELECTED. |
Returns
Returns an error code
Storage
#include "spotify_embedded_storage.h"
Data Structures
Data Structure | Description |
---|---|
SpDiskStorageCallbacks | Callbacks to be registered with SpRegisterStorageCallbacks |
Typedefs
Typedef | Description |
---|---|
SpCallbackStorageAlloc | Callback to allocate space for the resource being stored. Each successful alloc call is accompanied with a corresponding close call. It is obligatory for the user to use this callback to reserve actual space on device media for the key specified. |
SpCallbackStorageWrite | Callback for writing the data into storage. Before writing to the storage eSDK does one of two things: call alloc to reserve space for future write or call read to get the data. After that eSDK writes the data into storage. Once write is fully complete eSDK calls close callback. |
SpCallbackStorageRead | Callback for reading the data. Once eSDK reads all required data, the close callback is called to notify the user that the data handle referenced by storage_key can be closed. |
SpCallbackStorageClose | Callback to inform the user that the data handle referenced by storage_key can be closed. |
SpCallbackStorageDelete | Callback to inform the user that data referenced by storage_key should be deleted from storage. |
SpCallbackThrottleRequest | eSDK calls this callback to figure out if it needs to limit write access to the storage. |
Functions
Function | Description |
---|---|
SpRegisterStorageCallbacks | Register storage callbacks. |
’
Data Structures
SpDiskStorageCallbacks
Return to Storage data structures
Callbacks to be registered with SpRegisterStorageCallbacks
Storage callbacks must be either all NULLs or all valid pointers. Throttle callback may be NULL regardless of storage callbacks. See the documentation of the callback typedefs for information about the individual callbacks.
struct SpDiskStorageCallbacks {
SpCallbackStorageAlloc alloc_storage;
SpCallbackStorageWrite write_storage;
SpCallbackStorageRead read_storage;
SpCallbackStorageClose close_storage;
SpCallbackStorageDelete delete_storage;
SpCallbackThrottleRequest throttle_request;
};
SpCallbackStorageAlloc | alloc_storage | Alloc storage record callback. |
SpCallbackStorageWrite | write_storage | Write storage data callback. |
SpCallbackStorageRead | read_storage | Read storage data callback. |
SpCallbackStorageClose | close_storage | Close storage record callback. |
SpCallbackStorageDelete | delete_storage | Delete storage record callback. |
SpCallbackThrottleRequest | throttle_request | Asks the client if disk writes need to be throttled. |
Typedefs
SpCallbackStorageAlloc()
typedef enum SpCallbackStorageAlloc)(const char *storage_key, uint32_t total_size, void *context)
Callback to allocate space for the resource being stored. Each successful alloc call is accompanied with a corresponding close call. It is obligatory for the user to use this callback to reserve actual space on device media for the key specified.
To register this callback, use the function SpRegisterStorageCallbacks
Parameters
[in] | const char * storage_key |
Storage key identifying the record |
[in] | uint32_t total_size |
The full resource size in bytes or 0 if size is not known. |
[in] | void * context |
Context pointer that was passed when registering the callback. |
See also
Notes:
- The allocation of space should be done in the way that following read and write operations will succeed within the specified resource size.
SpCallbackStorageWrite()
typedef int(* SpCallbackStorageWrite)(const char *storage_key, uint32_t offset, const void *data, uint32_t data_size, void *context)
Callback for writing the data into storage. Before writing to the storage eSDK does one of two things: call alloc to reserve space for future write or call read to get the data. After that eSDK writes the data into storage. Once write is fully complete eSDK calls close callback.
To register this callback, use the function SpRegisterStorageCallbacks
Parameters
[in] | const char * storage_key |
Storage key identifying the record |
[in] | uint32_t offset |
The offset in bytes in the resource we are writing to. |
[in] | const void * data |
A pointer to the buffer containing the data to be written to storage. |
[in] | uint32_t data_size |
The number of bytes to be written to the storage. |
[in] | void * context |
Context pointer that was passed when registering the callback. |
See also
Notes:
- The application should not block or call other API functions in the callback. Offset field must always be respected on write operation. Application should consume whole data in the call.
SpCallbackStorageRead()
typedef int(* SpCallbackStorageRead)(const char *storage_key, uint32_t offset, void *data, uint32_t data_size, void *context)
Callback for reading the data. Once eSDK reads all required data, the close callback is called to notify the user that the data handle referenced by storage_key can be closed.
To register this callback, use the function SpRegisterStorageCallbacks
Parameters
[in] | const char * storage_key |
Storage key identifying the record |
[in] | uint32_t offset |
The offset eSDK is reading from. |
[out] | void * data |
A pointer to the buffer that receives the data read from storage. |
[in] | uint32_t data_size |
The number bytes to read. |
[in] | void * context |
Context pointer that was passed when registering the callback |
See also
Notes:
- The application should not block or call other API functions in the callback. If no storage read is possible, just return 0.
SpCallbackStorageClose()
typedef void(* SpCallbackStorageClose)(const char *storage_key, void *context)
Callback to inform the user that the data handle referenced by storage_key can be closed.
To register this callback, use the function SpRegisterStorageCallbacks
Parameters
[in] | const char * storage_key |
Storage key identifying the record |
[in] | void * context |
Context pointer that was passed when registering the callback. |
Notes:
- The application should not block or call other API functions in the callback. This callback would be called for any successful alloc. For any resource open caused by Read/Write API calls.
SpCallbackStorageDelete()
typedef enum SpCallbackStorageDelete)(const char *storage_key, void *context)
Callback to inform the user that data referenced by storage_key should be deleted from storage.
To register this callback, use the function SpRegisterStorageCallbacks
Parameters
[in] | const char * storage_key |
Storage key identifying the record. |
[in] | void * context |
Context pointer that was passed when registering the callback. |
Notes:
- The application should not block or call other API functions in the callback.
- If the deletion operation is expected to take some time the application shall return kSpAPITryAgain for the duration of the operation and kSpAPINoError once it has been completed. It is important to not block execution of eSDK for prolonged periods (ideally less than 10ms). This callback can be called for literally any storage_key.
SpCallbackThrottleRequest()
typedef int(* SpCallbackThrottleRequest)(const char *storage_key, void *context)
eSDK calls this callback to figure out if it needs to limit write access to the storage.
Parameters
[in] | const char * storage_key |
Storage key identifying the record. |
[in] | void * context |
Context pointer that was passed when registering the callback. |
Notes:
- The application should not block or call other API functions in the callback.
Functions
SpRegisterStorageCallbacks()
SpError SpRegisterStorageCallbacks(struct SpDiskStorageCallbacks *cb, void *context)
Register storage callbacks.
Parameters
[in] | struct SpDiskStorageCallbacks * cb |
Structure with pointers to individual callback functions. Any of the pointers in the structure may be NULL. |
[in] | void * context |
Application-defined pointer that will be passed unchanged as the context argument to the callbacks. |
Returns
Returns an error code
Tls
#include "spotify_embedded_tls.h"
Data Structures
Data Structure | Description |
---|---|
SpTLSCallbacks | Callbacks to be registered with SpRegisterTLSCallbacks |
Typedefs
Typedef | Description |
---|---|
SpCallbackTLSInit | This callback is invoked by eSDK to let the TLS library integration perform any one-time initialization. |
SpCallbackTLSDeinit | This callback is invoked by eSDK to let the TLS library integration perform deallocation of resources during teardown. |
SpCallbackTLSCreate | This callback is invoked once in the beginning of every TLS connection. |
SpCallbackTLSHandshake | This callback is invoked by eSDK to perform the TLS handshake. |
SpCallbackTLSRead | This callback is invoked by eSDK to read data on a TLS connection. |
SpCallbackTLSWrite | This callback is invoked by eSDK to write data on a TLS connection. |
SpCallbackTLSClose | This callback should clean up any resources allocated in the connect callback. |
SpCallbackTLSGetError | Callback invoked to get an error message for the last error. |
Functions
Function | Description |
---|---|
SpRegisterTLSCallbacks | Register TLS-related callbacks. |
SpTLSAddCARootCert | Add root certificate to the eSDK TLS stack. |
SpTLSFreeCARootCerts | Remove all certificates loaded on the TLS stack and free the memory used by them. |
’
Data Structures
SpTLSCallbacks
Callbacks to be registered with SpRegisterTLSCallbacks
None of the pointers may be NULL. See the documentation of the callback typedefs for information about the individual callbacks.
struct SpTLSCallbacks {
SpCallbackTLSInit init;
SpCallbackTLSDeinit deinit;
SpCallbackTLSCreate create;
SpCallbackTLSHandshake handshake;
SpCallbackTLSRead read;
SpCallbackTLSWrite write;
SpCallbackTLSClose close;
SpCallbackTLSGetError get_error;
};
SpCallbackTLSInit | init | Callback that performs one-time initialization. |
SpCallbackTLSDeinit | deinit | Callback that performs release of resources allocated during init. |
SpCallbackTLSCreate | create | Callback invoked once per connection to initialize TLS context. |
SpCallbackTLSHandshake | handshake | Callback invoked repeatedly to perform the TLS handshake. |
SpCallbackTLSRead | read | Callback for reading from the TLS data stream. |
SpCallbackTLSWrite | write | Callback for writing to the TLS data stream. |
SpCallbackTLSClose | close | Callback invoked to cleanup any TLS context before closing the socket. |
SpCallbackTLSGetError | get_error | Callback invoked to get an error message for the last error. |
Typedefs
SpCallbackTLSInit()
typedef enum SpCallbackTLSInit)(void *context)
This callback is invoked by eSDK to let the TLS library integration perform any one-time initialization.
Parameters
[in] | void * context |
Context provided in callback register function. |
Notes:
- The application should not block or call other API functions in the callback.
SpCallbackTLSDeinit()
typedef enum SpCallbackTLSDeinit)(void *context)
This callback is invoked by eSDK to let the TLS library integration perform deallocation of resources during teardown.
Parameters
[in] | void * context |
Context provided in callback register function. |
Notes:
- The application should not block or call other API functions in the callback.
SpCallbackTLSCreate()
typedef enum SpCallbackTLSCreate)(struct SpSocketHandle *socket, const char *hostname, void *context)
This callback is invoked once in the beginning of every TLS connection.
The callback receives a socket via the pointer to SpSocketHandle that is already connected to the remote peer. This callback should typically allocate and set up all TLS related resources. The tls field of the SpSocketHandle should be used to store any connection specific state that is needed.
Parameters
[in] | struct SpSocketHandle * socket |
Pointer to eSDK socket already connected to the remote peer. |
[in] | const char * hostname |
Hostname of the remote peer. |
[in] | void * context |
Context provided in callback register function. |
Notes:
- The application should not block or call other API functions in the callback.
SpCallbackTLSHandshake()
typedef enum SpCallbackTLSHandshake)(struct SpSocketHandle *socket, void *context)
This callback is invoked by eSDK to perform the TLS handshake.
The callback is invoked repeatedly to perform the handshake. This callback is invoked repeatedly as long as it returns kSpAPITryAgain The peer verification is mandatory and the implementation of this callback must validate the peer certificate against a list of trusted CA certificates. Should return kSpAPIGenericError if the handshake failed. Any specific information about the reason for the failure will be returned in the SpCallbackTLSGetError call.
Parameters
[in] | struct SpSocketHandle * socket |
Pointer to eSDK socket already connected to the remote peer. |
[in] | void * context |
Context provided in callback register function. |
Notes:
- The application must not block or call other API functions in the callback.
SpCallbackTLSRead()
typedef enum SpCallbackTLSRead)(struct SpSocketHandle *socket, void *buf, size_t len, size_t *actual, void *context)
This callback is invoked by eSDK to read data on a TLS connection.
Parameters
[in] | struct SpSocketHandle * socket |
Pointer to eSDK socket already connected to the remote peer. |
[in] | void * buf |
Pointer to buffer for the data to be received. |
[in] | size_t len | The size of the buffer (in bytes). |
[out] | size_t * actual | Actual number of bytes received. |
[in] | void * context |
Context provided in callback register function. |
Notes:
- The application should not block or call other API functions in the callback.
SpCallbackTLSWrite()
typedef enum SpCallbackTLSWrite)(struct SpSocketHandle *socket, const void *buf, size_t len, size_t *actual, void *context)
This callback is invoked by eSDK to write data on a TLS connection.
Parameters
[in] | struct SpSocketHandle * socket |
Pointer to eSDK socket already connected to the remote peer. |
[in] | const void * buf |
Pointer to buffer with data to be written. |
[in] | size_t len | Number of bytes of data in buffer. |
[out] | size_t * actual | Number of bytes actually written. |
[in] | void * context |
Context provided in callback register function. |
Notes:
- The application should not block or call other API functions in the callback.
SpCallbackTLSClose()
typedef void(* SpCallbackTLSClose)(struct SpSocketHandle *socket, void *context)
This callback should clean up any resources allocated in the connect callback.
Parameters
[in] | struct SpSocketHandle * socket |
Pointer to eSDK socket already connected to the remote peer. |
[in] | void * context |
Context provided in callback register function. |
Notes:
- The application should not block or call other API functions in the callback.
SpCallbackTLSGetError()
typedef int(* SpCallbackTLSGetError)(struct SpSocketHandle *socket, char *buf, size_t len, void *context)
Callback invoked to get an error message for the last error.
The implementation of this callback should put an error message in the form of a zero-terminated string in the buffer pointed to by buf. This error message should describe the latest error returned by any of the other callback functions.
Parameters
[in] | struct SpSocketHandle * socket |
Pointer to eSDK socket already connected to the remote peer. |
[in] | char * buf |
Pointer to buffer that will receive the error message. |
[in] | size_t len | Length of the buffer. |
[in] | void * context |
Context provided in callback register function. |
Notes:
- The application should not block or call other API functions in the callback.
Functions
SpRegisterTLSCallbacks()
SpError SpRegisterTLSCallbacks(struct SpTLSCallbacks *callbacks, void *context)
Register TLS-related callbacks.
Parameters
[in] | struct SpTLSCallbacks * callbacks |
Structure with pointers to individual callback functions. All pointers must be valid. |
[in] | void * context |
Application-defined pointer that will be passed unchanged as the context argument to the callbacks. |
Returns
Returns an error code
Notes:
- A call to this function has to be performed before SpInit is called. Calling this function when eSDK is initialized will fail with kSpErrorAlreadyInitialized The function will return kSpErrorUnsupported in the eSDK configurations with built-in TLS.
SpTLSAddCARootCert()
SpError SpTLSAddCARootCert(const uint8_t *certificate, size_t length, int *underlying_error)
Add root certificate to the eSDK TLS stack.
eSDK uses TLS secured HTTPS connections to download media files from CDN (Content Delivery Network) servers. All CDN servers are using certificates from common Certificate Authorities (CA). eSDK cannot read Certificate Authority (CA) root certificates from the operating system. The purpose of this function is to provide eSDK the CA root certificates which eSDK needs. As an example, integration can use the CA certificate bundle from Mozilla: https://curl.se/docs/caextract.html This API is cumulative and can be called several times until the integration has loaded all the certificates. This API allocates and owns the memory to store the certificates. The integration can reuse the memory used to pass the certificates (first parameter)
Parameters
[in] | const uint8_t * certificate |
Either a binary DER certificate or a string with a PEM-format certificate. |
Returns
Returns kSpErrorInvalidArgument if the certificate could not be parsed kSpErrorAlreadyInitialized if the function is called between SpInit() and SpFree(). If the return value is kSpErrorInvalidArgument and underlying_error is non-NULL, there will be an error code from the underlying TLS stack (currently MbedTLS) returned in *underlying_error.
Notes:
- If the buffer is a PEM-format certificate, it must be NULL-terminated.
- If the buffer is a PEM-format certificate, this length must include the NULL termination.
- Calls to this function have to be performed before SpInit is called or after SpFree
SpTLSFreeCARootCerts()
SpError SpTLSFreeCARootCerts(void)
Remove all certificates loaded on the TLS stack and free the memory used by them.
This API must be called before calling SpInit or after SpFree
Returns
kSpErrorUnavailable if the function is called between SpInit() and SpFree().
Token
#include "spotify_embedded_token.h"
Data Structures
Data Structure | Description |
---|---|
SpTokenCallbacks | Callbacks to be registered with SpRegisterTokenCallbacks |
Typedefs
Typedef | Description |
---|---|
SpCallbackConnectionReceiveAccessToken | Callback to deliver the access token requested by SpConnectionRequestAccessToken |
SpCallbackConnectionReceiveAuthCode | Callback to deliver the access token requested by SpConnectionRequestAuthCode |
Functions
Function | Description |
---|---|
SpRegisterTokenCallbacks | Register token callbacks. |
SpConnectionRequestAccessToken | Request an access token for the logged in user. |
SpConnectionRequestAuthCode | Request an authorization code for the logged in user. |
’
Data Structures
SpTokenCallbacks
Return to Token data structures
Callbacks to be registered with SpRegisterTokenCallbacks
Any of the pointers may be NULL. See the documentation of the callback typedefs for information about the individual callbacks.
struct SpTokenCallbacks {
SpCallbackConnectionReceiveAccessToken on_access_token;
SpCallbackConnectionReceiveAuthCode on_auth_code;
};
SpCallbackConnectionReceiveAccessToken | on_access_token | Access token event callbacks. |
SpCallbackConnectionReceiveAuthCode | on_auth_code | Authorization code event callbacks. |
Typedefs
SpCallbackConnectionReceiveAccessToken()
typedef void(* SpCallbackConnectionReceiveAccessToken)(const char *token_json, int error, void *context)
Callback to deliver the access token requested by SpConnectionRequestAccessToken
Parameters
[in] | const char * token_json |
A serialized JSON object containing the access token or an empty string if error is != 0. See Notes below. |
[in] | int error |
An internal error code or 0 on success. The token in token_json is only valid if this is 0. |
[in] | void * context |
Context pointer that was passed then the callback was registered. |
Notes:
- The JSON object looks as following: {"accessToken":"tokendata", "expiresIn":expiryinseconds,//typically3600 "tokenType":"tokentype"}//typically"Bearer"
SpCallbackConnectionReceiveAuthCode()
typedef void(* SpCallbackConnectionReceiveAuthCode)(const char *token_json, int error, void *context)
Callback to deliver the access token requested by SpConnectionRequestAuthCode
Parameters
[in] | const char * token_json |
A serialized JSON object containing the access token or an empty string if error is != 0. See Notes below. |
[in] | int error |
An internal error code or 0 on success. The token in token_json is only valid if this is 0. |
[in] | void * context |
Context pointer that was passed then the callback was registered. |
Notes:
- The JSON object looks as following: {"code":"tokendata", "redirectUri":"someUri"
Functions
SpRegisterTokenCallbacks()
SpError SpRegisterTokenCallbacks(struct SpTokenCallbacks *cb, void *context)
Register token callbacks.
Parameters
[in] | struct SpTokenCallbacks * cb |
Structure with pointers to individual callback functions. Any of the pointers in the structure may be NULL. |
[in] | void * context |
Application-defined pointer that will be passed unchanged as the context argument to the callbacks. |
Returns
Returns an error code
SpConnectionRequestAccessToken()
SpError SpConnectionRequestAccessToken(const char *scope)
Request an access token for the logged in user.
scope A comma-separated list of scopes for the resulting access token. See https://developer.spotify.com/documentation/general/guides/scopes/
Parameters
[in] | const char * scope |
A comma-separated list of scopes for the resulting access token. See https://developer.spotify.com/documentation/general/guides/scopes/ |
SpConnectionRequestAuthCode()
SpError SpConnectionRequestAuthCode(const char *scope)
Request an authorization code for the logged in user.
Parameters
[in] | const char * scope |
A comma-separated list of scopes for the resulting access token. See https://developer.spotify.com/documentation/general/guides/scopes/ |
Notes:
- The string scope must not be longer than 425 characters.