API Reference eSDK 3.203.239

Main

---

• Macros and Constants
• Data Structures
• Typedefs
• Enumerations
• Functions

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

---

Return to Main macros and constants

The version of the API defined in this header file.

See also

• SpInit

Return to Main macros and constants

Minimum recommended size of the buffer SpConfig::memory_block

Return to Main macros and constants

Maximum length of the brand name string (not counting terminating NULL)

See also

• SpConfig

Return to Main macros and constants

Maximum length of the model name string (not counting terminating NULL)

See also

• SpConfig

Return to Main macros and constants

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

See also

• SpConfig

Return to Main macros and constants

Maximum length of the client id string (not counting terminating NULL)

See also

• SpConfig

Return to Main macros and constants

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

See also

• SpConfig

Return to Main macros and constants

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

See also

• SpSetDisplayName
• SpConfig
• SpZeroConfVars

Return to Main macros and constants

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

See also

• SpSetAdUserAgent

Return to Main macros and constants

Maximum length of the device's unique ID (not counting terminating NULL)

See also

• SpConfig

Return to Main macros and constants

Maximum length of usernames (not counting terminating NULL)

See also

• SpZeroConfVars
• SpConnectionLoginZeroConf

Return to Main macros and constants

Maximum number of device aliases that can be configured.

See also

• SpConfig::device_aliases

Return to Main macros and constants

Maximum number of key/value pairs containing ad metadata.

Return to Main macros and constants

A value to use for alias_index when aliases are not used.

See also

• SpConfig::device_aliases

Return to Main macros and constants

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

See also

• SpGetMetadata
• SpMetadata

Notes:

• It is possible that metadata will be truncated to less than this length. Applications requiring full length metadata should request it from the Spotify web APIs https://developer.spotify.com/documentation/web-api/

Return to Main macros and constants

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

See also

• SpGetMetadata
• SpMetadata

Return to Main macros and constants

Maximum length of Track UID in track metadata (not counting terminating NULL)

See also

• SpGetMetadata
• SpMetadata

Return to Main macros and constants

Maximum length of URLs (not counting terminating NULL)

See also

• SpGetMetadataImageURL

Return to Main macros and constants

Length of player cookie (not counting terminating NULL)

See also

• SpGetPlayerCookie

Return to Main macros and constants

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

See also

• SpGetMetadata
• SpMetadata

Return to Main macros and constants

Maximum length of the public key used in ZeroConf logins (not counting terminating NULL)

See also

• SpZeroConfVars

Return to Main macros and constants

Maximum length of the device ID used for ZeroConf logins (not counting terminating NULL)

See also

• SpZeroConfVars

Return to Main macros and constants

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

See also

• SpZeroConfVars

Return to Main macros and constants

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

See also

• SpZeroConfVars

Return to Main macros and constants

Maximum length of the group status string (not counting terminating NULL)

See also

• SpZeroConfVars

Return to Main macros and constants

Maximum length of the token type used for OAuth logins (not counting terminating NULL)

See also

• SpZeroConfVars

Return to Main macros and constants

Maximum length of the scope used for OAuth login (not counting terminating NULL)

See also

• SpZeroConfVars

Return to Main macros and constants

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

See also

• SpConnectionLoginZeroConf

Return to Main macros and constants

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

See also

• SpConnectionLoginZeroConf

Return to Main macros and constants

Maximum length of the login ID used for ZeroConf logins (not counting terminating NULL)

See also

• SpConnectionLoginZeroConf

Return to Main macros and constants

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

See also

• SpConnectionLoginZeroConf

Return to Main macros and constants

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.

Return to Main macros and constants

Maximum length of filename fields (not counting terminating NULL)

Return to Main macros and constants

Value for SpConfig::zeroconf_serve when disabling built-in ZeroConf stack. Complete ZeroConf stack has to run externally.

See also

• SpInit

Return to Main macros and constants

Value for SpConfig::zeroconf_serve when activating complete built-in ZeroConf stack (both mDNS and http server).

See also

• SpInit

Return to Main macros and constants

Value for SpConfig::zeroconf_serve when activating built-in ZeroConf http server only while running the ZeroConf mDNS server externally.

See also

• SpInit

Return to Main macros and constants

Value for SpConfig::zeroconf_serve when activating built-in ZeroConf mDNS server only while running the ZeroConf http server externally.

See also

• SpInit

Return to Main macros and constants

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

Return to Main macros and constants

Set this bit in the device alias attributes integer (SpDeviceAlias::attributes) to mark a device alias as representing a group.

Notes:

• SpSetDeviceIsGroup also sets group status, but only for the currently selected alias.

Return to Main macros and constants

Set this bit in the global attributes integer (SpConfig::global_attributes) to mark that this device supports voice.

Return to Main macros and constants See also

• SpFormat
• SpConfig::supported_drm_media_formats

Return to Main macros and constants

The track is already paused.

Return to Main macros and constants

The track is already playing.

Return to Main macros and constants

Licensing rules disallow this action.

Return to Main macros and constants

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

Return to Main macros and constants

There is no track before the current one in the currently playing context.

Return to Main macros and constants

There is no track after the current one in the currently playing context.

Return to Main macros and constants

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.

Return to Main macros and constants

The action is restricted for context level reasons.

Return to Main macros and constants

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

See also

• SpAdMetadata

Return to Main macros and constants

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

See also

• SpAdMetadata

Data Structures

---

Return to Main data structures

Playback restrictions.

uint32_t	disallow_pausing_reasons	Bitfield of reasons the pause action is not allowed.
uint32_t	disallow_resuming_reasons	Bitfield of reasons the resume action is not allowed.
uint32_t	disallow_seeking_reasons	Bitfield of reasons seeking is not allowed.
uint32_t	disallow_peeking_prev_reasons	Bitfield of reasons peeking on the previous track is not allowed.
uint32_t	disallow_peeking_next_reasons	Bitfield of reasons peeking on the next track is not allowed.
uint32_t	disallow_skipping_prev_reasons	Bitfield of reasons skipping to the previous track is not allowed.
uint32_t	disallow_skipping_next_reasons	Bitfield of reasons skipping to the next track is not allowed.
uint32_t	disallow_toggling_repeat_context_reasons	Bitfield of reasons setting repeat context is not allowed.
uint32_t	disallow_toggling_repeat_track_reasons	Bitfield of reasons setting repeat track is not allowed.
uint32_t	disallow_toggling_shuffle_reasons	Bitfield of reasons toggling shuffle is not allowed.

Return to Main data structures

Track metadata.

See also

• SpGetMetadata

char	playback_source	Display name of the playback source. E.g., the name of the playlist from which playback was initiated (UTF-8-encoded)
char	playback_source_uri	Spotify URI of the playback source (in the form "spotify:xxxxxx:xxxxxxx...")
char	track	Display name of the track (UTF-8-encoded)
char	track_uri	Spotify URI of the track (in the form "spotify:track:xxxxxxx...")
char	artist	Display name of the artist of the track (UTF-8-encoded)
char	artist_uri	Spotify URI of the artist of the track (in the form "spotify:artist:xxxxxxx...")
char	album	Display name of the track's album (UTF-8-encoded)
char	album_uri	Spotify URI of the track's album (in the form "spotify:album:xxxxxxx...")
char	album_cover_uri	Spotify URI of the album's cover art image (in the form "spotify:image:xxxxxxx...")
char	original_track_uri	Spotify URI of the original track before relinking (in the form "spotify:track:xxxxxxx...")
uint32_t	duration_ms	Playback duration of the track in milliseconds.
int32_t	index	Index of the track in the currently playing context.
char	track_uid	Track UID of the track in the currently playing context.
uint32_t	original_index	Index of the track in the original (unchanged) playing context.
uint32_t	bitrate	The bitrate of the track in kbps. 0 means "unplayable".
struct SpPlaybackRestrictions	playback_restrictions	Restrictions that apply to playback and transitions related to this track.
char	playback_id	Playback-id of this playback of this specific track.
enum SpContent	content_type	Content type of this track.
enum SpMediaType	media_type	Media type of this track.
enum SpAudioQuality	audio_quality	Audio quality of this track.

Return to Main data structures

Key value pair for Ad-related metadata.

char	key	Key.
char	value	Value.

Return to Main data structures

Mapping of which media formats are supported in which DRM.

See also

• SpConfig::supported_drm_media_formats

enum SpDrmFormat	drm	DRM format which the integration supports.
uint64_t	media	Supported media formats for a DRM.

Return to Main data structures

ZeroConf DeviceAlias.

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

See also

• SpZeroConfGetVars

uint32_t	id	String to be sent in the "id" field of the alias in the "getInfo" response.
int	is_group	Boolean (0 = "false", 1 = "true") to be sent in the "isGroup" field of the alias in the "getInfo" response.
char	display_name	String to be sent in the "name" field of the alias in the "getInfo" response.

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

• SpZeroConfGetVars

char	public_key	String to be sent in the "publicKey" field of the "getInfo" response[*].
char	device_id	String to be sent in the "deviceID" field of the "getInfo" response[*].
char	remote_name	String to be sent in the "remoteName" field of the "getInfo" response[*].
char	device_type	String to be sent in the "deviceType" field of the "getInfo" response[*].
char	library_version	String to be sent in the "libraryVersion" field of the "getInfo" response[*].
int	resolver_version	Integer to be sent as string in the "resolverVersion" field of the "getInfo" response[*].
char	group_status	String to be sent in the "groupStatus" field of the "getInfo" response[*].
int	webserver_current_port	Current internal ZeroConf webserver port number. To be used when running an external mDNS server together with an internal webserver.
char	token_type	String to be sent in the "tokenType" field of the "getInfo" response[*].
char	client_id	String to be sent in the "clientID" field of the "getInfo" response[*].
char	scope	String to be sent in the "scope" field of the "getInfo" response[*].
char	availability	String to be sent in the "availability" field of the "getInfo" response[*].
uint32_t	product_id	Integer to be sent in the "productID" field of the "getInfo" response[*].
struct SpZeroConfDeviceAlias	aliases	Array of SpZeroConfDeviceAlias to be sent in the "aliases" field of the "getInfo" response[*].
uint32_t	alias_count	Number of valid items in aliases array.
struct SpFormat	supported_drm_media_formats	Array of SpFormat to be sent in the "supported_drm_media_formats" field of the "getInfo" response[*].
uint64_t	supported_capabilities	Integer representing a bitmask to be sent in the "supported_capabilities" field of the "getInfo" response[*].

Return to Main data structures

Sample format of the audio data.

int	channels	Number of channels (1 = mono, 2 = stereo)
int	sample_rate	Sample rate in Hz (such as 22050, 44100 or 48000)

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.

SpCallbackPlaybackNotify	on_notify	Notification callback.
SpCallbackPlaybackSeek	on_seek	Seek position callback.
SpCallbackPlaybackApplyVolume	on_apply_volume	Apply volume callback.

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.

SpCallbackDebugMessage

on_message

Debug message callback.

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.

SpCallbackConnectionNotify	on_notify	Notification callback.
SpCallbackConnectionNewCredentials	on_new_credentials	Credentials blob callback.
SpCallbackConnectionMessage	on_message	Connection message callback.

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.

const char *	display_name	A UTF-8 encoded display name for an alias of the application/device.
uint32_t	attributes	Attributes for this device alias.

Return to Main data structures

Configuration.

See also

• SpInit

int	api_version	The version of the API contained in this header file. Must be set to SP_API_VERSION.
void *	memory_block	Pointer to a memory block to be used by the library.
uint32_t	memory_block_size	Size of the memory_block buffer in bytes.
const char *	unique_id	A NULL-terminated character string that uniquely identifies the device (such as a MAC address)
const char *	display_name	A UTF-8-encoded display name for the application/device.
uint32_t	global_attributes	The global attributes is a bitfield where each attribute is OR:ed together and stored in this integer.
struct SpDeviceAlias	device_aliases	Device alias definitions. These are optional, if you don't want to define aliases this array must be zeroed.
const char *	brand_name	A NULL-terminated string containing the brand name of the hardware device (for hardware integrations)
const char *	brand_display_name	A UTF-8-encoded brand name of the hardware device (for hardware integrations). Should be very similar to brand_name.
const char *	model_name	A NULL-terminated string containing the model name of the hardware device (for hardware integrations)
const char *	model_display_name	A UTF-8-encoded model name of the hardware device (for hardware integrations)
const char *	platform_name	A NULL-terminated string containing the platform identifier.
const char *	client_id	A NULL-terminated string containing the client id of the application.
uint32_t	product_id	An integer enumerating the product for this partner.
const char *	scope	A NULL-terminated string containing the OAuth scope requested when authenticating with the Spotify backend.
const char *	os_version	A NULL-terminated string containing the os version running on the hardware.
enum SpDeviceType	device_type	The device type that best describes this product.
enum SpPlaybackBitrate	max_bitrate	The maximum bitrate to use for playback.
SpCallbackError	error_callback	Pointer to a callback function that will receive error notifications.
void *	error_callback_context	Application-defined pointer that will be passed unchanged as the context argument to the error_callback callback.
int	zeroconf_serve	Not applicable in this eSDK configuration.
const char *	host_name	Not applicable in this eSDK configuration.
int	zeroconf_port	Not applicable in this eSDK configuration.
int	zeroconf_port_range	Not applicable in this eSDK configuration.
struct SpFormat	supported_drm_media_formats
struct SpAdMetadata	ad_metadata	For clients that need to register ad-relasted metadata.

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.

SpCallbackSelectedDeviceAliasChanged	on_selected_device_alias_changed	Selected device alias updated callback.
SpCallbackDeviceAliasesUpdateDone	on_device_aliases_update_done	Device alias list updated.

Typedefs

---

Return to Main Typedefs

Callback for reporting errors to the application.

To register this callback, set the field SpConfig::error_callback when invoking the function SpInit

Parameters

Notes:

• The application should not block or call API functions that are not allowed in the callback.

Return to Main Typedefs

Callback for notifying the application about playback-related events.

To register this callback, use the function SpRegisterPlaybackCallbacks

Parameters

Notes:

• The application should not block or call API functions that are not allowed in the callback.

Return to Main Typedefs

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

Notes:

• The application should not block or call API functions that are not allowed in the callback.

Return to Main Typedefs

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

Notes:

• The application should not block or call API functions that are not allowed in the callback.

Return to Main Typedefs

Callback for notifying the application about events related to the connection to Spotify

To register this callback, use the function SpRegisterConnectionCallbacks

Parameters

Notes:

• The application should not block or call API functions that are not allowed in the callback.

Return to Main Typedefs

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

See also

• SpConnectionLoginBlob

Notes:

• The application should not block or call API functions that are not allowed in the callback.

Return to Main Typedefs

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

Notes:

• The application should not block or call API functions that are not allowed in the callback.

Return to Main Typedefs

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

Notes:

• The application should not block or call API functions that are not allowed in the callback.

Return to Main Typedefs

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

Notes:

• The application should not block or call API functions that are not allowed in the callback.

Return to Main Typedefs

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

Notes:

• The application should not block or call API functions that are not allowed in the callback.

Enumerations

---

Return to Main enumerations

kSpErrorOk	The operation was successful.
kSpErrorFailed	The operation failed due to an unspecified issue.
kSpErrorInitFailed	The library could not be initialized.
kSpErrorWrongAPIVersion	The library could not be initialized because of an incompatible API version.
kSpErrorNullArgument	An unexpected NULL pointer was passed as an argument to a function.
kSpErrorInvalidArgument	An unexpected argument value was passed to a function.
kSpErrorUninitialized	A function was invoked before SpInit or after SpFree was called.
kSpErrorAlreadyInitialized	SpInit was called more than once.
kSpErrorLoginBadCredentials	Login to Spotify failed because of invalid credentials.
kSpErrorNeedsPremium	The operation requires a Spotify Premium account.
kSpErrorTravelRestriction	The Spotify user is not allowed to log in from this country.
kSpErrorApplicationBanned	The application has been banned by Spotify
kSpErrorGeneralLoginError	An unspecified login error occurred.
kSpErrorUnsupported	The operation is not supported.
kSpErrorNotActiveDevice	The operation is not supported if the device is not the active playback device.
kSpErrorAPIRateLimited	The API has been rate-limited.
kSpErrorReentrancyDetected	The eSDK API was used from a callback.
kSpErrorMultiThreadingDetected	The eSDK API was used from multiple threads.
kSpErrorTryAgain	The eSDK API cannot be performed right now.
kSpErrorDuringLogout	Logout failed during SpFree call.
kSpErrorPermanentConnectionError	Permanent connection error. eSDK ceased attempts to reconnect.
kSpErrorEntropyFailure	Failed to get cryptographic random data from the platform.
kSpErrorZeroConfErrorStart	Error range reserved for ZeroConf-related errors.
kSpErrorZeroConfBadRequest	ZeroConf Web server problem or critically malformed request.
kSpErrorZeroConfUnknown	Fallback when no other ZeroConf error applies.
kSpErrorZeroConfNotImplemented	ZeroConf device does not implement this feature.
kSpErrorZeroConfNotInstalled	Spotify not installed (where applicable)
kSpErrorZeroConfNotLoaded	Spotify not loaded (where applicable)
kSpErrorZeroConfNotAuthorized	Spotify client not authorized to play.
kSpErrorZeroConfCannotLoad	Spotify cannot be loaded (where applicable)
kSpErrorZeroConfSystemUpdateRequired	Device system needs update (where applicable)
kSpErrorZeroConfSpotifyUpdateRequired	Spotify requires an update.
kSpErrorZeroConfLoginFailed	Spotify returned an error when trying to login.
kSpErrorZeroConfInvalidPublicKey	ZeroConf login failed due to an invalid public key.
kSpErrorZeroConfMissingAction	ZeroConf HTTP request has no action parameter.
kSpErrorZeroConfInvalidAction	ZeroConf HTTP request has an unrecognized action parameter.
kSpErrorZeroConfInvalidArguments	Incorrect or insufficient ZeroConf arguments supplied for requested action.
kSpErrorZeroConfNoSpotifySession	No valid Spotify session for requested Spotify action (where applicable)
kSpErrorZeroConfSpotifyError	A Spotify API call returned an error not covered by other error messages.
kSpErrorPlaybackErrorStart	Error range reserved for playback-related errors.
kSpErrorGeneralPlaybackError	An unspecified playback error occurred.
kSpErrorPlaybackRateLimited	The application has been rate-limited.
kSpErrorPlaybackCappingLimitReached	The Spotify user has reached a capping limit that is in effect in this country and/or for this track.
kSpErrorAdIsPlaying	Cannot change track while ad is playing.
kSpErrorCorruptTrack	The track is (temporarily) corrupted in the Spotify catalogue.
kSpErrorContextFailed	Unable to read all tracks from the playing context.
kSpErrorPrefetchItemUnavailable	The item that was being prefetched was unavailable, and cannot be fetched. This could be due to an invalid URI, changes in track availability, or geographical limitations. This is a permanent error, and the item should not be tried again.
kSpAlreadyPrefetching	An item is already actively being prefetched. You must stop the current prefetch request to start another one. This error is only relevant for builds with offline storage enabled.
kSpStorageReadError	A permanent error was encountered while reading to a registered file storage callback. This error is only relevant for builds with offline storage enabled.
kSpStorageWriteError	A permanent error was encountered while writing to a registered file storage callback. This error is only relevant for builds with offline storage enabled.
kSpPrefetchDownloadFailed	The prefetched item was not fully downloaded or failed. If error happens prefetch can be retried. This error is only relevant for builds with offline storage enabled.
kSpErrorBusy	The current API call cannot be completed because eSDK is busy. Same API call should be done sometime later with the same arguments.
kSpErrorUnavailable	The current API call cannot be completed because the requested operation is not available at the moment.
kSpErrorNotAllowed	This eSDK API is not allowed due to current license restrictions.
kSpErrorNetworkRequired	The current API call cannot be completed without connection to the Spotify backend.
kSpErrorNotLoggedIn	The current API call cannot be completed without being logged in.
kSpErrorInProgress	Used in callbacks to notify the application that the action is not yet complete.
kSpErrorPlaybackInitiation	Used in SpCallbackError callback to notify the application that playback initiation failed.
kSpErrorPresetFailed	Used in SpCallbackError callback to notify the application that recalling and playing a preset failed.
kSpErrorInvalidRequest	The queued track was rejected.
kSpErrorInvalidTrackId	Used in SpCallbackError callback to notify the application that an invalid track_id was used.
kSpErrorIncorrectMsPlayed	Used in SpCallbackError callback to notify the application that an incorrect value for ms_played was reported.
kSpErrorDeviceNotControllable	The operation is not allowed since the device is not controllable.
kSpErrorPlaybackInitiationTimeout	The playback initiation operation timed out.
kSpErrorGeneralDownloadError	Failed to download the requested track.

Return to Main enumerations

kSpAPINoError	This code should be used when the API call was successful.
kSpAPITryAgain	This code means operation cannot be performed right now. Same API call should be done sometime later with the same arguments.
kSpAPIDNSLookupError	Use to notify about any DNS lookup error that cannot be retried.
kSpAPIGenericError	API call has failed.
kSpAPINotSupported	Requested feature is not supported by platform.
kSpAPIEOF	End of file/socket reached.
kSpAPINotFound	Requested resource does not exist.

Return to Main enumerations

kSpPlaybackBitrateDefault	Set the bitrate to the default (currently High).
kSpPlaybackBitrateLow	Set the bitrate to low. Corresponds to e.g. 96 kbit/s ogg/vorbis.
kSpPlaybackBitrateNormal	Set the bitrate to normal. Corresponds to e.g. 160 kbit/s ogg/vorbis.

Return to Main enumerations

kSpPlaybackNotifyPlay	Playback has started or has resumed.
kSpPlaybackNotifyPause	Playback has been paused.
kSpPlaybackNotifyTrackChanged	The current track or its metadata has changed.
kSpPlaybackNotifyNext	Playback has skipped to the next track.
kSpPlaybackNotifyPrev	Playback has skipped to the previous track.
kSpPlaybackNotifyShuffleOn	"Shuffle" was switched on
kSpPlaybackNotifyShuffleOff	"Shuffle" was switched off
kSpPlaybackNotifyRepeatOn	"Repeat" was switched on
kSpPlaybackNotifyRepeatOff	"Repeat" was switched off
kSpPlaybackNotifyBecameActive	This device has become the active playback device.
kSpPlaybackNotifyBecameInactive	This device is no longer the active playback device.
kSpPlaybackNotifyAudioDeliveryDone	The library will not send any more audio data.
kSpPlaybackNotifyContextChanged	Playback changed to a different Spotify context.
kSpPlaybackNotifyMetadataChanged	Metadata is changed.
kSpPlaybackNotifyNetworkRequired	Playback is not allowed without network connection.
kSpPlaybackNotifyTrackDownloadStalled	Download of the current track stalled due to network outage.
kSpPlaybackNotifyQueuedTrackAccepted	The queued track was accepted.

Return to Main enumerations

kSpConnectionNotifyLoggedIn	The user has successfully logged in to Spotify
kSpConnectionNotifyLoggedOut	The user has been logged out of Spotify
kSpConnectionNotifyTemporaryError	A temporary connection error occurred. The library will automatically retry.
kSpConnectionNotifyDisconnect	The connection to Spotify has been lost.
kSpConnectionNotifyReconnect	The connection to Spotify has been (re-)established.
kSpConnectionNotifyProductTypeChanged	The connected user account type has changed (became premium, for example).
kSpConnectionNotifyZeroConfVarsChanged	The SpZeroConfVars has changed.
kSpConnectionNotifyTransmittingData	The eSDK is transmitting data.

Return to Main enumerations

kSpDeviceTypeComputer	Laptop or desktop computer device.
kSpDeviceTypeTablet	Tablet PC device.
kSpDeviceTypeSmartphone	Smartphone device.
kSpDeviceTypeSpeaker	Speaker device.
kSpDeviceTypeTV	Television device.
kSpDeviceTypeAVR	Audio/Video receiver device.
kSpDeviceTypeSTB	Set-Top Box device.
kSpDeviceTypeAudioDongle	Audio dongle device.
kSpDeviceTypeGameConsole	Game console device.
kSpDeviceTypeCastVideo	Chromecast Video.
kSpDeviceTypeCastAudio	Chromecast Audio.
kSpDeviceTypeAutomobile	Automobile.
kSpDeviceTypeSmartwatch	Smartwatch.
kSpDeviceTypeChromebook	Chromebook.

Return to Main enumerations

kSpMetadataTrackBeforePrevious	Index of the before previous track in the track list.
kSpMetadataTrackPrevious	Index of the previous track in the track list.
kSpMetadataTrackCurrent	Index of the current track in the track list.
kSpMetadataTrackNext	Index of the next track in the track list.
kSpMetadataTrackAfterNext	Index of the after next track in the track list.

Return to Main enumerations

kSpConnectivityNone	The device is not connected to the network.
kSpConnectivityWired	The device is connected to a wired network.
kSpConnectivityWireless	The device is connected to a wireless network.
kSpConnectivityMobile	The device uses a mobile data connection.

Return to Main enumerations

kSpContentUnknown	Unknown content type.
kSpContentMusicTrack	Music track.
kSpContentShowEpisode	Podcast show episode.
kSpContentAd	Advertisement.

Return to Main enumerations

kSpMediaTypeAudio	Audio media type.
kSpMediaTypeVideo	Video media type.

Return to Main enumerations

kSpAudioQualityUnknown	Unknown audio quality.
kSpAudioQualityLow	Low audio quality.
kSpAudioQualityNormal	Normal audio quality (e.g. 96 kbps ogg/vorbis)
kSpAudioQualityHigh	High audio quality (e.g. 160 kbps ogg/vorbis)
kSpAudioQualityVeryHigh	Very high audio quality (e.g. 320 kbps ogg/vorbis)

Return to Main enumerations

kSpDrmFormatUnknown	Unknown DRM.
kSpDrmFormatUnencrypted	No DRM, unencrypted.
kSpDrmFormatFairPlay	FairPlay.
kSpDrmFormatWidevine	Widevine.
kSpDrmFormatPlayReady	PlayReady.

Return to Main enumerations

kSpRedeliveryModeActivated	Redelivery is activated.
kSpRedeliveryModeDeactivated	Redelivery is deactivated.

Functions

---

Return to Main functions

Initialize the library.

Parameters

Returns

Returns an error code

Return to Main functions

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

Return to Main functions

Retrieve a version string for the library.

Returns

Version string

Notes:

• This API can be invoked from a callback.

Return to Main functions

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

Returns

Returns an error code

Return to Main functions

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.

Return to Main functions

Log in a user to Spotify using a credentials blob.

Parameters

Returns

Returns an error code

See also

• SpConnectionIsLoggedIn

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".

Return to Main functions

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

Returns

Returns an error code

See also

• SpConnectionIsLoggedIn

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.

Return to Main functions

Log the user out of Spotify

Returns

Returns an error code

See also

• SpConnectionIsLoggedIn

Notes:

• The logout is performed asynchronously. The logout is complete when the callback SpCallbackConnectionNotify is called with the event kSpConnectionNotifyLoggedOut

Return to Main functions

Is the user logged in to Spotify

Returns

1: The user is logged in 0: The user is not logged in

See also

• kSpConnectionNotifyLoggedIn
• kSpConnectionNotifyLoggedOut
• SpConnectionLoginBlob
• SpConnectionLogout

Notes:

• This API can be invoked from a callback.

Return to Main functions

Get the last Ack ID.

Notes:

• This function is deprecated and should not be used.

Return to Main functions

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.

Return to Main functions

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

Returns

Returns an error code

Notes:

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

Return to Main functions

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

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.

Return to Main functions

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

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.

Return to Main functions

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

Return to Main functions

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.

Return to Main functions

Return the currently selected device alias.

Returns

The currently selected device alias or SP_NO_ALIAS_SELECTED if no alias is selected.

Return to Main functions

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

Return to Main functions

Register callbacks related to the connection to Spotify

Parameters

Returns

Returns an error code

Return to Main functions

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

Returns

Returns an error code

Return to Main functions

Register playback-related callbacks.

Parameters

Returns

Returns an error code

Return to Main functions

Retrieve metadata for a track in the current track list.

Parameters

Returns

Returns an error code. Returns kSpErrorFailed if relative_index is out of range.

Notes:

• This API can be invoked from a callback.
• Be aware that many APIs that change the currently playing context are asynchronous, and the changes will not be immediately reflected in the metadata returned by SpGetMetadata For example, when calling SpPlaybackSkipToNext SpPlaybackEnableShuffle etc., the metadata returned by SpGetMetadata might be unchanged while the command is being processed (which involves network communication). The notification kSpPlaybackNotifyMetadataChanged will be sent as soon as SpGetMetadata would return a different result for any relative_index defined in the enum SpMetadataTrack

Return to Main functions

Return the HTTP URL to an image file from a spotify:image: URI.

Parameters

Returns

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

Notes:

• This API can be invoked from a callback.

Return to Main functions

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

Returns

Returns an error code. Returns kSpErrorUnsupported if the build configuration doesn't support player cookies.

Notes:

• Experimental, subject to change

Return to Main functions

Start or resume playback.

Parameters

Returns

Returns an error code

Return to Main functions

Pause playback.

If the device is not the active speaker (SpPlaybackIsActiveDevice()), the error code kSpErrorNotActiveDevice is returned.

Returns

Returns an error code

Return to Main functions

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

Return to Main functions

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

Return to Main functions

Seek to a position within the current track.

If the device is not the active speaker (SpPlaybackIsActiveDevice()), the error code kSpErrorNotActiveDevice is returned.

Parameters

Returns

Returns an error code

Return to Main functions

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

Returns

Returns an error code

Return to Main functions

Get the current playback position within the track.

Returns

Playback position in milliseconds

Notes:

• This API can be invoked from a callback.

Return to Main functions

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

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.

Return to Main functions

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.

Return to Main functions

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

• kSpPlaybackNotifyPlay
• kSpPlaybackNotifyPause
• SpPlaybackPlay
• SpPlaybackPause

Notes:

• This API can be invoked from a callback.
• The result of this API is analogous to the playback notifications kSpPlaybackNotifyPlay and kSpPlaybackNotifyPause

Return to Main functions

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

• kSpPlaybackNotifyTrackChanged

Notes:

• This API can be invoked from a callback.

Return to Main functions

Is "shuffle" mode enabled.

Returns

1: Shuffle is enabled 0: Shuffle is disabled

See also

• kSpPlaybackNotifyShuffleOn
• kSpPlaybackNotifyShuffleOff
• SpPlaybackEnableShuffle

Notes:

• This API can be invoked from a callback.

Return to Main functions

Is "repeat" mode enabled.

Returns

1: Repeat is enabled 0: Repeat is disabled

See also

• kSpPlaybackNotifyRepeatOn
• kSpPlaybackNotifyRepeatOff
• SpPlaybackEnableRepeat

Notes:

• This API can be invoked from a callback.

Return to Main functions

Which "repeat" mode is on.

Returns

0: Repeat is disabled 1: Repeat Context is enabled 2: Repeat Track is enabled

See also

• kSpPlaybackNotifyRepeatOn
• kSpPlaybackNotifyRepeatOff
• SpPlaybackEnableRepeat

Notes:

• This API can be invoked from a callback.

Return to Main functions

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

• kSpPlaybackNotifyBecameActive
• kSpPlaybackNotifyBecameInactive

Notes:

• This API can be invoked from a callback.

Return to Main functions

Enable or disable "shuffle" mode.

If the device is not the active speaker (SpPlaybackIsActiveDevice()), the error code kSpErrorNotActiveDevice is returned.

Parameters

Returns

Returns an error code

See also

• SpPlaybackIsShuffled

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.

Return to Main functions

Enable or disable "repeat" mode.

If the device is not the active speaker (SpPlaybackIsActiveDevice()), the error code kSpErrorNotActiveDevice is returned.

Parameters

Returns

Returns an error code

See also

• SpPlaybackIsRepeated

Return to Main functions

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.

Return to Main functions

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

Returns

Returns an error code

Return to Main functions

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

• SpPlaybackSetDeviceInactive
• SpPlaybackSetDeviceControllable

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

See also

• SpPlaybackIsAvailableToPlay

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.

Return to Main functions

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

• SpPlaybackIsDeviceControllable

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

• SpPlaybackSetAvailableToPlay

Return to Main functions

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

• SpPlaybackIsActiveDevice

Notes:

• The device gets active and starts playing when integration calls SpPlaybackPlay or SpPlayUri

Return to Main functions

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

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

Returns

Returns an error code

See also

• SpPlaybackIsDeviceControllable

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.

Return to Main functions

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

Returns

Returns an error code

Return to Main functions

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

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.

Return to Main functions

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

Return to Main functions

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

Return to Main functions

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

Notes:

• This API can be invoked from a callback.

Return to Main functions

Temporarily pause ZeroConf mDNS announcements.

Returns

Returns an error code

Notes:

• This call requires ZeroConf to be started by setting SpConfig::zeroconf_serve when calling SpInit

Return to Main functions

Resume ZeroConf mDNS announcement after calling SpZeroConfAnnouncePause

Returns

Returns an error code

Notes:

• This call requires ZeroConf to be started by setting SpConfig::zeroconf_serve when calling SpInit

Return to Main functions

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

Returns

Returns an error code

See also

• SpConnectionIsLoggedIn

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:

Return to Main functions

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.

Return to Main functions

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.

Return to Main functions

Register callbacks related to device aliases.

Parameters

Returns

Returns an error code

Return to Main functions

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

Return to Main functions

Set the ad user agent.

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

Parameters

See also

• SpConfig

Return to Main functions

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

• SpInit
• SpConfig::supported_drm_media_formats

Return to Main functions

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

See also

• SpFormat

Content

---

• Data Structures
• Typedefs
• Enumerations
• Functions

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

---

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.

SpCallbackTrackCacheState	track_state_callback	Track cached state callback.
SpCallbackStorageKeyContentMapping	store_key_map_callback	Content mapping callback.
SpCallbackTrackRelinked	track_relink_callback	Notify about track relink during prefetch/offline.
SpCallbackTrackRemoved	track_removed_callback	Notify about track removal.
SpCallbackOnAvailableContainer	on_available_container	Notify about an available container item.

Typedefs

---

Return to Content Typedefs

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

Notes:

• The application should not block or call other API functions in the callback. This callback is called before each track delivery is started.

Return to Content Typedefs

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

See also

• SpContentType

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.

Return to Content Typedefs

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

Return to Content Typedefs

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

Return to Content Typedefs

Callback for each available container.

Parameters

Notes:

• Experimental, subject of change

Enumerations

---

Return to Content enumerations

kSpContentTrack	Content pointed by descriptor is spotify playable item URI (track or episode)
kSpContentTrackMetadata	Content pointed by descriptor is spotify playable item URI for which metadata is saved.

Functions

---

Return to Content functions

Parameters

Returns

Returns an error code

Hal

---

• Data Structures
• Typedefs
• Enumerations
• Functions

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

---

Return to Hal data structures

Struct contains resolved hostname IP address and its family.

enum SpIPFamily	family	IP protocol family for which lookup is requested.
uint8_t	addr	Ip address. Network byte order.
int	port	Contains port value if applicable. Host byte order.

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.

SpCallbackPerformDNSLookup

dns_lookup_callback

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

Return to Hal data structures

Socket handle type.

void *	handle	Platform defined socket representation.
void *	tls	Can be used by the TLS implementation to store connection specific state.

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.

SpCallbackSocketCreate	socket_create	Callback to create socket instance.
SpCallbackSocketSetOption	socket_set_option	Callback to set options on created socket.
SpCallbackSocketClose	socket_close	Callback to close the socket.
SpCallbackSocketBind	socket_bind	Callback to bind to socket.
SpCallbackSocketListen	socket_listen	Callback to start listening the socket.
SpCallbackSocketConnect	socket_connect	Callback to connect to socket.
SpCallbackSocketAccept	socket_accept	Callback to accept connection on socket.
SpCallbackSocketRead	socket_read	Callback to read data from socket.
SpCallbackSocketWrite	socket_write	Callback to write data to socket.
SpCallbackSocketReadFrom	socket_read_from	Callback to read data from socket pointed by address.
SpCallbackSocketWriteTo	socket_write_to	Callback to write data to socket pointed by address.
SpCallbackSocketError	socket_error	Callback to get OS error on socket.
SpCallbackSocketReadable	socket_readable	Callback to get readable state on socket.
SpCallbackSocketWriteable	socket_writable	Callback to get writable state on socket.
SpCallbackLocalAddresses	local_addresses	Callback to get local interface addresses.
SpCallbackSocketAddress	socket_address	Callback to platform address representation.
SpCallbackPump	on_pump	Callback to pump network layer.

Typedefs

---

Return to Hal Typedefs

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

See also

• SpAPIReturnCode

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.

Return to Hal Typedefs

This callback, if set by the client, is called by eSDK to create a socket of a certain type and family.

Parameters

Notes:

• The application should not block or call other API functions in the callback.

Return to Hal Typedefs

This callback, if set by the client, is called by eSDK to set specific options on the previously created socket.

Parameters

Notes:

• The application should not block or call other API functions in the callback.

Return to Hal Typedefs

This callback, if set by the client, is called by eSDK to close the previously opened socket.

Parameters

Notes:

• The application should not block or call other API functions in the callback.

Return to Hal Typedefs

This callback, if set by the client, is called by eSDK to bind to the provided socket.

Parameters

Notes:

• The application should not block or call other API functions in the callback.

Return to Hal Typedefs

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

Notes:

• The application should not block or call other API functions in the callback.

Return to Hal Typedefs

This callback, if set by the client, is called by eSDK to connect to the specified address and remote port.

Parameters

Notes:

• The application should not block or call other API functions in the callback.

Return to Hal Typedefs

This callback, if set by the client, is called by eSDK to accept connection on the provided socket.

Parameters

Notes:

• The application should not block or call other API functions in the callback.

Return to Hal Typedefs

This callback, if set by the client, is called by eSDK to read data from the socket.

Parameters

Notes:

• The application should not block or call other API functions in the callback.

Return to Hal Typedefs

This callback, if set by the client, is called by eSDK to write data to the socket.

Parameters

Notes:

• The application should not block or call other API functions in the callback.

Return to Hal Typedefs

This callback, if set by the client, is called by eSDK to read data from the socket addressed by the SpSockaddr instance.

Parameters

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.

Return to Hal Typedefs

This callback, if set by the client, is called by eSDK to write data to the socket addressed by the SpSockaddr instance.

Parameters

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.

Return to Hal Typedefs

This callback, if set by the client, is called by eSDK to get the underlying OS error code.

Parameters

Notes:

• The application should not block or call other API functions in the callback.

Return to Hal Typedefs

This callback, if set by the client, is called by eSDK to figure out if the socket is readable.

Parameters

Notes:

• The application should not block or call other API functions in the callback.

Return to Hal Typedefs

This callback, if set by the client, is called by eSDK to figure out if the socket is writable.

Parameters

Notes:

• The application should not block or call other API functions in the callback.

Return to Hal Typedefs

This callback, if set by the client, is called by eSDK to get local interface addresses.

Parameters

Notes:

• The application should not block or call other API functions in the callback.

Return to Hal Typedefs

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

Notes:

• The application should not block or call other API functions in the callback.

Return to Hal Typedefs

This callback, if set by the client, is called by eSDK to pump the network layer.

Parameters

Notes:

• The application should not block or call other API functions in the callback.

Enumerations

---

Return to Hal enumerations

kSpIPV4	IP v4 family.
kSpIPV6	IP v6 family.

Return to Hal enumerations

kSpSocketPoolGeneral	Sockets used for backend, streaming, etc.
kSpSocketPoolZeroConf	Sockets used for ZeroConf.

Return to Hal enumerations

kSpSocketStream	Stream socket type.
kSpSocketDgram	Datagram socket type.

Return to Hal enumerations

kSpSocketNonBlocking	Nonblocking mode has to be set by the implementation if possible. POSIX analog: TCP_NODELAY. Option is passed as an intptr_t in a range [0, 1].
kSpSocketReuseAddr	Reuse address mode has to be set if possible. POSIX analog: SO_REUSEADDR. Option is passed as an intptr_t in a range [0, 1].
kSpSocketReusePort	Reuse port mode has to be set if possible. POSIX analog: SO_REUSEPORT. Option is passed an intptr_t in a range [0, 1].
kSpSocketMulticastTTL	Multicast TTL has to be set if possible. POSIX analog: IP_MULTICAST_TTL. Option is passed as an intptr_t in a range [0, 255].
kSpSocketMulticastLoop	Multicast loop has to be set if possible. POSIX analog: IP_MULTICAST_LOOP. Option is passed as an intptr_t in a range [0, 1].
kSpSocketMembership	Set group address if possible. POSIX analog: IP_ADD_MEMBERSHIP. Option is passed as a pointer to SpSockaddr Address is in network byte order. Port field is not applicable.
kSpSocketMcastSendIf	Set outgoing multicast interface. POSIX analog: IP_MULTICAST_IF. Option is passed as a pointer to SpSockaddr Address is in network byte order. Port field is not applicable.

Functions

---

Return to Hal functions

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

Parameters

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.

Return to Hal functions

Get eSDK's default DNS callbacks.

Parameters

Returns

Returns an error code.

Notes:

• These callbacks are made available so they may be wrapped by custom DNS functions provided with SpRegisterDnsHALCallbacks

Return to Hal functions

Register socket HAL-related callbacks. To remove callbacks, call SpRegisterSocketHALCallbacks with SpSocketHALCallbacks initialized to zeros.

Parameters

Returns

Returns an error code

Notes:

• A call to this function has to be performed before SpInit is called. Calling this function when eSDK is initialized will fail with kSpErrorAlreadyInitialized

Return to Hal functions

Get eSDK's default socket callbacks.

Parameters

Returns

Returns an error code.

Notes:

• These callbacks are made available so they may be wrapped by custom socket functions provided with SpRegisterSocketHALCallbacks

Log

---

• Macros and Constants
• Data Structures
• Enumerations
• Functions

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

---

Return to Log macros and constants

Preferred macro to log the file name, you might redefine SP_FILE_NAME using basename() or use -ffile-prefix-map.

Return to Log macros and constants

Default trace log level.

Return to Log macros and constants

Macro to define a trace object.

obj Name of the trace object

Return to Log macros and constants

Macro to declare a previously defined trace object.

obj Name of the trace object

Return to Log macros and constants

Macro to register a previously defined trace object.

obj Name of the trace object

Return to Log macros and constants

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

Return to Log macros and constants

Emit trace message with SP_LOG_LEVEL_FATAL.

Return to Log macros and constants

Emit trace message with SP_LOG_LEVEL_ERROR.

Return to Log macros and constants

Emit trace message with SP_LOG_LEVEL_WARNING.

Return to Log macros and constants

Emit trace message with SP_LOG_LEVEL_INFO.

Return to Log macros and constants

Emit trace message with SP_LOG_LEVEL_DEBUG.

Return to Log macros and constants

Emit trace message with SP_LOG_LEVEL_TRACE.

Data Structures

---

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.

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

Enumerations

---

Return to Log enumerations

SP_LOG_LEVEL_FATAL	Indicates a severe abnormal condition and program termination.
SP_LOG_LEVEL_ERROR	Indicates an abnormal condition that could result in degraded functionality.
SP_LOG_LEVEL_WARNING	Indicates a condition that probably has some impact on execution or performance.
SP_LOG_LEVEL_INFO	Informational message.
SP_LOG_LEVEL_DEBUG	Debug message.
SP_LOG_LEVEL_TRACE	Trace message.

Functions

---

Return to Log functions

Register a defined trace object with eSDK.

Parameters

Returns

Return kSpErrorOk on success, or error code on failure.

Return to Log functions

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

Return to Log functions

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

Returns

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

Return to Log functions

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

Returns

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

Media

---

• Data Structures
• Typedefs
• Enumerations
• Functions

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

---

Return to Media data structures

Stream Parameters.

uint32_t	size	Size of the stream in bytes. If the size is unknown, 0 is used.
int32_t	gain_mdb	Audio normalization gain (in mdB) to apply to the stream.
uint32_t	start_position_ms	Reserved for internal use.
const char *	track_uri	Spotify track URI.
const char *	resource	Reserved for internal use.

Return to Media data structures

Callbacks to be registered with SpRegisterStreamCallbacks

SpCallbackStreamStart	on_start	Start of delivery callback.
SpCallbackStreamData	on_data	Data delivery callback.
SpCallbackStreamEnd	on_end	End of delivery callback.
SpCallbackStreamGetPosition	on_get_position	Current playback position callback.
SpCallbackStreamSeekToPosition	on_seek_position	Seek to position callback.
SpCallbackStreamFlush	on_flush	Flush callback.

Typedefs

---

Return to Media Typedefs

Callback to provide track details to the application.

To register this callback, use the function SpRegisterStreamCallbacks

Parameters

See also

• SpStreamInfo

Return to Media Typedefs

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

Return to Media Typedefs

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

Return to Media Typedefs

Callback to get the playback position in milliseconds.

To register this callback, use the function SpRegisterStreamCallbacks

Parameters

Return to Media Typedefs

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

Return to Media Typedefs

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

Enumerations

---

Return to Media enumerations

kSpMediaFormatSpotifyOggVorbis	ogg/vorbis 44.1 kHz stereo audio format with Spotify metadata page
kSpMediaFormatMp3	mp3
kSpMediaFormatMp4AAC	mp4/aac-lc
kSpMediaFormatSpacAAC	spac/aac-he-v2
kSpMediaFormatSpotifyManifestId	Spotify video manifest id.
kSpMediaFormatSpotifyAdManifest	Spotify ad manifest.

Functions

---

Return to Media functions

Register callbacks related to the delivery API.

Parameters

Returns

Returns an error code

Return to Media functions

API to notify eSDK of the completion of seek operation.

Parameters

Returns

Returns an error code

Return to Media functions

API to notify eSDK of the track length in milliseconds.

Parameters

Returns

Returns an error code

Return to Media functions

API to notify eSDK of any track errors with last played position.

Parameters

Returns

Returns an error code

Return to Media functions

Notify eSDK that the first audio sample of the delivery has been played.

This is used by the eSDK to measure playback latency.

Parameters

Returns

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

Return to Media functions

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

Returns

Returns an error code

Return to Media functions

Notify eSDK that the delivery playback finished by playing the last sample of the delivery.

Parameters

Returns

Returns an error code

Return to Media functions

API to instruct eSDK to start downloading from a given byte offset.

Parameters

Returns

Returns an error code

Play

---

• Macros and Constants
• Data Structures
• Functions

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

---

Return to Play macros and constants

Indicates that the index value is not set. Note: Can only be used with eSDK 3.

See also

• SpPlayUri

Return to Play macros and constants

Maximum length of a UUID.

A 128 bit UUID containing 32 hexadecimal digits in five groups separated by hyphens.

Return to Play macros and constants

Maximum length of the type of playback source.

See also

• SpSourceInfo
• SpPlayUri

Return to Play macros and constants

Maximum length of the source URIs.

See also

• SpSourceInfo
• SpPlayUri

Return to Play macros and constants

Maximum length of the referrer.

See also

• SpSourceInfo
• SpPlayUri

Return to Play macros and constants

Internal macro.

See also

• SP_PLAYOPTIONS_INITIALIZER

Return to Play macros and constants

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

---

Return to Play data structures

Metadata for identifying where a playback request originated from.

See also

• SpPlayUri

char	type	The type of playlist/context/UI view that caused this playback to start. Note: If set, this MUST be one of the following strings (unless told otherwise):
char	uri	The URI of the parent container, if there is one.
char	expected_track_uri	The URI of the track that is expected to play.
char	referrer	The view you were in prior to initiating playback.

Return to Play data structures

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

Example:

int	from_index	Track index in the Context from which playback should start. Use SP_NO_INDEX if no specific index is required. In case of non-shuffled context this will result in the first track of the context being played whereas in shuffled context this will result in a random track being played.
const char *	from_uid	The UID to identify a unique track in the context.
int	offset_ms	The time offset to start playing specified track from.
int	shuffle_context	Set to enable or disable shuffle mode for the requested playback command.
int	repeat_mode	Set to enable or disable repeat mode for the requested playback command.
const struct SpSourceInfo *	source_info	Metadata about what user action caused this playback event, and the expected result.

Functions

---

Return to Play functions

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

Returns

Returns an error code

See also

• SpSourceInfo
• SP_NO_INDEX

Return to Play functions

Start local playback of the given Spotify URI with additional options.

Parameters

Returns

Returns an error code

Return to Play functions

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

Returns

Returns an error code

See also

• SpPlayUriWithOptions
• SpPlayOptions::from_uid

Return to Play functions

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

Returns

Returns an error code.

See also

• kSpPlaybackNotifyQueuedTrackAccepted
• kSpErrorInvalidRequest

Return to Play functions

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

Returns

Returns an error code

Storage

---

• Data Structures
• Typedefs
• Functions

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

---

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.

SpCallbackStorageAlloc	alloc_storage	Alloc storage record callback.
SpCallbackStorageWrite	write_storage	Write storage data callback.
SpCallbackStorageRead	read_storage	Read storage data callback.
SpCallbackStorageClose	close_storage	Close storage record callback.
SpCallbackStorageDelete	delete_storage	Delete storage record callback.
SpCallbackThrottleRequest	throttle_request	Asks the client if disk writes need to be throttled.

Typedefs

---

Return to Storage Typedefs

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

See also

• SpAPIReturnCode

Notes:

• The allocation of space should be done in the way that following read and write operations will succeed within the specified resource size.

Return to Storage Typedefs

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

See also

• SpAPIReturnCode

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.

Return to Storage Typedefs

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

See also

• SpAPIReturnCode

Notes:

• The application should not block or call other API functions in the callback. If no storage read is possible, just return 0.

Return to Storage Typedefs

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

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.

Return to Storage Typedefs

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

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.

Return to Storage Typedefs

eSDK calls this callback to figure out if it needs to limit write access to the storage.

Parameters

Notes:

• The application should not block or call other API functions in the callback.

Functions

---

Return to Storage functions

Register storage callbacks.

Parameters

Returns

Returns an error code

Tls

---

• Data Structures
• Typedefs
• Functions

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

---

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.

SpCallbackTLSInit	init	Callback that performs one-time initialization.
SpCallbackTLSDeinit	deinit	Callback that performs release of resources allocated during init.
SpCallbackTLSCreate	create	Callback invoked once per connection to initialize TLS context.
SpCallbackTLSHandshake	handshake	Callback invoked repeatedly to perform the TLS handshake.
SpCallbackTLSRead	read	Callback for reading from the TLS data stream.
SpCallbackTLSWrite	write	Callback for writing to the TLS data stream.
SpCallbackTLSClose	close	Callback invoked to cleanup any TLS context before closing the socket.
SpCallbackTLSGetError	get_error	Callback invoked to get an error message for the last error.

Typedefs

---

Return to Tls Typedefs

This callback is invoked by eSDK to let the TLS library integration perform any one-time initialization.

Parameters

Notes:

• The application should not block or call other API functions in the callback.

Return to Tls Typedefs

This callback is invoked by eSDK to let the TLS library integration perform deallocation of resources during teardown.

Parameters

Notes:

• The application should not block or call other API functions in the callback.

Return to Tls Typedefs

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

Notes:

• The application should not block or call other API functions in the callback.

Return to Tls Typedefs

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

Notes:

• The application must not block or call other API functions in the callback.

Return to Tls Typedefs

This callback is invoked by eSDK to read data on a TLS connection.

Parameters

Notes:

• The application should not block or call other API functions in the callback.

Return to Tls Typedefs

This callback is invoked by eSDK to write data on a TLS connection.

Parameters

Notes:

• The application should not block or call other API functions in the callback.

Return to Tls Typedefs

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

Parameters

Notes:

• The application should not block or call other API functions in the callback.

Return to Tls Typedefs

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

Notes:

• The application should not block or call other API functions in the callback.

Functions

---

Return to Tls functions

Register TLS-related callbacks.

Parameters

Returns

Returns an error code

Notes:

• A call to this function has to be performed before SpInit is called. Calling this function when eSDK is initialized will fail with kSpErrorAlreadyInitialized The function will return kSpErrorUnsupported in the eSDK configurations with built-in TLS.

Return to Tls functions

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

• SpTLSCallbacks

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

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

Return to Tls functions

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

• SpTLSCallbacks

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

---

• Data Structures
• Typedefs
• Functions

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

---

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.

SpCallbackConnectionReceiveAccessToken	on_access_token	Access token event callbacks.
SpCallbackConnectionReceiveAuthCode	on_auth_code	Authorization code event callbacks.

Typedefs

---

Return to Token Typedefs

Callback to deliver the access token requested by SpConnectionRequestAccessToken

Parameters

Notes:

• The JSON object looks as following: "accessToken":"tokendata", "expiresIn":expiryinseconds,//typically3600 "tokenType":"tokentype"//typically"Bearer"

Return to Token Typedefs

Callback to deliver the access token requested by SpConnectionRequestAuthCode

Parameters

Notes:

• The JSON object looks as following: "code":"tokendata", "redirectUri":"someUri"

Functions

---

Return to Token functions

Register token callbacks.

Parameters

Returns

Returns an error code

Return to Token functions

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

Return to Token functions

Request an authorization code for the logged in user.

Parameters

Notes:

• The string scope must not be longer than 425 characters.