API Reference eSDK 3.209.360

• Main
• Content
• Hal
• Log
• Media
• Play
• Storage
• Tls
• Token

Main

---

Back to top of page

• macros and constants
• data structures
• enumerations

macros and constants

---

main -> macros and constants

SP_MAX_METADATA_KEY_LENGTH	32
SP_MAX_METADATA_VALUE_LENGTH	64

data structures

---

main -> data structures

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

enumerations

---

main -> enumerations

SpDrmFormat

DRM formats.

SP_MAX_METADATA_KEY_LENGTH

---

main -> macros and constants -> SP_MAX_METADATA_KEY_LENGTH

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

See also

• SpAdMetadata

SP_MAX_METADATA_VALUE_LENGTH

---

main -> macros and constants -> SP_MAX_METADATA_VALUE_LENGTH

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

See also

• SpAdMetadata

SpPlayerModeDisallowReasons

---

main -> data structures -> SpPlayerModeDisallowReasons

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

---

main -> data structures -> SpPlayerModeRestrictions

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

---

main -> data structures -> SpPlaybackRestrictions

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

---

main -> data structures -> SpFormat

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

---

main -> data structures -> SpMetadata

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

---

main -> data structures -> SpAdMetadata

Key value pair for Ad-related metadata.

char	key	Key.
char	value	Value.

SpZeroConfDeviceAlias

---

main -> data structures -> SpZeroConfDeviceAlias

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

---

main -> data structures -> SpZeroConfVars

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

---

main -> data structures -> SpSampleFormat

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

---

main -> data structures -> SpPlaybackCallbacks

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

---

main -> data structures -> SpDebugCallbacks

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

---

main -> data structures -> SpConnectionCallbacks

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

---

main -> data structures -> SpDeviceAlias

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

---

main -> data structures -> SpConfig

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

---

main -> data structures -> SpDeviceAliasCallbacks

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.

SpDrmFormat

---

main -> enumerations -> SpDrmFormat

DRM formats.

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

Content

---

Back to top of page

• data structures

data structures

---

content -> data structures

SpContentCallbacks

Callbacks to be registered with SpRegisterContentCallbacks()

SpContentCallbacks

---

content -> data structures -> SpContentCallbacks

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.

Hal

---

Back to top of page

• data structures

data structures

---

hal -> data structures

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

SpSockaddr

---

hal -> data structures -> SpSockaddr

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

---

hal -> data structures -> SpDnsHALCallbacks

Callbacks to be registered with SpRegisterDnsHALCallbacks()

Any of the pointers may be NULL. To remove DNS callback at any time call SpRegisterDnsHALCallbacks() with SpDnsHALCallbacks::dns_lookup_callback set to NULL.

Notes:

• See the documentation of the callback typedefs for information about the individual callbacks.

SpCallbackPerformDNSLookup

dns_lookup_callback

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

SpSocketHandle

---

hal -> data structures -> SpSocketHandle

Socket handle type.

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

SpSocketHALCallbacks

---

hal -> data structures -> SpSocketHALCallbacks

Callbacks to be registered with SpRegisterSocketHALCallbacks()

Any of the pointers may be NULL. See the documentation of the callback typedefs for information about the individual callbacks.

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.

Log

---

Back to top of page

• macros and constants
• data structures

macros and constants

---

log -> macros and constants

SP_FILE_NAME

FILE

data structures

---

log -> data structures

SpLogTraceObject

Trace object.

SP_FILE_NAME

---

log -> macros and constants -> SP_FILE_NAME

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

SpLogTraceObject

---

log -> data structures -> SpLogTraceObject

Trace object.

The trace object is an abstraction of a specific trace message category and an associated log level. The level can be changed freely for individual trace objects.

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

Media

---

Back to top of page

• data structures

data structures

---

media -> data structures

SpStreamInfo	Stream Parameters.
SpStreamCallbacks	Callbacks to be registered with SpRegisterStreamCallbacks()

SpStreamInfo

---

media -> data structures -> SpStreamInfo

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

---

media -> data structures -> SpStreamCallbacks

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.

Play

---

Back to top of page

• data structures

data structures

---

play -> data structures

SpSourceInfo	Metadata for identifying where a playback request originated from.
SpPlayOptions	PlayOptions passed to SpPlayUriWithOptions(). Use SP_PLAYOPTIONS_INITIALIZER for initializing with default values.

SpSourceInfo

---

play -> data structures -> SpSourceInfo

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

---

play -> data structures -> SpPlayOptions

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.

Storage

---

Back to top of page

• data structures

data structures

---

storage -> data structures

SpDiskStorageCallbacks

Callbacks to be registered with SpRegisterStorageCallbacks()

SpDiskStorageCallbacks

---

storage -> data structures -> SpDiskStorageCallbacks

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.

Tls

---

Back to top of page

• data structures

data structures

---

tls -> data structures

SpTLSCallbacks

Callbacks to be registered with SpRegisterTLSCallbacks()

SpTLSCallbacks

---

tls -> data structures -> SpTLSCallbacks

Callbacks to be registered with SpRegisterTLSCallbacks()

None of the pointers may be NULL. See the documentation of the callback typedefs for information about the individual callbacks.

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.

Token

---

Back to top of page

• data structures

data structures

---

token -> data structures

SpTokenCallbacks

Callbacks to be registered with SpRegisterTokenCallbacks()

SpTokenCallbacks

---

token -> data structures -> SpTokenCallbacks

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.