An HTTP proxy for in-application Marlin media access. More...

Data Structures
struct	WSB_PlaylistProxy_MediaSourceParams
	Playlist Proxy URL parameters. More...

struct	WSB_PlaylistProxy_Event
	Event base class. More...

struct	WSB_PlaylistProxy_ErrorNotificationEvent
	Error notification event. More...

struct	WSB_PlaylistProxy_EventListener
	This structure pairs a listener instance value with a function pointer for receiving events. More...

Macros
#define	WSB_PP_FLAG_ENCRYPTED_HLS (1<<0)
	Make Playlist Proxy produce encrypted HLS content. More...

#define	WSB_PP_FLAG_AUTH_TOKEN_HEADER (1<<1)
	Make Playlist Proxy require client authentication token in the request HTTP header 'Wasabi-AuthToken'. More...

#define	WSB_PP_FLAG_SESSION_KEY (1<<2)
	Enables HLS AES-128 encryption key access through the HLS Key Tag line with a URL served by the Proxy. More...

#define	WSB_PP_FLAG_BLOCK_FOR_LICENSE_IMPLICIT (1<<3)
	Instruct proxy not to perform license lookup and evaluation until client requests protected fragments. More...

#define	WSB_PP_FLAG_BLOCK_FOR_LICENSE_EXPLICIT (1<<4)
	Instruct proxy not to perform license lookup and evaluation until the application invokes WSB_PlaylistProxy_UnblockForLicense. More...

#define	WSB_PP_FLAG_NO_SHORT_URLS (1<<5)
	Disable the mapping of proxy URLs to short URLs. More...

#define	WSB_PP_FLAG_ALLOW_EXTERNAL_CLIENT (1<<6)
	Allow HTTP client external to the device. More...

#define	WSB_PP_FLAG_FAIRPLAY_ENCRYPTED_HLS (1<<7)
	Make Playlist Proxy produce Fairplay encrypted HLS content. More...

#define	WSB_PP_FLAG_DEMUXED_HLS (1<<8)
	Make Playlist Proxy produce Demuxed Clear HLS content. More...

Typedefs
typedef struct WSB_PlaylistProxy	WSB_PlaylistProxy

Enumerations
enum	WSB_PlaylistProxy_MediaSourceType { WSB_PPMST_SINGLE_FILE, WSB_PPMST_HLS, WSB_PPMST_DASH }
	The media source type: More...

enum	WSB_PlaylistProxy_TrackSelector { WSB_PP_TRACK_ANY = 0, WSB_PP_TRACK_BY_ID, WSB_PP_TRACK_BY_INDEX }
	Media track selector mode. More...

enum	WSB_PlaylistProxy_LicenseType { WSB_PPLT_NONE, WSB_PPLT_MS3_SURL, WSB_PPLT_BB_TOKEN }

enum	WSB_PlaylistProxy_EventType { WSB_PPET_ERROR_NOTIFICATION = 0 }
	Event type. More...

enum	WSB_PlaylistProxySessionKeyFormat { WSB_PPSKF_CLEAR, WSB_PPSKF_SKB }
	The session key format enum. More...

Functions
WSB_EXPORT WSB_Result	WSB_PlaylistProxy_Create (WSB_PlaylistProxy **self)
	Create a playlist proxy instance. More...

WSB_EXPORT WSB_Result	WSB_PlaylistProxy_CreateWithFlags (WSB_UInt32 flags, WSB_PlaylistProxy **self)
	Create a playlist proxy instance with additional behavior selected through the flags. More...

WSB_EXPORT WSB_Result	WSB_PlaylistProxy_CreateWithListener (WSB_UInt32 flags, const WSB_PlaylistProxy_EventListener listener, WSB_PlaylistProxy **self)
	Create a playlist proxy instance with additional behavior selected through the flags and optional event listener that will receive the event callbacks. More...

WSB_EXPORT WSB_Result	WSB_PlaylistProxy_Destroy (WSB_PlaylistProxy *self)
	Destroy a playlist proxy instance. More...

WSB_EXPORT WSB_Result	WSB_PlaylistProxy_Start (WSB_PlaylistProxy *self)
	Start proxy execution. More...

WSB_EXPORT WSB_Result	WSB_PlaylistProxy_UnblockForLicense (WSB_PlaylistProxy self, WSB_PlaylistProxy_LicenseType type, const void license_data, WSB_Size license_length)
	Notify the proxy to proceed with license lookup and evaluation. More...

WSB_EXPORT WSB_Result	WSB_PlaylistProxy_Stop (WSB_PlaylistProxy *self)
	Stop proxy execution. More...

WSB_EXPORT WSB_Result	WSB_PlaylistProxy_GetAndClearLastError (WSB_PlaylistProxy *self)
	Return the most recent Wasabi error (if any) detected by the proxy threads and clear it. More...

WSB_EXPORT WSB_Result	WSB_PlaylistProxy_MakeUrl (WSB_PlaylistProxy self, const char media_source, WSB_PlaylistProxy_MediaSourceType media_source_type, const WSB_PlaylistProxy_MediaSourceParams media_source_params, const char *http_url)
	Create an HTTP url that points to the proxy. More...

WSB_EXPORT WSB_Result	WSB_PlaylistProxy_GetAuthToken (WSB_PlaylistProxy self, char auth_token, WSB_Size *token_size)
	Obtain the current Playlist Proxy authentication token. More...

WSB_EXPORT WSB_Result	WSB_PlaylistProxy_GetSessionKey (WSB_PlaylistProxy self, WSB_PlaylistProxySessionKeyFormat key_format, WSB_Byte key, WSB_Size *key_size)
	Obtain the current Playlist Proxy session key. More...

Detailed Description

An HTTP proxy for in-application Marlin media access.

Macro Definition Documentation

◆ WSB_PP_FLAG_ALLOW_EXTERNAL_CLIENT

#define WSB_PP_FLAG_ALLOW_EXTERNAL_CLIENT (1<<6)

Allow HTTP client external to the device.

This option is required to enable playback through AirPlay, e.g. on an AppleTV.

Since: 1.14

◆ WSB_PP_FLAG_AUTH_TOKEN_HEADER

#define WSB_PP_FLAG_AUTH_TOKEN_HEADER (1<<1)

Make Playlist Proxy require client authentication token in the request HTTP header 'Wasabi-AuthToken'.

The authentication token can be obtained through the WSB_PlaylistProxy_GetAuthToken call.

Since: 1.8

◆ WSB_PP_FLAG_BLOCK_FOR_LICENSE_EXPLICIT

#define WSB_PP_FLAG_BLOCK_FOR_LICENSE_EXPLICIT (1<<4)

Instruct proxy not to perform license lookup and evaluation until the application invokes WSB_PlaylistProxy_UnblockForLicense.

Since: 1.11 HLS; 1.13 DASH

See also: WSB_PlaylistProxy_UnblockForLicense

◆ WSB_PP_FLAG_BLOCK_FOR_LICENSE_IMPLICIT

#define WSB_PP_FLAG_BLOCK_FOR_LICENSE_IMPLICIT (1<<3)

Instruct proxy not to perform license lookup and evaluation until client requests protected fragments.

Since: 1.11 HLS; 1.13 DASH

◆ WSB_PP_FLAG_DEMUXED_HLS

#define WSB_PP_FLAG_DEMUXED_HLS (1<<8)

Make Playlist Proxy produce Demuxed Clear HLS content.

The output HLS stream will be demuxed to Audio only and Video only media playlists.

Since: 1.22

◆ WSB_PP_FLAG_ENCRYPTED_HLS

#define WSB_PP_FLAG_ENCRYPTED_HLS (1<<0)

Make Playlist Proxy produce encrypted HLS content.

The output HLS stream will be encrypted using the HLS AES-128 method.

The key material can be obtained through the WSB_PlaylistProxy_GetSessionKey call, and/or using the WSB_PP_FLAG_SESSION_KEY flag the key can be included in the HLS Playlist Key Tag.

See also: WSB_PlaylistProxy_GetSessionKey; WSB_PP_FLAG_SESSION_KEY

Since: 1.8

◆ WSB_PP_FLAG_FAIRPLAY_ENCRYPTED_HLS

#define WSB_PP_FLAG_FAIRPLAY_ENCRYPTED_HLS (1<<7)

Make Playlist Proxy produce Fairplay encrypted HLS content.

The output HLS stream will be encrypted using the SAMPLE-AES method. Input must be DASH-CENC/FMP4 content with Marlin signalling Other inputs have unexpected behaviour

Since: 1.20

◆ WSB_PP_FLAG_NO_SHORT_URLS

#define WSB_PP_FLAG_NO_SHORT_URLS (1<<5)

Disable the mapping of proxy URLs to short URLs.

Since: 1.12

◆ WSB_PP_FLAG_SESSION_KEY

#define WSB_PP_FLAG_SESSION_KEY (1<<2)

Enables HLS AES-128 encryption key access through the HLS Key Tag line with a URL served by the Proxy.

Alternatively, the HLS encryption key can be obtained through the WSB_PlaylistProxy_GetSessionKey call.

This flag makes sense only if the WSB_PP_FLAG_ENCRYPTED_HLS is also set.

See also: WSB_PlaylistProxy_GetSessionKey; WSB_PP_FLAG_ENCRYPTED_HLS

Since: 1.8

Typedef Documentation

◆ WSB_PlaylistProxy

typedef struct WSB_PlaylistProxy WSB_PlaylistProxy

Enumeration Type Documentation

◆ WSB_PlaylistProxy_EventType

enum WSB_PlaylistProxy_EventType

Event type.

Since: 1.13

Enumerator
WSB_PPET_ERROR_NOTIFICATION	Error notification event.

◆ WSB_PlaylistProxy_LicenseType

enum WSB_PlaylistProxy_LicenseType

Since: 1.11

Enumerator
WSB_PPLT_NONE
WSB_PPLT_MS3_SURL
WSB_PPLT_BB_TOKEN

◆ WSB_PlaylistProxy_MediaSourceType

enum WSB_PlaylistProxy_MediaSourceType

The media source type:

a single Marlin file (BBTS with index, PDCF, M4F or DCF),
a Marlin HLS playlist,
a DASH URL.

NOTE: the BB license or MS3 SAS used with DCF must relax the default Marlin output controls or the content will not be decrypted. This requires the SAS to carry an MS3 extension (of type 'wudo') or the Marlin Broadband license to indicate a Marlin Broadband output control override (type 'urn:marlin:organization:intertrust:wudo').

See also: WSB_PlaylistProxy_MakeUrl

Enumerator
WSB_PPMST_SINGLE_FILE	Single Marlin content URL (BBTS with index, PDCF, M4F, or DCF)
WSB_PPMST_HLS	Marlin HLS URL.
WSB_PPMST_DASH	Marlin DASH URL.

◆ WSB_PlaylistProxy_TrackSelector

enum WSB_PlaylistProxy_TrackSelector

Media track selector mode.

Since: 1.13.4

Enumerator
WSB_PP_TRACK_ANY	Any media track of the correct type.
WSB_PP_TRACK_BY_ID	Specific track selected by the track ID.
WSB_PP_TRACK_BY_INDEX	Specific track selected by the track index (0 based among all tracks).

◆ WSB_PlaylistProxySessionKeyFormat

enum WSB_PlaylistProxySessionKeyFormat

The session key format enum.

Since: 1.8

Enumerator
WSB_PPSKF_CLEAR	Clear AES-128 key.
WSB_PPSKF_SKB	SKB exported AES-128 key.

Function Documentation

◆ WSB_PlaylistProxy_Create()

WSB_EXPORT WSB_Result WSB_PlaylistProxy_Create ( WSB_PlaylistProxy ** self )

Create a playlist proxy instance.

Proxy internally creates several threads necessary for the operation of the proxy.

This call is equivalent to: WSB_PlaylistProxy_CreateWithFlags(0, self).

Parameters

self	pointer to variable where pointer to the newly created object is returned.

◆ WSB_PlaylistProxy_CreateWithFlags()

WSB_EXPORT WSB_Result WSB_PlaylistProxy_CreateWithFlags	(	WSB_UInt32	flags,
		WSB_PlaylistProxy **	self
	)

Create a playlist proxy instance with additional behavior selected through the flags.

Parameters

flags	WSB_PP_FLAG_* macros for the specific behaviors supported.
self	pointer to variable where pointer to the newly created object is returned.

Since: 1.8

◆ WSB_PlaylistProxy_CreateWithListener()

WSB_EXPORT WSB_Result WSB_PlaylistProxy_CreateWithListener	(	WSB_UInt32	flags,
		const WSB_PlaylistProxy_EventListener	listener,
		WSB_PlaylistProxy **	self
	)

Create a playlist proxy instance with additional behavior selected through the flags and optional event listener that will receive the event callbacks.

For iOS and Mac, the event listener implemented in Objective-C will be called in the main thread.

For Android, the event listener implemented in Java will be called in the thread where android.os.Handler object is instantiated and passed into the playlist proxy, see the Java playlist proxy interface for more details.

For Windows and Linux, the event listener will be called in the playlist proxy thread that initiates the event.

It is important to note that the implementation of the event listener should not call any playlist proxy methods.

Parameters

flags	WSB_PP_FLAG_* macros for the specific behaviors supported.
listener	an optional object that will receive various notification events.
self	pointer to variable where pointer to the newly created object is returned.

Since: 1.13

◆ WSB_PlaylistProxy_Destroy()

WSB_EXPORT WSB_Result WSB_PlaylistProxy_Destroy ( WSB_PlaylistProxy * self )

Destroy a playlist proxy instance.

Stops any internal threads, and destroys all the state associated with the proxy.

Parameters

self	pointer to an earlier created playlist proxy instance.

◆ WSB_PlaylistProxy_GetAndClearLastError()

WSB_EXPORT WSB_Result WSB_PlaylistProxy_GetAndClearLastError ( WSB_PlaylistProxy * self )

Return the most recent Wasabi error (if any) detected by the proxy threads and clear it.

The error is also returned as an HTTP header in the HTTP response to the media player. That is, the HTTP response supplied by the Playlist Proxy in response to an HTTP Request includes a Wasabi-Result header that contains the Wasabi result code from processing of the request.

A code of 0 indicates success. Any other code indicates failure. Any errors detected by proxy threads are accessible via WSB_PlaylistProxy_GetAndClearLastError.

If there are no errors, this method returns WSB_SUCCESS. Once the most-recent-error status code has been requested, it is cleared.

Parameters

self	pointer to an earlier created playlist proxy instance.

◆ WSB_PlaylistProxy_GetAuthToken()

WSB_EXPORT WSB_Result WSB_PlaylistProxy_GetAuthToken	(	WSB_PlaylistProxy *	self,
		char *	auth_token,
		WSB_Size *	token_size
	)

Obtain the current Playlist Proxy authentication token.

Depending on the flags at the creation time, the Playlist Proxy may require the authentication token in the HTTP request headers. See WSB_PP_FLAG_AUTH_TOKEN_HEADER macro for additional information.

If the *token_size is not large enough to accommodate the authentication token the error WSB_ERROR_NOT_ENOUGH_SPACE is returned.

Parameters

self	pointer to an earlier created playlist proxy instance.
auth_token	client allocated char array where the token is returned; if NULL, only the required size is returned in *token_size.
token_size	in/out parameter, length of the auth_token array on input and the number of characters in the auth_token on output, including the terminating '\0'.

Since: 1.8

◆ WSB_PlaylistProxy_GetSessionKey()

WSB_EXPORT WSB_Result WSB_PlaylistProxy_GetSessionKey	(	WSB_PlaylistProxy *	self,
		WSB_PlaylistProxySessionKeyFormat	key_format,
		WSB_Byte *	key,
		WSB_Size *	key_size
	)

Obtain the current Playlist Proxy session key.

The Playlist Proxy must have been created with the WSB_PP_FLAG_ENCRYPTED_HLS flag.

If the *key_size is not large enough to accommodate the HLS encryption key the error WSB_ERROR_NOT_ENOUGH_SPACE is returned.

Parameters

self	pointer to an earlier created playlist proxy instance.
key_format	the session key format requested
key	client allocated byte array where the key is returned; if NULL, only the required size is returned in *key_size.
key_size	in/out parameter, length of the 'key' array on input and the number of bytes in the key on output.

Since: 1.8

◆ WSB_PlaylistProxy_MakeUrl()

WSB_EXPORT WSB_Result WSB_PlaylistProxy_MakeUrl	(	WSB_PlaylistProxy *	self,
		const char *	media_source,
		WSB_PlaylistProxy_MediaSourceType	media_source_type,
		const WSB_PlaylistProxy_MediaSourceParams *	media_source_params,
		const char **	http_url
	)

Create an HTTP url that points to the proxy.

The result string is owned by the proxy object and is valid only until the next call to WSB_PlaylistProxy_MakeUrl. Therefore, the caller should copy and save the result if the value needs to survive other calls to WSB_PlaylistProxy_MakeUrl.

Parameters

self	pointer to an earlier created playlist proxy instance.
media_source	path or URL to the Marlin media source
media_source_type	type of the media source URL/file name
media_source_params	parameters further describing the media source. May be NULL if no parameters are required. However, if the media_source_type is WSB_PPMST_SINGLE_FILE, then media_source_params must be provided and the media_source_params.source_content_type must be set to the one of WSB_CONTENT_TYPE_VIDEO_MPEG2TS for BBTS, WSB_CONTENT_TYPE_VIDEO_MP4 or WSB_CONTENT_TYPE_AUDIO_MP4 for PDCF or M4F, and WSB_CONTENT_TYPE_DCF for DCF content.

NOTE: the BB license or MS3 SAS used with DCF must relax the default Marlin output controls or the content will not be decrypted. This requires the SAS to carry an MS3 extension (of type 'wudo') or a the Marlin Broadband license to indicate a Marlin Broadband output control override (type 'urn:marlin:organization:intertrust:wudo').

Parameters

http_url pointer to variable where pointer to the rewritten HTTP URL is returned. This URL includes a session ID, which identifies the session for accessing the specified Marlin media file or playlist. When a request is made using the URL, the Playlist Proxy ensures the request includes the appropriate session ID, thereby preventing other applications from unauthorized access.

◆ WSB_PlaylistProxy_Start()

WSB_EXPORT WSB_Result WSB_PlaylistProxy_Start ( WSB_PlaylistProxy * self )

Start proxy execution.

All the internal threads are created and started.

Parameters

self	pointer to an earlier created playlist proxy instance.

◆ WSB_PlaylistProxy_Stop()

WSB_EXPORT WSB_Result WSB_PlaylistProxy_Stop ( WSB_PlaylistProxy * self )

Stop proxy execution.

All the internal threads are stopped. No new requests are taken.

Important: The client application should stop the media player before trying to stop the Playlist Proxy. Otherwise, the application may deadlock.

Parameters

self	pointer to an earlier created playlist proxy instance.

◆ WSB_PlaylistProxy_UnblockForLicense()

WSB_EXPORT WSB_Result WSB_PlaylistProxy_UnblockForLicense	(	WSB_PlaylistProxy *	self,
		WSB_PlaylistProxy_LicenseType	type,
		const void *	license_data,
		WSB_Size	license_length
	)

Notify the proxy to proceed with license lookup and evaluation.

The call is asynchronous with actual license lookup and evaluation.

The proxy must have been created with the WSB_PP_FLAG_BLOCK_FOR_LICENSE_EXPLICIT.

Parameters

self	pointer to an earlier created playlist proxy instance.
type	license type, corresponding to the data in license_data, or WSB_PPLT_NONE if not license provided in the arguments
license_data	pointer to the start of license data
license_length	length in bytes of the license data

See also: WSB_PP_FLAG_BLOCK_FOR_LICENSE_EXPLICIT

Since: 1.11 HLS; 1.13 DASH

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ WSB_PP_FLAG_ALLOW_EXTERNAL_CLIENT

◆ WSB_PP_FLAG_AUTH_TOKEN_HEADER

◆ WSB_PP_FLAG_BLOCK_FOR_LICENSE_EXPLICIT

◆ WSB_PP_FLAG_BLOCK_FOR_LICENSE_IMPLICIT

◆ WSB_PP_FLAG_DEMUXED_HLS

◆ WSB_PP_FLAG_ENCRYPTED_HLS

◆ WSB_PP_FLAG_FAIRPLAY_ENCRYPTED_HLS

◆ WSB_PP_FLAG_NO_SHORT_URLS

◆ WSB_PP_FLAG_SESSION_KEY

Typedef Documentation

◆ WSB_PlaylistProxy

Enumeration Type Documentation

◆ WSB_PlaylistProxy_EventType

◆ WSB_PlaylistProxy_LicenseType

◆ WSB_PlaylistProxy_MediaSourceType

◆ WSB_PlaylistProxy_TrackSelector

◆ WSB_PlaylistProxySessionKeyFormat

Function Documentation

◆ WSB_PlaylistProxy_Create()

◆ WSB_PlaylistProxy_CreateWithFlags()

◆ WSB_PlaylistProxy_CreateWithListener()

◆ WSB_PlaylistProxy_Destroy()

◆ WSB_PlaylistProxy_GetAndClearLastError()

◆ WSB_PlaylistProxy_GetAuthToken()

◆ WSB_PlaylistProxy_GetSessionKey()

◆ WSB_PlaylistProxy_MakeUrl()

◆ WSB_PlaylistProxy_Start()

◆ WSB_PlaylistProxy_Stop()

◆ WSB_PlaylistProxy_UnblockForLicense()