Skip to content

API Reference eSDK 3.183.28

Main



_10
#include "spotify_embedded.h"

Macros and Constants


Return to header index
SP_API_VERSION 70
SP_RECOMMENDED_MEMORY_BLOCK_SIZE 1024 * 1024
SP_MAX_BRAND_NAME_LENGTH 32
SP_MAX_MODEL_NAME_LENGTH 30
SP_MAX_CLIENT_ID_LENGTH 32
SP_MAX_OS_VERSION_LENGTH 64
SP_MAX_DISPLAY_NAME_LENGTH 64
SP_MAX_UNIQUE_ID_LENGTH 64
SP_MAX_USERNAME_LENGTH 64
SP_MAX_DEVICE_ALIASES 8
SP_NO_ALIAS_SELECTED -1
SP_MAX_METADATA_NAME_LENGTH 255
SP_MAX_METADATA_URI_LENGTH 127
SP_MAX_TRACK_UID_LENGTH 64
SP_MAX_METADATA_IMAGE_URL_LENGTH 255
SP_PLAYER_COOKIE_LENGTH 32
SP_MAX_PLAYBACK_ID_LENGTH 32
SP_MAX_PUBLIC_KEY_LENGTH 149
SP_MAX_DEVICE_ID_LENGTH 64
SP_MAX_DEVICE_TYPE_LENGTH 15
SP_MAX_VERSION_LENGTH 30
SP_MAX_GROUP_STATUS_LENGTH 15
SP_MAX_TOKEN_TYPE_LENGTH 30
SP_MAX_SCOPE_LENGTH 64
SP_MAX_CLIENT_KEY_LENGTH 511
SP_MAX_ZEROCONF_BLOB_LENGTH 2047
SP_MAX_LOGIN_ID_LENGTH 64
SP_MAX_AVAILABILITY_LENGTH 15
SP_MAX_PARTNER_NAME_LENGTH 48
SP_MAX_FILENAME_LENGTH 63
SP_PRESET_BUFFER_SIZE 2064
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

Data Structures


Return to header index
SpPlaybackRestrictions Playback restrictions.
SpMetadata Track metadata.
SpFormat Mapping of which media formats are supported in which DRM.
SpZeroConfDeviceAlias ZeroConf DeviceAlias.
SpZeroConfVars ZeroConf variables.
SpSampleFormat Sample format of the audio data sent in SpCallbackPlaybackAudioData
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.
SpCallbackSavePreset Callback for receiving preset tokens.
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 selected device alias from the backend.
SpCallbackDeviceAliasesUpdateDone Callback for knowing when the device alias list has been updated after call to SpSetDeviceAliases

Enumerations


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

Functions


Return to header index
SpInit Initialize the library.
SpFree Shut down the library.
SpGetLibraryVersion Retrieve a version string for the library.
SpConnectionSetConnectivity Set the type of network connection of the device.
SpConnectionGetConnectivity Get the connectivity that was set with SpConnectionSetConnectivity
SpConnectionLoginBlob Log in a user to Spotify using a credentials blob.
SpConnectionLoginPassword Log in a user to Spotify using a password.
SpConnectionLoginOauthToken Log in a user to Spotify using a Spotify OAuth token.
SpConnectionLogout Log the user out of Spotify
SpConnectionIsLoggedIn Is the user logged in to Spotify
SpConnectionGetAckId Get last Ack ID.
SpGetCanonicalUsername Get the canonical username of the logged in user.
SpSetDisplayName Set the display name for the application/device.
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 the current track an Ad or not.
SpPlaybackIsShuffled Is "shuffle" mode enabled.
SpPlaybackIsRepeated Is "repeat" mode enabled.
SpPlaybackGetRepeatMode What "repeat" mode is on.
SpPlaybackIsActiveDevice Is the device the active playback device.
SpPlaybackEnableShuffle Enable or disable "shuffle" mode.
SpPlaybackEnableRepeat Enable or disable "repeat" mode.
SpPlaybackCycleRepeatMode Cycle through the available repeat modes.
SpPlaybackSetBitrate Change the bitrate at which compressed audio data is delivered.
SpPlaybackSetAvailableToPlay Allow or disallow the device to start playback.
SpPlaybackIsAvailableToPlay Is the device available for playback.
SpPlaybackSetDeviceInactive Set the device inactive.
SpPlaybackIsDeviceControllable Is the device controllable.
SpPlaybackSetDeviceControllable Allow or disallow the device to be controllable.
SpPlaybackIncreaseUnderrunCount Increase the underrun counter of the current track.
SpPlaybackSetBandwidthLimit Set a limit on the download speed.
SpPlaybackSetRedeliveryMode Activates redelivery of audio data on play or resume playback.
SpPlaybackIsRedeliveryModeActivated Gets the status of redelivery mode.
SpPresetSubscribe Subscribe to receive "preset" tokens for use with SpPlayPreset
SpPresetUnsubscribe Unsubscribe from a previously subscribed preset.
SpPlayPreset Recall and play a saved or default preset.
SpZeroConfGetVars Get variables for ZeroConf, mainly the "getInfo" request.
SpZeroConfAnnouncePause Temporarily pause ZeroConf mDNS annoucements.
SpZeroConfAnnounceResume Resume ZeroConf mDNS annoucement after calling SpZeroConfAnnouncePause
SpConnectionLoginZeroConf Log in a user to Spotify using a ZeroConf credentials blob.
SpGetBrandName
SpGetModelName
SpRegisterDeviceAliasCallbacks Register callbacks related to device aliases.
SpSetDeviceAliases Update the device alias definitions.
SpRestrictDrmMediaFormats
SpRestoreDrmMediaFormats

Macros and Constants


SP_API_VERSION

Return to Main macros and constants

_10
#define SP_API_VERSION 70

The version of the API defined in this header file.

See also
Return to Main macros and constants

_10
#define SP_RECOMMENDED_MEMORY_BLOCK_SIZE 1024 * 1024

Minimum recommended size of the buffer SpConfig::memory_block

SP_MAX_BRAND_NAME_LENGTH

Return to Main macros and constants

_10
#define SP_MAX_BRAND_NAME_LENGTH 32

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

See also

SP_MAX_MODEL_NAME_LENGTH

Return to Main macros and constants

_10
#define SP_MAX_MODEL_NAME_LENGTH 30

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

See also

SP_MAX_CLIENT_ID_LENGTH

Return to Main macros and constants

_10
#define SP_MAX_CLIENT_ID_LENGTH 32

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

See also

SP_MAX_OS_VERSION_LENGTH

Return to Main macros and constants

_10
#define SP_MAX_OS_VERSION_LENGTH 64

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

See also

SP_MAX_DISPLAY_NAME_LENGTH

Return to Main macros and constants

_10
#define SP_MAX_DISPLAY_NAME_LENGTH 64

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

See also

SP_MAX_UNIQUE_ID_LENGTH

Return to Main macros and constants

_10
#define SP_MAX_UNIQUE_ID_LENGTH 64

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

See also

SP_MAX_USERNAME_LENGTH

Return to Main macros and constants

_10
#define SP_MAX_USERNAME_LENGTH 64

Maximum length of usernames (not counting terminating NULL)

See also

SP_MAX_DEVICE_ALIASES

Return to Main macros and constants

_10
#define SP_MAX_DEVICE_ALIASES 8

Maximum number of device aliases that can be configured.

See also

SP_NO_ALIAS_SELECTED

Return to Main macros and constants

_10
#define SP_NO_ALIAS_SELECTED -1

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

See also

SP_MAX_METADATA_NAME_LENGTH

Return to Main macros and constants

_10
#define SP_MAX_METADATA_NAME_LENGTH 255

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

See also Notes:

SP_MAX_METADATA_URI_LENGTH

Return to Main macros and constants

_10
#define SP_MAX_METADATA_URI_LENGTH 127

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

See also

SP_MAX_TRACK_UID_LENGTH

Return to Main macros and constants

_10
#define SP_MAX_TRACK_UID_LENGTH 64

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

See also

SP_MAX_METADATA_IMAGE_URL_LENGTH

Return to Main macros and constants

_10
#define SP_MAX_METADATA_IMAGE_URL_LENGTH 255

Maximum length of URLs (not counting terminating NULL)

See also
Return to Main macros and constants

_10
#define SP_PLAYER_COOKIE_LENGTH 32

Length of player cookie (not including terminating null)

See also

SP_MAX_PLAYBACK_ID_LENGTH

Return to Main macros and constants

_10
#define SP_MAX_PLAYBACK_ID_LENGTH 32

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

See also

SP_MAX_PUBLIC_KEY_LENGTH

Return to Main macros and constants

_10
#define SP_MAX_PUBLIC_KEY_LENGTH 149

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

See also

SP_MAX_DEVICE_ID_LENGTH

Return to Main macros and constants

_10
#define SP_MAX_DEVICE_ID_LENGTH 64

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

See also

SP_MAX_DEVICE_TYPE_LENGTH

Return to Main macros and constants

_10
#define SP_MAX_DEVICE_TYPE_LENGTH 15

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

See also

SP_MAX_VERSION_LENGTH

Return to Main macros and constants

_10
#define SP_MAX_VERSION_LENGTH 30

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

See also

SP_MAX_GROUP_STATUS_LENGTH

Return to Main macros and constants

_10
#define SP_MAX_GROUP_STATUS_LENGTH 15

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

See also

SP_MAX_TOKEN_TYPE_LENGTH

Return to Main macros and constants

_10
#define SP_MAX_TOKEN_TYPE_LENGTH 30

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

See also

SP_MAX_SCOPE_LENGTH

Return to Main macros and constants

_10
#define SP_MAX_SCOPE_LENGTH 64

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

See also

SP_MAX_CLIENT_KEY_LENGTH

Return to Main macros and constants

_10
#define SP_MAX_CLIENT_KEY_LENGTH 511

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

See also

SP_MAX_ZEROCONF_BLOB_LENGTH

Return to Main macros and constants

_10
#define SP_MAX_ZEROCONF_BLOB_LENGTH 2047

Maximum length of the zeroconf blob. (not counting terminating NULL)

See also

SP_MAX_LOGIN_ID_LENGTH

Return to Main macros and constants

_10
#define SP_MAX_LOGIN_ID_LENGTH 64

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

See also

SP_MAX_AVAILABILITY_LENGTH

Return to Main macros and constants

_10
#define SP_MAX_AVAILABILITY_LENGTH 15

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

See also

SP_MAX_PARTNER_NAME_LENGTH

Return to Main macros and constants

_10
#define SP_MAX_PARTNER_NAME_LENGTH 48

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

SP_MAX_FILENAME_LENGTH

Return to Main macros and constants

_10
#define SP_MAX_FILENAME_LENGTH 63

Maximum length of filename fields (not counting terminating NULL)

SP_PRESET_BUFFER_SIZE

Return to Main macros and constants

_10
#define SP_PRESET_BUFFER_SIZE 2064

Maximum length of the preset blob returned by SpGetPreset

SP_ZEROCONF_DISABLED

Return to Main macros and constants

_10
#define SP_ZEROCONF_DISABLED 0

Value for SpConfig::zeroconf_serve when disabling builtin ZeroConf stack. Complete ZeroConf stack must be run externally.

See also

SP_ZEROCONF_SERVE

Return to Main macros and constants

_10
#define SP_ZEROCONF_SERVE 1

Value for SpConfig::zeroconf_serve when activating complete builtin ZeroConf stack.

See also

SP_ZEROCONF_SERVE_HTTP_ONLY

Return to Main macros and constants

_10
#define SP_ZEROCONF_SERVE_HTTP_ONLY 2

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

See also

SP_ZEROCONF_SERVE_MDNS_ONLY

Return to Main macros and constants

_10
#define SP_ZEROCONF_SERVE_MDNS_ONLY 3

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

See also

SP_SCOPE_STREAMING

Return to Main macros and constants

_10
#define SP_SCOPE_STREAMING "streaming"

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

SP_DEVICE_ALIAS_ATTRIBUTE_GROUP

Return to Main macros and constants

_10
#define SP_DEVICE_ALIAS_ATTRIBUTE_GROUP 1

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

Notes:

SP_GLOBAL_ATTRIBUTE_VOICE

Return to Main macros and constants

_10
#define SP_GLOBAL_ATTRIBUTE_VOICE 2

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

SP_MAX_SUPPORTED_FORMATS

Return to Main macros and constants

_10
#define SP_MAX_SUPPORTED_FORMATS 8

See also

SP_PLAYBACK_RESTRICTION_ALREADY_PAUSED

Return to Main macros and constants

_10
#define SP_PLAYBACK_RESTRICTION_ALREADY_PAUSED 1

The track is already paused.

SP_PLAYBACK_RESTRICTION_NOT_PAUSED

Return to Main macros and constants

_10
#define SP_PLAYBACK_RESTRICTION_NOT_PAUSED 2

The track is already playing.

SP_PLAYBACK_RESTRICTION_LICENSE_DISALLOW

Return to Main macros and constants

_10
#define SP_PLAYBACK_RESTRICTION_LICENSE_DISALLOW 4

Licensing rules disallow this action.

SP_PLAYBACK_RESTRICTION_AD_DISALLOW

Return to Main macros and constants

_10
#define SP_PLAYBACK_RESTRICTION_AD_DISALLOW 8

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

SP_PLAYBACK_RESTRICTION_NO_PREV_TRACK

Return to Main macros and constants

_10
#define SP_PLAYBACK_RESTRICTION_NO_PREV_TRACK 16

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

SP_PLAYBACK_RESTRICTION_NO_NEXT_TRACK

Return to Main macros and constants

_10
#define SP_PLAYBACK_RESTRICTION_NO_NEXT_TRACK 32

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

SP_PLAYBACK_RESTRICTION_UNKNOWN

Return to Main macros and constants

_10
#define SP_PLAYBACK_RESTRICTION_UNKNOWN 64

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

SP_PLAYBACK_RESTRICTION_ENDLESS_CONTEXT

Return to Main macros and constants

_10
#define SP_PLAYBACK_RESTRICTION_ENDLESS_CONTEXT 128

The action is restricted for context level reasons.

Data Structures


SpPlaybackRestrictions

Return to Main data structures

Playback restrictions.


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

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

SpMetadata

Return to Main data structures

Track metadata.

See also

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

char playback_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.

SpFormat

Return to Main data structures

Mapping of which media formats are supported in which DRM.

See also

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

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

SpZeroConfDeviceAlias

Return to Main data structures

ZeroConf DeviceAlias.

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

See also

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

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

SpZeroConfVars

Return to Main data structures

ZeroConf variables.

This structure contains the fields that the application needs for ZeroConf, mainly what to send in the response to the "getInfo" request. See the ZeroConf manual for more information.

See also

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

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

SpSampleFormat

Return to Main data structures

Sample format of the audio data sent in SpCallbackPlaybackAudioData

Notes:
  • The contents of this should be ignored when SpCallbackPlaybackAudioData is invoked with sample_count = 0.

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

int channels Number of channels (1 = mono, 2 = stereo)
int sample_rate Sample rate in Hz (such as 22050, 44100 or 48000)
int replay_gain_mdb If audio playback is normalized, this value is the suggested replay gain adjustment in milli-dBs (1000 = +1 dB, -1000 = -1 dB, 0 = no change)

SpPlaybackCallbacks

Return to Main data structures

Callbacks to be registered with SpRegisterPlaybackCallbacks

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


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

SpCallbackPlaybackNotify on_notify Notification callback.
SpCallbackPlaybackSeek on_seek Seek position callback.
SpCallbackPlaybackApplyVolume on_apply_volume Apply volume callback.
SpCallbackSavePreset on_save_preset Preset token callback.

SpDebugCallbacks

Return to Main data structures

Callbacks to be registered with SpRegisterDebugCallbacks

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


_10
struct SpDebugCallbacks {
_10
SpCallbackDebugMessage on_message;
_10
};

SpCallbackDebugMessage on_message Debug message callback.

SpConnectionCallbacks

Return to Main data structures

Callbacks to be registered with SpRegisterConnectionCallbacks

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


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

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

SpDeviceAlias

Return to Main data structures

Device alias definition.

This struct is used to define (optional) device aliases. It's a part of the SpConfig struct which will be passed to SpInit to initialize the eSDK.


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

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 Main data structures

Configuration.

See also

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

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 * 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

SpDeviceAliasCallbacks

Return to Main data structures

Callbacks to be registered with SpRegisterDeviceAliasCallbacks

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


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

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

Typedefs


SpCallbackError()

Return to Main Typedefs

_10
typedef void(* SpCallbackError)(SpError error, void *context)

Callback for reporting errors to the application.

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

Parameters

[in]SpError errorError code
[in]void * contextContext pointer that was passed when registering the callback
Notes:
  • The application should not block or call API functions that are not allowed in the callback.

SpCallbackPlaybackNotify()

Return to Main Typedefs

_10
typedef void(* SpCallbackPlaybackNotify)(enum SpPlaybackNotification event, void *context)

Callback for notifying the application about playback-related events.

To register this callback, use the function SpRegisterPlaybackCallbacks

Parameters

[in]enum SpPlaybackNotification eventType of event
[in]void * contextContext pointer that was passed when registering the callback
Notes:
  • The application should not block or call API functions that are not allowed in the callback.

SpCallbackPlaybackSeek()

Return to Main Typedefs

_10
typedef void(* SpCallbackPlaybackSeek)(uint32_t position_ms, void *context)

Callback to notify the application of a change in the playback position.

To register this callback, use the function SpRegisterPlaybackCallbacks This callback is invoked when SpPlaybackSeek is invoked or when the user seeks to a position within the track using Spotify Connect.

Parameters

[in]uint32_t position_msNew position within the track in milliseconds
[in]void * contextContext pointer that was passed when registering the callback
Notes:
  • The application should not block or call API functions that are not allowed in the callback.

SpCallbackPlaybackApplyVolume()

Return to Main Typedefs

_10
typedef void(* SpCallbackPlaybackApplyVolume)(uint16_t volume, uint8_t remote, void *context)

Callback to notify the application of a volume change using Spotify Connect.

To register this callback, use the function SpRegisterPlaybackCallbacks This callback is invoked in two cases: When the user changes the playback volume using Spotify Connect. When the application invoked SpPlaybackUpdateVolume In both cases, the application is responsible for applying the new volume to its audio output. The application should never invoke SpPlaybackUpdateVolume from this callback, as this might result in an endless loop.

Parameters

[in]uint16_t volumeVolume in the range 0 (silence) to 65535 (max volume)
[in]uint8_t remoteSet to 1 if the volume was changed using Spotify Connect, 0 otherwise
[in]void * contextContext pointer that was passed when registering the callback
Notes:
  • The application should not block or call API functions that are not allowed in the callback.

SpCallbackSavePreset()

Return to Main Typedefs

_10
typedef uint8_t(* SpCallbackSavePreset)(int preset_id, uint32_t playback_position, const uint8_t *buffer, size_t buff_size, SpError error, void *context)

Callback for receiving preset tokens.

To register this callback, use the function SpRegisterPlaybackCallbacks After subscribing to receive preset tokens for the currently playing context, this callback will be called periodically with an updated token that can be used to restore playback at a later time with SpPlayPreset This token must be saved to persistent storage, and must replace any previous token for the same preset. The rate at which this callback is called may vary based on the type of context playing. It will typically be called once per playing track, but may be called more or less often to satisfy the requirements of the expected Spotify user experience.

Parameters

[in]int preset_idThe value specified to SpPresetSubscribe
[in]uint32_t playback_positionCurrent playback time in milliseconds. This must be saved persistently with the preset token, and specified when calling SpPlayPreset
[in]const uint8_t * bufferThe buffer provided to SpPresetSubscribe filled with the binary preset token to save. This may be NULL if an error has occurred.
[in]size_t buff_sizeThe number of binary bytes in buffer to save.
[in]SpError errorAn error code if a problem occurred, or kSpErrorOk
[in]void * contextThe context provided when the callback was registered.
See also Notes:
  • The application should not block or call API functions that are not allowed in the callback.

SpCallbackConnectionNotify()

Return to Main Typedefs

_10
typedef void(* SpCallbackConnectionNotify)(enum SpConnectionNotification event, void *context)

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

To register this callback, use the function SpRegisterConnectionCallbacks

Parameters

[in]enum SpConnectionNotification eventType of event
[in]void * contextContext pointer that was passed when registering the callback
Notes:
  • The application should not block or call API functions that are not allowed in the callback.

SpCallbackConnectionNewCredentials()

Return to Main Typedefs

_10
typedef void(* SpCallbackConnectionNewCredentials)(const char *credentials_blob, const char *username, void *context)

Callback for passing a login blob to the application.

To register this callback, use the function SpRegisterConnectionCallbacks The application may save the credentials_blob for subsequent logins using the function SpConnectionLoginBlob The application should also discard any credentials blobs for this user that it received previously, either through this callback or through ZeroConf (see the ZeroConf manual). Note: If credentials_blob is an empty string, the application MUST delete any existing saved credentials for the account, and must not attempt to login again with the empty credentials. This happens when a permanent logout is requested.

Parameters

[in]const char * credentials_blobCredentials to be passed to SpConnectionLoginBlob
[in]const char * usernameuser name to be passed to SpConnectionLoginBlob
[in]void * contextContext pointer that was passed when registering the callback
See also Notes:
  • The application should not block or call API functions that are not allowed in the callback.

SpCallbackConnectionMessage()

Return to Main Typedefs

_10
typedef void(* SpCallbackConnectionMessage)(const char *message, void *context)

Callback for sending a message to the user.

To register this callback, use the function SpRegisterConnectionCallbacks This callback is invoked when Spotify wants to display a message to the user. The message is meant to be displayed to the user as is and should not be interpreted by the application (the format of the messages may change without notice). If the application does not have a graphical user interface, it can safely ignore this callback.

Parameters

[in]const char * messageMessage to be displayed to the user.
[in]void * contextContext pointer that was passed when registering the callback
Notes:
  • The application should not block or call API functions that are not allowed in the callback.

SpCallbackDebugMessage()

Return to Main Typedefs

_10
typedef void(* SpCallbackDebugMessage)(const char *debug_message, void *context)

Callback for sending debug messages/trace logs.

To register this callback, use the function SpRegisterDebugCallbacks In special builds of the library, this callback receives debug messages that the application may write to its logs. The application should not interpret the messages (the format of the messages may change without notice).

Parameters

[in]const char * debug_messageMessage to be logged
[in]void * contextContext pointer that was passed when registering the callback
Notes:
  • The application should not block or call API functions that are not allowed in the callback.

SpCallbackSelectedDeviceAliasChanged()

Return to Main Typedefs

_10
typedef void(* SpCallbackSelectedDeviceAliasChanged)(uint32_t alias_index, void *context)

Callback for receiving selected device alias from the backend.

To register this callback, use the function SpRegisterDeviceAliasCallbacks This callback is invoked whenever the selected device alias is updated. This can happen when, for example, the user selects an alias from Spotify Connect device picker.

Parameters

[in]uint32_t alias_indexIndex of the device alias which was selected
[in]void * contextContext pointer that was passed when registering the callback
Notes:
  • The application should not block or call API functions that are not allowed in the callback.

SpCallbackDeviceAliasesUpdateDone()

Return to Main Typedefs

_10
typedef void(* SpCallbackDeviceAliasesUpdateDone)(SpError error_code, void *context)

Callback for knowing when the device alias list has been updated after call to SpSetDeviceAliases

To register this callback, use the function SpRegisterDeviceAliasCallbacks This callback is invoked when the operation started by call to SpSetDeviceAliases has finished.

Parameters

[in]SpError error_codeif the update was successful, the value is kSpErrorOk
[in]void * contextContext pointer that was passed when registering the callback
Notes:
  • The application should not block or call API functions that are not allowed in the callback.

Enumerations


SpError

Return to Main enumerations

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

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

SpAPIReturnCode

Return to Main enumerations

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

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

SpPlaybackBitrate

Return to Main enumerations

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

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

SpPlaybackNotification

Return to Main enumerations

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

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

SpConnectionNotification

Return to Main enumerations

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

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

SpDeviceType

Return to Main enumerations

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

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

SpMetadataTrack

Return to Main enumerations

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

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

SpConnectivity

Return to Main enumerations

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

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

SpContent

Return to Main enumerations

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

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

SpMediaType

Return to Main enumerations

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

kSpMediaTypeAudio Audio media type.
kSpMediaTypeVideo Video media type.

SpAudioQuality

Return to Main enumerations

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

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

SpDrmFormat

Return to Main enumerations

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

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

SpReDeliveryMode

Return to Main enumerations

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

kSpRedeliveryModeActivated Redelivery is activated.
kSpRedeliveryModeDeactivated Redelivery is deactivated.

Functions


SpInit()

Return to Main functions

_10
SpError SpInit(struct SpConfig *conf)

Initialize the library.

Parameters

[in]struct SpConfig * confConfiguration parameters

Returns

Returns an error code

SpFree()

Return to Main functions

_10
SpError SpFree(void)

Shut down the library.

If a user is currently logged in, the application should first call SpConnectionLogout and wait for the kSpConnectionNotifyLoggedOut event, otherwise SpFree may take several seconds.

Returns

Returns an error code

SpGetLibraryVersion()

Return to Main functions

_10
const char * SpGetLibraryVersion(void)

Retrieve a version string for the library.

Returns

Version string

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

SpConnectionSetConnectivity()

Return to Main functions

_10
SpError SpConnectionSetConnectivity(enum SpConnectivity connectivity)

Set the type of network connection of the device.

When the application detects that the device has lost network connection, it should call this function with kSpConnectivityNone When network connection is restored, the application should call this function with one of the other values of SpConnectivity The library will then immediately retry to reconnect to Spotify (rather than waiting for the next retry timeout). The library may use the type of network connection to adapt its streaming and buffering strategies. Currently, however, all types of network connection are treated the same.

Parameters

[in]enum SpConnectivity connectivityType of connection

Returns

Returns an error code

SpConnectionGetConnectivity()

Return to Main functions

_10
enum SpConnectivity SpConnectionGetConnectivity(void)

Get the connectivity that was set with SpConnectionSetConnectivity

The library does not detect the type of network connection by itself. It only updates it if the application calls SpConnectionSetConnectivity If SpConnectionSetConnectivity was never called, the connection defaults to kSpConnectivityWired

Returns

Type of connection

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

SpConnectionLoginBlob()

Return to Main functions

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

Log in a user to Spotify using a credentials blob.

Parameters

[in]const char * usernameSpotify username. UTF-8 encoded. Must not be longer than SP_MAX_USERNAME_LENGTH bytes (not UTF-8-encoded characters), not counting the terminating NULL. (For users that log in via Facebook, this is an email address.)
[in]const char * credentials_blobCredentials blob received via ZeroConf or in the callback SpCallbackConnectionNewCredentials Note: if the credentials_blob is an empty string, this function should not be called or it will return kSpErrorFailed

Returns

Returns an error code

See also Notes:
  • The login is performed asynchronously. The return value only indicates whether the library is able to perform the login attempt. The status of the login will be reported via callbacks:
  • The blob can only be used for subsequent logins as long as the value of SpConfig::unique_id does not change. If SpConfig::unique_id has changed since the blob was received, this function returns an error and you will receive a debug message similar to "Parsing ZeroConf blob failed with code -3".

SpConnectionLoginPassword()

Return to Main functions

_10
SpError SpConnectionLoginPassword(const char *username, const char *password)

Log in a user to Spotify using a password.

Returns kSpErrorGeneralLoginError if a connection is not present. For logging in offline please use SpConnectionLoginBlob Applications must not store the password. Instead, they should implement the callback SpCallbackConnectionNewCredentials and store the credentials blob that they receive for subsequent logins using the function SpConnectionLoginBlob

Parameters

[in]const char * usernameSpotify username. UTF-8 encoded. Must not be longer than SP_MAX_USERNAME_LENGTH bytes (not UTF-8-encoded characters), not counting the terminating NULL. (For users that log in via Facebook, this is an email address.)
[in]const char * passwordPassword

Returns

Returns an error code

See also Notes:
  • The login is performed asynchronously. The return value only indicates whether the library is able to perform the login attempt. The status of the login will be reported via callbacks:
  • Spotify Connect-enabled hardware devices must not use this function. Such devices must implement the ZeroConf and use the function SpConnectionLoginBlob instead.

SpConnectionLoginOauthToken()

Return to Main functions

_10
SpError SpConnectionLoginOauthToken(const char *oauth_token)

Log in a user to Spotify using a Spotify OAuth token.

For subsequent logins the SpCallbackConnectionNewCredentials callback should be implemented and the received credentials blob should be stored and used. (Note that the OAuth access token itself expires after a short time. The credentials blob returned by the callback allows you to re-login even after the token has expired.)

Parameters

[in]const char * oauth_tokenSpotify OAuth access token with "streaming" scope. See https://developer.spotify.com/documentation/web-api/concepts/authorization/

Returns

Returns an error code

See also Notes:
  • The login is performed asynchronously. The return value only indicates whether the library is able to perform the login attempt. The status of the login will be reported via callbacks:
  • Spotify Connect-enabled hardware devices that implement the ZeroConf stack must use the function SpConnectionLoginBlob instead.

SpConnectionLogout()

Return to Main functions

_10
SpError SpConnectionLogout(void)

Log the user out of Spotify

Returns

Returns an error code

See also Notes:

SpConnectionIsLoggedIn()

Return to Main functions

_10
uint8_t SpConnectionIsLoggedIn(void)

Is the user logged in to Spotify

Returns

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

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

SpConnectionGetAckId()

Return to Main functions

_10
const char * SpConnectionGetAckId(void)

Get last Ack ID.

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

SpGetCanonicalUsername()

Return to Main functions

_10
const char * SpGetCanonicalUsername(void)

Get the canonical username of the logged in user.

This function returns the canonical username of the logged in user, which is the unique username used for identifying a specific user for things like playlists and the Spotify Web API. This username might differ from the username used to login. A user can login with an e-mail address or non-canonical unicode. This function will return the canonicalized version of the username after a successful login.

Returns

Returns a string containing the username, or NULL if no user is logged in.

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

SpSetDisplayName()

Return to Main functions

_10
SpError SpSetDisplayName(const char *display_name)

Set the display name for the application/device.

This function can be used to change the display name that was passed to SpInit in the field SpConfig::display_name

Parameters

[in]const char * display_nameA UTF-8-encoded display name

Returns

Returns an error code

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

SpSetVolumeSteps()

Return to Main functions

_10
SpError SpSetVolumeSteps(uint32_t steps)

Set the volume steps the device is capable of.

This function will indicate the number of intermediate steps from ´min_volume´ to ´max_volume´ that the device supports. If there's no volume control ability it must be set to zero to inform that no volume control is possible at all. The default number of steps if this function is not called is 16.

Parameters

[in]uint32_t stepsthe number of volume steps the device can support. 0 means no volume steps at all. The max value that is possible to set is 65535.

Returns

Returns an error code

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

SpSetDeviceIsGroup()

Return to Main functions

_10
SpError SpSetDeviceIsGroup(int is_group)

Control if the device represents a group.

A group is a number of devices all playing back the same sound synchronized. Setting this status correctly will allow Spotify clients to display the correct metadata for this device.

Parameters

[in]int is_group0: Indicate that this device is a single stand-alone device. 1: Indicate that this device represents a group.
Notes:
  • If device aliases are used, this function should not be used to set the group status. Instead, SpSetDeviceAliases should be used to update group status individually for each alias.

SpEnableConnect()

Return to Main functions

_10
SpError SpEnableConnect(void)

Enable Connect functionality for this device.

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

SpDisableConnect()

Return to Main functions

_10
SpError SpDisableConnect(void)

Disable Connect functionality for this device.

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

SpGetSelectedDeviceAlias()

Return to Main functions

_10
int SpGetSelectedDeviceAlias(void)

Return the currently selected device alias.

Returns

The currently selected device alias or -1 if no alias selected.

SpPumpEvents()

Return to Main functions

_10
SpError SpPumpEvents(void)

Allow the library to perform asynchronous tasks and process events.

Note: The suggested time interval to call this function is 10ms. This function should not be called from a callback. A typical usage pattern looks like this:

Returns

Returns an error code

SpRegisterConnectionCallbacks()

Return to Main functions

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

Register callbacks related to the connection to Spotify

Parameters

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

Returns

Returns an error code

SpRegisterDebugCallbacks()

Return to Main functions

_10
SpError SpRegisterDebugCallbacks(struct SpDebugCallbacks *cb, void *context)

Register a callback that receives debug messages/trace logs.

These callbacks can be registered before SpInit has been called, in order to receive debug logs that occur during initialization.

Parameters

[in]struct SpDebugCallbacks * cbStructure with pointers to individual callback functions.
[in]void * contextApplication-defined pointer that will be passed unchanged as the context argument to the callback.

Returns

Returns an error code

SpRegisterPlaybackCallbacks()

Return to Main functions

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

Register playback-related callbacks.

Parameters

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

Returns

Returns an error code

SpGetMetadata()

Return to Main functions

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

Retrieve metadata for a track in the current track list.

Parameters

[out]struct SpMetadata * metadataStructure to be filled with the metadata for the track
[in]int relative_indexTrack index relative to the current track. Some relative indices are defined in the enum SpMetadataTrack

Returns

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

Notes:

SpGetMetadataImageURL()

Return to Main functions

_10
SpError SpGetMetadataImageURL(const char *image_uri, char *image_url, size_t image_url_size)

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

Parameters

[in]const char * image_uriimage URI returned in SpMetadata::album_cover_uri
[out]char * image_urlPointer to a buffer that will be filled with HTTP URL.
[in]size_t image_url_sizesize of the image_url buffer. SP_MAX_METADATA_IMAGE_URL_LENGTH is the max amount od data that can be returned in image_url.

Returns

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

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

SpGetPlayerCookie()

Return to Main functions

_10
SpError SpGetPlayerCookie(char *player_cookie, size_t player_cookie_size)

Obtain player cookie for current playback.

The obtained player cookie can then be used to get more detailed metadata for current playback from Spotify's backend using Spotify Web API.

Parameters

[out]char * player_cookiePointer to a buffer where the player cookie will be copied. This buffer will be reset even if there is no player cookie available.
[in]size_t player_cookie_sizeSize of the player_cookie buffer. Player cookie length is defined SP_PLAYER_COOKIE_LENGTH and the buffer should be at least SP_PLAYER_COOKIE_LENGTH+1 in size.

Returns

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

Notes:
  • Experimental, subject to change

SpPlaybackPlay()

Return to Main functions

_10
SpError SpPlaybackPlay(int alias_index)

Start or resume playback.

Parameters

[in]int alias_indexThe index of the device alias to start playback on. If aliases aren't used, pass -1.

Returns

Returns an error code

SpPlaybackPause()

Return to Main functions

_10
SpError SpPlaybackPause(void)

Pause playback.

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

Returns

Returns an error code

SpPlaybackSkipToNext()

Return to Main functions

_10
SpError SpPlaybackSkipToNext(void)

Skip playback to the next track in the track list.

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

Returns

Returns an error code

SpPlaybackSkipToPrev()

Return to Main functions

_10
SpError SpPlaybackSkipToPrev(void)

Skip playback to the previous track in the track list.

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

Returns

Returns an error code

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

SpPlaybackSeek()

Return to Main functions

_10
SpError SpPlaybackSeek(uint32_t position_ms)

Seek to a position within the current track.

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

Parameters

[in]uint32_t position_msPosition within the track in milliseconds

Returns

Returns an error code

SpPlaybackSeekRelative()

Return to Main functions

_10
SpError SpPlaybackSeekRelative(int32_t time_ms)

Seek a relative amount of time within the current track.

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

Parameters

[in]int32_t time_msAmount of time to seek within the current track, negative values seek backwards and positive values seek forward.

Returns

Returns an error code

SpPlaybackGetPosition()

Return to Main functions

_10
uint32_t SpPlaybackGetPosition(void)

Get the current playback position within the track.

Returns

Playback position in milliseconds

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

SpPlaybackUpdateVolume()

Return to Main functions

_10
SpError SpPlaybackUpdateVolume(uint16_t volume)

Request a change to the playback volume.

It is the application's responsibility to apply the volume change to its audio output. This function merely notifies the library of the volume change, so that the library can inform other Spotify Connect-enabled devices. Calling this function invokes the SpCallbackPlaybackApplyVolume callback, which the application can use to apply the actual volume change.

Parameters

[in]uint16_t volumeVolume in the range 0 (silence) to 65535 (full volume)

Returns

Returns an error code

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

SpPlaybackGetVolume()

Return to Main functions

_10
uint16_t SpPlaybackGetVolume(void)

Get the playback volume level.

This returns the last volume level that the application set using SpPlaybackUpdateVolume or that was reported to the application using SpCallbackPlaybackApplyVolume

Returns

Volume level in the range 0 (silence) to 65535 (full volume).

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

SpPlaybackIsPlaying()

Return to Main functions

_10
uint8_t SpPlaybackIsPlaying(void)

Is the playback status playing or paused.

Returns

1: Playback status is playing 0: Playback status is paused (or no playback has been started at all)

See also Notes:
  • 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 Main functions

_10
uint8_t SpPlaybackIsAdPlaying(void)

Is the the current track an Ad or not.

Returns

1: The current playing track is an Ad 0: The current playing track is not an Ad.

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

SpPlaybackIsShuffled()

Return to Main functions

_10
uint8_t SpPlaybackIsShuffled(void)

Is "shuffle" mode enabled.

Returns

1: Shuffle is enabled 0: Shuffle is disabled

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

SpPlaybackIsRepeated()

Return to Main functions

_10
uint8_t SpPlaybackIsRepeated(void)

Is "repeat" mode enabled.

Returns

1: Repeat is enabled 0: Repeat is disabled

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

SpPlaybackGetRepeatMode()

Return to Main functions

_10
uint8_t SpPlaybackGetRepeatMode(void)

What "repeat" mode is on.

Returns

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

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

SpPlaybackIsActiveDevice()

Return to Main functions

_10
uint8_t SpPlaybackIsActiveDevice(void)

Is the device the active playback device.

Returns

1: The device is the active playback device 0: Another device is the active playback device

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

SpPlaybackEnableShuffle()

Return to Main functions

_10
SpError SpPlaybackEnableShuffle(uint8_t enable)

Enable or disable "shuffle" mode.

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

Parameters

[in]uint8_t enable1 to enable, 0 to disable

Returns

Returns an error code

See also Notes:
  • The change to the shuffle mode might not take effect if the API is invoked in the time window between requesting playback of a new context (e.g., by calling SpPlayUri), and playback of the new context actually starting.

SpPlaybackEnableRepeat()

Return to Main functions

_10
SpError SpPlaybackEnableRepeat(uint8_t enable)

Enable or disable "repeat" mode.

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

Parameters

[in]uint8_t enable0 to disable, 1 to Repeat Context, 2 to Repeat Track The Repeat values where previously called Repeat and Repeat-1.

Returns

Returns an error code

See also

SpPlaybackCycleRepeatMode()

Return to Main functions

_10
SpError SpPlaybackCycleRepeatMode(void)

Cycle through the available repeat modes.

Cycles through repeat modes (repeat off, repeat context, repeat track) given their current availability. If for example repeat context is enabled and repeat track is disallowed due to restrictions, this API will go directly to repeat off.

Returns

Returns an error code.

SpPlaybackSetBitrate()

Return to Main functions

_10
SpError SpPlaybackSetBitrate(enum SpPlaybackBitrate bitrate)

Change the bitrate at which compressed audio data is delivered.

This will take effect for the next chunk of audio data that is streamed from the backend. The format or sample rate of the audio data that is received does not change.

Parameters

[in]enum SpPlaybackBitrate bitrateThe bitrate to be set

Returns

Returns an error code

SpPlaybackSetAvailableToPlay()

Return to Main functions

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

_10
SpError SpPlaybackSetAvailableToPlay(uint8_t can_play)

Allow or disallow the device to start playback.

On some platforms, there might be certain situations in which playback should be disallowed temporarily. In this case, when the user tries to start playback on the device using the mobile application, the device should be marked as "Unavailable for playback" in the UI.

Parameters

[in]uint8_t can_play2 to allow playback (default), 1 to disallow playback without becoming inactive, the playback will be paused, 0 to disallow playback and become inactive.
See also Notes:
  • This functionality is reserved for specific integration scenarios. In most cases, when integrating the SDK into a device, this API must not be used. If the device is unable to play (for example, if a firmware upgrade is about to be performed), the application shall log out, shut down the library, and stop announcing the device via the ZeroConf.)
  • If the device is currently the active device when setting can_play to 0, the notification kSpPlaybackNotifyBecameInactive will be sent. Playback-related APIs (SpPlaybackPlay(), ...) will return an error code. This setting will persist across logout/login.

SpPlaybackIsAvailableToPlay()

Return to Main functions

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

_10
uint8_t SpPlaybackIsAvailableToPlay(void)

Is the device available for playback.

Returns

1: The device is available for playback 0: The device can't accept playback request nor start playback either.

See also

SpPlaybackSetDeviceInactive()

Return to Main functions

_10
SpError SpPlaybackSetDeviceInactive(void)

Set the device inactive.

If the device is currently the active device, this function stops the playback if playing, sets the device inactive, and sends the notification kSpPlaybackNotifyBecameInactive If the device is already inactive, the error code kSpErrorNotActiveDevice is returned.

Returns

Returns an error code

See also Notes:

SpPlaybackIsDeviceControllable()

Return to Main functions

_10
uint8_t SpPlaybackIsDeviceControllable(void)

Is the device controllable.

Returns

1: The device is controllable. 0: The device is not controllable so can't accept playback request nor start playback either.

SpPlaybackSetDeviceControllable()

Return to Main functions

_10
SpError SpPlaybackSetDeviceControllable(uint8_t is_controllable)

Allow or disallow the device to be controllable.

On some platforms, there might be certain situations in which the control of the playback should be disallowed temporarily. In this case, when the user tries to start playback on the device using the mobile application, the device should be marked as "Unavailable for playback" in the UI.

Parameters

[in]uint8_t is_controllableWhen set to 0 eSDK will pause the playback and won't accept local and remote playback commands, the device gets grayed off in the picker. Set to 1 to allow device control, eSDK will accept both local and remote playback commands and the device becomes available in the picker.

Returns

Returns an error code

See also Notes:
  • This functionality is reserved for specific integration scenarios. It can be used to temporarily disallow playback when for example playing cutscenes in video games or taking a phone call while driving a car. This API should not be used if the device is unable to play (for example, if a firmware upgrade is about to be performed), the application shall then instead log out, shut down the library, and stop announcing the device via the ZeroConf.

SpPlaybackIncreaseUnderrunCount()

Return to Main functions

_10
SpError SpPlaybackIncreaseUnderrunCount(uint32_t count)

Increase the underrun counter of the current track.

If playback underruns have been detected in the current track, use this API to report it to eSDK. This should only be called when there was no data to play at all and there was a audible glitch or gap for the user. It should only be called if audio was expected to be played and there was audio before. For example if eSDK is active and playing, but there is an underrun, report it. If eSDK is active and was requested to play something, but it never started, do not report it. If eSDK is active and playing and user skips, there is an expected gap, so report an underrun only if audio data started being delivered from eSDK and then stopped.

Parameters

[in]uint32_t countA counter of how many underruns happened. Some audio stacks have only a getUnderrunCount, so more than one could have occurred since the last one.

Returns

Returns an error code

SpPlaybackSetBandwidthLimit()

Return to Main functions

_10
SpError SpPlaybackSetBandwidthLimit(uint32_t max_bytes_per_sec)

Set a limit on the download speed.

By calling this function eSDK will attempt to limit how fast it downloads a track. In some use cases it is preferred to not use the full bandwidth. At the beginning of a download eSDK will do a burst download and then try to obey the limit.

Parameters

[in]uint32_t max_bytes_per_secapproximate bandwidth budget for downloads. To use default bandwidth specify 0.

Returns

Returns an error code

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

SpPlaybackSetRedeliveryMode()

Return to Main functions

_10
SpError SpPlaybackSetRedeliveryMode(SpReDeliveryMode mode)

Activates redelivery of audio data on play or resume playback.

This function should be called to activate or deactivate audio redelivery for the next calls to SpPlaybackPlay When the client application can't keep unplayed audio in its playback buffers (for example when audio from some other source was played while Spotify was paused) the eSDK should be notified that redelivery of audio data is needed. The audio data is redelivered from the last playback position reported by the integration with the same precision as seek. eSDK will need to redownload the data that was already delivered to integration and therefore there will be a penalty of increased data consumption and latencies. Only use this function when unplayed audio is discarded.

Returns

Returns an error code

SpPlaybackIsRedeliveryModeActivated()

Return to Main functions

_10
SpReDeliveryMode SpPlaybackIsRedeliveryModeActivated(void)

Gets the status of redelivery mode.

When redelivery mode is activated or deactivated through the API SpPlaybackSetRedeliveryMode, an internal state is updated to keep track of the redelivery behavior. This API exposes this internal state.

Returns

Returns redelivery mode status: kSpRedeliveryModeActivated or kSpRedeliveryModeDeactivated

SpPresetSubscribe()

Return to Main functions

_10
SpError SpPresetSubscribe(int preset_id, uint8_t *buffer, size_t buff_size)

Subscribe to receive "preset" tokens for use with SpPlayPreset

This function subscribes to receive periodic "preset" tokens that represent the currently playing context. They can be used to resume from the current context and position with SpPlayPreset This allows implementation of presets, which can be mapped to physical or virtual buttons, to allow users to save their favorite contexts for quick access. The tokens must be saved to persistent storage and be maintained across power cycles. SpPresetSubscribe must be provided a buffer to store the preset tokens in. This buffer must be a pointer to valid, writeable memory until the callback is unregistered with SpPresetUnsubscribe SpConnectionLogout or SpFree or whenever the playing context changes. The tokens are delivered asynchronously via the SpCallbackSavePreset callback, which must be registered with SpRegisterPlaybackCallbacks prior to calling SpPresetSubscribe Each time the SpCallbackSavePreset callback is called, any previously saved token for the current preset must be discarded and replaced with the updated value.

Parameters

[in]int preset_idAn integer indicating which preset this subscription is for. For products with numbered presets, this should match the number of the preset button. For use-cases with no integer mapping, this should be specified as -1.
[in]uint8_t * bufferPointer to a buffer that will be filled with the preset tokens. This must be a valid memory location until the preset is unregistered.
[in]size_t buff_sizeInput: buff_size specifies the size of the buffer pointed to by buffer. The buffer should be big enough to hold SP_PRESET_BUFFER_SIZE bytes.

Returns

Returns an error code

Notes:
  • The buffer passed to SpPresetSubscribe must be SP_PRESET_BUFFER_SIZE, but the actual preset tokens received from the SpCallbackSavePreset callback will typically be much smaller.
  • A subscription is only for the currently playing context, and only one subscription is possible at a time.
  • At times, some contexts may not be possible to save as presets. Errors will be indicated via the SpCallbackSavePreset callback.

SpPresetUnsubscribe()

Return to Main functions

_10
SpError SpPresetUnsubscribe(void)

Unsubscribe from a previously subscribed preset.

SpPresetUnsubscribe unsubscribes from receiving preset callbacks. This is the opposite of SpPresetSubscribe After calling this function, the memory buffer provided to SpPresetSubscribe is released by eSDK and can be deallocated.

Returns

Returns an error code

SpPlayPreset()

Return to Main functions

_10
SpError SpPlayPreset(int preset_id, uint32_t playback_position, uint8_t *buffer, size_t buff_size, int alias_index)

Recall and play a saved or default preset.

SpPlayPreset accepts a preset token that was previously received from using SpPresetSubscribe restores the context and playback state to as it was when the token was saved, and starts playback. For default user-recommended playlists, SpPlayPreset can be used with buffer set to NULL. Spotify will pick a default playlist to play based on popularity and user recommendations. The correct preset_id should still be provided to guarantee a good mixture of recommended playlists. Default presets do not require subscribing with SpPresetSubscribe Integrations should always use SpPresetSubscribe to subscribe to token updates in conjunction with using SpPlayPreset

Parameters

[in]int preset_idAn integer indicating which preset this token is for. For products with numbered presets, this should match the number of the preset button, starting from 1. For use-cases with no integer mapping, this should be specified as -1.
[in]uint32_t playback_positionThe playback position specified with the preset token from the SpCallbackSavePreset callback.
[in]uint8_t * bufferPreset blob obtained with SpPresetSubscribe or NULL to play a default user-recommended playlist.
[in]size_t buff_sizeThe size of buffer, or 0 if buffer is NULL.
[in]int alias_indexThe index of the device alias to start playback on. If aliases aren't used, pass -1.

Returns

Returns an error code

SpZeroConfGetVars()

Return to Main functions

_10
SpError SpZeroConfGetVars(struct SpZeroConfVars *vars)

Get variables for ZeroConf, mainly the "getInfo" request.

The application should use this function to retrieve the data that it should send in the response to the "getInfo" request. See the ZeroConf manual for more information. There are also other fields here that might be needed for ZeroConf.

Parameters

[out]struct SpZeroConfVars * varsStructure to be filled with the variables
Notes:
  • This API can be invoked from a callback.

SpZeroConfAnnouncePause()

Return to Main functions

_10
SpError SpZeroConfAnnouncePause(void)

Temporarily pause ZeroConf mDNS annoucements.

Returns

Returns an error code

Notes:

SpZeroConfAnnounceResume()

Return to Main functions

_10
SpError SpZeroConfAnnounceResume(void)

Resume ZeroConf mDNS annoucement after calling SpZeroConfAnnouncePause

Returns

Returns an error code

Notes:

SpConnectionLoginZeroConf()

Return to Main functions

_10
SpError SpConnectionLoginZeroConf(const char *username, const char *zero_conf_blob, const char *client_key, const char *login_id, const char *token_type)

Log in a user to Spotify using a ZeroConf credentials blob.

This function logs in with the information that the application receives in the "addUser" ZeroConf request. See the ZeroConf manual.

Parameters

[in]const char * usernameSpotify username. UTF-8 encoded. Must not be longer than SP_MAX_USERNAME_LENGTH bytes (not UTF-8-encoded characters), not counting the terminating NULL.
[in]const char * zero_conf_blobCredentials blob from the "blob" field of the request. Must not be longer than SP_MAX_ZEROCONF_BLOB_LENGTH bytes, not counting the terminating NULL.
[in]const char * client_keyClient key from the "clientKey" field of the request. This may be NULL if not supplied in the "addUser" request. Must not be longer than SP_MAX_CLIENT_KEY_LENGTH bytes, not counting the terminating NULL.
[in]const char * login_idLogin ID from the "loginId" field of the request. This may be NULL if not supplied in the "addUser" request. Must not be longer than SP_MAX_LOGIN_ID_LENGTH bytes, not counting the terminating NULL.
[in]const char * token_typeToken type from the "tokenType" field of the request. This may be NULL if not supplied in the "addUser" request. Must not be longer than SP_MAX_TOKEN_TYPE_LENGTH bytes, not counting the terminating NULL.

Returns

Returns an error code

See also Notes:
  • The login is performed asynchronously. The return value only indicates whether the library is able to perform the login attempt. The status of the login will be reported via callbacks:

SpGetBrandName()

Return to Main functions

_10
const char * SpGetBrandName(void)

This function can be used to get the brand name. If the field SpConfig::brand_display_name was set at SpInit it returns that, otherwise it returns what was set in the mandatory field SpConfig::brand_name

Returns

The UTF-8-encoded brand name

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

SpGetModelName()

Return to Main functions

_10
const char * SpGetModelName(void)

This function can be used to get the model name. If the field SpConfig::model_display_name was set at SpInit it returns that, otherwise it returns what was set in the mandatory field SpConfig::model_name

Returns

The UTF-8-encoded model name

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

SpRegisterDeviceAliasCallbacks()

Return to Main functions

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

Register callbacks related to device aliases.

Parameters

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

Returns

Returns an error code

SpSetDeviceAliases()

Return to Main functions

_10
SpError SpSetDeviceAliases(const struct SpDeviceAlias *aliases)

Update the device alias definitions.

Call this whenever the current alias definitions are updated. The id values for the aliases must be unique within the array. aliases Pointer to an array of SpDeviceAlias structs filled in with the new alias names and corresponding attributes. The array size must be of size SP_MAX_DEVICE_ALIASES.

Parameters

[in]const struct SpDeviceAlias * aliasesPointer to an array of SpDeviceAlias structs filled in with the new alias names and corresponding attributes. The array size must be of size SP_MAX_DEVICE_ALIASES.

SpRestrictDrmMediaFormats()

Return to Main functions

_10
SpError SpRestrictDrmMediaFormats(const struct SpFormat formats[SP_MAX_SUPPORTED_FORMATS])

Restricts the list of DRM and media formats to a subset of the formats registered in SpInit To lift the restrictions use SpRestoreDrmMediaFormats

See also

SpRestoreDrmMediaFormats()

Return to Main functions

_10
SpError SpRestoreDrmMediaFormats(void)

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

See also

Content



_10
#include "spotify_embedded_content.h"

Data Structures


Return to header index
SpContentCallbacks Callbacks to be registered with SpRegisterContentCallbacks

Typedefs


Return to header index
SpCallbackTrackCacheState This callback if set by client is called by eSDK to inform the client about how much data is actually cached for particular track starting from the beginning in percents. For example is 60 reported it mean 60% of the track is cached started from the beginning.
SpCallbackStorageKeyContentMapping This callback if set by client is called by eSDK to notify the client how storage_key used to store the data through Storage API is mapped to particular content being stored. SpContentType is used to specify exact content type. For example: hint being equal to kSpContentTrack means descriptor would be in form of: spotify:track:[base62].
SpCallbackTrackRelinked This callback if set by client is called by eSDK to notify the client about the fact that requested track is substituted with another (relinked) one during prefetch/offline process.
SpCallbackTrackRemoved This callback if set by client is called by eSDK to notify the client that the track is removed.
SpCallbackOnAvailableContainer Callback for each available container.

Enumerations


Return to header index
SpContentType

Functions


Return to header index
SpRegisterContentCallbacks

Data Structures


SpContentCallbacks

Return to Content data structures

Callbacks to be registered with SpRegisterContentCallbacks

Any of the pointers may be NULL.

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

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

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

Typedefs


SpCallbackTrackCacheState()

Return to Content Typedefs

_10
typedef void(* SpCallbackTrackCacheState)(const char *track_uri, uint32_t percents, void *context)

This callback if set by client is called by eSDK to inform the client about how much data is actually cached for particular track starting from the beginning in percents. For example is 60 reported it mean 60% of the track is cached started from the beginning.

Parameters

[in]const char * track_uriTrack URI which status is reported.
[in]uint32_t percentsHow much data is cached in percent. Range: [0 - 100%]
[in]void * contextContext provided in callback register procedure.
Notes:
  • The application should not block or call other API functions in the callback. This callback is called before each track delivery is started.

SpCallbackStorageKeyContentMapping()

Return to Content Typedefs

_10
typedef void(* SpCallbackStorageKeyContentMapping)(const char *storage_key, const char *descriptor, enum SpContentType hint, void *context)

This callback if set by client is called by eSDK to notify the client how storage_key used to store the data through Storage API is mapped to particular content being stored. SpContentType is used to specify exact content type. For example: hint being equal to kSpContentTrack means descriptor would be in form of: spotify:track:[base62].

Parameters

[in]const char * storage_keyStorage key that was used in Alloc/Read/Write API.
[in]const char * descriptorContent descriptor. Value depends on hint.
See also Notes:
  • The application should not block or call other API functions in the callback. This callback is called as soon as possible after Alloc callback of Storage API has been called and succeeds.

SpCallbackTrackRelinked()

Return to Content Typedefs

_10
typedef void(* SpCallbackTrackRelinked)(const char *original_uri, const char *new_uri, void *context)

This callback if set by client is called by eSDK to notify the client about the fact that requested track is substituted with another (relinked) one during prefetch/offline process.

Parameters

[in]const char * original_uriInitial URI passed into eSDK PrefetchURI/OfflineURI function calls.
[in]const char * new_uriURI that is obtained after relink has happened.
[in]void * contextContext provided in callback register procedure.

SpCallbackTrackRemoved()

Return to Content Typedefs

_10
typedef void(* SpCallbackTrackRemoved)(const char *track_uri, void *context)

This callback if set by client is called by eSDK to notify the client that the track is removed.

track_uri URI passed into eSDK PlayURI/PrefetchURI/OfflineURI function calls. context Context provided in callback register procedure.

Parameters

[in]const char * track_uriURI passed into eSDK PlayURI/PrefetchURI/OfflineURI function calls.
[in]void * contextContext provided in callback register procedure.

SpCallbackOnAvailableContainer()

Return to Content Typedefs

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

Callback for each available container.

Parameters

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

Enumerations


SpContentType

Return to Content enumerations

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

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

Functions


SpRegisterContentCallbacks()

Return to Content functions

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

Parameters

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

Returns

Returns an error code

Hal



_10
#include "spotify_embedded_hal.h"

Data Structures


Return to header index
SpSockaddr Struct contains resolved hostname ip address and its family.
SpDnsHALCallbacks Callbacks to be registered with SpRegisterDnsHALCallbacks
SpSocketHandle Socket handle type.
SpSocketHALCallbacks Callbacks to be registered with SpRegisterSocketHALCallbacks

Typedefs


Return to header index
SpCallbackPerformDNSLookup This callback if set by client is called by eSDK to perform DNS lookup. If expected that lookup could take significant amount of time client may do it asynchronously in which case value of kSpAPITryAgain could be returned.
SpCallbackSocketCreate This callback if set by client is called by eSDK to create socket of certain type and family.
SpCallbackSocketSetOption This callback if set by client is called by eSDK to set specific options on previously created socket.
SpCallbackSocketClose This callback if set by client is called by eSDK to close previously opened socket.
SpCallbackSocketBind This callback if set by client is called by eSDK to bind to provided socket.
SpCallbackSocketListen This callback if set by client is called by eSDK to start listening provided socket. This callbacks has no effect on UPD sockets.
SpCallbackSocketConnect This callback if set by client is called by eSDK to connect to specified host and remote port.
SpCallbackSocketAccept This callback if set by client is called by eSDK to accept connection on provided socket.
SpCallbackSocketRead This callback if set by client is called by eSDK to read the data from socket.
SpCallbackSocketWrite This callback if set by client is called by eSDK to write data to socket.
SpCallbackSocketReadFrom This callback if set by client is called by eSDK to read the data from socket addressed by SpSockaddr instance.
SpCallbackSocketWriteTo This callback if set by client is called by eSDK to write data to socket addressed by SpSockaddr instance.
SpCallbackSocketError This callback if set by client is called by eSDK to get underlying OS error code.
SpCallbackSocketReadable This callback if set by client is called by eSDK to figure out if socket is readable.
SpCallbackSocketWriteable This callback if set by client is called by eSDK to figure out if socket is writable.
SpCallbackLocalAddresses This callback if set by client is called by eSDK to get local interface addresses. If the clent can't get local interfaces implementation should fill provided *num_addrs with 0.
SpCallbackSocketAddress This callback if set by client is called by eSDK to provide platform defined representation of address that can be used in SpCallbackSocketReadFrom and SpCallbackSocketWriteTo Client responsible for providing returned pointer lifetime.
SpCallbackPump This callback if set by client is called by eSDK to pump network layer.

Enumerations


Return to header index
SpIPFamily
SpSocketPool
SpSocketType
SpSocketOptions

Functions


Return to header index
SpRegisterDnsHALCallbacks Register HAL-related callbacks. Should be called right after SpInit
SpGetDefaultDnsHALCallbacks Get eSDK's default DNS callbacks.
SpRegisterSocketHALCallbacks Register socket HAL-related callbacks. To remove callbacks call SpRegisterSocketHALCallbacks with SpSocketHALCallbacks initialized to zeros.
SpGetDefaultSocketHALCallbacks Get eSDK's default socket callbacks.

Data Structures


SpSockaddr

Return to Hal data structures

Struct contains resolved hostname ip address and its family.


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

enum SpIPFamily 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 Hal data structures

Callbacks to be registered with SpRegisterDnsHALCallbacks

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

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

_10
struct SpDnsHALCallbacks {
_10
SpCallbackPerformDNSLookup dns_lookup_callback;
_10
};

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

SpSocketHandle

Return to Hal data structures

Socket handle type.


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

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

SpSocketHALCallbacks

Return to Hal data structures

Callbacks to be registered with SpRegisterSocketHALCallbacks

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


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

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

Typedefs


SpCallbackPerformDNSLookup()

Return to Hal Typedefs

_10
typedef enum SpCallbackPerformDNSLookup)(const char *hostname, struct SpSockaddr *sockaddr, void *context)

This callback if set by client is called by eSDK to perform DNS lookup. If expected that lookup could take significant amount of time client may do it asynchronously in which case value of kSpAPITryAgain could be returned.

Parameters

[in]const char * hostnameName to be resolved.
[in]struct SpSockaddr * sockaddrPointer to SpSockaddr structure.
See also Notes:
  • The application should not block or call other API functions in the callback. Port value of SpSockaddr is ignored.

SpCallbackSocketCreate()

Return to Hal Typedefs

_10
typedef enum SpCallbackSocketCreate)(enum SpIPFamily family, enum SpSocketType type, enum SpSocketPool pool_id, struct SpSocketHandle **socket, void *context)

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

Parameters

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

SpCallbackSocketSetOption()

Return to Hal Typedefs

_10
typedef enum SpCallbackSocketSetOption)(struct SpSocketHandle *socket, enum SpSocketOptions option, void *value, void *context)

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

Parameters

[in]struct SpSocketHandle * socketSocket instance to perform action with.
[in]enum SpSocketOptions optionOne of SpSocketOptions options.
[in]void * valueOption value. Depends on particular SpSocketOptions option.
[in]void * contextContext provided in callback register procedure.
Notes:
  • The application should not block or call other API functions in the callback.

SpCallbackSocketClose()

Return to Hal Typedefs

_10
typedef enum SpCallbackSocketClose)(struct SpSocketHandle *socket, void *context)

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

Parameters

[in]struct SpSocketHandle * socketSocket instance to perform action with.
[in]void * contextContext provided in callback register procedure.
Notes:
  • The application should not block or call other API functions in the callback.

SpCallbackSocketBind()

Return to Hal Typedefs

_10
typedef enum SpCallbackSocketBind)(struct SpSocketHandle *socket, int *port, void *context)

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

Parameters

[in]struct SpSocketHandle * socketSocket instance to perform action with.
[in]int * portPort which eSDK would listen to (host byte order). If (*port) is zero, the bound port should be stored in (*port).
[in]void * contextContext provided in callback register procedure.
Notes:
  • The application should not block or call other API functions in the callback.

SpCallbackSocketListen()

Return to Hal Typedefs

_10
typedef enum SpCallbackSocketListen)(struct SpSocketHandle *socket, int backlog, void *context)

This callback if set by client is called by eSDK to start listening provided socket. This callbacks has no effect on UPD sockets.

Parameters

[in]struct SpSocketHandle * socketSocket instance to perform action with.
[in]int backlogParameter defines the maximum length for the queue of pending connections.
[in]void * contextContext provided in callback register procedure.
Notes:
  • The application should not block or call other API functions in the callback.

SpCallbackSocketConnect()

Return to Hal Typedefs

_10
typedef enum SpCallbackSocketConnect)(struct SpSocketHandle *socket, const struct SpSockaddr *addr, void *context)

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

Parameters

[in]struct SpSocketHandle * socketSocket instance to perform action with.
[in]const struct SpSockaddr * addrAddress to connect to.
[in]void * contextContext provided in callback register procedure.
Notes:
  • The application should not block or call other API functions in the callback.

SpCallbackSocketAccept()

Return to Hal Typedefs

_10
typedef enum SpCallbackSocketAccept)(struct SpSocketHandle *socket, enum SpSocketPool pool_id, struct SpSocketHandle **out_socket, void *context)

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

Parameters

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

SpCallbackSocketRead()

Return to Hal Typedefs

_10
typedef enum SpCallbackSocketRead)(struct SpSocketHandle *socket, void *data, int data_size, int *bytes_read, void *context)

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

Parameters

[in]struct SpSocketHandle * socketSocket instance to perform action with.
[in]void * dataBuffer to read data into.
[in]int data_sizeAmount of requested data to read.
[in]int * bytes_readPointer to store how much bytes actually read. If NULL, read is still performed. Should be unchanged if read failed.
[in]void * contextContext provided in callback register procedure.
Notes:
  • The application should not block or call other API functions in the callback.

SpCallbackSocketWrite()

Return to Hal Typedefs

_10
typedef enum SpCallbackSocketWrite)(struct SpSocketHandle *socket, const void *data, int data_size, int *bytes_written, void *context)

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

Parameters

[in]struct SpSocketHandle * socketSocket instance to perform action with.
[in]const void * dataBuffer with data to be written.
[in]int data_sizeAmount of data to write.
[in]int * bytes_writtenPointer to store how much bytes actually written. If NULL, write is still performed. Should unchanged if write failed.
[in]void * contextContext provided in callback register procedure.
Notes:
  • The application should not block or call other API functions in the callback.

SpCallbackSocketReadFrom()

Return to Hal Typedefs

_10
typedef enum SpCallbackSocketReadFrom)(struct SpSocketHandle *socket, void *data, int data_size, const void **addr, int *bytes_read, void *context)

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

Parameters

[in]struct SpSocketHandle * socketSocket instance to perform action with.
[in]void * dataBuffer to read data into.
[in]int data_sizeAmount of requested data to read.
[in]const void ** addrPlatform defined addr pointer. eSDK does not modify it. Just pass through to write_to.
[in]int * bytes_readPointer to store how much bytes actually read. If NULL, read is still performed. Should be unchanged if read failed.
[in]void * contextContext provided in callback register procedure.
Notes:
  • The application should not block or call other API functions in the callback. This callback should mirror the behavior of recvfrom for connected/non-connected sockets.

SpCallbackSocketWriteTo()

Return to Hal Typedefs

_10
typedef enum SpCallbackSocketWriteTo)(struct SpSocketHandle *socket, const void *data, int data_size, const void *addr, int *bytes_written, void *context)

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

Parameters

[in]struct SpSocketHandle * socketSocket instance to perform action with.
[in]const void * dataBuffer with data to be written.
[in]int data_sizeAmount of data to write.
[in]const void * addrPointer received in the call to SpCallbackSocketReadFrom
[in]int * bytes_writtenPointer to store how much bytes actually written. If NULL, write is still performed. Should unchanged if write failed.
[in]void * contextContext provided in callback register procedure.
Notes:
  • The application should not block or call other API functions in the callback. This callback should mirror the behavior of writeto for connected/non-connected sockets.

SpCallbackSocketError()

Return to Hal Typedefs

_10
typedef int(* SpCallbackSocketError)(struct SpSocketHandle *socket, void *context)

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

Parameters

[in]struct SpSocketHandle * socketSocket instance for which error code is requested.
[in]void * contextContext provided in callback register procedure.
Notes:
  • The application should not block or call other API functions in the callback.

SpCallbackSocketReadable()

Return to Hal Typedefs

_10
typedef int(* SpCallbackSocketReadable)(struct SpSocketHandle *socket, void *context)

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

Parameters

[in]struct SpSocketHandle * socketSocket instance to perform action with.
[in]void * contextContext provided in callback register procedure.
Notes:
  • The application should not block or call other API functions in the callback.

SpCallbackSocketWriteable()

Return to Hal Typedefs

_10
typedef int(* SpCallbackSocketWriteable)(struct SpSocketHandle *socket, void *context)

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

Parameters

[in]struct SpSocketHandle * socketSocket instance to perform action with.
[in]void * contextContext provided in callback register procedure.
Notes:
  • The application should not block or call other API functions in the callback.

SpCallbackLocalAddresses()

Return to Hal Typedefs

_10
typedef void(* SpCallbackLocalAddresses)(struct SpSockaddr *addrs, int *num_addrs, void *context)

This callback if set by client is called by eSDK to get local interface addresses. If the clent can't get local interfaces implementation should fill provided *num_addrs with 0.

Parameters

[in]int *num_ addrsPointer to array of SpSockaddr to store the data. Data in network byte order.
[in]int * num_addrsArray size on input, number of items stored in the array on output.
[in]void * contextContext provided in callback register procedure.
Notes:
  • The application should not block or call other API functions in the callback.

SpCallbackSocketAddress()

Return to Hal Typedefs

_10
typedef const void *(* SpCallbackSocketAddress)(const struct SpSockaddr *addr, void *context)

This callback if set by client is called by eSDK to provide platform defined representation of address that can be used in SpCallbackSocketReadFrom and SpCallbackSocketWriteTo Client responsible for providing returned pointer lifetime.

Parameters

[in]const struct SpSockaddr * addrAddress to convert. Network byte order.
[in]void * contextContext provided in callback register procedure.
Notes:
  • The application should not block or call other API functions in the callback.

SpCallbackPump()

Return to Hal Typedefs

_10
typedef enum SpCallbackPump)(unsigned max_wait_ms, void *context)

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

Parameters

[in]unsigned max_wait_msMaximum time to wait in one pump call
[in]void * contextContext provided in callback register procedure.
Notes:
  • The application should not block or call other API functions in the callback.

Enumerations


SpIPFamily

Return to Hal enumerations

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

kSpIPV4 IP v4 family.
kSpIPV6 IP v6 family.

SpSocketPool

Return to Hal enumerations

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

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

SpSocketType

Return to Hal enumerations

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

kSpSocketStream Stream socket type.
kSpSocketDgram Datagram socket type.

SpSocketOptions

Return to Hal enumerations

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

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

Functions


SpRegisterDnsHALCallbacks()

Return to Hal functions

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

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

Parameters

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

Returns

Returns an error code.

Notes:
  • To remove DNS callback at any time call SpRegisterDnsHALCallbacks with SpDnsHALCallbacks which has dns_lookup_callback set to NULL. Setting DNS callback make sense only if eSDK uses its own socket implementation. If the client provides whole socket API it is also reponsible for hostname resolving if needed. Setting DNS callbacks with provided socket callbacks makes no effect.

SpGetDefaultDnsHALCallbacks()

Return to Hal functions

_10
SpError SpGetDefaultDnsHALCallbacks(struct SpDnsHALCallbacks *callbacks)

Get eSDK's default DNS callbacks.

Parameters

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

Returns

Returns an error code.

Notes:

SpRegisterSocketHALCallbacks()

Return to Hal functions

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

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

Parameters

[in]struct SpSocketHALCallbacks * callbacksStructure with pointers to individual callback functions. Either all pointers are NULL or all are valid.
[in]void * contextApplication-defined pointer that will be passed unchanged as the context argument to the callbacks.

Returns

Returns an error code

Notes:

SpGetDefaultSocketHALCallbacks()

Return to Hal functions

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

Get eSDK's default socket callbacks.

Parameters

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

Returns

Returns an error code.

Notes:

Log



_10
#include "spotify_embedded_log.h"

Macros and Constants


Return to header index
SP_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 See macro below
SpLogInfo See macro below
SpLogDebug See macro below
SpLogTrace See macro below

Data Structures


Return to header index
SpLogTraceObject Trace object.

Enumerations


Return to header index
SpLogLevel

Functions


Return to header index
SpLogRegisterTraceObject Register a defined trace object with eSDK.
SpLog Output a debug message via eSDK.
SpLogSetLevel Control the current logging level.
SpLogGetLevels Get registered trace objects and log levels.

Macros and Constants


SP_LOG_DEFAULT_LEVEL

Return to Log macros and constants

_10
#define SP_LOG_DEFAULT_LEVEL SP_LOG_LEVEL_INFO

Default trace log level.

SP_LOG_DEFINE_TRACE_OBJ

Return to Log macros and constants

_10
#define SP_LOG_DEFINE_TRACE_OBJ struct

Macro to define a trace object.

obj Name of the trace object

SP_LOG_DECLARE_TRACE_OBJ

Return to Log macros and constants

_10
#define SP_LOG_DECLARE_TRACE_OBJ extern struct

Macro to declare a previously defined trace object.

obj Name of the trace object

SP_LOG_REGISTER_TRACE_OBJ

Return to Log macros and constants

_10
#define SP_LOG_REGISTER_TRACE_OBJ SpLogRegisterTraceObject(&trace_obj_##obj)

Macro to register a previously defined trace object.

obj Name of the trace object

SP_LOG

Return to Log macros and constants

_10
#define SP_LOG do { \
_10
if (trace_obj_##obj.level >= lvl) { \

Macro that outputs a trace message.

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

SpLogFatal

Return to Log macros and constants

_10
#define SpLogFatal SP_LOG(obj, SP_LOG_LEVEL_FATAL, __FILE__, __func__, __LINE__, __VA_ARGS__)

Emit trace message with SP_LOG_LEVEL_FATAL.

SpLogError

Return to Log macros and constants

_10
#define SpLogError SP_LOG(obj, SP_LOG_LEVEL_ERROR, __FILE__, __func__, __LINE__, __VA_ARGS__)

Emit trace message with SP_LOG_LEVEL_ERROR.

SpLogWarning

Return to Log macros and constants

_10
#define SpLogWarning SP_LOG(obj, SP_LOG_LEVEL_WARNING, __FILE__, __func__, __LINE__, __VA_ARGS__)

Emit trace message with SP_LOG_LEVEL_WARNING.

SpLogInfo

Return to Log macros and constants

_10
#define SpLogInfo SP_LOG(obj, SP_LOG_LEVEL_INFO, __FILE__, __func__, __LINE__, __VA_ARGS__)

Emit trace message with SP_LOG_LEVEL_INFO.

SpLogDebug

Return to Log macros and constants

_10
#define SpLogDebug SP_LOG(obj, SP_LOG_LEVEL_DEBUG, __FILE__, __func__, __LINE__, __VA_ARGS__)

Emit trace message with SP_LOG_LEVEL_DEBUG.

SpLogTrace

Return to Log macros and constants

_10
#define SpLogTrace SP_LOG(obj, SP_LOG_LEVEL_TRACE, __FILE__, __func__, __LINE__, __VA_ARGS__)

Emit trace message with SP_LOG_LEVEL_TRACE.

Data Structures


SpLogTraceObject

Return to Log data structures

Trace object.

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


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

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

Enumerations


SpLogLevel

Return to Log enumerations

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

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

Functions


SpLogRegisterTraceObject()

Return to Log functions

_10
SpError SpLogRegisterTraceObject(struct SpLogTraceObject *obj)

Register a defined trace object with eSDK.

Parameters

[in]struct SpLogTraceObject * objPointer to trace object

Returns

Return kSpErrorOk on success, or error code on failure.

SpLog()

Return to Log functions

_10
void SpLog(const struct SpLogTraceObject *obj, SpLogLevel level, const char *file, const char *func, int line, const char *format,...)

Output a debug message via eSDK.

obj Pointer to trace object level The log level associated this this message file The source file from where the call is made, typically FILE. func The function name from where the call is made, typically func. line The line number from where the call is made, typically LINE. format A printf style format string followed by arguments.

Parameters

[in]const struct SpLogTraceObject * objPointer to trace object
[in]SpLogLevel levelThe log level associated this this message
[in]const char * fileThe source file from where the call is made, typically FILE.
[in]const char * funcThe function name from where the call is made, typically func.
[in]int lineThe line number from where the call is made, typically LINE.
[in]const char * formatA printf style format string followed by arguments.

SpLogSetLevel()

Return to Log functions

_10
SpError SpLogSetLevel(const char *category, SpLogLevel level)

Control the current logging level.

Control the logging level for a particular category. If the current configured log level is greater than or equal to the level associated with the message, the log message will be passed to the debug log callback. Each log message is also associated with a category. The category is a string that is included in the log message output. Each individual category has a separate current log level. The log messages produced by the eSDK are formatted as: LEVEL CATEGORY MESSAGE where LEVEL is a single letter indicating the log level (E=Error, I=Info, etc.), CATEGORY is a short string that identifies the log category, for example 'api' and MESSAGE is the actual debug message. As an example, a debug output string with level set to SP_LOG_LEVEL_ERROR (letter "E") and the category "api" could look something like this (the timestamp is not actually part of the debug message from eSDK, but added by the DebugMessageCallback. Thus, the format may not exactly match the example below). 12:01:02.000 E api Invalid parameter passed to SpInit

Parameters

[in]const char * categoryIdentifies the log category for which to set the logging level. If NULL is passed in this parameter, the level will be applied to all categories.
[in]SpLogLevel levelThe log level defined by SpLogLevel

Returns

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

SpLogGetLevels()

Return to Log functions

_10
SpError SpLogGetLevels(char *buffer, int buffer_len)

Get registered trace objects and log levels.

The information about trace objects and levels is represented as a string containing comma separated tuples level:trace obj, e.g. "4:app,4:esdk,4:audio".

Parameters

[in]char * bufferA buffer to copy the string to.
[in]int buffer_lenLength of the buffer

Returns

Returns an error code if buffer is not big enough.

Media



_10
#include "spotify_embedded_media.h"

Data Structures


Return to header index
SpStreamCallbacks Callbacks to be registered with SpRegisterStreamCallbacks

Typedefs


Return to header index
SpCallbackStreamStart Callback to tell application of the track details.
SpCallbackStreamData Callback deliver data to the integration.
SpCallbackStreamEnd Callback to tell integration that all data was delivered.
SpCallbackStreamGetPosition Callback get the playback position in milliseconds.
SpCallbackStreamSeekToPosition Callback to tell the integration to seek to a position.
SpCallbackStreamFlush Callback to tell the integration to flush.

Enumerations


Return to header index
SpMediaFormat

Functions


Return to header index
SpRegisterStreamCallbacks Register callbacks related to the delivery api.
SpNotifySeekComplete API to notify eSDK of the completion of seek operation.
SpNotifyTrackLength API to notify eSDK of the track length in milliseconds.
SpNotifyTrackError API to notify eSDK of any track errors with last played position.
SpNotifyStreamPlaybackStarted Notify eSDK that the first audio sample of the delivery has been played.
SpNotifyStreamPlaybackContinued Notify eSDK that the first audio sample after a flush of a delivery has been played.
SpNotifyStreamPlaybackFinishedNaturally Notify eSDK that the delivery playback finished by playing the last sample of the delivery.
SpSetDownloadPosition API to instruct eSDK to start downloading from given byte offset.

Data Structures


SpStreamCallbacks

Return to Media data structures

Callbacks to be registered with SpRegisterStreamCallbacks


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

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

Typedefs


SpCallbackStreamStart()

Return to Media Typedefs

_10
typedef void(* SpCallbackStreamStart)(unsigned int stream_id, enum SpMediaFormat media_format, enum SpDrmFormat drm_format, uint32_t stream_size_bytes, void *format_specifics, void *context)

Callback to tell application of the track details.

To register this callback, use the function SpRegisterStreamCallbacks stream_id Unique identifier to identify tracks media_format Information about the format of the audio data. drm_format Information about the used DRM method stream_size_bytes Size of the stream in bytes. If the size is unknown, 0 is used. format_specifics Format dependent additional information. context Context pointer that was passed when registering the callback

Parameters

[in]unsigned int stream_idUnique identifier to identify tracks
[in]enum SpMediaFormat media_formatInformation about the format of the audio data.
[in]enum SpDrmFormat drm_formatInformation about the used DRM method
[in]uint32_t stream_size_bytesSize of the stream in bytes. If the size is unknown, 0 is used.
[in]void * format_specificsFormat dependent additional information.
[in]void * contextContext pointer that was passed when registering the callback

SpCallbackStreamData()

Return to Media Typedefs

_10
typedef size_t(* SpCallbackStreamData)(unsigned int stream_id, const void *buf, size_t len, uint32_t offset, void *context)

Callback deliver data to the integration.

To register this callback, use the function SpRegisterStreamCallbacks

Parameters

[in]unsigned int stream_idUnique identifier to identify tracks
[in]const void * bufBlock of data (it can be audio or video data)
[in]size_t lenSize of the data
[in]uint32_t offsetByte offset in the data stream (relative to the start)
[in]void * contextContext pointer that was passed when registering the callback

SpCallbackStreamEnd()

Return to Media Typedefs

_10
typedef void(* SpCallbackStreamEnd)(unsigned int stream_id, void *context)

Callback to tell integration that all data was delivered.

To register this callback, use the function SpRegisterStreamCallbacks stream_id Unique identifier to identify tracks context Context pointer that was passed when registering the callback

Parameters

[in]unsigned int stream_idUnique identifier to identify tracks
[in]void * contextContext pointer that was passed when registering the callback

SpCallbackStreamGetPosition()

Return to Media Typedefs

_10
typedef uint32_t(* SpCallbackStreamGetPosition)(unsigned int stream_id, void *context)

Callback get the playback position in milliseconds.

To register this callback, use the function SpRegisterStreamCallbacks

Parameters

[in]unsigned int stream_idUnique identifier to identify tracks
[in]void * contextContext pointer that was passed when registering the callback

SpCallbackStreamSeekToPosition()

Return to Media Typedefs

_10
typedef void(* SpCallbackStreamSeekToPosition)(unsigned int stream_id, uint32_t position_ms, void *context)

Callback to tell the integration to seek to a position.

To register this callback, use the function SpRegisterStreamCallbacks When receiving this callback, the integration should start to seek to the given position. The integration is expected to call SpSetDownloadPosition to instruct eSDK to start downloading from a byte offset corresponding to the position given in this callback. stream_id Unique identifier to identify tracks position_ms Position in time within the track where to seek to context Context pointer that was passed when registering the callback

Parameters

[in]unsigned int stream_idUnique identifier to identify tracks
[in]uint32_t position_msPosition in time within the track where to seek to
[in]void * contextContext pointer that was passed when registering the callback

SpCallbackStreamFlush()

Return to Media Typedefs

_10
typedef uint32_t(* SpCallbackStreamFlush)(unsigned int *playing_stream_id, void *context)

Callback to tell the integration to flush.

To register this callback, use the function SpRegisterStreamCallbacks When receiving this callback, the integration should: Forget all queued audio and compressed data Forget any deliveries that have ended except the playing one

Parameters

[out]unsigned int * playing_stream_idThe delivery of the track which is currently playing. If nothing is playing, zero should be used
[in]void * contextContext pointer that was passed when registering the callback

Enumerations


SpMediaFormat

Return to Media enumerations

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

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

Functions


SpRegisterStreamCallbacks()

Return to Media functions

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

Register callbacks related to the delivery api.

Parameters

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

Returns

Returns an error code

SpNotifySeekComplete()

Return to Media functions

_10
SpError SpNotifySeekComplete(unsigned int stream_id)

API to notify eSDK of the completion of seek operation.

Parameters

[in]unsigned int stream_idUnique identifier to identify tracks

Returns

Returns an error code

SpNotifyTrackLength()

Return to Media functions

_10
SpError SpNotifyTrackLength(unsigned int stream_id, uint32_t length_ms)

API to notify eSDK of the track length in milliseconds.

Parameters

[in]unsigned int stream_idUnique identifier to identify tracks
[in]uint32_t length_msPosition in milliseconds of the track

Returns

Returns an error code

SpNotifyTrackError()

Return to Media functions

_10
SpError SpNotifyTrackError(unsigned int stream_id, uint32_t position_ms, const char *reason)

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

Parameters

[in]unsigned int stream_idUnique identifier to identify tracks
[in]uint32_t position_msPosition in milliseconds of the track
[in]const char * reasonThe reason for the error

Returns

Returns an error code

SpNotifyStreamPlaybackStarted()

Return to Media functions

_10
SpError SpNotifyStreamPlaybackStarted(unsigned int stream_id)

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

This is used by the eSDK to measure playback latency.

Parameters

[in]unsigned int stream_idUnique identifier to identify tracks

Returns

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

SpNotifyStreamPlaybackContinued()

Return to Media functions

_10
SpError SpNotifyStreamPlaybackContinued(unsigned int stream_id)

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

This is used by the eSDK to measure seek latency.

Parameters

[in]unsigned int stream_idUnique identifier to identify tracks

Returns

Returns an error code

SpNotifyStreamPlaybackFinishedNaturally()

Return to Media functions

_10
SpError SpNotifyStreamPlaybackFinishedNaturally(unsigned int stream_id, uint32_t last_pos_ms)

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

Parameters

[in]unsigned int stream_idUnique identifier to identify tracks
[in]uint32_t last_pos_msPosition in milliseconds of the track

Returns

Returns an error code

SpSetDownloadPosition()

Return to Media functions

_10
SpError SpSetDownloadPosition(unsigned int stream_id, uint32_t byte_offset)

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

Parameters

[in]unsigned int stream_idUnique identifier to identify tracks
[in]uint32_t byte_offsetNew download byte offset (relative to the start of the stream) where downloading could continue.

Returns

Returns an error code

Play



_10
#include "spotify_embedded_play_api.h"

Macros and Constants


Return to header index
SP_NO_INDEX -1
SP_MAX_UUID_LENGTH 36
SP_MAX_SOURCE_TYPE_LENGTH 63
SP_MAX_SOURCE_URI_LENGTH 511
SP_MAX_REFERRER_LENGTH 16

Data Structures


Return to header index
SpSourceInfo Metadata for identifying where a playback request originated from.
SpPlayOptions PlayOptions passed to SpPlayUriWithOptions

Functions


Return to header index
SpPlayUri Start local playback of any Spotify URI.
SpPlayUriWithOptions Play Uri with SpPlayOptions
SpPlayContextUri Start local playback of any 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.
SpPlayPresetEx Extension for SpPlayPreset: Play a saved preset from different position, optionally with source info.

Macros and Constants


SP_NO_INDEX

Return to Play macros and constants

_10
#define SP_NO_INDEX -1

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

See also

SP_MAX_UUID_LENGTH

Return to Play macros and constants

_10
#define SP_MAX_UUID_LENGTH 36

Maximum length of a UUID.

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

SP_MAX_SOURCE_TYPE_LENGTH

Return to Play macros and constants

_10
#define SP_MAX_SOURCE_TYPE_LENGTH 63

Maximum length of the type of playback source.

See also

SP_MAX_SOURCE_URI_LENGTH

Return to Play macros and constants

_10
#define SP_MAX_SOURCE_URI_LENGTH 511

Maximum length of the source URIs.

See also

SP_MAX_REFERRER_LENGTH

Return to Play macros and constants

_10
#define SP_MAX_REFERRER_LENGTH 16

Maximum length of the referrer.

See also

Data Structures


SpSourceInfo

Return to Play data structures

Metadata for identifying where a playback request originated from.

See also

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

char 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 Play data structures

PlayOptions passed to SpPlayUriWithOptions


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

int from_index Track index in the Context from which playback should start.
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 shuffle mode for the requested playback command.
const struct SpSourceInfo * source_info Metadata about what user action caused this playback event, and the expected result.

Functions


SpPlayUri()

Return to Play functions

_10
SpError SpPlayUri(const char *uri, int index, int offset_ms, const struct SpSourceInfo *source, int alias_index)

Start local playback of any Spotify URI.

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

Parameters

[in]const char * uriURI of resource (ex: spotify:album:6tSdnCBm5HCAjwNxWfUC7m)
[in]int alias_ indexThe zero based index of the item to start playing in the resource (for instance, '4' would play the 5th track in a playlist). Set to zero if resource does not have multiple items. In eSDK 3, this can be set to SP_NO_INDEX if no specific index is required. In case of non-shuffled context this will result in first track of the context being played whereas in shuffled context this will result in a random track being played.
[in]int offset_msThe time offset to start playing specified track from. Set to zero to start from the beginning.
[in]const struct SpSourceInfo * sourceMetadata about what user action caused this playback event, and the expected result. This information is used to correct behavior when the exact request isn't possible, and to enable better recommendations and suggestions for users. This field is optional, but MUST be provided whenever possible. Failure to fill in this data accurately will result in a downgraded Spotify experience.
[in]int alias_indexThe index of the device alias to start playback on. If aliases aren't used, pass -1.

Returns

Returns an error code

See also

SpPlayUriWithOptions()

Return to Play functions

_10
SpError SpPlayUriWithOptions(const char *uri, const struct SpPlayOptions *opts, int alias_index)

Play Uri with SpPlayOptions

Parameters

[in]const char * uriThe context URI to play.
[in]const struct SpPlayOptions * optsThe options to apply to the play command.
[in]int alias_indexDevice alias index.

Returns

Returns an error code

SpPlayContextUri()

Return to Play functions

_10
SpError SpPlayContextUri(const char *uri, const char *from_uid, int offset_ms, const struct SpSourceInfo *source, int alias_index)

Start local playback of any 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 expected_track_uri parameter in SpPlayUri is that while one track URI can occur more than once in the context, UIDs are unique for each track in it. Valid Spotify URIs can be obtained via the Spotify Web API. Track UIDs are currently available when resolving contexts from a small subset of services. Using this call will 'pull' playback from any other Spotify Connect client active on the same account.

Parameters

[in]const char * uriURI of resource (ex: spotify:album:6tSdnCBm5HCAjwNxWfUC7m)
[in]const char * from_uidThe UID to identify a unique track in the context.
[in]int offset_msThe time offset to start playing specified track from. Set to zero to start from the beginning.
[in]const struct SpSourceInfo * sourceMetadata about what user action caused this playback event, and the expected result. This information is used to correct behavior when the exact request isn't possible, and to enable better recommendations and suggestions for users. This field is optional, but MUST be provided whenever possible. Failure to fill in this data accurately will result in a downgraded Spotify experience.
[in]int alias_indexThe index of the device alias to start playback on. If aliases aren't used, pass -1.

Returns

Returns an error code

SpQueueUri()

Return to Play functions

_10
SpError SpQueueUri(const char *uri)

Queue a URI. The track will be in queue only after kSpPlaybackNotifyQueuedTrackAccepted event is raised, but for UI purposes one can choose to monitor for kSpPlaybackNotifyMetadataChanged instead.

Parameters

[in]const char * uriURI to queue.

Returns

Returns an error code.

SpPlaybackBecomeActiveDevice()

Return to Play functions

_10
SpError SpPlaybackBecomeActiveDevice(int alias_index)

Become active without starting to play.

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

Parameters

[in]int alias_indexThe index of the device alias that should become active. If aliases aren't used, pass -1.

Returns

Returns an error code

SpPlayPresetEx()

Return to Play functions

_10
SpError SpPlayPresetEx(int preset_id, uint8_t *buffer, size_t buff_size, int relative_index, uint32_t offset_ms, const struct SpSourceInfo *source, int alias_index)

Extension for SpPlayPreset: Play a saved preset from different position, optionally with source info.

Note: This is an experimental extension, and is not guaranteed to be stable.

Parameters

[in]int preset_idSame as

Returns

Returns an error code

See also

Storage



_10
#include "spotify_embedded_storage.h"

Data Structures


Return to header index
SpDiskStorageCallbacks Callbacks to be registered with SpRegisterDataCacheCallbacks

Typedefs


Return to header index
SpCallbackStorageAlloc Callback to allocate space for resource being stored. Each successful alloc call is accompanied with 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 read all required data close callback is called to notify the user that data handle referenced by storage_key can be closed.
SpCallbackStorageClose Callback to inform the user that data handle referenced by storage_key can be closed.
SpCallbackStorageDelete Callback to inform the user that data referenced by storage_key should be deleted from storage.
SpCallbackThrottleRequest eSDK calls this callback to figure out if it needs to limit write access to the storage.

Functions


Return to header index
SpRegisterStorageCallbacks Register storage callbacks.

Data Structures


SpDiskStorageCallbacks

Return to Storage data structures

Callbacks to be registered with SpRegisterDataCacheCallbacks

Storage callbacks must be either all NULLs or all valid pointers. Throttle callback maybe be NULL regardless of storage callbacks value. See the documentation of the callback typedefs for information about the individual callbacks.


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

SpCallbackStorageAlloc alloc_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 client if disk writes needs to be throttled.

Typedefs


SpCallbackStorageAlloc()

Return to Storage Typedefs

_10
typedef enum SpCallbackStorageAlloc)(const char *storage_key, uint32_t total_size, void *context)

Callback to allocate space for resource being stored. Each successful alloc call is accompanied with 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 SpRegisterDiskStorageCallbacks

Parameters

[in]const char * storage_keyStorage key identifying the record
[in]uint32_t total_sizeThe full resource size in bytes or 0 if size is not known.
[in]void * contextContext pointer that was passed when registering the callback.
See also Notes:
  • The allocation of space should be done in the way that following read and write operations will succeed within the specified resource size.

SpCallbackStorageWrite()

Return to Storage Typedefs

_10
typedef int(* SpCallbackStorageWrite)(const char *storage_key, uint32_t offset, const void *data, uint32_t data_size, void *context)

Callback for writing the data into storage. Before writing to the storage eSDK does one of two things: call alloc to reserve space for future write or call read to get the data. After that eSDK writes the data into storage. Once write is fully complete eSDK calls close callback.

To register this callback, use the function SpRegisterDiskStorageCallbacks

Parameters

[in]const char * storage_keyStorage key identifying the record
[in]uint32_t offsetThe offset in bytes in the resource we are writing to.
[in]const void * dataA pointer to the buffer containing the data to be written to storage.
[in]uint32_t data_sizeThe number of bytes to be written to the storage.
[in]void * contextContext pointer that was passed when registering the callback.
See also Notes:
  • The application should not block or call other API functions in the callback. Offset field must always be respected on write operation. Application should consume whole data in the call.

SpCallbackStorageRead()

Return to Storage Typedefs

_10
typedef int(* SpCallbackStorageRead)(const char *storage_key, uint32_t offset, void *data, uint32_t data_size, void *context)

Callback for reading the data. Once eSDK read all required data close callback is called to notify the user that data handle referenced by storage_key can be closed.

To register this callback, use the function SpRegisterDiskStorageCallbacks

Parameters

[in]const char * storage_keyStorage key identifying the record
[in]uint32_t offsetThe offset eSDK are reading from.
[out]void * dataA pointer to the buffer that receives the data read from storage.
[in]uint32_t data_sizeThe number bytes to read.
[in]void * contextContext pointer that was passed when registering the callback
See also Notes:
  • The application should not block or call other API functions in the callback. If no storage read is possible, just return 0.

SpCallbackStorageClose()

Return to Storage Typedefs

_10
typedef void(* SpCallbackStorageClose)(const char *storage_key, void *context)

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

To register this callback, use the function SpRegisterDiskStorageCallbacks

Parameters

[in]const char * storage_keyStorage key identifying the record
[in]void * contextContext pointer that was passed when registering the callback.
Notes:
  • The application should not block or call other API functions in the callback. This callback would be called for any successful Alloc. For any resource open caused by Read/Write API calls.

SpCallbackStorageDelete()

Return to Storage Typedefs

_10
typedef enum SpCallbackStorageDelete)(const char *storage_key, void *context)

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

To register this callback, use the function SpRegisterDiskStorageCallbacks

Parameters

[in]const char * storage_keyStorage key identifying the record.
[in]void * contextContext pointer that was passed when registering the callback.
Notes:
  • The application should not block or call other API functions in the callback.
  • If the deletion operation is expected to take some time the application shall return kSpAPITryAgain for the duration of the operation and kSpAPINoError once it has been completed. It is important to not block execution of eSDK for prolonged periods (ideally less than 10ms). This callback can be called for literally any storage_key.

SpCallbackThrottleRequest()

Return to Storage Typedefs

_10
typedef int(* SpCallbackThrottleRequest)(const char *storage_key, void *context)

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

Parameters

[in]const char * storage_keyStorage key identifying the record.
[in]void * contextContext pointer that was passed when registering the callback.
Notes:
  • The application should not block or call other API functions in the callback.

Functions


SpRegisterStorageCallbacks()

Return to Storage functions

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

Register storage callbacks.

Parameters

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

Returns

Returns an error code

Tls



_10
#include "spotify_embedded_tls.h"

Data Structures


Return to header index
SpTLSCallbacks Callbacks to be registered with SpRegisterTLSCallbacks

Typedefs


Return to header index
SpCallbackTLSInit This callback is invoked by eSDK to let the TLS library integration perform any one-time initialization.
SpCallbackTLSDeinit This callback is invoked by eSDK to let the TLS library integration perform deallocation of resource 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 frees the memory used by them.

Data Structures


SpTLSCallbacks

Return to Tls data structures

Callbacks to be registered with SpRegisterTLSCallbacks

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


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

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

Typedefs


SpCallbackTLSInit()

Return to Tls Typedefs

_10
typedef enum SpCallbackTLSInit)(void *context)

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

Parameters

[in]void * contextContext provided in callback register function.
Notes:
  • The application should not block or call other API functions in the callback.

SpCallbackTLSDeinit()

Return to Tls Typedefs

_10
typedef enum SpCallbackTLSDeinit)(void *context)

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

Parameters

[in]void * contextContext provided in callback register function.
Notes:
  • The application should not block or call other API functions in the callback.

SpCallbackTLSCreate()

Return to Tls Typedefs

_10
typedef enum SpCallbackTLSCreate)(struct SpSocketHandle *socket, const char *hostname, void *context)

This callback is invoked once in the beginning of every TLS connection.

The callback receives a socket via the pointer to SpSocketHandle that is already connected to the remote peer. This callback should typically allocate and setup all TLS related resources. The tls field of the SpSocketHandle should be used to store any connection specific state that is needed.

Parameters

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

SpCallbackTLSHandshake()

Return to Tls Typedefs

_10
typedef enum SpCallbackTLSHandshake)(struct SpSocketHandle *socket, void *context)

This callback is invoked by eSDK to perform the TLS handshake.

The callback is invoked repeatedly to perform the handshake. This callback is invoked repeatedly as long as it returns kSpAPITryAgain The peer verification is mandatory and the implementation of this callback must validate the peer certificate against a list of trusted CA certificates. Should return kSpAPIGenericError is the handshake failed. Any specific information about the reason for the failure will be returned in the SpCallbackTLSGetError call.

Parameters

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

SpCallbackTLSRead()

Return to Tls Typedefs

_10
typedef enum SpCallbackTLSRead)(struct SpSocketHandle *socket, void *buf, size_t len, size_t *actual, void *context)

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

Parameters

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

SpCallbackTLSWrite()

Return to Tls Typedefs

_10
typedef enum SpCallbackTLSWrite)(struct SpSocketHandle *socket, const void *buf, size_t len, size_t *actual, void *context)

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

Parameters

[in]struct SpSocketHandle * socketPointer to eSDK socket already connected to the remote peer.
[in]const void * bufPointer to buffer with data to be written.
[in]size_t lenNumber of bytes of data in buffer.
[out]size_t * actualNumber of byte actually written.
[in]void * contextContext provided in callback register function.
Notes:
  • The application should not block or call other API functions in the callback.

SpCallbackTLSClose()

Return to Tls Typedefs

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

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

Parameters

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

SpCallbackTLSGetError()

Return to Tls Typedefs

_10
typedef int(* SpCallbackTLSGetError)(struct SpSocketHandle *socket, char *buf, size_t len, void *context)

Callback invoked to get an error message for the last error.

The implementation of this callback should put a error message in the form of a zero-terminated string in the buffer pointed to by buf. This error message should describe the latest error returned by any of the other callback functions.

Parameters

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

Functions


SpRegisterTLSCallbacks()

Return to Tls functions

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

Register TLS-related callbacks.

Parameters

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

Returns

Returns an error code

Notes:

SpTLSAddCARootCert()

Return to Tls functions

_10
SpError SpTLSAddCARootCert(const uint8_t *certificate, size_t length, int *underlying_error)

Add root certificate to the eSDK TLS stack.

eSDK uses TLS secured HTTPS connections to download media files from CDN (Content Delivery Network) servers. The servers that CDN providers use are using certificates from common Certificate Authorities (CA). eSDK cannot read Certificate Authority (CA) root certificates from the operating system, but the integration has to provide the certificates. 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

Parameters

[in]const uint8_t * certificateEither a binary DER certificate or a string with a PEM-format certificate.

Returns

Returns kSpErrorInvalidArgument if the certificate could not be parsed kSpErrorAlreadyInitialized if the function is called between SpInit and SpFree. If the return value is kSpErrorInvalidArgument and underlying_error is non-NULL, there will be an error code from the underlying TLS stack (currently MbedTLS) returned in *underlying_error.

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

SpTLSFreeCARootCerts()

Return to Tls functions

_10
SpError SpTLSFreeCARootCerts(void)

Remove all certificates loaded on the TLS stack and frees the memory used by them.

Returns

kSpErrorUnavailable if the function is called between SpInit and SpFree.

Token



_10
#include "spotify_embedded_token.h"

Data Structures


Return to header index
SpTokenCallbacks Callbacks to be registered with SpRegisterTokenCallbacks

Typedefs


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

Functions


Return to header index
SpRegisterTokenCallbacks Register token callbacks.
SpConnectionRequestAccessToken Request an access token for the logged in user.
SpConnectionRequestAuthCode Request an authorization code for the logged in user.

Data Structures


SpTokenCallbacks

Return to Token data structures

Callbacks to be registered with SpRegisterTokenCallbacks

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


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

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

Typedefs


SpCallbackConnectionReceiveAccessToken()

Return to Token Typedefs

_10
typedef void(* SpCallbackConnectionReceiveAccessToken)(const char *token_json, int error, void *context)

Callback to deliver the access token requested by SpConnectionRequestAccessToken

Parameters

[in]const char * token_jsonA serialized JSON object containing the access token or an empty string if error is != 0. See Notes below.
[in]int errorAn internal error code or 0 on success. The token in token_json is only valid if this is 0.
[in]void * contextContext pointer that was passed then the callback was registered.
Notes:
  • The JSON object looks as follows: "accessToken":"tokendata", "expiresIn":expiryinseconds,//typically3600 "tokenType":"tokentype"//typically"Bearer"

SpCallbackConnectionReceiveAuthCode()

Return to Token Typedefs

_10
typedef void(* SpCallbackConnectionReceiveAuthCode)(const char *token_json, int error, void *context)

Callback to deliver the access token requested by SpConnectionRequestAuthCode

Parameters

[in]const char * token_jsonA serialized JSON object containing the access token or an empty string if error is != 0. See Notes below.
[in]int errorAn internal error code or 0 on success. The token in token_json is only valid if this is 0.
[in]void * contextContext pointer that was passed then the callback was registered.
Notes:
  • The JSON object looks as follows: "code":"tokendata", "redirectUri":"someUri"

Functions


SpRegisterTokenCallbacks()

Return to Token functions

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

Register token callbacks.

Parameters

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

Returns

Returns an error code

SpConnectionRequestAccessToken()

Return to Token functions

_10
SpError SpConnectionRequestAccessToken(const char *scope)

Request an access token for the logged in user.

scope A comma-separated list of scopes for the resulting access token. See https://developer.spotify.com/documentation/web-api/concepts/scopes/

Parameters

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

SpConnectionRequestAuthCode()

Return to Token functions

_10
SpError SpConnectionRequestAuthCode(const char *scope)

Request an authorization code for the logged in user.

Parameters

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