WSB_PlaybackEnabler Class

High level Marlin protected content enabler module. More...

Functions
WSB_EXPORT WSB_Result	WSB_PlaybackEnabler_Create (WSB_RightsEnabler_EventListener listener, WSB_PlaybackEnabler **enabler)
	Creates an instance of a WSB_PlaybackEnabler object. More...
WSB_EXPORT WSB_Result	WSB_PlaybackEnabler_SetRightsEnablerOptions (WSB_PlaybackEnabler *self, WSB_UInt32 option_flags)
	Sets the options of the internal WSB_RightsEnabler object using the WSB_RIGHTSENABLER_OPTION_FLAG_* flags. More...
WSB_EXPORT WSB_Result	WSB_PlaybackEnabler_ResolveUrl (WSB_PlaybackEnabler *self, const char *url, SHI_Data **content_url)
	Resolves a URL that is potentially an MS3 URL into a content URL. More...
WSB_EXPORT WSB_Result	WSB_PlaybackEnabler_EnableMediaFile (WSB_PlaybackEnabler *self, WSB_MediaFile *file, const void *license_data, WSB_Size license_data_size)
	Tries all available avenues to obtain a working license for the content in a specified media file. More...
WSB_EXPORT WSB_Result	WSB_PlaybackEnabler_EnableContentId (WSB_PlaybackEnabler *self, const char *content_id, const char *sla_url, const void *license_data, WSB_Size license_data_size)
	Tries all available avenues to obtain a working license for the content with the specified content ID. More...
WSB_EXPORT WSB_Result	WSB_PlaybackEnabler_PerformPlayAction (WSB_PlaybackEnabler *self, SHI_ActionResult **action_result)
	Performs the play action on the license obtained through the WSB_PlaybackEnabler_EnableMediaFile call, which MUST occur before calling this method. More...
WSB_EXPORT WSB_Result	WSB_PlaybackEnabler_AcceptActionResult (WSB_PlaybackEnabler *self, WSB_KeyManager *key_manager, SHI_Action **action)
	This method must be called after the action result (assuming the right to play was granted) from the WSB_PlaybackEnabler_PerformPlayAction has been inspected and the caller has made sure that no critical unsupported callbacks/obligations were present. More...
WSB_EXPORT WSB_Result	WSB_PlaybackEnabler_Destroy (WSB_PlaybackEnabler *self)
	Destroys the WSB_PlaybackEnabler object. More...

Detailed Description

High level Marlin protected content enabler module.

Function Documentation

WSB_PlaybackEnabler_AcceptActionResult()

WSB_EXPORT WSB_Result WSB_PlaybackEnabler_AcceptActionResult	(	WSB_PlaybackEnabler *	self,
		WSB_KeyManager *	key_manager,
		SHI_Action **	action
	)

This method must be called after the action result (assuming the right to play was granted) from the WSB_PlaybackEnabler_PerformPlayAction has been inspected and the caller has made sure that no critical unsupported callbacks/obligations were present.

This method obtains the content keys and supplies them to the passed-in WSB_KeyManager.

Parameters

self	The WSB_PlaybackEnabler object.
key_manager	The WSB_KeyManager object that will be populated with content keys.
action	An optional address (can be NULL) of a SHI_Action pointer that will be set to refer to the internal SHI_Action object, which may be needed for exercising callbacks. The caller does NOT take ownership and therefore MUST NOT destroy the action.

Returns

This method returns WSB_SUCCESS in case of success, WSB_ERROR_INVALID_PARAMETERS if the self or key_manager parameters are set to NULL, WSB_ERROR_INVALID_STATE if this method called before a call to WSB_PlaybackEnabler_PerformPlayAction, WSB_ERROR_DRM_DENY_RIGHTS if the action result did not grant access to the content in the first place, WSB_ERROR_DRM_GET_KEY if the key cannot be retrieved, WSB_ERROR_NOT_SUPPORTED if the key format of the key manager is not supported, WSB_DRM_ERROR_UNKNOWN if an unexpected error was encountered.

WSB_PlaybackEnabler_Create()

WSB_EXPORT WSB_Result WSB_PlaybackEnabler_Create	(	WSB_RightsEnabler_EventListener	listener,
		WSB_PlaybackEnabler **	enabler
	)

Creates an instance of a WSB_PlaybackEnabler object.

Parameters

listener	An object that will receive various notification events during a WSB_PlaybackEnabler_EnableMediaFile call.
enabler	Address of a WSB_PlaybackEnabler pointer that will be set to refer to the WSB_PlaybackEnabler object created.

Returns

This method returns WSB_SUCCESS in case of success, WSB_ERROR_INVALID_PARAMETERS if the enabler parameter is NULL, WSB_ERROR_DRM_CLIENT_SYSTEM_ERROR if the enabler could not be created because the DRM client is in a bad state.

WSB_PlaybackEnabler_Destroy()

WSB_EXPORT WSB_Result WSB_PlaybackEnabler_Destroy

(

WSB_PlaybackEnabler *

self

)

Destroys the WSB_PlaybackEnabler object.

Parameters

self	The WSB_PlaybackEnabler object.

Returns

This method returns WSB_SUCCESS in case of success, WSB_ERROR_INVALID_PARAMETERS if the self parameter is set to NULL.

WSB_PlaybackEnabler_EnableContentId()

WSB_EXPORT WSB_Result WSB_PlaybackEnabler_EnableContentId	(	WSB_PlaybackEnabler *	self,
		const char *	content_id,
		const char *	sla_url,
		const void *	license_data,
		WSB_Size	license_data_size
	)

Tries all available avenues to obtain a working license for the content with the specified content ID.

Internally calls WSB_RightsEnabler_EnableContentId (see documentation). Any events that occur during that call are forwarded to the listener specified in the call to WSB_PlaybackEnabler_Create. Whenever a license is found, the license data will be forwarded to the listener in an event of type WSB_RIGHTSENABLER_EVENT_TYPE_LICENSE. The listener will decide whether the license is suitable or it wants the Rights Enabler to continue its license search.

Parameters

self	The WSB_PlaybackEnabler object.
content_id	Content ID.
sla_url	Optional silent license acquisition URL.
license_data	An optional license (can be NULL) obtained externally.
license_data_size	Size of the license_data, in bytes.

Returns

This method returns WSB_SUCCESS if a valid license (validated with the WSB_Config_ValidateActionResult method) was found, WSB_ERROR_INVALID_PARAMETERS if the self parameter is NULL, WSB_ERROR_DRM_UNKNOWN if an unexpected error was encountered, WSB_ERROR_DRM_DENY_RIGHTS if a valid license could not be found.

WSB_PlaybackEnabler_EnableMediaFile()

WSB_EXPORT WSB_Result WSB_PlaybackEnabler_EnableMediaFile	(	WSB_PlaybackEnabler *	self,
		WSB_MediaFile *	file,
		const void *	license_data,
		WSB_Size	license_data_size
	)

Tries all available avenues to obtain a working license for the content in a specified media file.

Internally calls WSB_RightsEnabler_EnableMediaFile (see documentation). Any events that occur during that call are forwarded to the listener specified in the call to WSB_PlaybackEnabler_Create. Whenever a license is found, the license data will be forwarded to the listener in an event of type WSB_RIGHTSENABLER_EVENT_TYPE_LICENSE. The listener will decide whether the license is suitable or it wants the Rights Enabler to continue its license search.

Parameters

self	The WSB_PlaybackEnabler object.
file	The media file to be enabled.
license_data	An optional license (can be NULL) obtained externally.
license_data_size	Size of the license_data, in bytes.

Returns

This method returns WSB_SUCCESS if a valid license (validated with the WSB_Config_ValidateActionResult method) was found, WSB_ERROR_INVALID_PARAMETERS if the self or file parameters are NULL, WSB_ERROR_DRM_BAD_CONTENT_FORMAT if the needed information cannot be found in the media file, WSB_ERROR_DRM_UNKNOWN if an unexpected error was encountered, WSB_ERROR_DRM_DENY_RIGHTS if the media file is valid but a valid license could not be found.

WSB_PlaybackEnabler_PerformPlayAction()

WSB_EXPORT WSB_Result WSB_PlaybackEnabler_PerformPlayAction	(	WSB_PlaybackEnabler *	self,
		SHI_ActionResult **	action_result
	)

Performs the play action on the license obtained through the WSB_PlaybackEnabler_EnableMediaFile call, which MUST occur before calling this method.

That is, this method determines whether the license allows playback of the content it governs, and the result is stored in a SHI_ActionResult object created by this call. (See Sushi documentation.) A WSB_Result of WSB_SUCCESS does NOT mean that the play action is granted. The SHI_ActionResult must be examined to determine that.

Parameters

self	The WSB_PlaybackEnabler object.
action_result	Address of a SHI_ActionResult pointer that will be set to refer to the resulting SHI_ActionResult object. The caller does NOT take ownership and therefore MUST NOT release the SHI_ActionResult.

Returns

This method returns WSB_SUCCESS in case of success, WSB_ERROR_INVALID_PARAMETERS if the self or action_result parameters are set to NULL, WSB_ERROR_INVALID_STATE if this method was called before a call to WSB_PlaybackEnabler_EnablerMediaFile, WSB_ERROR_DRM_BAD_LICENSE_FORMAT if the hmac signature verification on the license failed, WSB_ERROR_DRM_UNKNOWN if an unexpected error was encountered.

WSB_PlaybackEnabler_ResolveUrl()

WSB_EXPORT WSB_Result WSB_PlaybackEnabler_ResolveUrl	(	WSB_PlaybackEnabler *	self,
		const char *	url,
		SHI_Data **	content_url
	)

Resolves a URL that is potentially an MS3 URL into a content URL.

In the case of an MS3 URL, this method will trigger one or more server connections in order to retrive the stream access statement and the content URL.

Parameters

self	The WSB_PlaybackEnabler object.
url	The URL to resolve.
content_url	The content URL (as a string).

Returns

This method returns WSB_SUCCESS in case of success, WSB_ERROR_INVALID_PARAMETERS if any of the parameters is NULL, WSB_ERROR_DRM_INVALID_URL if the URL is invalid, WSB_ERROR_DRM_BAD_SERVER_RESPONSE if a server response is invalid, WSB_ERROR_DRM_CLIENT_SYSTEM_ERROR if the DRM client is in a bad state, WSB_ERROR_DRM_DENIED_BY_SERVER if the resource pointed directly or indirectly by this URL has its access denied by the server, WSB_ERROR_DRM_SERVER_UNREACHABLE if a server addressed directly or indirectly by this URL could not be reached, WSB_ERROR_DRM_UNKNOWN for all other error conditions.

WSB_PlaybackEnabler_SetRightsEnablerOptions()

WSB_EXPORT WSB_Result WSB_PlaybackEnabler_SetRightsEnablerOptions	(	WSB_PlaybackEnabler *	self,
		WSB_UInt32	option_flags
	)

Sets the options of the internal WSB_RightsEnabler object using the WSB_RIGHTSENABLER_OPTION_FLAG_* flags.

By default, all flags are off.

Parameters

self	The WSB_PlaybackEnabler object.
option_flags	The option flags.

Returns

This method returns WSB_SUCCESS in case of success, WSB_ERROR_INVALID_PARAMETERS if the self parameter is NULL.