The central object for DRM interaction. More...

Typedefs
typedef struct SHI_Engine	SHI_Engine
	A SHI_Engine object is the initial point of interaction between an application and a DRM Engine. More...

Functions
SHI_PUBLIC_API void *	SHI_Engine_GetInterface (SHI_Engine *self, SHI_InterfaceId iface_id)
	Obtains a pointer to a SHI_Engine object with a different interface. More...

SHI_PUBLIC_API SHI_Result	SHI_Engine_Destroy (SHI_Engine *self)
	Destroys this engine object. More...

SHI_PUBLIC_API SHI_Boolean	SHI_Engine_IsPersonalized (SHI_Engine *self)
	Indicates whether or not this engine has been personalized. More...

SHI_PUBLIC_API SHI_Result	SHI_Engine_Personalize (SHI_Engine self, const char token, SHI_Size token_size, const void *cookie)
	Requests that this engine engage in the personalization process. More...

SHI_PUBLIC_API SHI_Result	SHI_Engine_UpdatePersonality (SHI_Engine self, const char token, SHI_Size token_size, const void *cookie)
	Requests that this engine engage in the personality update process to renew its public credentials. More...

SHI_PUBLIC_API SHI_Result	SHI_Engine_GetTrustedTime (SHI_Engine self, SHI_DateTime now)
	Returns the current value of the trusted time. More...

SHI_PUBLIC_API SHI_Result	SHI_Engine_ProcessServiceToken (SHI_Engine self, const char token, SHI_Size token_size, const void *cookie)
	Requests that this engine process a service token, such as a Broadband Action Token. More...

SHI_PUBLIC_API SHI_Result	SHI_Engine_ProcessServiceTokenEx (SHI_Engine self, const char token, SHI_Size token_size, const void cookie, SHI_RegistrationDataManager registration_data_manager)
	Use this API instead of SHI_Engine_ProcessServiceToken if you want to overwrite the default behavior for saving and loading nodes and links during registration. More...

SHI_PUBLIC_API SHI_Result	SHI_Engine_EnumerateServices (SHI_Engine self, SHI_List *services)
	Gets the list of the services that are currently configured for this engine. More...

SHI_PUBLIC_API SHI_Result	SHI_Engine_EnumerateServiceUsers (SHI_Engine self, const char service_id, SHI_List **users)
	Gets a list of service users of one or more of this engine's configured services. More...

SHI_PUBLIC_API SHI_Result	SHI_Engine_EnumerateServiceSubscriptions (SHI_Engine self, const char service_id, const char user_id, SHI_List *subscriptions)
	Gets a list of subscriptions associated with one or more of the engine's configured services. More...

SHI_PUBLIC_API SHI_Result	SHI_Engine_CreateLicense (SHI_Engine self, SHI_License *license)
	Creates a new SHI_License object managed by this engine. More...

SHI_PUBLIC_API SHI_Result	SHI_Engine_UpdateSecurityData (SHI_Engine self, const char service_id, SHI_UInt32 last_update, const void *cookie)
	Updates security data for a specified service configured for this engine object. More...

SHI_PUBLIC_API SHI_Result	SHI_Engine_VacuumData (SHI_Engine *self, SHI_Flags vacuum_options)
	Removes expired data stored in Sushi's database. More...

SHI_PUBLIC_API SHI_Result	SHI_Engine_GetObjectDetails (SHI_Engine self, const char object_id, SHI_Attribute **details)
	Gets the details of this Octopus object. More...

SHI_PUBLIC_API SHI_Result	SHI_Engine_DeleteObject (SHI_Engine self, const char object_id)
	Removes the given Octopus object from the Sushi database. More...

SHI_PUBLIC_API SHI_Result	SHI_Engine_GetLinkIds (SHI_Engine self, SHI_Data *id_array)
	Gets list of all Octopus links known to this Sushi instance. More...

SHI_PUBLIC_API SHI_Result	SHI_Engine_GetNodeIds (SHI_Engine self, SHI_Data *id_array)
	Gets list of all Octopus nodes known to this Sushi instance. More...

SHI_PUBLIC_API SHI_Result	SHI_Engine_TransformURITemplate (SHI_Engine self, const char uri_template, SHI_Data **uri)
	Transforms a URI template according to the "URI Templates for Marlin" specification. More...

SHI_PUBLIC_API SHI_Result	SHI_Engine_GetCertificateChain (SHI_Engine self, SHI_EngineCertChain cert_chain, SHI_Data *cert_array)
	Get the certificates of the specified certificate chain. More...

SHI_PUBLIC_API SHI_Result	SHI_Engine_Create (const SHI_EngineConfig config, SHI_Engine *engine)
	Creates a SHI_Engine object. More...

Detailed Description

The central object for DRM interaction.

Typedef Documentation

◆ SHI_Engine

typedef struct SHI_Engine SHI_Engine

A SHI_Engine object is the initial point of interaction between an application and a DRM Engine.

It encapsulates the state of a DRM Engine, provides access to internal data structures, and provides information about transactions that it is performing on behalf of the application.

Function Documentation

◆ SHI_Engine_Create()

SHI_PUBLIC_API SHI_Result SHI_Engine_Create	(	const SHI_EngineConfig *	config,
		SHI_Engine **	engine
	)

Creates a SHI_Engine object.

This object must be destroyed by calling SHI_Engine_Destroy when it is no longer needed.

The configuration passed to this method specifies configuration flags and the listener that will receive the event callbacks.

Parameters

config	Pointer to the configuration for the engine.
engine	Address of a SHI_Engine pointer that will be set to refer to the SHI_Engine object created.

◆ SHI_Engine_CreateLicense()

SHI_PUBLIC_API SHI_Result SHI_Engine_CreateLicense	(	SHI_Engine *	self,
		SHI_License **	license
	)

Creates a new SHI_License object managed by this engine.

That is, the SHI_License object is local to this engine, and cannot be used independently of it. The SHI_License object must be destroyed by calling SHI_License_Destroy when it is no longer needed, prior to destroying the engine.

Parameters

self	The SHI_Engine that will manage the license.
license	Address of a SHI_License pointer that will be set to refer to the SHI_License created.

◆ SHI_Engine_DeleteObject()

SHI_PUBLIC_API SHI_Result SHI_Engine_DeleteObject	(	SHI_Engine *	self,
		const char *	object_id
	)

Removes the given Octopus object from the Sushi database.

This object must be a link or a node, and cannot be the personality node.

Parameters

self	A SHI_Engine pointer.
object_id	The ID of the Octopus object.

◆ SHI_Engine_Destroy()

SHI_PUBLIC_API SHI_Result SHI_Engine_Destroy ( SHI_Engine * self )

Destroys this engine object.

The object can no longer be used after this method returns. All objects obtained from method calls to this object must be released or destroyed before this object is destroyed.

Parameters

self	The SHI_Engine to destroy.

◆ SHI_Engine_EnumerateServices()

SHI_PUBLIC_API SHI_Result SHI_Engine_EnumerateServices	(	SHI_Engine *	self,
		SHI_List **	services
	)

Gets the list of the services that are currently configured for this engine.

The SHI_List object returned is a list of SHI_Data objects, each having as value a SHI_TypedObject pointing to a SHI_Service object. This list must be released before destroying the engine.

Parameters

self	The SHI_Engine whose services are listed.
services	Address of a SHI_List pointer that will be set to refer to a SHI_List object containing the list of services.

◆ SHI_Engine_EnumerateServiceSubscriptions()

SHI_PUBLIC_API SHI_Result SHI_Engine_EnumerateServiceSubscriptions	(	SHI_Engine *	self,
		const char *	service_id,
		const char *	user_id,
		SHI_List **	subscriptions
	)

Gets a list of subscriptions associated with one or more of the engine's configured services.

The SHI_List object returned is a list of SHI_Data objects, each having as value a SHI_TypedObject pointing to a SHI_ServiceSubscription object. This list must be released before destroying the engine.

Parameters

self	The SHI_Engine for which the service is configured.
service_id	ID of one of the services currently configured, or NULL to enumerate all the service subscriptions.
user_id	ID of one of the users, or NULL to enumerate the subscriptions of all users.
subscriptions	Address of a SHI_List pointer that will be set to refer to a SHI_List object containing the list of service subscriptions.

◆ SHI_Engine_EnumerateServiceUsers()

SHI_PUBLIC_API SHI_Result SHI_Engine_EnumerateServiceUsers	(	SHI_Engine *	self,
		const char *	service_id,
		SHI_List **	users
	)

Gets a list of service users of one or more of this engine's configured services.

The SHI_List object returned is a list of SHI_Data objects, each having as value a SHI_TypedObject pointing to a SHI_ServiceUser object. This list must be released before destroying the engine.

Parameters

self	The SHI_Engine for which the service is configured.
service_id	ID of one of the services currently configured, or NULL to enumerate all the service users.
users	Address of a SHI_List pointer that will be set to refer to a SHI_List object containing the list of users of the service.

◆ SHI_Engine_GetCertificateChain()

SHI_PUBLIC_API SHI_Result SHI_Engine_GetCertificateChain	(	SHI_Engine *	self,
		SHI_EngineCertChain	cert_chain,
		SHI_Data **	cert_array
	)

Get the certificates of the specified certificate chain.

The returned certificates are in DER (Distinguished Encoding Rules) encoded format starting with the leaf certificate to the trust anchor.

Parameters

self	A SHI_Engine pointer.
cert_chain	The type of certificate chain to be fetched.
cert_array	Address of a SHI_Data pointer that will be set to point to a SHI_Data object representing an array of certificates. This SHI_Data object will be of type SHI_DATA_TYPE_ARRAY, where each element in the array will be of type SHI_DATA_TYPE_BYTE_ARRAY, and its value is a SHI_ByteArray. Each SHI_ByteArray structure contains the DER encoded certificate data and its size in bytes. The caller is responsible for calling SHI_Data_Release to release the SHI_Data object when it is no longer needed.

Since: 1.19

◆ SHI_Engine_GetInterface()

SHI_PUBLIC_API void* SHI_Engine_GetInterface	(	SHI_Engine *	self,
		SHI_InterfaceId	iface_id
	)

Obtains a pointer to a SHI_Engine object with a different interface.

This method returns NULL if the object does not implement the requested interface.

Parameters

self	The SHI_Engine whose interface will be returned.
iface_id	The ID of the interface that is requested.

Returns: A pointer to the requested interface, or NULL if the object does not implement it.

◆ SHI_Engine_GetLinkIds()

SHI_PUBLIC_API SHI_Result SHI_Engine_GetLinkIds	(	SHI_Engine *	self,
		SHI_Data **	id_array
	)

Gets list of all Octopus links known to this Sushi instance.

These links are returned as a SHI_Data array of strings that contain the object id's.

Parameters

self	A SHI_Engine pointer.
id_array	Address of a SHI_Data pointer that will be set to refer to a SHI_Data array object.

◆ SHI_Engine_GetNodeIds()

SHI_PUBLIC_API SHI_Result SHI_Engine_GetNodeIds	(	SHI_Engine *	self,
		SHI_Data **	id_array
	)

Gets list of all Octopus nodes known to this Sushi instance.

These nodes are returned as a SHI_Data array of strings that contain the object id's.

Parameters

self	A SHI_Engine pointer.
id_array	Address of a SHI_Data pointer that will be set to refer to a SHI_Data array object.

◆ SHI_Engine_GetObjectDetails()

SHI_PUBLIC_API SHI_Result SHI_Engine_GetObjectDetails	(	SHI_Engine *	self,
		const char *	object_id,
		SHI_Attribute **	details
	)

Gets the details of this Octopus object.

These details are returned as a tree of SHI_Attribute objects that represent detailed information about the object's attributes and more. If the object is not found, this method returns SHI_ERROR_NOT_AVAILABLE.

Parameters

self	A SHI_Engine pointer.
object_id	The ID of the requested Octopus object.
details	Address of a SHI_Attribute pointer that will be set to refer to a SHI_Attribute object containing the details.

◆ SHI_Engine_GetTrustedTime()

SHI_PUBLIC_API SHI_Result SHI_Engine_GetTrustedTime	(	SHI_Engine *	self,
		SHI_DateTime *	now
	)

Returns the current value of the trusted time.

The time is expressed as a GMT date+time.

Parameters

self	The SHI_Engine from which the trusted time is obtained.
now	A pointer to a SHI_DateTime struct that will be set to contain the current time.

◆ SHI_Engine_IsPersonalized()

SHI_PUBLIC_API SHI_Boolean SHI_Engine_IsPersonalized ( SHI_Engine * self )

Indicates whether or not this engine has been personalized.

Parameters

self	The SHI_Engine that is checked.

Returns: SHI_TRUE if the engine is already personalized, or SHI_FALSE if it has not yet been personalized.

◆ SHI_Engine_Personalize()

SHI_PUBLIC_API SHI_Result SHI_Engine_Personalize	(	SHI_Engine *	self,
		const char *	token,
		SHI_Size	token_size,
		const void *	cookie
	)

Requests that this engine engage in the personalization process.

This method performs the personalization synchronously and does not return until it is complete. The progress and results are signaled by callbacks to the engine's event listener. Note: The personalization process is represented by a transaction of SHI_TransactionType SHI_TRANSACTION_TYPE_PERSONALIZATION.

The 'token' parameter can be NULL in which case the token_size is ignored, and a default personalization token is utilized. Such a default personalization token can be selected at build time through the Sushi Configuration procedure. See the Sushi Deployment Guide for details.

The return value for this method indicates simply whether the method call succeeded. The success or failure result of the transaction for performing personalization is specified in the final callback indicating the end of the transaction.

See SHI_EngineConfig for pseudo code of a proper listener that captures any transaction failure.

If this engine is already personalized, this method returns SHI_ERROR_ENGINE_ALREADY_PERSONALIZED.

Parameters

self	The SHI_Engine to be personalized.
token	Pointer to the service token data, or NULL.
token_size	Size in bytes of the service token data.
cookie	An arbitrary pointer that will be passed back to the engine listener in callbacks regarding any transaction related to the processing of the personalization.

◆ SHI_Engine_ProcessServiceToken()

SHI_PUBLIC_API SHI_Result SHI_Engine_ProcessServiceToken	(	SHI_Engine *	self,
		const char *	token,
		SHI_Size	token_size,
		const void *	cookie
	)

Requests that this engine process a service token, such as a Broadband Action Token.

This method performs all operations synchronously and does not return until completing processing of the service token. The progress and status information are signaled by callbacks to the engine's event listener.

The return value for this method indicates simply whether the method call succeeded. The success or failure result of the transaction for processing the service token is specified in the final callback indicating the end of the transaction.

See SHI_EngineConfig for pseudo code of a proper listener that captures any transaction failure.

Parameters

self	The SHI_Engine that will process the token.
token	Pointer to the service token data.
token_size	Size in bytes of the service token data.
cookie	An arbitrary pointer that will be passed back to the engine listener in callbacks regarding any transaction related to the processing of this token.

◆ SHI_Engine_ProcessServiceTokenEx()

SHI_PUBLIC_API SHI_Result SHI_Engine_ProcessServiceTokenEx	(	SHI_Engine *	self,
		const char *	token,
		SHI_Size	token_size,
		const void *	cookie,
		SHI_RegistrationDataManager *	registration_data_manager
	)

Use this API instead of SHI_Engine_ProcessServiceToken if you want to overwrite the default behavior for saving and loading nodes and links during registration.

Requests that this engine process a service token, such as a Broadband Action Token.

This method performs all operations synchronously and does not return until completing processing of the service token. The progress and status information are signaled by callbacks to the engine's event listener.

The return value for this method indicates simply whether the method call succeeded. The success or failure result of the transaction for processing the service token is specified in the final callback indicating the end of the transaction.

See SHI_EngineConfig for pseudo code of a proper listener that captures any transaction failure.

Parameters

self	The SHI_Engine that will process the token.
token	Pointer to the service token data.
token_size	Size in bytes of the service token data.
cookie	An arbitrary pointer that will be passed back to the engine listener in callbacks regarding any transaction related to the processing of this token.
registration_data_manager	Pointer to the interface that handles the nodes saving and loading and the links saving

◆ SHI_Engine_TransformURITemplate()

SHI_PUBLIC_API SHI_Result SHI_Engine_TransformURITemplate	(	SHI_Engine *	self,
		const char *	uri_template,
		SHI_Data **	uri
	)

Transforms a URI template according to the "URI Templates for Marlin" specification.

Parameters

self	A SHI_Engine pointer.
uri_template	The URI template, containing zero or more placeholder substrings to be replaced.
uri	Address of a SHI_Data pointer that will be set to refer to a SHI_Data string object containing the result of transforming the URI template.

◆ SHI_Engine_UpdatePersonality()

SHI_PUBLIC_API SHI_Result SHI_Engine_UpdatePersonality	(	SHI_Engine *	self,
		const char *	token,
		SHI_Size	token_size,
		const void *	cookie
	)

Requests that this engine engage in the personality update process to renew its public credentials.

This method performs the personality update synchronously and does not return until it is complete. The progress and results are signaled by callbacks to the engine's event listener. Note: The personality update process is represented by a transaction of SHI_TransactionType SHI_TRANSACTION_TYPE_PERSONALITY_UPDATE.

The return value for this method indicates simply whether the method call succeeded. The success or failure result of the transaction for performing personalization is specified in the final callback indicating the end of the transaction.

See SHI_EngineConfig for pseudo code of a proper listener that captures any transaction failure.

If this engine is not personalized, this method returns SHI_ERROR_ENGINE_NOT_PERSONALIZED.

Parameters

self	The SHI_Engine to be personalized.
token	Pointer to the service token data.
token_size	Size in bytes of the service token data.
cookie	An arbitrary pointer that will be passed back to the engine listener in callbacks regarding any transaction related to the processing of the update personality.

◆ SHI_Engine_UpdateSecurityData()

SHI_PUBLIC_API SHI_Result SHI_Engine_UpdateSecurityData	(	SHI_Engine *	self,
		const char *	service_id,
		SHI_UInt32	last_update,
		const void *	cookie
	)

Updates security data for a specified service configured for this engine object.

The return value for this method indicates simply whether the method call succeeded. The success or failure result of the underlying transaction is specified in the final callback indicating the end of the transaction.

See SHI_EngineConfig for pseudo code of a proper listener that captures any transaction failure.

Parameters

self	The SHI_Engine for which a service will be updated.
service_id	ID of the service whose security data will be updated.
last_update	If an update has occurred within the last last_update seconds, the security data will not be updated when the function is called. Callers can pass zero to mean update regardless of when the last update occurred.
cookie	An arbitrary pointer that will be passed back to the engine listener in callbacks regarding any transaction related to the processing of this update.

◆ SHI_Engine_VacuumData()

SHI_PUBLIC_API SHI_Result SHI_Engine_VacuumData	(	SHI_Engine *	self,
		SHI_Flags	vacuum_options
	)

Removes expired data stored in Sushi's database.

After this method is called, this engine instance may not be used again. You must destroy this engine and create a new instance. Engine methods may return SHI_ERROR_ENGINE_POST_VACUUM after this call. Note: the engine must be destroyed even if SHI_Engine_VacuumData returns an error code.

Parameters

self	A SHI_Engine pointer.
vacuum_options	The type of data to be vacuumed (permanently deleted), as specified in SHI_ENGINE_VACUUM_FLAG_XXX flags.

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ SHI_Engine

Function Documentation

◆ SHI_Engine_Create()

◆ SHI_Engine_CreateLicense()

◆ SHI_Engine_DeleteObject()

◆ SHI_Engine_Destroy()

◆ SHI_Engine_EnumerateServices()

◆ SHI_Engine_EnumerateServiceSubscriptions()

◆ SHI_Engine_EnumerateServiceUsers()

◆ SHI_Engine_GetCertificateChain()

◆ SHI_Engine_GetInterface()

◆ SHI_Engine_GetLinkIds()

◆ SHI_Engine_GetNodeIds()

◆ SHI_Engine_GetObjectDetails()

◆ SHI_Engine_GetTrustedTime()

◆ SHI_Engine_IsPersonalized()

◆ SHI_Engine_Personalize()

◆ SHI_Engine_ProcessServiceToken()

◆ SHI_Engine_ProcessServiceTokenEx()

◆ SHI_Engine_TransformURITemplate()

◆ SHI_Engine_UpdatePersonality()

◆ SHI_Engine_UpdateSecurityData()

◆ SHI_Engine_VacuumData()