Skip to content

API Reference eSDK 3.203.239

Main



_10
#include "spotify_embedded.h"

Macros and Constants


Return to header index
SP_API_VERSION 77
SP_RECOMMENDED_MEMORY_BLOCK_SIZE 1024 * 1024
SP_MAX_BRAND_NAME_LENGTH 32
SP_MAX_MODEL_NAME_LENGTH 30
SP_MAX_PLATFORM_NAME_LENGTH 64
SP_MAX_CLIENT_ID_LENGTH 32
SP_MAX_OS_VERSION_LENGTH 64
SP_MAX_DISPLAY_NAME_LENGTH 64
SP_MAX_AD_USER_AGENT_LENGTH 256
SP_MAX_UNIQUE_ID_LENGTH 64
SP_MAX_USERNAME_LENGTH 64
SP_MAX_DEVICE_ALIASES 8
SP_MAX_AD_METADATA_PAIRS 4
SP_NO_ALIAS_SELECTED -1
SP_MAX_METADATA_NAME_LENGTH 255
SP_MAX_METADATA_URI_LENGTH 127
SP_MAX_TRACK_UID_LENGTH 64
SP_MAX_METADATA_IMAGE_URL_LENGTH 255
SP_PLAYER_COOKIE_LENGTH 32
SP_MAX_PLAYBACK_ID_LENGTH 32
SP_MAX_PUBLIC_KEY_LENGTH 149
SP_MAX_DEVICE_ID_LENGTH 64
SP_MAX_DEVICE_TYPE_LENGTH 15
SP_MAX_VERSION_LENGTH 30
SP_MAX_GROUP_STATUS_LENGTH 15
SP_MAX_TOKEN_TYPE_LENGTH 30
SP_MAX_SCOPE_LENGTH 64
SP_MAX_CLIENT_KEY_LENGTH 511
SP_MAX_ZEROCONF_BLOB_LENGTH 2047
SP_MAX_LOGIN_ID_LENGTH 64
SP_MAX_AVAILABILITY_LENGTH 15
SP_MAX_PARTNER_NAME_LENGTH 48
SP_MAX_FILENAME_LENGTH 63
SP_ZEROCONF_DISABLED 0
SP_ZEROCONF_SERVE 1
SP_ZEROCONF_SERVE_HTTP_ONLY 2
SP_ZEROCONF_SERVE_MDNS_ONLY 3
SP_SCOPE_STREAMING "streaming"
SP_DEVICE_ALIAS_ATTRIBUTE_GROUP 1
SP_GLOBAL_ATTRIBUTE_VOICE 2
SP_MAX_SUPPORTED_FORMATS 8
SP_PLAYBACK_RESTRICTION_ALREADY_PAUSED 1
SP_PLAYBACK_RESTRICTION_NOT_PAUSED 2
SP_PLAYBACK_RESTRICTION_LICENSE_DISALLOW 4
SP_PLAYBACK_RESTRICTION_AD_DISALLOW 8
SP_PLAYBACK_RESTRICTION_NO_PREV_TRACK 16
SP_PLAYBACK_RESTRICTION_NO_NEXT_TRACK 32
SP_PLAYBACK_RESTRICTION_UNKNOWN 64
SP_PLAYBACK_RESTRICTION_ENDLESS_CONTEXT 128
SP_MAX_METADATA_KEY_LENGTH 32
SP_MAX_METADATA_VALUE_LENGTH 64

Data Structures


Return to header index
SpPlaybackRestrictions Playback restrictions.
SpMetadata Track metadata.
SpAdMetadata Key value pair for Ad-related 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


Return to header index
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


Return to header index
SpError
SpAPIReturnCode
SpPlaybackBitrate
SpPlaybackNotification
SpConnectionNotification
SpDeviceType
SpMetadataTrack
SpConnectivity
SpContent
SpMediaType
SpAudioQuality
SpDrmFormat
SpReDeliveryMode

Functions


Return to header index
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.
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.
SpSetAdUserAgent Set the ad user agent.
SpRestrictDrmMediaFormats
SpRestoreDrmMediaFormats

Macros and Constants


SP_API_VERSION

Return to Main macros and constants

_10
#define SP_API_VERSION 77

The version of the API defined in this header file.

See also
Return to Main macros and constants

_10
#define SP_RECOMMENDED_MEMORY_BLOCK_SIZE 1024 * 1024

Minimum recommended size of the buffer SpConfig::memory_block

SP_MAX_BRAND_NAME_LENGTH

Return to Main macros and constants

_10
#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

Return to Main macros and constants

_10
#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

Return to Main macros and constants

_10
#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

Return to Main macros and constants

_10
#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

Return to Main macros and constants

_10
#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

Return to Main macros and constants

_10
#define SP_MAX_DISPLAY_NAME_LENGTH 64

Maximum length of the device display name (not counting terminating NULL)

See also

SP_MAX_AD_USER_AGENT_LENGTH

Return to Main macros and constants

_10
#define SP_MAX_AD_USER_AGENT_LENGTH 256

Maximum length of the ad UserAgent (not counting terminating NULL)

See also

SP_MAX_UNIQUE_ID_LENGTH

Return to Main macros and constants

_10
#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

Return to Main macros and constants

_10
#define SP_MAX_USERNAME_LENGTH 64

Maximum length of usernames (not counting terminating NULL)

See also

SP_MAX_DEVICE_ALIASES

Return to Main macros and constants

_10
#define SP_MAX_DEVICE_ALIASES 8

Maximum number of device aliases that can be configured.

See also

SP_MAX_AD_METADATA_PAIRS

Return to Main macros and constants

_10
#define SP_MAX_AD_METADATA_PAIRS 4

Maximum number of key/value pairs containing ad metadata.

SP_NO_ALIAS_SELECTED

Return to Main macros and constants

_10
#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

Return to Main macros and constants

_10
#define SP_MAX_METADATA_NAME_LENGTH 255

Maximum length of display names in track metadata (not counting terminating NULL)

See also Notes:

SP_MAX_METADATA_URI_LENGTH

Return to Main macros and constants

_10
#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

Return to Main macros and constants

_10
#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

Return to Main macros and constants

_10
#define SP_MAX_METADATA_IMAGE_URL_LENGTH 255

Maximum length of URLs (not counting terminating NULL)

See also
Return to Main macros and constants

_10
#define SP_PLAYER_COOKIE_LENGTH 32

Length of player cookie (not counting terminating NULL)

See also

SP_MAX_PLAYBACK_ID_LENGTH

Return to Main macros and constants

_10
#define SP_MAX_PLAYBACK_ID_LENGTH 32

Maximum length of Playback-Id (not counting terminating NULL)

See also

SP_MAX_PUBLIC_KEY_LENGTH

Return to Main macros and constants

_10
#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

Return to Main macros and constants

_10
#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

Return to Main macros and constants

_10
#define SP_MAX_DEVICE_TYPE_LENGTH 15

Maximum length of the device type string (not counting terminating NULL)

See also

SP_MAX_VERSION_LENGTH

Return to Main macros and constants

_10
#define SP_MAX_VERSION_LENGTH 30

Maximum length of the library version string (not counting terminating NULL)

See also

SP_MAX_GROUP_STATUS_LENGTH

Return to Main macros and constants

_10
#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

Return to Main macros and constants

_10
#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

Return to Main macros and constants

_10
#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

Return to Main macros and constants

_10
#define SP_MAX_CLIENT_KEY_LENGTH 511

Maximum length of the client key (not counting terminating NULL)

See also

SP_MAX_ZEROCONF_BLOB_LENGTH

Return to Main macros and constants

_10
#define SP_MAX_ZEROCONF_BLOB_LENGTH 2047

Maximum length of the ZeroConf blob (not counting terminating NULL)

See also

SP_MAX_LOGIN_ID_LENGTH

Return to Main macros and constants

_10
#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

Return to Main macros and constants

_10
#define SP_MAX_AVAILABILITY_LENGTH 15

Maximum length of the availability string (not counting terminating NULL)

See also

SP_MAX_PARTNER_NAME_LENGTH

Return to Main macros and constants

_10
#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

Return to Main macros and constants

_10
#define SP_MAX_FILENAME_LENGTH 63

Maximum length of filename fields (not counting terminating NULL)

SP_ZEROCONF_DISABLED

Return to Main macros and constants

_10
#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

Return to Main macros and constants

_10
#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

Return to Main macros and constants

_10
#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

Return to Main macros and constants

_10
#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

Return to Main macros and constants

_10
#define SP_SCOPE_STREAMING "streaming"

Value for SpConfig::scope when implementing a basic streaming device.

SP_DEVICE_ALIAS_ATTRIBUTE_GROUP

Return to Main macros and constants

_10
#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:

SP_GLOBAL_ATTRIBUTE_VOICE

Return to Main macros and constants

_10
#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

Return to Main macros and constants

_10
#define SP_MAX_SUPPORTED_FORMATS 8

See also

SP_PLAYBACK_RESTRICTION_ALREADY_PAUSED

Return to Main macros and constants

_10
#define SP_PLAYBACK_RESTRICTION_ALREADY_PAUSED 1

The track is already paused.

SP_PLAYBACK_RESTRICTION_NOT_PAUSED

Return to Main macros and constants

_10
#define SP_PLAYBACK_RESTRICTION_NOT_PAUSED 2

The track is already playing.

SP_PLAYBACK_RESTRICTION_LICENSE_DISALLOW

Return to Main macros and constants

_10
#define SP_PLAYBACK_RESTRICTION_LICENSE_DISALLOW 4

Licensing rules disallow this action.

SP_PLAYBACK_RESTRICTION_AD_DISALLOW

Return to Main macros and constants

_10
#define SP_PLAYBACK_RESTRICTION_AD_DISALLOW 8

Action can't be performed while an ad is playing.

SP_PLAYBACK_RESTRICTION_NO_PREV_TRACK

Return to Main macros and constants

_10
#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

Return to Main macros and constants

_10
#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

Return to Main macros and constants

_10
#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

Return to Main macros and constants

_10
#define SP_PLAYBACK_RESTRICTION_ENDLESS_CONTEXT 128

The action is restricted for context level reasons.

SP_MAX_METADATA_KEY_LENGTH

Return to Main macros and constants

_10
#define SP_MAX_METADATA_KEY_LENGTH 32

Maximum number of characters in the key of a SpAdMetadata struct, not counting the terminating NULL.

See also

SP_MAX_METADATA_VALUE_LENGTH

Return to Main macros and constants

_10
#define SP_MAX_METADATA_VALUE_LENGTH 64

Maximum number of characters in the value of a SpAdMetadata struct, not counting the terminating NULL.

See also

Data Structures


SpPlaybackRestrictions

Return to Main data structures

Playback restrictions.


_12
struct SpPlaybackRestrictions {
_12
uint32_t disallow_pausing_reasons;
_12
uint32_t disallow_resuming_reasons;
_12
uint32_t disallow_seeking_reasons;
_12
uint32_t disallow_peeking_prev_reasons;
_12
uint32_t disallow_peeking_next_reasons;
_12
uint32_t disallow_skipping_prev_reasons;
_12
uint32_t disallow_skipping_next_reasons;
_12
uint32_t disallow_toggling_repeat_context_reasons;
_12
uint32_t disallow_toggling_repeat_track_reasons;
_12
uint32_t disallow_toggling_shuffle_reasons;
_12
};

uint32_t disallow_pausing_reasonsBitfield of reasons the pause action is not allowed.
uint32_t disallow_resuming_reasonsBitfield of reasons the resume action is not allowed.
uint32_t disallow_seeking_reasonsBitfield of reasons seeking is not allowed.
uint32_t disallow_peeking_prev_reasonsBitfield of reasons peeking on the previous track is not allowed.
uint32_t disallow_peeking_next_reasonsBitfield of reasons peeking on the next track is not allowed.
uint32_t disallow_skipping_prev_reasonsBitfield of reasons skipping to the previous track is not allowed.
uint32_t disallow_skipping_next_reasonsBitfield of reasons skipping to the next track is not allowed.
uint32_t disallow_toggling_repeat_context_reasonsBitfield of reasons setting repeat context is not allowed.
uint32_t disallow_toggling_repeat_track_reasonsBitfield of reasons setting repeat track is not allowed.
uint32_t disallow_toggling_shuffle_reasonsBitfield of reasons toggling shuffle is not allowed.

SpMetadata

Return to Main data structures

Track metadata.

See also

_22
struct SpMetadata {
_22
char playback_source;
_22
char playback_source_uri;
_22
char track;
_22
char track_uri;
_22
char artist;
_22
char artist_uri;
_22
char album;
_22
char album_uri;
_22
char album_cover_uri;
_22
char original_track_uri;
_22
uint32_t duration_ms;
_22
int32_t index;
_22
char track_uid;
_22
uint32_t original_index;
_22
uint32_t bitrate;
_22
struct SpPlaybackRestrictions playback_restrictions;
_22
char playback_id;
_22
enum SpContent content_type;
_22
enum SpMediaType media_type;
_22
enum SpAudioQuality audio_quality;
_22
};

char playback_sourceDisplay name of the playback source. E.g., the name of the playlist from which playback was initiated (UTF-8-encoded)
char playback_source_uriSpotify URI of the playback source (in the form "spotify:xxxxxx:xxxxxxx...")
char trackDisplay name of the track (UTF-8-encoded)
char track_uriSpotify URI of the track (in the form "spotify:track:xxxxxxx...")
char artistDisplay name of the artist of the track (UTF-8-encoded)
char artist_uriSpotify URI of the artist of the track (in the form "spotify:artist:xxxxxxx...")
char albumDisplay name of the track's album (UTF-8-encoded)
char album_uriSpotify URI of the track's album (in the form "spotify:album:xxxxxxx...")
char album_cover_uriSpotify URI of the album's cover art image (in the form "spotify:image:xxxxxxx...")
char original_track_uriSpotify URI of the original track before relinking (in the form "spotify:track:xxxxxxx...")
uint32_t duration_msPlayback duration of the track in milliseconds.
int32_t indexIndex of the track in the currently playing context.
char track_uidTrack UID of the track in the currently playing context.
uint32_t original_indexIndex of the track in the original (unchanged) playing context.
uint32_t bitrateThe bitrate of the track in kbps. 0 means "unplayable".
struct SpPlaybackRestrictions playback_restrictionsRestrictions that apply to playback and transitions related to this track.
char playback_idPlayback-id of this playback of this specific track.
enum SpContent content_typeContent type of this track.
enum SpMediaType media_typeMedia type of this track.
enum SpAudioQuality audio_qualityAudio quality of this track.

SpAdMetadata

Return to Main data structures

Key value pair for Ad-related metadata.


_10
struct SpAdMetadata {
_10
char key;
_10
char value;
_10
};

char keyKey.
char valueValue.

SpFormat

Return to Main data structures

Mapping of which media formats are supported in which DRM.

See also

_10
struct SpFormat {
_10
enum SpDrmFormat drm;
_10
uint64_t media;
_10
};

enum SpDrmFormat drmDRM format which the integration supports.
uint64_t mediaSupported media formats for a DRM.

SpZeroConfDeviceAlias

Return to Main data structures

ZeroConf DeviceAlias.

This structure contains information about a single device alias, as returned by SpZeroConfGetVars

See also

_10
struct SpZeroConfDeviceAlias {
_10
uint32_t id;
_10
int is_group;
_10
char display_name;
_10
};

uint32_t idString to be sent in the "id" field of the alias in the "getInfo" response.
int is_groupBoolean (0 = "false", 1 = "true") to be sent in the "isGroup" field of the alias in the "getInfo" response.
char display_nameString 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

_19
struct SpZeroConfVars {
_19
char public_key;
_19
char device_id;
_19
char remote_name;
_19
char device_type;
_19
char library_version;
_19
int resolver_version;
_19
char group_status;
_19
int webserver_current_port;
_19
char token_type;
_19
char client_id;
_19
char scope;
_19
char availability;
_19
uint32_t product_id;
_19
struct SpZeroConfDeviceAlias aliases;
_19
uint32_t alias_count;
_19
struct SpFormat supported_drm_media_formats;
_19
uint64_t supported_capabilities;
_19
};

char public_keyString to be sent in the "publicKey" field of the "getInfo" response[*].
char device_idString to be sent in the "deviceID" field of the "getInfo" response[*].
char remote_nameString to be sent in the "remoteName" field of the "getInfo" response[*].
char device_typeString to be sent in the "deviceType" field of the "getInfo" response[*].
char library_versionString to be sent in the "libraryVersion" field of the "getInfo" response[*].
int resolver_versionInteger to be sent as string in the "resolverVersion" field of the "getInfo" response[*].
char group_statusString to be sent in the "groupStatus" field of the "getInfo" response[*].
int webserver_current_portCurrent internal ZeroConf webserver port number. To be used when running an external mDNS server together with an internal webserver.
char token_typeString to be sent in the "tokenType" field of the "getInfo" response[*].
char client_idString to be sent in the "clientID" field of the "getInfo" response[*].
char scopeString to be sent in the "scope" field of the "getInfo" response[*].
char availabilityString to be sent in the "availability" field of the "getInfo" response[*].
uint32_t product_idInteger to be sent in the "productID" field of the "getInfo" response[*].
struct SpZeroConfDeviceAlias aliasesArray of SpZeroConfDeviceAlias to be sent in the "aliases" field of the "getInfo" response[*].
uint32_t alias_countNumber of valid items in aliases array.
struct SpFormat supported_drm_media_formatsArray of SpFormat to be sent in the "supported_drm_media_formats" field of the "getInfo" response[*].
uint64_t supported_capabilitiesInteger 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.


_10
struct SpSampleFormat {
_10
int channels;
_10
int sample_rate;
_10
};

int channelsNumber of channels (1 = mono, 2 = stereo)
int sample_rateSample 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.


_10
struct SpPlaybackCallbacks {
_10
SpCallbackPlaybackNotify on_notify;
_10
SpCallbackPlaybackSeek on_seek;
_10
SpCallbackPlaybackApplyVolume on_apply_volume;
_10
};

SpCallbackPlaybackNotify on_notifyNotification callback.
SpCallbackPlaybackSeek on_seekSeek position callback.
SpCallbackPlaybackApplyVolume on_apply_volumeApply 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.


_10
struct SpDebugCallbacks {
_10
SpCallbackDebugMessage on_message;
_10
};

SpCallbackDebugMessage on_messageDebug 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.


_10
struct SpConnectionCallbacks {
_10
SpCallbackConnectionNotify on_notify;
_10
SpCallbackConnectionNewCredentials on_new_credentials;
_10
SpCallbackConnectionMessage on_message;
_10
};

SpCallbackConnectionNotify on_notifyNotification callback.
SpCallbackConnectionNewCredentials on_new_credentialsCredentials blob callback.
SpCallbackConnectionMessage on_messageConnection 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.


_10
struct SpDeviceAlias {
_10
const char *display_name;
_10
uint32_t attributes;
_10
};

const char * display_nameA UTF-8 encoded display name for an alias of the application/device.
uint32_t attributesAttributes for this device alias.

SpConfig

Return to Main data structures

Configuration.

See also

_28
struct SpConfig {
_28
int api_version;
_28
void *memory_block;
_28
uint32_t memory_block_size;
_28
const char *unique_id;
_28
const char *display_name;
_28
uint32_t global_attributes;
_28
struct SpDeviceAlias device_aliases;
_28
const char *brand_name;
_28
const char *brand_display_name;
_28
const char *model_name;
_28
const char *model_display_name;
_28
const char *platform_name;
_28
const char *client_id;
_28
uint32_t product_id;
_28
const char *scope;
_28
const char *os_version;
_28
enum SpDeviceType device_type;
_28
enum SpPlaybackBitrate max_bitrate;
_28
SpCallbackError error_callback;
_28
void *error_callback_context;
_28
int zeroconf_serve;
_28
const char *host_name;
_28
int zeroconf_port;
_28
int zeroconf_port_range;
_28
struct SpFormat supported_drm_media_formats;
_28
struct SpAdMetadata ad_metadata;
_28
};

int api_versionThe version of the API contained in this header file. Must be set to SP_API_VERSION.
void * memory_blockPointer to a memory block to be used by the library.
uint32_t memory_block_sizeSize of the memory_block buffer in bytes.
const char * unique_idA NULL-terminated character string that uniquely identifies the device (such as a MAC address)
const char * display_nameA UTF-8-encoded display name for the application/device.
uint32_t global_attributesThe global attributes is a bitfield where each attribute is OR:ed together and stored in this integer.
struct SpDeviceAlias device_aliasesDevice alias definitions. These are optional, if you don't want to define aliases this array must be zeroed.
const char * brand_nameA NULL-terminated string containing the brand name of the hardware device (for hardware integrations)
const char * brand_display_nameA UTF-8-encoded brand name of the hardware device (for hardware integrations). Should be very similar to brand_name.
const char * model_nameA NULL-terminated string containing the model name of the hardware device (for hardware integrations)
const char * model_display_nameA UTF-8-encoded model name of the hardware device (for hardware integrations)
const char * platform_nameA NULL-terminated string containing the platform identifier.
const char * client_idA NULL-terminated string containing the client id of the application.
uint32_t product_idAn integer enumerating the product for this partner.
const char * scopeA NULL-terminated string containing the OAuth scope requested when authenticating with the Spotify backend.
const char * os_versionA NULL-terminated string containing the os version running on the hardware.
enum SpDeviceType device_typeThe device type that best describes this product.
enum SpPlaybackBitrate max_bitrateThe maximum bitrate to use for playback.
SpCallbackError error_callbackPointer to a callback function that will receive error notifications.
void * error_callback_contextApplication-defined pointer that will be passed unchanged as the context argument to the error_callback callback.
int zeroconf_serveNot applicable in this eSDK configuration.
const char * host_nameNot applicable in this eSDK configuration.
int zeroconf_portNot applicable in this eSDK configuration.
int zeroconf_port_rangeNot applicable in this eSDK configuration.
struct SpFormat supported_drm_media_formats
struct SpAdMetadata ad_metadataFor clients that need to register ad-relasted metadata.

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.


_10
struct SpDeviceAliasCallbacks {
_10
SpCallbackSelectedDeviceAliasChanged on_selected_device_alias_changed;
_10
SpCallbackDeviceAliasesUpdateDone on_device_aliases_update_done;
_10
};

SpCallbackSelectedDeviceAliasChanged on_selected_device_alias_changedSelected device alias updated callback.
SpCallbackDeviceAliasesUpdateDone on_device_aliases_update_doneDevice alias list updated.

Typedefs


SpCallbackError()

Return to Main Typedefs

_10
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 errorError code
[in]void * contextContext 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()

Return to Main Typedefs

_10
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 eventType of event
[in]void * contextContext 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()

Return to Main Typedefs

_10
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_msNew position within the track in milliseconds
[in]void * contextContext 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()

Return to Main Typedefs

_10
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 volumeVolume in the range 0 (silence) to 65535 (max volume)
[in]uint8_t remoteSet to 1 if the volume was changed using Spotify Connect, 0 otherwise
[in]void * contextContext 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()

Return to Main Typedefs

_10
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 eventType of event
[in]void * contextContext 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()

Return to Main Typedefs

_10
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_blobCredentials to be passed to SpConnectionLoginBlob
[in]const char * usernameuser name to be passed to SpConnectionLoginBlob
[in]void * contextContext 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()

Return to Main Typedefs

_10
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 * messageMessage to be displayed to the user.
[in]void * contextContext 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()

Return to Main Typedefs

_10
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_messageMessage to be logged
[in]void * contextContext 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()

Return to Main Typedefs

_10
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_indexIndex of the device alias which was selected
[in]void * contextContext 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()

Return to Main Typedefs

_10
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_codeif the update was successful, the value is kSpErrorOk
[in]void * contextContext 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

Return to Main enumerations

_67
enum SpError {
_67
kSpErrorOk,
_67
kSpErrorFailed,
_67
kSpErrorInitFailed,
_67
kSpErrorWrongAPIVersion,
_67
kSpErrorNullArgument,
_67
kSpErrorInvalidArgument,
_67
kSpErrorUninitialized,
_67
kSpErrorAlreadyInitialized,
_67
kSpErrorLoginBadCredentials,
_67
kSpErrorNeedsPremium,
_67
kSpErrorTravelRestriction,
_67
kSpErrorApplicationBanned,
_67
kSpErrorGeneralLoginError,
_67
kSpErrorUnsupported,
_67
kSpErrorNotActiveDevice,
_67
kSpErrorAPIRateLimited,
_67
kSpErrorReentrancyDetected,
_67
kSpErrorMultiThreadingDetected,
_67
kSpErrorTryAgain,
_67
kSpErrorDuringLogout,
_67
kSpErrorPermanentConnectionError,
_67
kSpErrorEntropyFailure,
_67
kSpErrorZeroConfErrorStart,
_67
kSpErrorZeroConfBadRequest,
_67
kSpErrorZeroConfUnknown,
_67
kSpErrorZeroConfNotImplemented,
_67
kSpErrorZeroConfNotInstalled,
_67
kSpErrorZeroConfNotLoaded,
_67
kSpErrorZeroConfNotAuthorized,
_67
kSpErrorZeroConfCannotLoad,
_67
kSpErrorZeroConfSystemUpdateRequired,
_67
kSpErrorZeroConfSpotifyUpdateRequired,
_67
kSpErrorZeroConfLoginFailed,
_67
kSpErrorZeroConfInvalidPublicKey,
_67
kSpErrorZeroConfMissingAction,
_67
kSpErrorZeroConfInvalidAction,
_67
kSpErrorZeroConfInvalidArguments,
_67
kSpErrorZeroConfNoSpotifySession,
_67
kSpErrorZeroConfSpotifyError,
_67
kSpErrorPlaybackErrorStart,
_67
kSpErrorGeneralPlaybackError,
_67
kSpErrorPlaybackRateLimited,
_67
kSpErrorPlaybackCappingLimitReached,
_67
kSpErrorAdIsPlaying,
_67
kSpErrorCorruptTrack,
_67
kSpErrorContextFailed,
_67
kSpErrorPrefetchItemUnavailable,
_67
kSpAlreadyPrefetching,
_67
kSpStorageReadError,
_67
kSpStorageWriteError,
_67
kSpPrefetchDownloadFailed,
_67
kSpErrorBusy,
_67
kSpErrorUnavailable,
_67
kSpErrorNotAllowed,
_67
kSpErrorNetworkRequired,
_67
kSpErrorNotLoggedIn,
_67
kSpErrorInProgress,
_67
kSpErrorPlaybackInitiation,
_67
kSpErrorPresetFailed,
_67
kSpErrorInvalidRequest,
_67
kSpErrorInvalidTrackId,
_67
kSpErrorIncorrectMsPlayed,
_67
kSpErrorDeviceNotControllable,
_67
kSpErrorPlaybackInitiationTimeout,
_67
kSpErrorGeneralDownloadError,
_67
};

kSpErrorOkThe operation was successful.
kSpErrorFailedThe operation failed due to an unspecified issue.
kSpErrorInitFailedThe library could not be initialized.
kSpErrorWrongAPIVersionThe library could not be initialized because of an incompatible API version.
kSpErrorNullArgumentAn unexpected NULL pointer was passed as an argument to a function.
kSpErrorInvalidArgumentAn unexpected argument value was passed to a function.
kSpErrorUninitializedA function was invoked before SpInit or after SpFree was called.
kSpErrorAlreadyInitializedSpInit was called more than once.
kSpErrorLoginBadCredentialsLogin to Spotify failed because of invalid credentials.
kSpErrorNeedsPremiumThe operation requires a Spotify Premium account.
kSpErrorTravelRestrictionThe Spotify user is not allowed to log in from this country.
kSpErrorApplicationBannedThe application has been banned by Spotify
kSpErrorGeneralLoginErrorAn unspecified login error occurred.
kSpErrorUnsupportedThe operation is not supported.
kSpErrorNotActiveDeviceThe operation is not supported if the device is not the active playback device.
kSpErrorAPIRateLimitedThe API has been rate-limited.
kSpErrorReentrancyDetectedThe eSDK API was used from a callback.
kSpErrorMultiThreadingDetectedThe eSDK API was used from multiple threads.
kSpErrorTryAgainThe eSDK API cannot be performed right now.
kSpErrorDuringLogoutLogout failed during SpFree call.
kSpErrorPermanentConnectionErrorPermanent connection error. eSDK ceased attempts to reconnect.
kSpErrorEntropyFailureFailed to get cryptographic random data from the platform.
kSpErrorZeroConfErrorStartError range reserved for ZeroConf-related errors.
kSpErrorZeroConfBadRequestZeroConf Web server problem or critically malformed request.
kSpErrorZeroConfUnknownFallback when no other ZeroConf error applies.
kSpErrorZeroConfNotImplementedZeroConf device does not implement this feature.
kSpErrorZeroConfNotInstalledSpotify not installed (where applicable)
kSpErrorZeroConfNotLoadedSpotify not loaded (where applicable)
kSpErrorZeroConfNotAuthorizedSpotify client not authorized to play.
kSpErrorZeroConfCannotLoadSpotify cannot be loaded (where applicable)
kSpErrorZeroConfSystemUpdateRequiredDevice system needs update (where applicable)
kSpErrorZeroConfSpotifyUpdateRequiredSpotify requires an update.
kSpErrorZeroConfLoginFailedSpotify returned an error when trying to login.
kSpErrorZeroConfInvalidPublicKeyZeroConf login failed due to an invalid public key.
kSpErrorZeroConfMissingActionZeroConf HTTP request has no action parameter.
kSpErrorZeroConfInvalidActionZeroConf HTTP request has an unrecognized action parameter.
kSpErrorZeroConfInvalidArgumentsIncorrect or insufficient ZeroConf arguments supplied for requested action.
kSpErrorZeroConfNoSpotifySessionNo valid Spotify session for requested Spotify action (where applicable)
kSpErrorZeroConfSpotifyErrorA Spotify API call returned an error not covered by other error messages.
kSpErrorPlaybackErrorStartError range reserved for playback-related errors.
kSpErrorGeneralPlaybackErrorAn unspecified playback error occurred.
kSpErrorPlaybackRateLimitedThe application has been rate-limited.
kSpErrorPlaybackCappingLimitReachedThe Spotify user has reached a capping limit that is in effect in this country and/or for this track.
kSpErrorAdIsPlayingCannot change track while ad is playing.
kSpErrorCorruptTrackThe track is (temporarily) corrupted in the Spotify catalogue.
kSpErrorContextFailedUnable to read all tracks from the playing context.
kSpErrorPrefetchItemUnavailableThe 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.
kSpAlreadyPrefetchingAn 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.
kSpStorageReadErrorA permanent error was encountered while reading to a registered file storage callback. This error is only relevant for builds with offline storage enabled.
kSpStorageWriteErrorA permanent error was encountered while writing to a registered file storage callback. This error is only relevant for builds with offline storage enabled.
kSpPrefetchDownloadFailedThe 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.
kSpErrorBusyThe current API call cannot be completed because eSDK is busy. Same API call should be done sometime later with the same arguments.
kSpErrorUnavailableThe current API call cannot be completed because the requested operation is not available at the moment.
kSpErrorNotAllowedThis eSDK API is not allowed due to current license restrictions.
kSpErrorNetworkRequiredThe current API call cannot be completed without connection to the Spotify backend.
kSpErrorNotLoggedInThe current API call cannot be completed without being logged in.
kSpErrorInProgressUsed in callbacks to notify the application that the action is not yet complete.
kSpErrorPlaybackInitiationUsed in SpCallbackError callback to notify the application that playback initiation failed.
kSpErrorPresetFailedUsed in SpCallbackError callback to notify the application that recalling and playing a preset failed.
kSpErrorInvalidRequestThe queued track was rejected.
kSpErrorInvalidTrackIdUsed in SpCallbackError callback to notify the application that an invalid track_id was used.
kSpErrorIncorrectMsPlayedUsed in SpCallbackError callback to notify the application that an incorrect value for ms_played was reported.
kSpErrorDeviceNotControllableThe operation is not allowed since the device is not controllable.
kSpErrorPlaybackInitiationTimeoutThe playback initiation operation timed out.
kSpErrorGeneralDownloadErrorFailed to download the requested track.

SpAPIReturnCode

Return to Main enumerations

_10
enum SpAPIReturnCode {
_10
kSpAPINoError,
_10
kSpAPITryAgain,
_10
kSpAPIDNSLookupError,
_10
kSpAPIGenericError,
_10
kSpAPINotSupported,
_10
kSpAPIEOF,
_10
kSpAPINotFound,
_10
};

kSpAPINoErrorThis code should be used when the API call was successful.
kSpAPITryAgainThis code means operation cannot be performed right now. Same API call should be done sometime later with the same arguments.
kSpAPIDNSLookupErrorUse to notify about any DNS lookup error that cannot be retried.
kSpAPIGenericErrorAPI call has failed.
kSpAPINotSupportedRequested feature is not supported by platform.
kSpAPIEOFEnd of file/socket reached.
kSpAPINotFoundRequested resource does not exist.

SpPlaybackBitrate

Return to Main enumerations

_10
enum SpPlaybackBitrate {
_10
kSpPlaybackBitrateDefault,
_10
kSpPlaybackBitrateLow,
_10
kSpPlaybackBitrateNormal,
_10
};

kSpPlaybackBitrateDefaultSet the bitrate to the default (currently High).
kSpPlaybackBitrateLowSet the bitrate to low. Corresponds to e.g. 96 kbit/s ogg/vorbis.
kSpPlaybackBitrateNormalSet the bitrate to normal. Corresponds to e.g. 160 kbit/s ogg/vorbis.

SpPlaybackNotification

Return to Main enumerations

_19
enum SpPlaybackNotification {
_19
kSpPlaybackNotifyPlay,
_19
kSpPlaybackNotifyPause,
_19
kSpPlaybackNotifyTrackChanged,
_19
kSpPlaybackNotifyNext,
_19
kSpPlaybackNotifyPrev,
_19
kSpPlaybackNotifyShuffleOn,
_19
kSpPlaybackNotifyShuffleOff,
_19
kSpPlaybackNotifyRepeatOn,
_19
kSpPlaybackNotifyRepeatOff,
_19
kSpPlaybackNotifyBecameActive,
_19
kSpPlaybackNotifyBecameInactive,
_19
kSpPlaybackNotifyAudioDeliveryDone,
_19
kSpPlaybackNotifyContextChanged,
_19
kSpPlaybackNotifyMetadataChanged,
_19
kSpPlaybackNotifyNetworkRequired,
_19
kSpPlaybackNotifyTrackDownloadStalled,
_19
kSpPlaybackNotifyQueuedTrackAccepted,
_19
};

kSpPlaybackNotifyPlayPlayback has started or has resumed.
kSpPlaybackNotifyPausePlayback has been paused.
kSpPlaybackNotifyTrackChangedThe current track or its metadata has changed.
kSpPlaybackNotifyNextPlayback has skipped to the next track.
kSpPlaybackNotifyPrevPlayback 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
kSpPlaybackNotifyBecameActiveThis device has become the active playback device.
kSpPlaybackNotifyBecameInactiveThis device is no longer the active playback device.
kSpPlaybackNotifyAudioDeliveryDoneThe library will not send any more audio data.
kSpPlaybackNotifyContextChangedPlayback changed to a different Spotify context.
kSpPlaybackNotifyMetadataChangedMetadata is changed.
kSpPlaybackNotifyNetworkRequiredPlayback is not allowed without network connection.
kSpPlaybackNotifyTrackDownloadStalledDownload of the current track stalled due to network outage.
kSpPlaybackNotifyQueuedTrackAcceptedThe queued track was accepted.

SpConnectionNotification

Return to Main enumerations

_10
enum SpConnectionNotification {
_10
kSpConnectionNotifyLoggedIn,
_10
kSpConnectionNotifyLoggedOut,
_10
kSpConnectionNotifyTemporaryError,
_10
kSpConnectionNotifyDisconnect,
_10
kSpConnectionNotifyReconnect,
_10
kSpConnectionNotifyProductTypeChanged,
_10
kSpConnectionNotifyZeroConfVarsChanged,
_10
kSpConnectionNotifyTransmittingData,
_10
};

kSpConnectionNotifyLoggedInThe user has successfully logged in to Spotify
kSpConnectionNotifyLoggedOutThe user has been logged out of Spotify
kSpConnectionNotifyTemporaryErrorA temporary connection error occurred. The library will automatically retry.
kSpConnectionNotifyDisconnectThe connection to Spotify has been lost.
kSpConnectionNotifyReconnectThe connection to Spotify has been (re-)established.
kSpConnectionNotifyProductTypeChangedThe connected user account type has changed (became premium, for example).
kSpConnectionNotifyZeroConfVarsChangedThe SpZeroConfVars has changed.
kSpConnectionNotifyTransmittingDataThe eSDK is transmitting data.

SpDeviceType

Return to Main enumerations

_16
enum SpDeviceType {
_16
kSpDeviceTypeComputer,
_16
kSpDeviceTypeTablet,
_16
kSpDeviceTypeSmartphone,
_16
kSpDeviceTypeSpeaker,
_16
kSpDeviceTypeTV,
_16
kSpDeviceTypeAVR,
_16
kSpDeviceTypeSTB,
_16
kSpDeviceTypeAudioDongle,
_16
kSpDeviceTypeGameConsole,
_16
kSpDeviceTypeCastVideo,
_16
kSpDeviceTypeCastAudio,
_16
kSpDeviceTypeAutomobile,
_16
kSpDeviceTypeSmartwatch,
_16
kSpDeviceTypeChromebook,
_16
};

kSpDeviceTypeComputerLaptop or desktop computer device.
kSpDeviceTypeTabletTablet PC device.
kSpDeviceTypeSmartphoneSmartphone device.
kSpDeviceTypeSpeakerSpeaker device.
kSpDeviceTypeTVTelevision device.
kSpDeviceTypeAVRAudio/Video receiver device.
kSpDeviceTypeSTBSet-Top Box device.
kSpDeviceTypeAudioDongleAudio dongle device.
kSpDeviceTypeGameConsoleGame console device.
kSpDeviceTypeCastVideoChromecast Video.
kSpDeviceTypeCastAudioChromecast Audio.
kSpDeviceTypeAutomobileAutomobile.
kSpDeviceTypeSmartwatchSmartwatch.
kSpDeviceTypeChromebookChromebook.

SpMetadataTrack

Return to Main enumerations

_10
enum SpMetadataTrack {
_10
kSpMetadataTrackBeforePrevious,
_10
kSpMetadataTrackPrevious,
_10
kSpMetadataTrackCurrent,
_10
kSpMetadataTrackNext,
_10
kSpMetadataTrackAfterNext,
_10
};

kSpMetadataTrackBeforePreviousIndex of the before previous track in the track list.
kSpMetadataTrackPreviousIndex of the previous track in the track list.
kSpMetadataTrackCurrentIndex of the current track in the track list.
kSpMetadataTrackNextIndex of the next track in the track list.
kSpMetadataTrackAfterNextIndex of the after next track in the track list.

SpConnectivity

Return to Main enumerations

_10
enum SpConnectivity {
_10
kSpConnectivityNone,
_10
kSpConnectivityWired,
_10
kSpConnectivityWireless,
_10
kSpConnectivityMobile,
_10
};

kSpConnectivityNoneThe device is not connected to the network.
kSpConnectivityWiredThe device is connected to a wired network.
kSpConnectivityWirelessThe device is connected to a wireless network.
kSpConnectivityMobileThe device uses a mobile data connection.

SpContent

Return to Main enumerations

_10
enum SpContent {
_10
kSpContentUnknown,
_10
kSpContentMusicTrack,
_10
kSpContentShowEpisode,
_10
kSpContentAd,
_10
};

kSpContentUnknownUnknown content type.
kSpContentMusicTrackMusic track.
kSpContentShowEpisodePodcast show episode.
kSpContentAdAdvertisement.

SpMediaType

Return to Main enumerations

_10
enum SpMediaType {
_10
kSpMediaTypeAudio,
_10
kSpMediaTypeVideo,
_10
};

kSpMediaTypeAudioAudio media type.
kSpMediaTypeVideoVideo media type.

SpAudioQuality

Return to Main enumerations

_10
enum SpAudioQuality {
_10
kSpAudioQualityUnknown,
_10
kSpAudioQualityLow,
_10
kSpAudioQualityNormal,
_10
kSpAudioQualityHigh,
_10
kSpAudioQualityVeryHigh,
_10
};

kSpAudioQualityUnknownUnknown audio quality.
kSpAudioQualityLowLow audio quality.
kSpAudioQualityNormalNormal audio quality (e.g. 96 kbps ogg/vorbis)
kSpAudioQualityHighHigh audio quality (e.g. 160 kbps ogg/vorbis)
kSpAudioQualityVeryHighVery high audio quality (e.g. 320 kbps ogg/vorbis)

SpDrmFormat

Return to Main enumerations

_10
enum SpDrmFormat {
_10
kSpDrmFormatUnknown,
_10
kSpDrmFormatUnencrypted,
_10
kSpDrmFormatFairPlay,
_10
kSpDrmFormatWidevine,
_10
kSpDrmFormatPlayReady,
_10
};

kSpDrmFormatUnknownUnknown DRM.
kSpDrmFormatUnencryptedNo DRM, unencrypted.
kSpDrmFormatFairPlayFairPlay.
kSpDrmFormatWidevineWidevine.
kSpDrmFormatPlayReadyPlayReady.

SpReDeliveryMode

Return to Main enumerations

_10
enum SpReDeliveryMode {
_10
kSpRedeliveryModeActivated,
_10
kSpRedeliveryModeDeactivated,
_10
};

kSpRedeliveryModeActivatedRedelivery is activated.
kSpRedeliveryModeDeactivatedRedelivery is deactivated.

Functions


SpInit()

Return to Main functions

_10
SpError SpInit(struct SpConfig *conf)

Initialize the library.

Parameters

[in]struct SpConfig * confConfiguration parameters

Returns

Returns an error code

SpFree()

Return to Main functions

_10
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()

Return to Main functions

_10
const char * SpGetLibraryVersion(void)

Retrieve a version string for the library.

Returns

Version string

Notes:
  • This API can be invoked from a callback.

SpConnectionSetConnectivity()

Return to Main functions

_10
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 connectivityType of connection

Returns

Returns an error code

SpConnectionGetConnectivity()

Return to Main functions

_10
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()

Return to Main functions

_10
SpError SpConnectionLoginBlob(const char *username, const char *credentials_blob)

Log in a user to Spotify using a credentials blob.

Parameters

[in]const char * usernameSpotify 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_blobCredentials 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".

SpConnectionLoginOauthToken()

Return to Main functions

_10
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_tokenSpotify OAuth access token with "streaming" scope. See https://developer.spotify.com/documentation/web-api/concepts/authorization/

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()

Return to Main functions

_10
SpError SpConnectionLogout(void)

Log the user out of Spotify

Returns

Returns an error code

See also Notes:

SpConnectionIsLoggedIn()

Return to Main functions

_10
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()

Return to Main functions

_10
const char * SpConnectionGetAckId(void)

Get the last Ack ID.

Notes:
  • This function is deprecated and should not be used.

SpGetCanonicalUsername()

Return to Main functions

_10
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()

Return to Main functions

_10
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_nameA UTF-8-encoded display name

Returns

Returns an error code

Notes:
  • The display name is not allowed to be an empty string.

SpSetVolumeSteps()

Return to Main functions

_10
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 stepsthe 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()

Return to Main functions

_10
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_group0: 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()

Return to Main functions

_10
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()

Return to Main functions

_10
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()

Return to Main functions

_10
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()

Return to Main functions

_10
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()

Return to Main functions

_10
SpError SpRegisterConnectionCallbacks(struct SpConnectionCallbacks *cb, void *context)

Register callbacks related to the connection to Spotify

Parameters

[in]struct SpConnectionCallbacks * cbStructure with pointers to individual callback functions. Any of the pointers in the structure may be NULL.
[in]void * contextApplication-defined pointer that will be passed unchanged as the context argument to the callbacks.

Returns

Returns an error code

SpRegisterDebugCallbacks()

Return to Main functions

_10
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 * cbStructure with pointers to individual callback functions.
[in]void * contextApplication-defined pointer that will be passed unchanged as the context argument to the callback.

Returns

Returns an error code

SpRegisterPlaybackCallbacks()

Return to Main functions

_10
SpError SpRegisterPlaybackCallbacks(struct SpPlaybackCallbacks *cb, void *context)

Register playback-related callbacks.

Parameters

[in]struct SpPlaybackCallbacks * cbStructure with pointers to individual callback functions. Any of the pointers in the structure may be NULL.
[in]void * contextApplication-defined pointer that will be passed unchanged as the context argument to the callbacks.

Returns

Returns an error code

SpGetMetadata()

Return to Main functions

_10
SpError SpGetMetadata(struct SpMetadata *metadata, int relative_index)

Retrieve metadata for a track in the current track list.

Parameters

[out]struct SpMetadata * metadataStructure to be filled with the metadata for the track
[in]int relative_indexTrack 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:

SpGetMetadataImageURL()

Return to Main functions

_10
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_uriimage URI returned in SpMetadata::album_cover_uri
[out]char * image_urlPointer to a buffer that will be filled with HTTP URL.
[in]size_t image_url_sizesize 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()

Return to Main functions

_10
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_cookiePointer 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_sizeSize 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()

Return to Main functions

_10
SpError SpPlaybackPlay(int alias_index)

Start or resume playback.

Parameters

[in]int alias_indexThe 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()

Return to Main functions

_10
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()

Return to Main functions

_10
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()

Return to Main functions

_10
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()

Return to Main functions

_10
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_msPosition within the track in milliseconds

Returns

Returns an error code

SpPlaybackSeekRelative()

Return to Main functions

_10
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_msAmount of time to seek within the current track, negative values seek backwards and positive values seek forward.

Returns

Returns an error code

SpPlaybackGetPosition()

Return to Main functions

_10
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()

Return to Main functions

_10
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 volumeVolume 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()

Return to Main functions

_10
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()

Return to Main functions

_10
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:

SpPlaybackIsAdPlaying()

Return to Main functions

_10
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()

Return to Main functions

_10
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()

Return to Main functions

_10
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()

Return to Main functions

_10
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()

Return to Main functions

_10
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()

Return to Main functions

_10
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 enable1 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()

Return to Main functions

_10
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 enable0 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()

Return to Main functions

_10
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()

Return to Main functions

_10
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 bitrateThe bitrate to be set

Returns

Returns an error code

SpPlaybackSetAvailableToPlay()

Return to Main functions

This function is deprecated and should not be used. See alternatives:

_10
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_play2 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()

Return to Main functions

This function is deprecated and should not be used. See alternatives:

_10
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()

Return to Main functions

_10
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:

SpPlaybackIsDeviceControllable()

Return to Main functions

_10
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()

Return to Main functions

_10
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_controllableWhen 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()

Return to Main functions

_10
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 countA counter of how many underruns happened. More than one could have occurred since the last one.

Returns

Returns an error code

SpPlaybackSetBandwidthLimit()

Return to Main functions

_10
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_secapproximate 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()

Return to Main functions

_10
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()

Return to Main functions

_10
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()

Return to Main functions

_10
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 * varsStructure to be filled with the variables
Notes:
  • This API can be invoked from a callback.

SpZeroConfAnnouncePause()

Return to Main functions

_10
SpError SpZeroConfAnnouncePause(void)

Temporarily pause ZeroConf mDNS announcements.

Returns

Returns an error code

Notes:

SpZeroConfAnnounceResume()

Return to Main functions

_10
SpError SpZeroConfAnnounceResume(void)

Resume ZeroConf mDNS announcement after calling SpZeroConfAnnouncePause

Returns

Returns an error code

Notes:

SpConnectionLoginZeroConf()

Return to Main functions

_10
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 * usernameSpotify 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_blobCredentials 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_keyClient 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_idLogin 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_typeToken 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()

Return to Main functions

_10
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()

Return to Main functions

_10
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()

Return to Main functions

_10
SpError SpRegisterDeviceAliasCallbacks(struct SpDeviceAliasCallbacks *cb, void *context)

Register callbacks related to device aliases.

Parameters

[in]struct SpDeviceAliasCallbacks * cbStructure with pointers to individual callback functions. Any of the pointers in the structure may be NULL.
[in]void * contextApplication-defined pointer that will be passed unchanged as the context argument to the callbacks.

Returns

Returns an error code

SpSetDeviceAliases()

Return to Main functions

_10
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 * aliasesPointer 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.

SpSetAdUserAgent()

Return to Main functions

_10
SpError SpSetAdUserAgent(const char *user_agent)

Set the ad user agent.

For clients that need to register a specific UserAgent for ads.

Parameters

[in]const char * user_agentPointer to a user agent string with the maximum length of SP_MAX_AD_USER_AGENT not counting the terminating NULL.
See also

SpRestrictDrmMediaFormats()

Return to Main functions

_10
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()

Return to Main functions

_10
SpError SpRestoreDrmMediaFormats(void)

Resets the list of DRM formats and media formats to the ones registered in SpInit

See also

Content



_10
#include "spotify_embedded_content.h"

Data Structures


Return to header index
SpContentCallbacks Callbacks to be registered with SpRegisterContentCallbacks

Typedefs


Return to header index
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


Return to header index
SpContentType

Functions


Return to header index
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.

_10
struct SpContentCallbacks {
_10
SpCallbackTrackCacheState track_state_callback;
_10
SpCallbackStorageKeyContentMapping store_key_map_callback;
_10
SpCallbackTrackRelinked track_relink_callback;
_10
SpCallbackTrackRemoved track_removed_callback;
_10
SpCallbackOnAvailableContainer on_available_container;
_10
};

SpCallbackTrackCacheState track_state_callbackTrack cached state callback.
SpCallbackStorageKeyContentMapping store_key_map_callbackContent mapping callback.
SpCallbackTrackRelinked track_relink_callbackNotify about track relink during prefetch/offline.
SpCallbackTrackRemoved track_removed_callbackNotify about track removal.
SpCallbackOnAvailableContainer on_available_containerNotify about an available container item.

Typedefs


SpCallbackTrackCacheState()

Return to Content Typedefs

_10
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_uriTrack URI which status is reported.
[in]uint32_t percentsHow much data is cached in percent. Range: [0 - 100%]
[in]void * contextContext 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()

Return to Content Typedefs

_10
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_keyStorage key that was used in Alloc/Read/Write API.
[in]const char * descriptorContent 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()

Return to Content Typedefs

_10
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_uriInitial URI passed into eSDK PrefetchURI/OfflineURI function calls.
[in]const char * new_uriURI that is obtained after relink has happened.
[in]void * contextContext provided in callback register procedure.

SpCallbackTrackRemoved()

Return to Content Typedefs

_10
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_uriURI passed into eSDK PlayURI/PrefetchURI/OfflineURI function calls.
[in]void * contextContext provided in callback register procedure.

SpCallbackOnAvailableContainer()

Return to Content Typedefs

_10
typedef void(* SpCallbackOnAvailableContainer)(const char *uri, int total, void *context)

Callback for each available container.

Parameters

[in]const char * uriURI of a container
[in]int totalTotal number of containers
[in]void * contextContext provided in callback register procedure.
Notes:
  • Experimental, subject of change

Enumerations


SpContentType

Return to Content enumerations

_10
enum SpContentType {
_10
kSpContentTrack,
_10
kSpContentTrackMetadata,
_10
};

kSpContentTrackContent pointed by descriptor is spotify playable item URI (track or episode)
kSpContentTrackMetadataContent pointed by descriptor is spotify playable item URI for which metadata is saved.

Functions


SpRegisterContentCallbacks()

Return to Content functions

_10
SpError SpRegisterContentCallbacks(struct SpContentCallbacks *callbacks, void *context)

Parameters

[in]struct SpContentCallbacks * callbacksStructure with pointers to individual callback functions. Any of the pointers in the structure may be NULL.
[in]void * contextApplication-defined pointer that will be passed unchanged as the context argument to the callbacks.

Returns

Returns an error code

Hal



_10
#include "spotify_embedded_hal.h"

Data Structures


Return to header index
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


Return to header index
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


Return to header index
SpIPFamily
SpSocketPool
SpSocketType
SpSocketOptions

Functions


Return to header index
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

Return to Hal data structures

Struct contains resolved hostname IP address and its family.


_10
struct SpSockaddr {
_10
enum SpIPFamily family;
_10
uint8_t addr;
_10
int port;
_10
};

enum SpIPFamily familyIP protocol family for which lookup is requested.
uint8_t addrIp address. Network byte order.
int portContains port value if applicable. Host byte order.

SpDnsHALCallbacks

Return to Hal data structures

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.

_10
struct SpDnsHALCallbacks {
_10
SpCallbackPerformDNSLookup dns_lookup_callback;
_10
};

SpCallbackPerformDNSLookup dns_lookup_callbackDNS lookup callback. If NULL eSDK will use its internal DNS resolve mechanism.

SpSocketHandle

Return to Hal data structures

Socket handle type.


_10
struct SpSocketHandle {
_10
void *handle;
_10
void *tls;
_10
};

void * handlePlatform defined socket representation.
void * tlsCan be used by the TLS implementation to store connection specific state.

SpSocketHALCallbacks

Return to Hal data structures

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.


_19
struct SpSocketHALCallbacks {
_19
SpCallbackSocketCreate socket_create;
_19
SpCallbackSocketSetOption socket_set_option;
_19
SpCallbackSocketClose socket_close;
_19
SpCallbackSocketBind socket_bind;
_19
SpCallbackSocketListen socket_listen;
_19
SpCallbackSocketConnect socket_connect;
_19
SpCallbackSocketAccept socket_accept;
_19
SpCallbackSocketRead socket_read;
_19
SpCallbackSocketWrite socket_write;
_19
SpCallbackSocketReadFrom socket_read_from;
_19
SpCallbackSocketWriteTo socket_write_to;
_19
SpCallbackSocketError socket_error;
_19
SpCallbackSocketReadable socket_readable;
_19
SpCallbackSocketWriteable socket_writable;
_19
SpCallbackLocalAddresses local_addresses;
_19
SpCallbackSocketAddress socket_address;
_19
SpCallbackPump on_pump;
_19
};

SpCallbackSocketCreate socket_createCallback to create socket instance.
SpCallbackSocketSetOption socket_set_optionCallback to set options on created socket.
SpCallbackSocketClose socket_closeCallback to close the socket.
SpCallbackSocketBind socket_bindCallback to bind to socket.
SpCallbackSocketListen socket_listenCallback to start listening the socket.
SpCallbackSocketConnect socket_connectCallback to connect to socket.
SpCallbackSocketAccept socket_acceptCallback to accept connection on socket.
SpCallbackSocketRead socket_readCallback to read data from socket.
SpCallbackSocketWrite socket_writeCallback to write data to socket.
SpCallbackSocketReadFrom socket_read_fromCallback to read data from socket pointed by address.
SpCallbackSocketWriteTo socket_write_toCallback to write data to socket pointed by address.
SpCallbackSocketError socket_errorCallback to get OS error on socket.
SpCallbackSocketReadable socket_readableCallback to get readable state on socket.
SpCallbackSocketWriteable socket_writableCallback to get writable state on socket.
SpCallbackLocalAddresses local_addressesCallback to get local interface addresses.
SpCallbackSocketAddress socket_addressCallback to platform address representation.
SpCallbackPump on_pumpCallback to pump network layer.

Typedefs


SpCallbackPerformDNSLookup()

Return to Hal Typedefs

_10
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 * hostnameName to be resolved.
[out]struct SpSockaddr * sockaddrPointer 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 * contextContext 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()

Return to Hal Typedefs

_10
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 familySocket family as specified in SpIPFamily
[in]enum SpSocketType typeSocket type as specified in SpSocketType
[in]enum SpSocketPool pool_idSocket pool ID to create the new socket from
[in]struct SpSocketHandle ** socketPointer to valid SpSocketHandle instance in case of success. Unchanged in case of failure.
[in]void * contextContext provided in callback register procedure.
Notes:
  • The application should not block or call other API functions in the callback.

SpCallbackSocketSetOption()

Return to Hal Typedefs

_10
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 * socketSocket instance to perform action with.
[in]enum SpSocketOptions optionOne of SpSocketOptions options.
[in]void * valueOption value. Depends on the particular SpSocketOptions option.
[in]void * contextContext provided in callback register procedure.
Notes:
  • The application should not block or call other API functions in the callback.

SpCallbackSocketClose()

Return to Hal Typedefs

_10
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 * socketSocket instance to perform action with.
[in]void * contextContext provided in callback register procedure.
Notes:
  • The application should not block or call other API functions in the callback.

SpCallbackSocketBind()

Return to Hal Typedefs

_10
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 * socketSocket instance to perform action with.
[in]int * portPort 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 * contextContext provided in callback register procedure.
Notes:
  • The application should not block or call other API functions in the callback.

SpCallbackSocketListen()

Return to Hal Typedefs

_10
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 * socketSocket instance to perform action with.
[in]int backlogParameter defines the maximum length for the queue of pending connections.
[in]void * contextContext provided in callback register procedure.
Notes:
  • The application should not block or call other API functions in the callback.

SpCallbackSocketConnect()

Return to Hal Typedefs

_10
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 * socketSocket instance to perform action with.
[in]const struct SpSockaddr * addrAddress to connect to.
[in]void * contextContext provided in callback register procedure.
Notes:
  • The application should not block or call other API functions in the callback.

SpCallbackSocketAccept()

Return to Hal Typedefs

_10
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_ socketSocket instance to perform action with.
[in]enum SpSocketPool pool_idSocket pool ID to create the new socket from
[in]struct SpSocketHandle ** out_socketSocket created by accepting connection.
[in]void * contextContext provided in callback register procedure.
Notes:
  • The application should not block or call other API functions in the callback.

SpCallbackSocketRead()

Return to Hal Typedefs

_10
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 * socketSocket instance to perform action with.
[in]void * dataBuffer to read data into.
[in]int data_sizeAmount of requested data to read.
[in]int * bytes_readPointer 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 * contextContext provided in callback register procedure.
Notes:
  • The application should not block or call other API functions in the callback.

SpCallbackSocketWrite()

Return to Hal Typedefs

_10
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 * socketSocket instance to perform action with.
[in]const void * dataBuffer with data to be written.
[in]int data_sizeAmount of data to write.
[in]int * bytes_writtenPointer 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 * contextContext provided in callback register procedure.
Notes:
  • The application should not block or call other API functions in the callback.

SpCallbackSocketReadFrom()

Return to Hal Typedefs

_10
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 * socketSocket instance to perform action with.
[in]void * dataBuffer to read data into.
[in]int data_sizeAmount of requested data to read.
[in]const void ** addrPlatform defined address representation. See SpCallbackSocketAddress
[in]int * bytes_readPointer to store how many bytes were actually read. If NULL, read is still performed. Should stay unchanged if reading has failed.
[in]void * contextContext 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()

Return to Hal Typedefs

_10
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 * socketSocket instance to perform action with.
[in]const void * dataBuffer with data to be written.
[in]int data_sizeAmount of data to write.
[in]const void * addrPlatform defined address representation. See SpCallbackSocketAddress
[in]int * bytes_writtenPointer to store how many bytes were actually written. If NULL, write is still performed. Should stay unchanged if writing has failed.
[in]void * contextContext 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()

Return to Hal Typedefs

_10
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 * socketSocket instance for which error code is requested.
[in]void * contextContext provided in callback register procedure.
Notes:
  • The application should not block or call other API functions in the callback.

SpCallbackSocketReadable()

Return to Hal Typedefs

_10
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 * socketSocket instance to perform action with.
[in]void * contextContext provided in callback register procedure.
Notes:
  • The application should not block or call other API functions in the callback.

SpCallbackSocketWriteable()

Return to Hal Typedefs

_10
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 * socketSocket instance to perform action with.
[in]void * contextContext provided in callback register procedure.
Notes:
  • The application should not block or call other API functions in the callback.

SpCallbackLocalAddresses()

Return to Hal Typedefs

_10
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_ addrsPointer to array of SpSockaddr to store the data. Data in network byte order.
[in]int * num_addrseSDK 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 * contextContext provided in callback register procedure.
Notes:
  • The application should not block or call other API functions in the callback.

SpCallbackSocketAddress()

Return to Hal Typedefs

_10
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 * addrAddress to convert. Network byte order.
[in]void * contextContext provided in callback register procedure.
Notes:
  • The application should not block or call other API functions in the callback.

SpCallbackPump()

Return to Hal Typedefs

_10
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_msMaximum time to wait in one pump call
[in]void * contextContext provided in callback register procedure.
Notes:
  • The application should not block or call other API functions in the callback.

Enumerations


SpIPFamily

Return to Hal enumerations

_10
enum SpIPFamily {
_10
kSpIPV4,
_10
kSpIPV6,
_10
};

kSpIPV4IP v4 family.
kSpIPV6IP v6 family.

SpSocketPool

Return to Hal enumerations

_10
enum SpSocketPool {
_10
kSpSocketPoolGeneral,
_10
kSpSocketPoolZeroConf,
_10
};

kSpSocketPoolGeneralSockets used for backend, streaming, etc.
kSpSocketPoolZeroConfSockets used for ZeroConf.

SpSocketType

Return to Hal enumerations

_10
enum SpSocketType {
_10
kSpSocketStream,
_10
kSpSocketDgram,
_10
};

kSpSocketStreamStream socket type.
kSpSocketDgramDatagram socket type.

SpSocketOptions

Return to Hal enumerations

_10
enum SpSocketOptions {
_10
kSpSocketNonBlocking,
_10
kSpSocketReuseAddr,
_10
kSpSocketReusePort,
_10
kSpSocketMulticastTTL,
_10
kSpSocketMulticastLoop,
_10
kSpSocketMembership,
_10
kSpSocketMcastSendIf,
_10
};

kSpSocketNonBlockingNonblocking 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].
kSpSocketReuseAddrReuse address mode has to be set if possible. POSIX analog: SO_REUSEADDR. Option is passed as an intptr_t in a range [0, 1].
kSpSocketReusePortReuse port mode has to be set if possible. POSIX analog: SO_REUSEPORT. Option is passed an intptr_t in a range [0, 1].
kSpSocketMulticastTTLMulticast TTL has to be set if possible. POSIX analog: IP_MULTICAST_TTL. Option is passed as an intptr_t in a range [0, 255].
kSpSocketMulticastLoopMulticast loop has to be set if possible. POSIX analog: IP_MULTICAST_LOOP. Option is passed as an intptr_t in a range [0, 1].
kSpSocketMembershipSet 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.
kSpSocketMcastSendIfSet 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()

Return to Hal functions

_10
SpError SpRegisterDnsHALCallbacks(struct SpDnsHALCallbacks *callbacks, void *context)

Register HAL-related callbacks. Should be called right after SpInit

Parameters

[in]struct SpDnsHALCallbacks * callbacksStructure with pointers to individual callback functions. Any of the pointers in the structure may be NULL.
[in]void * contextApplication-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()

Return to Hal functions

_10
SpError SpGetDefaultDnsHALCallbacks(struct SpDnsHALCallbacks *callbacks)

Get eSDK's default DNS callbacks.

Parameters

[in]struct SpDnsHALCallbacks * callbacksSpDnsHALCallbacks struct to be populated with pointers to callback functions

Returns

Returns an error code.

Notes:

SpRegisterSocketHALCallbacks()

Return to Hal functions

_10
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 * callbacksStructure with pointers to individual callback functions. Either all pointers are NULL or all are valid.
[in]void * contextApplication-defined pointer that will be passed unchanged as the context argument to the callbacks.

Returns

Returns an error code

Notes:

SpGetDefaultSocketHALCallbacks()

Return to Hal functions

_10
SpError SpGetDefaultSocketHALCallbacks(struct SpSocketHALCallbacks *callbacks, void **context)

Get eSDK's default socket callbacks.

Parameters

[in]struct SpSocketHALCallbacks * callbacksSpSocketHALCallbacks struct to be populated with pointers to callback functions
[in]void ** contextthe default context that is being used.

Returns

Returns an error code.

Notes:

Log



_10
#include "spotify_embedded_log.h"

Macros and Constants


Return to header index
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


Return to header index
SpLogTraceObject Trace object.

Enumerations


Return to header index
SpLogLevel

Functions


Return to header index
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

Return to Log macros and constants

_10
#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

Return to Log macros and constants

_10
#define SP_LOG_DEFAULT_LEVEL SP_LOG_LEVEL_INFO

Default trace log level.

SP_LOG_DEFINE_TRACE_OBJ

Return to Log macros and constants

_10
#define SP_LOG_DEFINE_TRACE_OBJ struct

Macro to define a trace object.

obj Name of the trace object

SP_LOG_DECLARE_TRACE_OBJ

Return to Log macros and constants

_10
#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

Return to Log macros and constants

_10
#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

Return to Log macros and constants

_10
#define SP_LOG do { \
_10
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

Return to Log macros and constants

_10
#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

Return to Log macros and constants

_10
#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

Return to Log macros and constants

_10
#define SpLogWarning

Emit trace message with SP_LOG_LEVEL_WARNING.

SpLogInfo

Return to Log macros and constants

_10
#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

Return to Log macros and constants

_10
#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

Return to Log macros and constants

_10
#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

Return to Log data structures

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.


_10
struct SpLogTraceObject {
_10
SpLogLevel level;
_10
const char *name;
_10
};

SpLogLevel levelThe current debug level for this trace object.
const char * nameThe trace category name describing this trace object.

Enumerations


SpLogLevel

Return to Log enumerations

_10
enum SpLogLevel {
_10
SP_LOG_LEVEL_FATAL,
_10
SP_LOG_LEVEL_ERROR,
_10
SP_LOG_LEVEL_WARNING,
_10
SP_LOG_LEVEL_INFO,
_10
SP_LOG_LEVEL_DEBUG,
_10
SP_LOG_LEVEL_TRACE,
_10
};

SP_LOG_LEVEL_FATALIndicates a severe abnormal condition and program termination.
SP_LOG_LEVEL_ERRORIndicates an abnormal condition that could result in degraded functionality.
SP_LOG_LEVEL_WARNINGIndicates a condition that probably has some impact on execution or performance.
SP_LOG_LEVEL_INFOInformational message.
SP_LOG_LEVEL_DEBUGDebug message.
SP_LOG_LEVEL_TRACETrace message.

Functions


SpLogRegisterTraceObject()

Return to Log functions

_10
SpError SpLogRegisterTraceObject(struct SpLogTraceObject *obj)

Register a defined trace object with eSDK.

Parameters

[in]struct SpLogTraceObject * objPointer to trace object

Returns

Return kSpErrorOk on success, or error code on failure.

SpLog()

Return to Log functions

_10
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 * objPointer to trace object
[in]SpLogLevel levelThe log level associated this this message
[in]const char * fileThe source file from where the call is made, see SP_FILE_NAME.
[in]const char * funcThe function name from where the call is made, typically func.
[in]int lineThe line number from where the call is made, typically LINE.
[in]const char * formatA printf style format string followed by arguments.

SpLogSetLevel()

Return to Log functions

_10
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 * categoryIdentifies 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 levelThe log level defined by SpLogLevel

Returns

Returns an error code if the category is not a valid log category.

SpLogGetLevels()

Return to Log functions

_10
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 * bufferA buffer to copy the string to.
[in]int buffer_lenLength of the buffer

Returns

Returns an error code if the buffer is not big enough.

Media



_10
#include "spotify_embedded_media.h"

Data Structures


Return to header index
SpStreamInfo Stream Parameters.
SpStreamCallbacks Callbacks to be registered with SpRegisterStreamCallbacks

Typedefs


Return to header index
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


Return to header index
SpMediaFormat

Functions


Return to header index
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.


_10
struct SpStreamInfo {
_10
uint32_t size;
_10
int32_t gain_mdb;
_10
uint32_t start_position_ms;
_10
const char *track_uri;
_10
const char *resource;
_10
};

uint32_t sizeSize of the stream in bytes. If the size is unknown, 0 is used.
int32_t gain_mdbAudio normalization gain (in mdB) to apply to the stream.
uint32_t start_position_msReserved for internal use.
const char * track_uriSpotify track URI.
const char * resourceReserved for internal use.

SpStreamCallbacks

Return to Media data structures

Callbacks to be registered with SpRegisterStreamCallbacks


_10
struct SpStreamCallbacks {
_10
SpCallbackStreamStart on_start;
_10
SpCallbackStreamData on_data;
_10
SpCallbackStreamEnd on_end;
_10
SpCallbackStreamGetPosition on_get_position;
_10
SpCallbackStreamSeekToPosition on_seek_position;
_10
SpCallbackStreamFlush on_flush;
_10
};

SpCallbackStreamStart on_startStart of delivery callback.
SpCallbackStreamData on_dataData delivery callback.
SpCallbackStreamEnd on_endEnd of delivery callback.
SpCallbackStreamGetPosition on_get_positionCurrent playback position callback.
SpCallbackStreamSeekToPosition on_seek_positionSeek to position callback.
SpCallbackStreamFlush on_flushFlush callback.

Typedefs


SpCallbackStreamStart()

Return to Media Typedefs

_10
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_idUnique identifier to identify tracks
[in]enum SpMediaFormat media_formatInformation about the format of the audio data
[in]enum SpDrmFormat drm_formatInformation about the used DRM method
[in]const struct SpStreamInfo * stream_infoAdditional information related to the stream
See also

SpCallbackStreamData()

Return to Media Typedefs

_10
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_idUnique identifier to identify tracks
[in]const void * bufBlock of data (it can be audio or video data)
[in]size_t lenSize of the data
[in]uint32_t offsetByte offset in the data stream (relative to the start)
[in]void * contextContext pointer that was passed when registering the callback

SpCallbackStreamEnd()

Return to Media Typedefs

_10
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_idUnique identifier to identify tracks
[in]void * contextContext pointer that was passed when registering the callback

SpCallbackStreamGetPosition()

Return to Media Typedefs

_10
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_idUnique identifier to identify tracks
[in]void * contextContext pointer that was passed when registering the callback

SpCallbackStreamSeekToPosition()

Return to Media Typedefs

_10
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_idUnique identifier to identify tracks
[in]uint32_t position_msPosition in time within the track where to seek to
[in]void * contextContext pointer that was passed when registering the callback

SpCallbackStreamFlush()

Return to Media Typedefs

_10
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_idThe delivery of the track which is currently playing. If nothing is playing, zero should be used
[in]void * contextContext pointer that was passed when registering the callback

Enumerations


SpMediaFormat

Return to Media enumerations

_10
enum SpMediaFormat {
_10
kSpMediaFormatSpotifyOggVorbis,
_10
kSpMediaFormatMp3,
_10
kSpMediaFormatMp4AAC,
_10
kSpMediaFormatSpacAAC,
_10
kSpMediaFormatSpotifyManifestId,
_10
kSpMediaFormatSpotifyAdManifest,
_10
};

kSpMediaFormatSpotifyOggVorbisogg/vorbis 44.1 kHz stereo audio format with Spotify metadata page
kSpMediaFormatMp3mp3
kSpMediaFormatMp4AACmp4/aac-lc
kSpMediaFormatSpacAACspac/aac-he-v2
kSpMediaFormatSpotifyManifestIdSpotify video manifest id.
kSpMediaFormatSpotifyAdManifestSpotify ad manifest.

Functions


SpRegisterStreamCallbacks()

Return to Media functions

_10
SpError SpRegisterStreamCallbacks(struct SpStreamCallbacks *cb, void *context)

Register callbacks related to the delivery API.

Parameters

[in]struct SpStreamCallbacks * cbStructure with pointers to individual callback functions. Any of the pointers in the structure may be NULL.
[in]void * contextApplication-defined pointer that will be passed unchanged as the context argument to the callbacks.

Returns

Returns an error code

SpNotifySeekComplete()

Return to Media functions

_10
SpError SpNotifySeekComplete(unsigned int stream_id)

API to notify eSDK of the completion of seek operation.

Parameters

[in]unsigned int stream_idUnique identifier to identify tracks

Returns

Returns an error code

SpNotifyTrackLength()

Return to Media functions

_10
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_idUnique identifier to identify tracks
[in]uint32_t length_msPosition in milliseconds of the track

Returns

Returns an error code

SpNotifyTrackError()

Return to Media functions

_10
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_idUnique identifier to identify tracks
[in]uint32_t position_msPosition in milliseconds of the track
[in]const char * reasonThe reason for the error

Returns

Returns an error code

SpNotifyStreamPlaybackStarted()

Return to Media functions

_10
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_idUnique identifier to identify tracks

Returns

Returns an error code. Returns kSpErrorAlreadyInitialized if SpNotifyStreamPlaybackStarted() has already been called for this delivery.

SpNotifyStreamPlaybackContinued()

Return to Media functions

_10
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_idUnique identifier to identify tracks

Returns

Returns an error code

SpNotifyStreamPlaybackFinishedNaturally()

Return to Media functions

_10
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_idUnique identifier to identify tracks
[in]uint32_t last_pos_msPosition in milliseconds of the track

Returns

Returns an error code

SpSetDownloadPosition()

Return to Media functions

_10
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_idUnique identifier to identify tracks
[in]uint32_t byte_offsetNew download byte offset (relative to the start of the stream) where downloading could continue.

Returns

Returns an error code

Play



_10
#include "spotify_embedded_play_api.h"

Macros and Constants


Return to header index
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


Return to header index
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


Return to header index
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

Return to Play macros and constants

_10
#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

Return to Play macros and constants

_10
#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

Return to Play macros and constants

_10
#define SP_MAX_SOURCE_TYPE_LENGTH 63

Maximum length of the type of playback source.

See also

SP_MAX_SOURCE_URI_LENGTH

Return to Play macros and constants

_10
#define SP_MAX_SOURCE_URI_LENGTH 511

Maximum length of the source URIs.

See also

SP_MAX_REFERRER_LENGTH

Return to Play macros and constants

_10
#define SP_MAX_REFERRER_LENGTH 16

Maximum length of the referrer.

See also

SP_PLAYOPTIONS_INITIALIZER_LOGGING_PARAMS

Return to Play macros and constants

_10
#define SP_PLAYOPTIONS_INITIALIZER_LOGGING_PARAMS

Internal macro.

See also

SP_PLAYOPTIONS_INITIALIZER

Return to Play macros and constants

_10
#define SP_PLAYOPTIONS_INITIALIZER { \
_10
/*.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

_10
struct SpSourceInfo {
_10
char type;
_10
char uri;
_10
char expected_track_uri;
_10
char referrer;
_10
};

char typeThe 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):
char uriThe URI of the parent container, if there is one.
char expected_track_uriThe URI of the track that is expected to play.
char referrerThe view you were in prior to initiating playback.

SpPlayOptions

Return to Play data structures

PlayOptions passed to SpPlayUriWithOptions Use SP_PLAYOPTIONS_INITIALIZER for initializing with default values.

Example:

_10
struct SpPlayOptions options= SP_PLAYOPTIONS_INITIALIZER;


_10
struct SpPlayOptions {
_10
int from_index;
_10
const char *from_uid;
_10
int offset_ms;
_10
int shuffle_context;
_10
int repeat_mode;
_10
const struct SpSourceInfo *source_info;
_10
};

int from_indexTrack 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_uidThe UID to identify a unique track in the context.
int offset_msThe time offset to start playing specified track from.
int shuffle_contextSet to enable or disable shuffle mode for the requested playback command.
int repeat_modeSet to enable or disable repeat mode for the requested playback command.
const struct SpSourceInfo * source_infoMetadata about what user action caused this playback event, and the expected result.

Functions


SpPlayUri()

Return to Play functions

_10
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 * uriURI of resource (ex: spotify:album:6tSdnCBm5HCAjwNxWfUC7m)
[in]int alias_ indexThe 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_msThe time offset to start playing specified track from. Set to zero to start from the beginning.
[in]const struct SpSourceInfo * sourceMetadata 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_indexThe 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()

Return to Play functions

_10
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 * uriThe context URI to play.
[in]const struct SpPlayOptions * optsThe options to apply to the play command.
[in]int alias_indexDevice alias index. If aliases aren't used, pass SP_NO_ALIAS_SELECTED.

Returns

Returns an error code

SpPlayContextUri()

Return to Play functions

_10
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 * uriURI of resource (ex: spotify:album:6tSdnCBm5HCAjwNxWfUC7m)
[in]const char * from_uidThe UID to identify a unique track in the context.
[in]int offset_msThe time offset to start playing specified track from. Set to zero to start from the beginning.
[in]const struct SpSourceInfo * sourceMetadata 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_indexThe 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()

Return to Play functions

_10
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 * uriURI to queue.

Returns

Returns an error code.

See also

SpPlaybackBecomeActiveDevice()

Return to Play functions

_10
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_indexThe 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



_10
#include "spotify_embedded_storage.h"

Data Structures


Return to header index
SpDiskStorageCallbacks Callbacks to be registered with SpRegisterStorageCallbacks

Typedefs


Return to header index
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


Return to header index
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.


_10
struct SpDiskStorageCallbacks {
_10
SpCallbackStorageAlloc alloc_storage;
_10
SpCallbackStorageWrite write_storage;
_10
SpCallbackStorageRead read_storage;
_10
SpCallbackStorageClose close_storage;
_10
SpCallbackStorageDelete delete_storage;
_10
SpCallbackThrottleRequest throttle_request;
_10
};

SpCallbackStorageAlloc alloc_storageAlloc storage record callback.
SpCallbackStorageWrite write_storageWrite storage data callback.
SpCallbackStorageRead read_storageRead storage data callback.
SpCallbackStorageClose close_storageClose storage record callback.
SpCallbackStorageDelete delete_storageDelete storage record callback.
SpCallbackThrottleRequest throttle_requestAsks the client if disk writes need to be throttled.

Typedefs


SpCallbackStorageAlloc()

Return to Storage Typedefs

_10
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_keyStorage key identifying the record
[in]uint32_t total_sizeThe full resource size in bytes or 0 if size is not known.
[in]void * contextContext 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()

Return to Storage Typedefs

_10
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_keyStorage key identifying the record
[in]uint32_t offsetThe offset in bytes in the resource we are writing to.
[in]const void * dataA pointer to the buffer containing the data to be written to storage.
[in]uint32_t data_sizeThe number of bytes to be written to the storage.
[in]void * contextContext 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()

Return to Storage Typedefs

_10
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_keyStorage key identifying the record
[in]uint32_t offsetThe offset eSDK is reading from.
[out]void * dataA pointer to the buffer that receives the data read from storage.
[in]uint32_t data_sizeThe number bytes to read.
[in]void * contextContext 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()

Return to Storage Typedefs

_10
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_keyStorage key identifying the record
[in]void * contextContext 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()

Return to Storage Typedefs

_10
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_keyStorage key identifying the record.
[in]void * contextContext 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()

Return to Storage Typedefs

_10
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_keyStorage key identifying the record.
[in]void * contextContext pointer that was passed when registering the callback.
Notes:
  • The application should not block or call other API functions in the callback.

Functions


SpRegisterStorageCallbacks()

Return to Storage functions

_10
SpError SpRegisterStorageCallbacks(struct SpDiskStorageCallbacks *cb, void *context)

Register storage callbacks.

Parameters

[in]struct SpDiskStorageCallbacks * cbStructure with pointers to individual callback functions. Any of the pointers in the structure may be NULL.
[in]void * contextApplication-defined pointer that will be passed unchanged as the context argument to the callbacks.

Returns

Returns an error code

Tls



_10
#include "spotify_embedded_tls.h"

Data Structures


Return to header index
SpTLSCallbacks Callbacks to be registered with SpRegisterTLSCallbacks

Typedefs


Return to header index
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


Return to header index
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

Return to Tls data structures

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.


_10
struct SpTLSCallbacks {
_10
SpCallbackTLSInit init;
_10
SpCallbackTLSDeinit deinit;
_10
SpCallbackTLSCreate create;
_10
SpCallbackTLSHandshake handshake;
_10
SpCallbackTLSRead read;
_10
SpCallbackTLSWrite write;
_10
SpCallbackTLSClose close;
_10
SpCallbackTLSGetError get_error;
_10
};

SpCallbackTLSInit initCallback that performs one-time initialization.
SpCallbackTLSDeinit deinitCallback that performs release of resources allocated during init.
SpCallbackTLSCreate createCallback invoked once per connection to initialize TLS context.
SpCallbackTLSHandshake handshakeCallback invoked repeatedly to perform the TLS handshake.
SpCallbackTLSRead readCallback for reading from the TLS data stream.
SpCallbackTLSWrite writeCallback for writing to the TLS data stream.
SpCallbackTLSClose closeCallback invoked to cleanup any TLS context before closing the socket.
SpCallbackTLSGetError get_errorCallback invoked to get an error message for the last error.

Typedefs


SpCallbackTLSInit()

Return to Tls Typedefs

_10
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 * contextContext provided in callback register function.
Notes:
  • The application should not block or call other API functions in the callback.

SpCallbackTLSDeinit()

Return to Tls Typedefs

_10
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 * contextContext provided in callback register function.
Notes:
  • The application should not block or call other API functions in the callback.

SpCallbackTLSCreate()

Return to Tls Typedefs

_10
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 * socketPointer to eSDK socket already connected to the remote peer.
[in]const char * hostnameHostname of the remote peer.
[in]void * contextContext provided in callback register function.
Notes:
  • The application should not block or call other API functions in the callback.

SpCallbackTLSHandshake()

Return to Tls Typedefs

_10
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 * socketPointer to eSDK socket already connected to the remote peer.
[in]void * contextContext provided in callback register function.
Notes:
  • The application must not block or call other API functions in the callback.

SpCallbackTLSRead()

Return to Tls Typedefs

_10
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 * socketPointer to eSDK socket already connected to the remote peer.
[in]void * bufPointer to buffer for the data to be received.
[in]size_t lenThe size of the buffer (in bytes).
[out]size_t * actualActual number of bytes received.
[in]void * contextContext provided in callback register function.
Notes:
  • The application should not block or call other API functions in the callback.

SpCallbackTLSWrite()

Return to Tls Typedefs

_10
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 * socketPointer to eSDK socket already connected to the remote peer.
[in]const void * bufPointer to buffer with data to be written.
[in]size_t lenNumber of bytes of data in buffer.
[out]size_t * actualNumber of bytes actually written.
[in]void * contextContext provided in callback register function.
Notes:
  • The application should not block or call other API functions in the callback.

SpCallbackTLSClose()

Return to Tls Typedefs

_10
typedef void(* SpCallbackTLSClose)(struct SpSocketHandle *socket, void *context)

This callback should clean up any resources allocated in the connect callback.

Parameters

[in]struct SpSocketHandle * socketPointer to eSDK socket already connected to the remote peer.
[in]void * contextContext provided in callback register function.
Notes:
  • The application should not block or call other API functions in the callback.

SpCallbackTLSGetError()

Return to Tls Typedefs

_10
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 * socketPointer to eSDK socket already connected to the remote peer.
[in]char * bufPointer to buffer that will receive the error message.
[in]size_t lenLength of the buffer.
[in]void * contextContext provided in callback register function.
Notes:
  • The application should not block or call other API functions in the callback.

Functions


SpRegisterTLSCallbacks()

Return to Tls functions

_10
SpError SpRegisterTLSCallbacks(struct SpTLSCallbacks *callbacks, void *context)

Register TLS-related callbacks.

Parameters

[in]struct SpTLSCallbacks * callbacksStructure with pointers to individual callback functions. All pointers must be valid.
[in]void * contextApplication-defined pointer that will be passed unchanged as the context argument to the callbacks.

Returns

Returns an error code

Notes:

SpTLSAddCARootCert()

Return to Tls functions

This function is deprecated and should not be used. See alternatives:

_10
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 * certificateEither 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()

Return to Tls functions

This function is deprecated and should not be used. See alternatives:

_10
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



_10
#include "spotify_embedded_token.h"

Data Structures


Return to header index
SpTokenCallbacks Callbacks to be registered with SpRegisterTokenCallbacks

Typedefs


Return to header index
SpCallbackConnectionReceiveAccessToken Callback to deliver the access token requested by SpConnectionRequestAccessToken
SpCallbackConnectionReceiveAuthCode Callback to deliver the access token requested by SpConnectionRequestAuthCode

Functions


Return to header index
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.


_10
struct SpTokenCallbacks {
_10
SpCallbackConnectionReceiveAccessToken on_access_token;
_10
SpCallbackConnectionReceiveAuthCode on_auth_code;
_10
};

SpCallbackConnectionReceiveAccessToken on_access_tokenAccess token event callbacks.
SpCallbackConnectionReceiveAuthCode on_auth_codeAuthorization code event callbacks.

Typedefs


SpCallbackConnectionReceiveAccessToken()

Return to Token Typedefs

_10
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_jsonA serialized JSON object containing the access token or an empty string if error is != 0. See Notes below.
[in]int errorAn internal error code or 0 on success. The token in token_json is only valid if this is 0.
[in]void * contextContext 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()

Return to Token Typedefs

_10
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_jsonA serialized JSON object containing the access token or an empty string if error is != 0. See Notes below.
[in]int errorAn internal error code or 0 on success. The token in token_json is only valid if this is 0.
[in]void * contextContext pointer that was passed then the callback was registered.
Notes:
  • The JSON object looks as following: "code":"tokendata", "redirectUri":"someUri"

Functions


SpRegisterTokenCallbacks()

Return to Token functions

_10
SpError SpRegisterTokenCallbacks(struct SpTokenCallbacks *cb, void *context)

Register token callbacks.

Parameters

[in]struct SpTokenCallbacks * cbStructure with pointers to individual callback functions. Any of the pointers in the structure may be NULL.
[in]void * contextApplication-defined pointer that will be passed unchanged as the context argument to the callbacks.

Returns

Returns an error code

SpConnectionRequestAccessToken()

Return to Token functions

_10
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/web-api/concepts/scopes/

Parameters

[in]const char * scopeA comma-separated list of scopes for the resulting access token. See https://developer.spotify.com/documentation/web-api/concepts/scopes/

SpConnectionRequestAuthCode()

Return to Token functions

_10
SpError SpConnectionRequestAuthCode(const char *scope)

Request an authorization code for the logged in user.

Parameters

[in]const char * scopeA comma-separated list of scopes for the resulting access token. See https://developer.spotify.com/documentation/web-api/concepts/scopes/
Notes:
  • The string scope must not be longer than 425 characters.