API Reference eSDK 3.208.26

Main

---

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

Macros and Constants

---

Return to header index

SP_API_VERSION	82
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_PLAYER_MODES	8
SP_MAX_MODE_KEY_LENGTH	32
SP_MAX_MODE_VALUE_LENGTH	32
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_MAX_RESPONSE_SOURCE_LENGTH	20
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_PLAYER_MODES_RESTRICTIONS	Maximum number of Player Mode Restrictions eSDK can provide through SpPlaybackRestrictions in Metadata.
SP_MAX_PLAYER_MODE_VALUE_DISALLOW_REASONS	16
SP_MAX_METADATA_KEY_LENGTH	32
SP_MAX_METADATA_VALUE_LENGTH	64

Data Structures

---

Return to header index

SpPlayerModeDisallowReasons	This struct stores a Mode value and the restriction disallow reasons associated with it.
SpPlayerModeRestrictions	this struct stores a Mode key and the list of restricted values.
SpPlaybackRestrictions	Playback restrictions.
SpFormat	Mapping of which media formats are supported in which DRM.
SpMetadata	Track metadata.
SpAdMetadata	Key value pair for Ad-related metadata.
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	Error codes.
SpAPIReturnCode	Enum describes return codes that public API functions can report to eSDK.
SpPlaybackBitrate	Valid bitrate values. This enum is used for selecting the audio quality of the files to play.
SpPlaybackNotification	Playback-related notification events.
SpConnectionNotification	Notifications related to the connection to Spotify.
SpDeviceType	Device type reported to client applications.
SpMetadataTrack	Metadata track selector.
SpConnectivity	Type of network connection.
SpContent	Content type.
SpMediaType	Media Type.
SpAudioQuality	Audio quality.
SpDrmFormat	DRM formats.
SpReDeliveryMode	Redelivery mode types.

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.
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	Restrict DRM/Media formats.

SP_API_VERSION

---

Return to header index

The version of the API defined in this header file.

See also

• SpInit

SP_RECOMMENDED_MEMORY_BLOCK_SIZE

---

Return to header index

Minimum recommended size of the buffer SpConfig::memory_block.

SP_MAX_BRAND_NAME_LENGTH

---

Return to header index

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

See also

• SpConfig

SP_MAX_MODEL_NAME_LENGTH

---

Return to header index

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

See also

• SpConfig

SP_MAX_PLATFORM_NAME_LENGTH

---

Return to header index

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

See also

• SpConfig

SP_MAX_CLIENT_ID_LENGTH

---

Return to header index

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

See also

• SpConfig

SP_MAX_OS_VERSION_LENGTH

---

Return to header index

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

See also

• SpConfig

SP_MAX_DISPLAY_NAME_LENGTH

---

Return to header index

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

See also

• SpSetDisplayName
• SpConfig
• SpZeroConfVars

SP_MAX_AD_USER_AGENT_LENGTH

---

Return to header index

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

See also

• SpSetAdUserAgent

SP_MAX_UNIQUE_ID_LENGTH

---

Return to header index

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

See also

• SpConfig

SP_MAX_USERNAME_LENGTH

---

Return to header index

Maximum length of usernames (not counting terminating NULL)

See also

• SpZeroConfVars
• SpConnectionLoginZeroConf

SP_MAX_DEVICE_ALIASES

---

Return to header index

Maximum number of device aliases that can be configured.

See also

• SpConfig::device_aliases

SP_MAX_AD_METADATA_PAIRS

---

Return to header index

Maximum number of key/value pairs containing ad metadata.

SP_NO_ALIAS_SELECTED

---

Return to header index

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

See also

• SpConfig::device_aliases

SP_MAX_PLAYER_MODES

---

Return to header index

Maximum number of Player Option Modes eSDK can provide when calling SpPlaybackGetPlayerModes()

Note: reserved for future use.

SP_MAX_MODE_KEY_LENGTH

---

Return to header index

Maximum length of the key field in struct SpPlayerModePair.

Note: reserved for future use.

SP_MAX_MODE_VALUE_LENGTH

---

Return to header index

Maximum length of the value field in struct SpPlayerModePair.

Note: reserved for future use.

SP_MAX_METADATA_NAME_LENGTH

---

Return to header index

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

SP_MAX_METADATA_URI_LENGTH

---

Return to header index

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

See also

• SpGetMetadata
• SpMetadata

SP_MAX_TRACK_UID_LENGTH

---

Return to header index

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

See also

• SpGetMetadata
• SpMetadata

SP_MAX_METADATA_IMAGE_URL_LENGTH

---

Return to header index

Maximum length of URLs (not counting terminating NULL)

See also

• SpGetMetadataImageURL

SP_PLAYER_COOKIE_LENGTH

---

Return to header index

Length of player cookie (not counting terminating NULL)

See also

• SpGetPlayerCookie

SP_MAX_PLAYBACK_ID_LENGTH

---

Return to header index

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

See also

• SpGetMetadata
• SpMetadata

SP_MAX_PUBLIC_KEY_LENGTH

---

Return to header index

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

See also

• SpZeroConfVars

SP_MAX_DEVICE_ID_LENGTH

---

Return to header index

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

See also

• SpZeroConfVars

SP_MAX_DEVICE_TYPE_LENGTH

---

Return to header index

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

See also

• SpZeroConfVars

SP_MAX_VERSION_LENGTH

---

Return to header index

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

See also

• SpZeroConfVars

SP_MAX_GROUP_STATUS_LENGTH

---

Return to header index

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

See also

• SpZeroConfVars

SP_MAX_TOKEN_TYPE_LENGTH

---

Return to header index

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

See also

• SpZeroConfVars

SP_MAX_SCOPE_LENGTH

---

Return to header index

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

See also

• SpZeroConfVars

SP_MAX_CLIENT_KEY_LENGTH

---

Return to header index

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

See also

• SpConnectionLoginZeroConf

SP_MAX_ZEROCONF_BLOB_LENGTH

---

Return to header index

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

See also

• SpConnectionLoginZeroConf

SP_MAX_LOGIN_ID_LENGTH

---

Return to header index

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

See also

• SpConnectionLoginZeroConf

SP_MAX_AVAILABILITY_LENGTH

---

Return to header index

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

See also

• SpConnectionLoginZeroConf

SP_MAX_PARTNER_NAME_LENGTH

---

Return to header index

Maximum length of the Partner Name (TSP_PARTNER_NAME) (not counting terminating NULL) The longest partner name when this was written was "imagination_technologies_mips" at 29 characters.

SP_MAX_FILENAME_LENGTH

---

Return to header index

Maximum length of filename fields (not counting terminating NULL)

SP_MAX_RESPONSE_SOURCE_LENGTH

---

Return to header index

Maximum length of the response source string (not counting terminating NULL)

SP_ZEROCONF_DISABLED

---

Return to header index

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

See also

• SpInit

SP_ZEROCONF_SERVE

---

Return to header index

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

See also

• SpInit

SP_ZEROCONF_SERVE_HTTP_ONLY

---

Return to header index

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

See also

• SpInit

SP_ZEROCONF_SERVE_MDNS_ONLY

---

Return to header index

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

See also

• SpInit

SP_SCOPE_STREAMING

---

Return to header index

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

SP_DEVICE_ALIAS_ATTRIBUTE_GROUP

---

Return to header index

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

Notes:

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

SP_GLOBAL_ATTRIBUTE_VOICE

---

Return to header index

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

SP_MAX_SUPPORTED_FORMATS

---

Return to header index See also

• SpFormat
• SpConfig::supported_drm_media_formats

SP_PLAYBACK_RESTRICTION_ALREADY_PAUSED

---

Return to header index

The track is already paused.

SP_PLAYBACK_RESTRICTION_NOT_PAUSED

---

Return to header index

The track is already playing.

SP_PLAYBACK_RESTRICTION_LICENSE_DISALLOW

---

Return to header index

Licensing rules disallow this action.

SP_PLAYBACK_RESTRICTION_AD_DISALLOW

---

Return to header index

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

SP_PLAYBACK_RESTRICTION_NO_PREV_TRACK

---

Return to header index

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

SP_PLAYBACK_RESTRICTION_NO_NEXT_TRACK

---

Return to header index

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

SP_PLAYBACK_RESTRICTION_UNKNOWN

---

Return to header index

The action is restricted, but no reason is provided.

This means that eSDK has not retrieved the restrictions from the backend yet and therefore the action is not allowed right now. As soon as eSDK retrieves the information, the notification kSpPlaybackNotifyMetadataChanged will be sent, and the application can check the field again.

SP_PLAYBACK_RESTRICTION_ENDLESS_CONTEXT

---

Return to header index

The action is restricted for context level reasons.

SP_MAX_PLAYER_MODES_RESTRICTIONS

---

Return to header index

Maximum number of Player Mode Restrictions eSDK can provide through SpPlaybackRestrictions in Metadata.

Note: reserved for future use.

SP_MAX_PLAYER_MODE_VALUE_DISALLOW_REASONS

---

Return to header index

Maximum number of restriction disallow reasons per value of a Player Mode.

SP_MAX_METADATA_KEY_LENGTH

---

Return to header index

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

See also

• SpAdMetadata

SP_MAX_METADATA_VALUE_LENGTH

---

Return to header index

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

See also

• SpAdMetadata

SpPlayerModeDisallowReasons

---

Return to header index

This struct stores a Mode value and the restriction disallow reasons associated with it.

char	value	A null-terminated string to represent the value of the restricted Player Mode.
uint32_t	disallow_reasons	Bitfield of reasons for disallowing setting the mode value.

SpPlayerModeRestrictions

---

Return to header index

this struct stores a Mode key and the list of restricted values.

char	key	A null-terminated string to represent the key of the Player Mode that is restricted.
struct SpPlayerModeDisallowReasons	reasons	the list of restricted values and the disallow reasons.

SpPlaybackRestrictions

---

Return to header index

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.

SpFormat

---

Return to header index

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.

SpMetadata

---

Return to header index

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.

SpAdMetadata

---

Return to header index

Key value pair for Ad-related metadata.

char	key	Key.
char	value	Value.

SpZeroConfDeviceAlias

---

Return to header index

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.

SpZeroConfVars

---

Return to header index

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

SpSampleFormat

---

Return to header index

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)
int	bits_per_sample	Bits per sample (16 or 24)

SpPlaybackCallbacks

---

Return to header index

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.

SpDebugCallbacks

---

Return to header index

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.

SpConnectionCallbacks

---

Return to header index

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.

SpDeviceAlias

---

Return to header index

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.

SpConfig

---

Return to header index

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.

SpDeviceAliasCallbacks

---

Return to header index

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.

SpCallbackError

---

Return to header index

Callback for reporting errors to the application.

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

Notes:

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

SpCallbackPlaybackNotify

---

Return to header index

Callback for notifying the application about playback-related events.

To register this callback, use the function SpRegisterPlaybackCallbacks().

Notes:

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

SpCallbackPlaybackSeek

---

Return to header index

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.

Notes:

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

SpCallbackPlaybackApplyVolume

---

Return to header index

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.

Notes:

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

SpCallbackConnectionNotify

---

Return to header index

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

To register this callback, use the function SpRegisterConnectionCallbacks().

Notes:

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

SpCallbackConnectionNewCredentials

---

Return to header index

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.

See also

• SpConnectionLoginBlob

Notes:

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

SpCallbackConnectionMessage

---

Return to header index

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.

Notes:

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

SpCallbackDebugMessage

---

Return to header index

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

Notes:

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

SpCallbackSelectedDeviceAliasChanged

---

Return to header index

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.

Notes:

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

SpCallbackDeviceAliasesUpdateDone

---

Return to header index

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.

Notes:

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

SpError

---

Return to header index

Error codes.

These are the possible status codes returned by functions in the SDK. They should be used to determine if an action was successful, and if not, why the action failed.

See also

• SpCallbackError

SpAPIReturnCode

---

Return to header index

Enum describes return codes that public API functions can report to eSDK.

SpPlaybackBitrate

---

Return to header index

Valid bitrate values. This enum is used for selecting the audio quality of the files to play.

See also

• SpPlaybackSetBitrate

SpPlaybackNotification

---

Return to header index

Playback-related notification events.

See also

• SpCallbackPlaybackNotify

SpConnectionNotification

---

Return to header index

Notifications related to the connection to Spotify.

See also

• SpCallbackConnectionNotify

SpDeviceType

---

Return to header index

Device type reported to client applications.

SpMetadataTrack

---

Return to header index

Metadata track selector.

See also

• SpGetMetadata

SpConnectivity

---

Return to header index

Type of network connection.

See also

• SpConnectionSetConnectivity

SpContent

---

Return to header index

Content type.

SpMediaType

---

Return to header index

Media Type.

SpAudioQuality

---

Return to header index

Audio quality.

SpDrmFormat

---

Return to header index

DRM formats.

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

SpReDeliveryMode

---

Return to header index

Redelivery mode types.

SpInit

---

Return to header index

Initialize the library.

SpFree

---

Return to header index

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.

SpGetLibraryVersion

---

Return to header index

Retrieve a version string for the library.

Notes:

• This API can be invoked from a callback.

SpConnectionSetConnectivity

---

Return to header index

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.

SpConnectionGetConnectivity

---

Return to header index

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.

Notes:

• This API can be invoked from a callback.

SpConnectionLoginBlob

---

Return to header index

Log in a user to Spotify using a credentials blob.

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

SpConnectionLoginOauthToken

---

Return to header index

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

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.

SpConnectionLogout

---

Return to header index

Log the user out of Spotify.

See also

• SpConnectionIsLoggedIn

Notes:

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

SpConnectionIsLoggedIn

---

Return to header index

Is the user logged in to Spotify.

See also

• kSpConnectionNotifyLoggedIn
• kSpConnectionNotifyLoggedOut
• SpConnectionLoginBlob
• SpConnectionLogout

Notes:

• This API can be invoked from a callback.

SpConnectionGetAckId

---

Return to header index

Get the last Ack ID.

Notes:

• This function is deprecated and should not be used.

SpGetCanonicalUsername

---

Return to header index

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.

Notes:

• The canonical username should not be stored persistently. Always store the username as provided by the user, not the canonicalized version.
• This API can be invoked from a callback.

SpSetDisplayName

---

Return to header index

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.

Notes:

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

SpSetVolumeSteps

---

Return to header index

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.

Notes:

• There's no commitment from the other Connect clients to respect the volume steps. It's important to call this function passing zero if no volume control is possible though.

SpSetDeviceIsGroup

---

Return to header index

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.

Notes:

• If device aliases are used, this function should not be used to set the group status. Instead, SpSetDeviceAliases() should be used to update group status individually for each alias.

SpEnableConnect

---

Return to header index

Enable Connect functionality for this device.

A device with enabled Connect functionality will show up in other devices' Connect pickers, and will be able to both control them and be controlled. The Spotify embedded library will enable Connect functionality by default

SpDisableConnect

---

Return to header index

Disable Connect functionality for this device.

A device that disables Connect will not be able to control playback on other devices, or be controlled by them.

SpGetSelectedDeviceAlias

---

Return to header index

Return the currently selected device alias.

SpPumpEvents

---

Return to header index

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:

Example:

SpRegisterConnectionCallbacks

---

Return to header index

Register callbacks related to the connection to Spotify.

SpRegisterDebugCallbacks

---

Return to header index

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.

SpRegisterPlaybackCallbacks

---

Return to header index

Register playback-related callbacks.

SpGetMetadata

---

Return to header index

Retrieve metadata for a track in the current track list.

Notes:

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

SpGetMetadataImageURL

---

Return to header index

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

Notes:

• This API can be invoked from a callback.

SpGetPlayerCookie

---

Return to header index

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.

Notes:

• Experimental, subject to change

SpPlaybackPlay

---

Return to header index

Start or resume playback.

SpPlaybackPause

---

Return to header index

Pause playback.

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

SpPlaybackSkipToNext

---

Return to header index

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.

SpPlaybackSkipToPrev

---

Return to header index

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.

Notes:

• This function will try to skip to the previous track regardless of the current playback position. If the desired behaviour is to only skip to the previous track UNLESS the current playback position is beyond 3 seconds, the following code example is suggested as a base: if(SpPlaybackGetPosition()/1000=3) SpPlaybackSeek(0); else SpPlaybackSkipToPrev();

SpPlaybackSeek

---

Return to header index

Seek to a position within the current track.

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

SpPlaybackSeekRelative

---

Return to header index

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.

SpPlaybackGetPosition

---

Return to header index

Get the current playback position within the track.

Notes:

• This API can be invoked from a callback.

SpPlaybackUpdateVolume

---

Return to header index

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.

Notes:

• When the library is initialized, it assumes a volume level of 32768 (50% volume). The application must invoke SpPlaybackUpdateVolume() at some point after calling SpInit() to inform the library of the actual volume level of the device's audio output.

SpPlaybackGetVolume

---

Return to header index

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

Notes:

• This API can be invoked from a callback.

SpPlaybackIsPlaying

---

Return to header index

Is the playback status playing or paused.

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.

SpPlaybackIsAdPlaying

---

Return to header index

Is the current track an Ad or not.

See also

• kSpPlaybackNotifyTrackChanged

Notes:

• This API can be invoked from a callback.

SpPlaybackIsShuffled

---

Return to header index

Is "shuffle" mode enabled.

See also

• kSpPlaybackNotifyShuffleOn
• kSpPlaybackNotifyShuffleOff
• SpPlaybackEnableShuffle

Notes:

• This API can be invoked from a callback.

SpPlaybackIsRepeated

---

Return to header index

Is "repeat" mode enabled.

See also

• kSpPlaybackNotifyRepeatOn
• kSpPlaybackNotifyRepeatOff
• SpPlaybackEnableRepeat

Notes:

• This API can be invoked from a callback.

SpPlaybackGetRepeatMode

---

Return to header index

Which "repeat" mode is on.

See also

• kSpPlaybackNotifyRepeatOn
• kSpPlaybackNotifyRepeatOff
• SpPlaybackEnableRepeat

Notes:

• This API can be invoked from a callback.

SpPlaybackIsActiveDevice

---

Return to header index

Is the device the active playback device.

See also

• kSpPlaybackNotifyBecameActive
• kSpPlaybackNotifyBecameInactive

Notes:

• This API can be invoked from a callback.

SpPlaybackEnableShuffle

---

Return to header index

Enable or disable "shuffle" mode.

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

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.

SpPlaybackEnableRepeat

---

Return to header index

Enable or disable "repeat" mode.

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

See also

• SpPlaybackIsRepeated

SpPlaybackCycleRepeatMode

---

Return to header index

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.

SpPlaybackSetBitrate

---

Return to header index

Change the bitrate at which compressed audio data is delivered.

The integration will be required to flush the data it has already received at the current audio quality. The data in the new audio quality will then be streamed from the playback position we were at when this API was called.

SpPlaybackSetDeviceInactive

---

Return to header index

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.

See also

• SpPlaybackIsActiveDevice

Notes:

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

SpPlaybackIsDeviceControllable

---

Return to header index

Is the device controllable.

See also

• SpPlaybackSetDeviceControllable

SpPlaybackSetDeviceControllable

---

Return to header index

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.

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.

SpPlaybackIncreaseUnderrunCount

---

Return to header index

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.

SpPlaybackSetBandwidthLimit

---

Return to header index

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.

Notes:

• eSDK is not guaranteed to stay strictly below the limit but will not exceed it by much. It is also not guaranteed to use all available bandwidth.

SpPlaybackSetRedeliveryMode

---

Return to header index

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.

SpPlaybackIsRedeliveryModeActivated

---

Return to header index

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.

SpZeroConfGetVars

---

Return to header index

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.

Notes:

• This API can be invoked from a callback.

SpZeroConfAnnouncePause

---

Return to header index

Temporarily pause ZeroConf mDNS announcements.

Notes:

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

SpZeroConfAnnounceResume

---

Return to header index

Resume ZeroConf mDNS announcement after calling SpZeroConfAnnouncePause()

Notes:

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

SpConnectionLoginZeroConf

---

Return to header index

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.

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:

SpGetBrandName

---

Return to header index

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.

Notes:

• This API can be invoked from a callback.

SpGetModelName

---

Return to header index

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.

Notes:

• This API can be invoked from a callback.

SpRegisterDeviceAliasCallbacks

---

Return to header index

Register callbacks related to device aliases.

SpSetDeviceAliases

---

Return to header index

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.

SpSetAdUserAgent

---

Return to header index

Set the ad user agent.

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

See also

• SpConfig

SpRestrictDrmMediaFormats

---

Return to header index

Restrict DRM/Media formats.

restricted_formats An array of DRM/media format pairs to restrict. Restricts the list of DRM and media formats to a subset of the formats registered in SpInit(). COMPATIBILITY NOTE: To restore the restricted capabilitites to the ones registered in SpInit() call this API again with a NULL parameter. That is, SpRestoreDrmMediaFormats() is now removed.

See also

• SpInit
• SpConfig::supported_drm_media_formats

Notes:

• This API can be invoked from a callback.

Example:

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

Enum describes content type being stored by eSDK.

Functions

---

Return to header index

SpRegisterContentCallbacks

SpContentCallbacks

---

Return to header index

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.

SpCallbackTrackCacheState

---

Return to header index

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.

Notes:

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

SpCallbackStorageKeyContentMapping

---

Return to header index

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

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.

SpCallbackTrackRelinked

---

Return to header index

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

---

Return to header index

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.

SpCallbackOnAvailableContainer

---

Return to header index

Callback for each available container.

Notes:

• Experimental, subject of change

SpContentType

---

Return to header index

Enum describes content type being stored by eSDK.

SpRegisterContentCallbacks

---

Return to header index

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	Enum describes the IP family.
SpSocketPool	Socket pool IDs.
SpSocketType	Enum defines the type of socket supported by eSDK.
SpSocketOptions	Enum defines options that can be applied to sockets.

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.

SpSockaddr

---

Return to header index

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.

SpDnsHALCallbacks

---

Return to header index

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.

SpSocketHandle

---

Return to header index

Socket handle type.

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

SpSocketHALCallbacks

---

Return to header index

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.

SpCallbackPerformDNSLookup

---

Return to header index

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.

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.

SpCallbackSocketCreate

---

Return to header index

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

Notes:

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

SpCallbackSocketSetOption

---

Return to header index

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

Notes:

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

SpCallbackSocketClose

---

Return to header index

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

Notes:

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

SpCallbackSocketBind

---

Return to header index

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

Notes:

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

SpCallbackSocketListen

---

Return to header index

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.

Notes:

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

SpCallbackSocketConnect

---

Return to header index

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

Notes:

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

SpCallbackSocketAccept

---

Return to header index

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

Notes:

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

SpCallbackSocketRead

---

Return to header index

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

Notes:

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

SpCallbackSocketWrite

---

Return to header index

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

Notes:

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

SpCallbackSocketReadFrom

---

Return to header index

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

Notes:

• The application should not block or call other API functions in the callback. This callback should mirror the behavior of recvfrom() for connected/non-connected sockets.

SpCallbackSocketWriteTo

---

Return to header index

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

Notes:

• The application should not block or call other API functions in the callback. This callback should mirror the behavior of sendto() for connected/non-connected sockets.

SpCallbackSocketError

---

Return to header index

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

Notes:

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

SpCallbackSocketReadable

---

Return to header index

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

Notes:

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

SpCallbackSocketWriteable

---

Return to header index

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

Notes:

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

SpCallbackLocalAddresses

---

Return to header index

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

Notes:

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

SpCallbackSocketAddress

---

Return to header index

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.

Notes:

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

SpCallbackPump

---

Return to header index

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

Notes:

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

SpIPFamily

---

Return to header index

Enum describes the IP family.

SpSocketPool

---

Return to header index

Socket pool IDs.

SpSocketType

---

Return to header index

Enum defines the type of socket supported by eSDK.

SpSocketOptions

---

Return to header index

Enum defines options that can be applied to sockets.

SpRegisterDnsHALCallbacks

---

Return to header index

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

Notes:

• To remove DNS callback at any time call SpRegisterDnsHALCallbacks() with SpDnsHALCallbacks::dns_lookup_callback set to NULL.
• eSDK provides built-in implementation for DNS lookups. For integrations built with glibc = 2.2.3 DNS lookups will be implemented via getaddrinfo_a() and therefore will be done asynchronously. Such integrations have to link libanl (-lanl). Remaining builds will use blocking DNS lookups (e.g. getaddrinfo() for POSIX). Depending on the platform's timeout settings they might cause SpPumpEvents() to block for a long time and result in audio stutters. For affected platforms it's recommended to provide an asynchronous implementation instead.

SpGetDefaultDnsHALCallbacks

---

Return to header index

Get eSDK's default DNS callbacks.

Notes:

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

SpRegisterSocketHALCallbacks

---

Return to header index

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

Notes:

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

SpGetDefaultSocketHALCallbacks

---

Return to header index

Get eSDK's default socket callbacks.

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

Log levels.

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.

SP_FILE_NAME

---

Return to header index

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

SP_LOG_DEFAULT_LEVEL

---

Return to header index

Default trace log level.

SP_LOG_DEFINE_TRACE_OBJ

---

Return to header index

Macro to define a trace object.

obj Name of the trace object

SP_LOG_DECLARE_TRACE_OBJ

---

Return to header index

Macro to declare a previously defined trace object.

obj Name of the trace object

SP_LOG_REGISTER_TRACE_OBJ

---

Return to header index

Macro to register a previously defined trace object.

obj Name of the trace object

SP_LOG

---

Return to header index

Macro that outputs a trace message.

obj Trace object name lvl Trace level for the message file Source file name func Calling function name line Line number in the source file

SpLogFatal

---

Return to header index

Emit trace message with SP_LOG_LEVEL_FATAL.

SpLogError

---

Return to header index

Emit trace message with SP_LOG_LEVEL_ERROR.

SpLogWarning

---

Return to header index

Emit trace message with SP_LOG_LEVEL_WARNING.

SpLogInfo

---

Return to header index

Emit trace message with SP_LOG_LEVEL_INFO.

SpLogDebug

---

Return to header index

Emit trace message with SP_LOG_LEVEL_DEBUG.

SpLogTrace

---

Return to header index

Emit trace message with SP_LOG_LEVEL_TRACE.

SpLogTraceObject

---

Return to header index

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.

SpLogLevel

---

Return to header index

Log levels.

These are the log levels assigned to log messages emitted by the eSDK.

See also

• SpLogSetLevel

SpLogRegisterTraceObject

---

Return to header index

Register a defined trace object with eSDK.

SpLog

---

Return to header index

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.

SpLogSetLevel

---

Return to header index

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

Example:

SpLogGetLevels

---

Return to header index

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

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

Media formats.

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.

SpStreamInfo

---

Return to header index

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.

SpStreamCallbacks

---

Return to header index

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.

SpCallbackStreamStart

---

Return to header index

Callback to provide track details to the application.

To register this callback, use the function SpRegisterStreamCallbacks().

See also

• SpStreamInfo

SpCallbackStreamData

---

Return to header index

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.

SpCallbackStreamEnd

---

Return to header index

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

SpCallbackStreamGetPosition

---

Return to header index

Callback to get the playback position in milliseconds.

To register this callback, use the function SpRegisterStreamCallbacks().

SpCallbackStreamSeekToPosition

---

Return to header index

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

SpCallbackStreamFlush

---

Return to header index

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.

SpMediaFormat

---

Return to header index

Media formats.

SpRegisterStreamCallbacks

---

Return to header index

Register callbacks related to the delivery API.

SpNotifySeekComplete

---

Return to header index

API to notify eSDK of the completion of seek operation.

SpNotifyTrackLength

---

Return to header index

API to notify eSDK of the track length in milliseconds.

SpNotifyTrackError

---

Return to header index

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

SpNotifyStreamPlaybackStarted

---

Return to header index

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

This is used by the eSDK to measure playback latency.

SpNotifyStreamPlaybackContinued

---

Return to header index

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.

SpNotifyStreamPlaybackFinishedNaturally

---

Return to header index

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

SpSetDownloadPosition

---

Return to header index

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

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	Internal macro.
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.

SP_NO_INDEX

---

Return to header index

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

See also

• SpPlayUri

SP_MAX_UUID_LENGTH

---

Return to header index

Maximum length of a UUID.

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

SP_MAX_SOURCE_TYPE_LENGTH

---

Return to header index

Maximum length of the type of playback source.

See also

• SpSourceInfo
• SpPlayUri

SP_MAX_SOURCE_URI_LENGTH

---

Return to header index

Maximum length of the source URIs.

See also

• SpSourceInfo
• SpPlayUri

SP_MAX_REFERRER_LENGTH

---

Return to header index

Maximum length of the referrer.

See also

• SpSourceInfo
• SpPlayUri

SP_PLAYOPTIONS_INITIALIZER_LOGGING_PARAMS

---

Return to header index

Internal macro.

See also

• SP_PLAYOPTIONS_INITIALIZER

SP_PLAYOPTIONS_INITIALIZER

---

Return to header index

Macro for initialization of struct SpPlayOptions. Use it instead of memset() due to the fact that some fields are optional and encoded as non-zero values.

SpSourceInfo

---

Return to header index

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.

SpPlayOptions

---

Return to header index

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.

SpPlayUri

---

Return to header index

Start local playback of the given Spotify URI.

This call starts playback of a Spotify URI, such as a playlist, album, artist, or track. Valid Spotify URIs can be obtained via the Spotify Web API. Using this call will 'pull' playback from any other Spotify Connect client active on the same account. Note that there may be a lag between the introduction of new URI types and support for playing them with this call.

See also

• SpSourceInfo
• SP_NO_INDEX

SpPlayUriWithOptions

---

Return to header index

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

SpPlayContextUri

---

Return to header index

Start local playback of the given Spotify URI with an optional track UID.

This call will start playback of any Spotify context URI. In addition, it allows the client to provide a UID to start the playback from a given track in the context. The main difference between UIDs and the field SpSourceInfo::expected_track_uri is that while one track URI can occur more than once in the context, UIDs are unique for each track in it. Valid Spotify URIs can be obtained via the Spotify Web API. Track UIDs are currently available when resolving contexts from a small subset of services. Using this call will 'pull' playback from any other Spotify Connect client active on the same account.

See also

• SpPlayUriWithOptions
• SpPlayOptions::from_uid

SpQueueUri

---

Return to header index

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.

See also

• kSpPlaybackNotifyQueuedTrackAccepted
• kSpErrorInvalidRequest

SpPlaybackBecomeActiveDevice

---

Return to header index

Become active without starting to play.

alias_index The index of the device alias that should become active. If aliases aren't used, pass SP_NO_ALIAS_SELECTED. This call makes the device active, without starting to play anything, if playback is paused or no device is active. The device is active after the kSpPlaybackNotifyBecameActive event is received. If another Connect-enabled device was active and playing, it will be interrupted. If the currently active device is playing, this call behaves like SpPlaybackPlay(). If device aliases are used, this function will switch the selected alias. If the selected alias was changed during playback, the playback will continue uninterrupted with the new alias.

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.

SpDiskStorageCallbacks

---

Return to header index

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.

SpCallbackStorageAlloc

---

Return to header index

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

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.

SpCallbackStorageWrite

---

Return to header index

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

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.

SpCallbackStorageRead

---

Return to header index

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

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.

SpCallbackStorageClose

---

Return to header index

Callback to inform the user that the data handle referenced by storage_key can be closed.

To register this callback, use the function SpRegisterStorageCallbacks().

Notes:

• The application should not block or call other API functions in the callback. This callback would be called for any successful alloc. For any resource open caused by Read/Write API calls.

SpCallbackStorageDelete

---

Return to header index

Callback to inform the user that data referenced by storage_key should be deleted from storage.

To register this callback, use the function SpRegisterStorageCallbacks().

Notes:

• The application should not block or call other API functions in the callback.
• If the deletion operation is expected to take some time the application shall return kSpAPITryAgain for the duration of the operation and kSpAPINoError once it has been completed. It is important to not block execution of eSDK for prolonged periods (ideally less than 10ms). This callback can be called for literally any storage_key.

SpCallbackThrottleRequest

---

Return to header index

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

Notes:

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

SpRegisterStorageCallbacks

---

Return to header index

Register storage callbacks.

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.

SpTLSCallbacks

---

Return to header index

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.

SpCallbackTLSInit

---

Return to header index

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

Notes:

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

SpCallbackTLSDeinit

---

Return to header index

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

Notes:

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

SpCallbackTLSCreate

---

Return to header index

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.

Notes:

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

SpCallbackTLSHandshake

---

Return to header index

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.

Notes:

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

SpCallbackTLSRead

---

Return to header index

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

Notes:

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

SpCallbackTLSWrite

---

Return to header index

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

Notes:

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

SpCallbackTLSClose

---

Return to header index

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

Notes:

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

SpCallbackTLSGetError

---

Return to header index

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.

Notes:

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

SpRegisterTLSCallbacks

---

Return to header index

Register TLS-related callbacks.

Notes:

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

SpTLSAddCARootCert

---

Return to header index

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)

Notes:

• If the buffer is a PEM-format certificate, it must be NULL-terminated.
• If the buffer is a PEM-format certificate, this length must include the NULL termination.
• Calls to this function have to be performed before SpInit() is called or after SpFree().

SpTLSFreeCARootCerts

---

Return to header index

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

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.

SpTokenCallbacks

---

Return to header index

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.

SpCallbackConnectionReceiveAccessToken

---

Return to header index

Callback to deliver the access token requested by SpConnectionRequestAccessToken().

Notes:

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

SpCallbackConnectionReceiveAuthCode

---

Return to header index

Callback to deliver the access token requested by SpConnectionRequestAuthCode().

Notes:

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

SpRegisterTokenCallbacks

---

Return to header index

Register token callbacks.

SpConnectionRequestAccessToken

---

Return to header index

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/

SpConnectionRequestAuthCode

---

Return to header index

Request an authorization code for the logged in user.

Notes:

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