Wasabi ExpressPlay SDK for iOS  1.10
Data Structures | Macros | Typedefs | Enumerations | Functions
WSB_PlaylistProxy Class

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

Data Structures

struct  WSB_PlaylistProxy_MediaSourceParams
 Playlist Proxy URL parameters. 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_DEBUG_SESSION_KEY   (1<<2)
 In debug builds only, support HLS AES-128 encryption key access through a proxy URL. 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_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_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_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

#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
#define WSB_PP_FLAG_DEBUG_SESSION_KEY   (1<<2)

In debug builds only, support HLS AES-128 encryption key access through a proxy URL.

Since
1.8
#define WSB_PP_FLAG_ENCRYPTED_HLS   (1<<0)

Make Playlist Proxy produce encrypted HLS content.

The key material can be obtained through the WSB_PlaylistProxy_GetSessionKey call.

Since
1.8

Typedef Documentation

Enumeration Type Documentation

The media source type:

  • a single Marlin file (BBTS with index, PDCF, or DCF),
  • a Marlin HLS playlist,
  • a DASH URL.
See Also
WSB_PlaylistProxy_MakeUrl
Enumerator
WSB_PPMST_SINGLE_FILE 

Single Marlin content URL (BBTS with index, PDCF, or DCF)

WSB_PPMST_HLS 

Marlin HLS URL.

WSB_PPMST_DASH 

Marlin DASH URL.

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_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
selfpointer to variable where pointer to the newly created object is returned.
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
flagsWSB_PP_FLAG_* macros for the specific behaviors supported.
selfpointer to variable where pointer to the newly created object is returned.
Since
1.8
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
selfpointer to an earlier created playlist proxy instance.
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
selfpointer to an earlier created playlist proxy instance.
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
selfpointer to an earlier created playlist proxy instance.
auth_tokenclient allocated char array where the token is returned; if NULL, only the required size is returned in *token_size.
token_sizein/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_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.

Depending on the flags at the creation time, the Playlist Proxy may encrypt HLS output. See WSB_PP_FLAG_ENCRYPTED_HLS macro for additional information.

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

Parameters
selfpointer to an earlier created playlist proxy instance.
key_formatthe session key format requested
keyclient allocated byte array where the key is returned; if NULL, only the required size is returned in *key_size.
key_sizein/out parameter, length of the 'key' array on input and the number of bytes in the key on output.
Since
1.8
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
selfpointer to an earlier created playlist proxy instance.
media_sourcepath or URL to the Marlin media source
media_source_typetype of the media source URL/file name
media_source_paramsparameters 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, and WSB_CONTENT_TYPE_DCF for DCF content.
http_urlpointer 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_EXPORT WSB_Result WSB_PlaylistProxy_Start ( WSB_PlaylistProxy self)

Start proxy execution.

All the internal threads are created and started.

Parameters
selfpointer to an earlier created playlist proxy instance.
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
selfpointer to an earlier created playlist proxy instance.