cobalt/site/docs/reference/starboard/modules/13/drm.md - cobalt.git - Git at Google

 Project: /youtube/cobalt/_project.yaml
 Book: /youtube/cobalt/_book.yaml

 # Starboard Module Reference: `drm.h`

 Provides definitions that allow for DRM support, which are common between Player
 and Decoder interfaces.

 ## Macros

 ### kSbDrmSystemInvalid

 An invalid SbDrmSystem.

 ### kSbDrmTicketInvalid

 A ticket for callback invocations initiated by the DRM system.

 ## Enums

 ### SbDrmEncryptionScheme

 Encryption scheme of the input sample, as defined in ISO/IEC 23001 part 7.

 #### Values

 *   `kSbDrmEncryptionSchemeAesCtr`
 *   `kSbDrmEncryptionSchemeAesCbc`

 ### SbDrmKeyStatus

 Status of a particular media key. [https://w3c.github.io/encrypted-media/#idl-def-MediaKeyStatus](https://w3c.github.io/encrypted-media/#idl-def-MediaKeyStatus)

 #### Values

 *   `kSbDrmKeyStatusUsable`
 *   `kSbDrmKeyStatusExpired`
 *   `kSbDrmKeyStatusReleased`
 *   `kSbDrmKeyStatusRestricted`
 *   `kSbDrmKeyStatusDownscaled`
 *   `kSbDrmKeyStatusPending`
 *   `kSbDrmKeyStatusError`

 ### SbDrmSessionRequestType

 The type of the session request. [https://www.w3.org/TR/encrypted-media/#idl-def-mediakeymessagetype](https://www.w3.org/TR/encrypted-media/#idl-def-mediakeymessagetype)

 #### Values

 *   `kSbDrmSessionRequestTypeLicenseRequest`
 *   `kSbDrmSessionRequestTypeLicenseRenewal`
 *   `kSbDrmSessionRequestTypeLicenseRelease`
 *   `kSbDrmSessionRequestTypeIndividualizationRequest`

 ### SbDrmStatus

 The status of session related operations. Used by
 `SbDrmSessionUpdateRequestFunc`, `SbDrmSessionUpdatedFunc`, and
 `SbDrmServerCertificateUpdatedFunc` to indicate the status of the operation. [https://w3c.github.io/encrypted-media/#error-names](https://w3c.github.io/encrypted-media/#error-names)

 #### Values

 *   `kSbDrmStatusSuccess`
 *   `kSbDrmStatusTypeError`
 *   `kSbDrmStatusNotSupportedError`
 *   `kSbDrmStatusInvalidStateError`
 *   `kSbDrmStatusQuotaExceededError`
 *   `kSbDrmStatusUnknownError`

     The following error can be used when the error status cannot be mapped to
     one of the above errors.

 ## Typedefs

 ### SbDrmServerCertificateUpdatedFunc

 A callback to notify the caller of SbDrmUpdateServerCertificate() whether the
 update has been successfully updated or not.

 #### Definition

 ```
 typedef void(* SbDrmServerCertificateUpdatedFunc) (SbDrmSystem drm_system, void *context, int ticket, SbDrmStatus status, const char *error_message)
 ```

 ### SbDrmSessionClosedFunc

 A callback for signalling that a session has been closed by the SbDrmSystem

 #### Definition

 ```
 typedef void(* SbDrmSessionClosedFunc) (SbDrmSystem drm_system, void *context, const void *session_id, int session_id_size)
 ```

 ### SbDrmSessionKeyStatusesChangedFunc

 A callback for notifications that the status of one or more keys in a session
 has been changed. All keys of the session and their new status will be passed
 along. Any keys not in the list is considered as deleted.

 #### Definition

 ```
 typedef void(* SbDrmSessionKeyStatusesChangedFunc) (SbDrmSystem drm_system, void *context, const void *session_id, int session_id_size, int number_of_keys, const SbDrmKeyId *key_ids, const SbDrmKeyStatus *key_statuses)
 ```

 ### SbDrmSessionUpdateRequestFunc

 A callback that will receive generated session update request when requested
 from a SbDrmSystem. `drm_system` will be the DRM system that
 SbDrmGenerateSessionUpdateRequest() was called on. `context` will be the same
 context that was passed into the call to SbDrmCreateSystem().

 `status` is the status of the session request.

 `type` is the status of the session request.

 `error_message` may contain an optional error message when `status` isn't
 `kSbDrmStatusSuccess` to provide more details about the error. It may be NULL if
 `status` is `kSbDrmStatusSuccess` or if no error message can be provided.
 `ticket` will be the same ticket that was passed to
 SbDrmGenerateSessionUpdateRequest() or `kSbDrmTicketInvalid` if the update
 request was generated by the DRM system.

 `session_id` cannot be NULL when `ticket` is `kSbDrmTicketInvalid`, even when
 there was an error generating the request. This allows Cobalt to find and reject
 the correct Promise corresponding to the associated
 SbDrmGenerateSessionUpdateRequest().

 #### Definition

 ```
 typedef void(* SbDrmSessionUpdateRequestFunc) (SbDrmSystem drm_system, void *context, int ticket, SbDrmStatus status, SbDrmSessionRequestType type, const char *error_message, const void *session_id, int session_id_size, const void *content, int content_size, const char *url)
 ```

 ### SbDrmSessionUpdatedFunc

 A callback for notifications that a session has been added, and subsequent
 encrypted samples are actively ready to be decoded. `drm_system` will be the DRM
 system that SbDrmUpdateSession() was called on. `context` will be the same
 context passed into that call to SbDrmCreateSystem().

 `ticket` will be the same ticket that was passed to SbDrmUpdateSession().

 `status` is the status of the session request.

 `error_message` may contain an optional error message when `status` isn't
 `kSbDrmStatusSuccess` to provide more details about the error. It may be NULL if
 `status` is `kSbDrmStatusSuccess` or if no error message can be provided.
 `succeeded` is whether the session was successfully updated or not.

 #### Definition

 ```
 typedef void(* SbDrmSessionUpdatedFunc) (SbDrmSystem drm_system, void *context, int ticket, SbDrmStatus status, const char *error_message, const void *session_id, int session_id_size)
 ```

 ### SbDrmSystem

 A handle to a DRM system which can be used with either an SbDecoder or an
 SbPlayer.

 #### Definition

 ```
 typedef struct SbDrmSystemPrivate* SbDrmSystem
 ```

 ## Structs

 ### SbDrmEncryptionPattern

 Encryption pattern of the input sample, as defined in ISO/IEC 23001 part 7.

 #### Members

 *   `uint32_t crypt_byte_block`
 *   `uint32_t skip_byte_block`

 ### SbDrmKeyId

 #### Members

 *   `uint8_t identifier`

     The ID of the license (or key) required to decrypt this sample. For
     PlayReady, this is the license GUID in packed little-endian binary form.
 *   `int identifier_size`

 ### SbDrmSampleInfo

 All the optional information needed per sample for encrypted samples.

 #### Members

 *   `SbDrmEncryptionScheme encryption_scheme`

     The encryption scheme of this sample.
 *   `SbDrmEncryptionPattern encryption_pattern`

     The encryption pattern of this sample.
 *   `uint8_t initialization_vector`

     The Initialization Vector needed to decrypt this sample.
 *   `int initialization_vector_size`
 *   `uint8_t identifier`

     The ID of the license (or key) required to decrypt this sample. For
     PlayReady, this is the license GUID in packed little-endian binary form.
 *   `int identifier_size`
 *   `int32_t subsample_count`

     The number of subsamples in this sample, must be at least 1.
 *   `constSbDrmSubSampleMapping* subsample_mapping`

     The clear/encrypted mapping of each subsample in this sample. This must be
     an array of `subsample_count` mappings.

 ### SbDrmSubSampleMapping

 A mapping of clear and encrypted bytes for a single subsample. All subsamples
 within a sample must be encrypted with the same encryption parameters. The clear
 bytes always appear first in the sample.

 #### Members

 *   `int32_t clear_byte_count`

     How many bytes of the corresponding subsample are not encrypted
 *   `int32_t encrypted_byte_count`

     How many bytes of the corresponding subsample are encrypted.

 ## Functions

 ### SbDrmCloseSession

 Clear any internal states/resources related to the specified `session_id`.

 `drm_system` must not be `kSbDrmSystemInvalid`. `session_id` must not be NULL.

 #### Declaration

 ```
 void SbDrmCloseSession(SbDrmSystem drm_system, const void *session_id, int session_id_size)
 ```

 ### SbDrmDestroySystem

 Destroys `drm_system`, which implicitly removes all keys installed in it and
 invalidates all outstanding session update requests. A DRM system cannot be
 destroyed unless any associated SbPlayer or SbDecoder has first been destroyed.

 All callbacks are guaranteed to be finished when this function returns. As a
 result, if this function is called from a callback that is passed to
 SbDrmCreateSystem(), a deadlock will occur.

 `drm_system`: The DRM system to be destroyed. Must not be `kSbDrmSystemInvalid`.

 #### Declaration

 ```
 void SbDrmDestroySystem(SbDrmSystem drm_system)
 ```

 ### SbDrmGenerateSessionUpdateRequest

 Asynchronously generates a session update request payload for
 `initialization_data`, of `initialization_data_size`, in case sensitive `type`,
 extracted from the media stream, in `drm_system`'s key system.

 This function calls `drm_system`'s `update_request_callback` function, which is
 defined when the DRM system is created by SbDrmCreateSystem. When calling that
 function, this function either sends `context` (also from `SbDrmCreateSystem`)
 and a populated request, or it sends NULL `session_id` if an error occurred.

 `drm_system`'s `context` may be used to route callbacks back to an object
 instance.

 Callbacks may be called either from the current thread before this function
 returns or from another thread.

 `drm_system`: The DRM system that defines the key system used for the session
 update request payload as well as the callback function that is called as a
 result of the function being called. Must not be `kSbDrmSystemInvalid`.

 `ticket`: The opaque ID that allows to distinguish callbacks from multiple
 concurrent calls to SbDrmGenerateSessionUpdateRequest(), which will be passed to
 `update_request_callback` as-is. It is the responsibility of the caller to
 establish ticket uniqueness, issuing multiple requests with the same ticket may
 result in undefined behavior. The value `kSbDrmTicketInvalid` must not be used.

 `type`: The case-sensitive type of the session update request payload. Must not
 be NULL. `initialization_data`: The data for which the session update request
 payload is created. Must not be NULL. `initialization_data_size`: The size of
 the session update request payload.

 #### Declaration

 ```
 void SbDrmGenerateSessionUpdateRequest(SbDrmSystem drm_system, int ticket, const char *type, const void *initialization_data, int initialization_data_size)
 ```

 ### SbDrmGetMetrics

 Get the metrics of the underlying drm system.

 When it is called on an implementation that supports drm system metrics, it
 should return a pointer containing the metrics as a blob, encoded using url safe
 base64 without padding and line wrapping, with the size of the encoded result in
 `size` on return. For example, on Android API level 28 or later, it should
 return the result of MediaDrm.getPropertyByteArray("metrics"), encoded using url
 safe base64 without padding and line wrapping. On systems using Widevine CE CDM
 with oemcrypto 16 or later, it should return the metrics retrieved via
 Cdm::getMetrics(), encoded using url safe base64 without padding and line
 wrapping. The returned pointer should remain valid and its content should remain
 unmodified until the next time this function is called on the associated
 `drm_system` or the `drm_system` is destroyed.

 When the metrics is empty on supported system, it should return a non-null
 pointer with `size` set to 0.

 It should return NULL when there is no metrics support in the underlying drm
 system, or when the drm system implementation fails to retrieve the metrics.

 `drm_system` must not be `kSbDrmSystemInvalid`. `size` must not be NULL.

 #### Declaration

 ```
 const void* SbDrmGetMetrics(SbDrmSystem drm_system, int *size)
 ```

 ### SbDrmIsServerCertificateUpdatable

 Returns true if server certificate of `drm_system` can be updated via
 SbDrmUpdateServerCertificate(). The return value should remain the same during
 the life time of `drm_system`.

 `drm_system`: The DRM system to check if its server certificate is updatable.
 Must not be `kSbDrmSystemInvalid`.

 #### Declaration

 ```
 bool SbDrmIsServerCertificateUpdatable(SbDrmSystem drm_system)
 ```

 ### SbDrmSystemIsValid

 Indicates whether `drm_system` is a valid SbDrmSystem.

 #### Declaration

 ```
 static bool SbDrmSystemIsValid(SbDrmSystem drm)
 ```

 ### SbDrmTicketIsValid

 Indicates whether `ticket` is a valid ticket.

 #### Declaration

 ```
 static bool SbDrmTicketIsValid(int ticket)
 ```

 ### SbDrmUpdateServerCertificate

 Update the server certificate of `drm_system`. The function can be called
 multiple times. It is possible that a call to it happens before the callback of
 a previous call is called. Note that this function should only be called after
 `SbDrmIsServerCertificateUpdatable` is called first and returned true.

 `drm_system`: The DRM system whose server certificate is being updated. Must not
 be `kSbDrmSystemInvalid`. `ticket`: The opaque ID that allows to distinguish
 callbacks from multiple concurrent calls to SbDrmUpdateServerCertificate(),
 which will be passed to `server_certificate_updated_callback` as-is. It is the
 responsibility of the caller to establish ticket uniqueness, issuing multiple
 requests with the same ticket may result in undefined behavior. The value
 `kSbDrmTicketInvalid` must not be used. `certificate`: Pointer to the server
 certificate data. Must not be NULL. `certificate_size`: Size of the server
 certificate data.

 #### Declaration

 ```
 void SbDrmUpdateServerCertificate(SbDrmSystem drm_system, int ticket, const void *certificate, int certificate_size)
 ```

 ### SbDrmUpdateSession

 Update session with `key`, in `drm_system`'s key system, from the license server
 response. Calls `session_updated_callback` with `context` and whether the update
 succeeded. `context` may be used to route callbacks back to an object instance.
 The `key` must not be NULL.

 `drm_system` must not be `kSbDrmSystemInvalid`. `ticket` is the opaque ID that
 allows to distinguish callbacks from multiple concurrent calls to
 SbDrmUpdateSession(), which will be passed to `session_updated_callback` as-is.
 It is the responsibility of the caller to establish ticket uniqueness, issuing
 multiple calls with the same ticket may result in undefined behavior.

 Once the session is successfully updated, an SbPlayer or SbDecoder associated
 with that DRM key system will be able to decrypt encrypted samples.

 `drm_system`'s `session_updated_callback` may called either from the current
 thread before this function returns or from another thread. The `session_id`
 must not be NULL.

 #### Declaration

 ```
 void SbDrmUpdateSession(SbDrmSystem drm_system, int ticket, const void *key, int key_size, const void *session_id, int session_id_size)
 ```
	Project: /youtube/cobalt/_project.yaml
	Book: /youtube/cobalt/_book.yaml

	# Starboard Module Reference: `drm.h`

	Provides definitions that allow for DRM support, which are common between Player
	and Decoder interfaces.

	## Macros

	### kSbDrmSystemInvalid

	An invalid SbDrmSystem.

	### kSbDrmTicketInvalid

	A ticket for callback invocations initiated by the DRM system.

	## Enums

	### SbDrmEncryptionScheme

	Encryption scheme of the input sample, as defined in ISO/IEC 23001 part 7.

	#### Values

	* `kSbDrmEncryptionSchemeAesCtr`
	* `kSbDrmEncryptionSchemeAesCbc`

	### SbDrmKeyStatus

	Status of a particular media key. [https://w3c.github.io/encrypted-media/#idl-def-MediaKeyStatus](https://w3c.github.io/encrypted-media/#idl-def-MediaKeyStatus)

	#### Values

	* `kSbDrmKeyStatusUsable`
	* `kSbDrmKeyStatusExpired`
	* `kSbDrmKeyStatusReleased`
	* `kSbDrmKeyStatusRestricted`
	* `kSbDrmKeyStatusDownscaled`
	* `kSbDrmKeyStatusPending`
	* `kSbDrmKeyStatusError`

	### SbDrmSessionRequestType

	The type of the session request. [https://www.w3.org/TR/encrypted-media/#idl-def-mediakeymessagetype](https://www.w3.org/TR/encrypted-media/#idl-def-mediakeymessagetype)

	#### Values

	* `kSbDrmSessionRequestTypeLicenseRequest`
	* `kSbDrmSessionRequestTypeLicenseRenewal`
	* `kSbDrmSessionRequestTypeLicenseRelease`
	* `kSbDrmSessionRequestTypeIndividualizationRequest`

	### SbDrmStatus

	The status of session related operations. Used by
	`SbDrmSessionUpdateRequestFunc`, `SbDrmSessionUpdatedFunc`, and
	`SbDrmServerCertificateUpdatedFunc` to indicate the status of the operation. [https://w3c.github.io/encrypted-media/#error-names](https://w3c.github.io/encrypted-media/#error-names)

	#### Values

	* `kSbDrmStatusSuccess`
	* `kSbDrmStatusTypeError`
	* `kSbDrmStatusNotSupportedError`
	* `kSbDrmStatusInvalidStateError`
	* `kSbDrmStatusQuotaExceededError`
	* `kSbDrmStatusUnknownError`

	The following error can be used when the error status cannot be mapped to
	one of the above errors.

	## Typedefs

	### SbDrmServerCertificateUpdatedFunc

	A callback to notify the caller of SbDrmUpdateServerCertificate() whether the
	update has been successfully updated or not.

	#### Definition

	```
	typedef void(* SbDrmServerCertificateUpdatedFunc) (SbDrmSystem drm_system, void context, int ticket, SbDrmStatus status, const char error_message)
	```

	### SbDrmSessionClosedFunc

	A callback for signalling that a session has been closed by the SbDrmSystem

	#### Definition

	```
	typedef void(* SbDrmSessionClosedFunc) (SbDrmSystem drm_system, void context, const void session_id, int session_id_size)
	```

	### SbDrmSessionKeyStatusesChangedFunc

	A callback for notifications that the status of one or more keys in a session
	has been changed. All keys of the session and their new status will be passed
	along. Any keys not in the list is considered as deleted.

	#### Definition

	```
	typedef void(* SbDrmSessionKeyStatusesChangedFunc) (SbDrmSystem drm_system, void context, const void session_id, int session_id_size, int number_of_keys, const SbDrmKeyId key_ids, const SbDrmKeyStatus key_statuses)
	```

	### SbDrmSessionUpdateRequestFunc

	A callback that will receive generated session update request when requested
	from a SbDrmSystem. `drm_system` will be the DRM system that
	SbDrmGenerateSessionUpdateRequest() was called on. `context` will be the same
	context that was passed into the call to SbDrmCreateSystem().

	`status` is the status of the session request.

	`type` is the status of the session request.

	`error_message` may contain an optional error message when `status` isn't
	`kSbDrmStatusSuccess` to provide more details about the error. It may be NULL if
	`status` is `kSbDrmStatusSuccess` or if no error message can be provided.
	`ticket` will be the same ticket that was passed to
	SbDrmGenerateSessionUpdateRequest() or `kSbDrmTicketInvalid` if the update
	request was generated by the DRM system.

	`session_id` cannot be NULL when `ticket` is `kSbDrmTicketInvalid`, even when
	there was an error generating the request. This allows Cobalt to find and reject
	the correct Promise corresponding to the associated
	SbDrmGenerateSessionUpdateRequest().

	#### Definition

	```
	typedef void(* SbDrmSessionUpdateRequestFunc) (SbDrmSystem drm_system, void context, int ticket, SbDrmStatus status, SbDrmSessionRequestType type, const char error_message, const void session_id, int session_id_size, const void content, int content_size, const char *url)
	```

	### SbDrmSessionUpdatedFunc

	A callback for notifications that a session has been added, and subsequent
	encrypted samples are actively ready to be decoded. `drm_system` will be the DRM
	system that SbDrmUpdateSession() was called on. `context` will be the same
	context passed into that call to SbDrmCreateSystem().

	`ticket` will be the same ticket that was passed to SbDrmUpdateSession().

	`status` is the status of the session request.

	`error_message` may contain an optional error message when `status` isn't
	`kSbDrmStatusSuccess` to provide more details about the error. It may be NULL if
	`status` is `kSbDrmStatusSuccess` or if no error message can be provided.
	`succeeded` is whether the session was successfully updated or not.

	#### Definition

	```
	typedef void(* SbDrmSessionUpdatedFunc) (SbDrmSystem drm_system, void context, int ticket, SbDrmStatus status, const char error_message, const void *session_id, int session_id_size)
	```

	### SbDrmSystem

	A handle to a DRM system which can be used with either an SbDecoder or an
	SbPlayer.

	#### Definition

	```
	typedef struct SbDrmSystemPrivate* SbDrmSystem
	```

	## Structs

	### SbDrmEncryptionPattern

	Encryption pattern of the input sample, as defined in ISO/IEC 23001 part 7.

	#### Members

	* `uint32_t crypt_byte_block`
	* `uint32_t skip_byte_block`

	### SbDrmKeyId

	#### Members

	* `uint8_t identifier`

	The ID of the license (or key) required to decrypt this sample. For
	PlayReady, this is the license GUID in packed little-endian binary form.
	* `int identifier_size`

	### SbDrmSampleInfo

	All the optional information needed per sample for encrypted samples.

	#### Members

	* `SbDrmEncryptionScheme encryption_scheme`

	The encryption scheme of this sample.
	* `SbDrmEncryptionPattern encryption_pattern`

	The encryption pattern of this sample.
	* `uint8_t initialization_vector`

	The Initialization Vector needed to decrypt this sample.
	* `int initialization_vector_size`
	* `uint8_t identifier`

	The ID of the license (or key) required to decrypt this sample. For
	PlayReady, this is the license GUID in packed little-endian binary form.
	* `int identifier_size`
	* `int32_t subsample_count`

	The number of subsamples in this sample, must be at least 1.
	* `constSbDrmSubSampleMapping* subsample_mapping`

	The clear/encrypted mapping of each subsample in this sample. This must be
	an array of `subsample_count` mappings.

	### SbDrmSubSampleMapping

	A mapping of clear and encrypted bytes for a single subsample. All subsamples
	within a sample must be encrypted with the same encryption parameters. The clear
	bytes always appear first in the sample.

	#### Members

	* `int32_t clear_byte_count`

	How many bytes of the corresponding subsample are not encrypted
	* `int32_t encrypted_byte_count`

	How many bytes of the corresponding subsample are encrypted.

	## Functions

	### SbDrmCloseSession

	Clear any internal states/resources related to the specified `session_id`.

	`drm_system` must not be `kSbDrmSystemInvalid`. `session_id` must not be NULL.

	#### Declaration

	```
	void SbDrmCloseSession(SbDrmSystem drm_system, const void *session_id, int session_id_size)
	```

	### SbDrmDestroySystem

	Destroys `drm_system`, which implicitly removes all keys installed in it and
	invalidates all outstanding session update requests. A DRM system cannot be
	destroyed unless any associated SbPlayer or SbDecoder has first been destroyed.

	All callbacks are guaranteed to be finished when this function returns. As a
	result, if this function is called from a callback that is passed to
	SbDrmCreateSystem(), a deadlock will occur.

	`drm_system`: The DRM system to be destroyed. Must not be `kSbDrmSystemInvalid`.

	#### Declaration

	```
	void SbDrmDestroySystem(SbDrmSystem drm_system)
	```

	### SbDrmGenerateSessionUpdateRequest

	Asynchronously generates a session update request payload for
	`initialization_data`, of `initialization_data_size`, in case sensitive `type`,
	extracted from the media stream, in `drm_system`'s key system.

	This function calls `drm_system`'s `update_request_callback` function, which is
	defined when the DRM system is created by SbDrmCreateSystem. When calling that
	function, this function either sends `context` (also from `SbDrmCreateSystem`)
	and a populated request, or it sends NULL `session_id` if an error occurred.

	`drm_system`'s `context` may be used to route callbacks back to an object
	instance.

	Callbacks may be called either from the current thread before this function
	returns or from another thread.

	`drm_system`: The DRM system that defines the key system used for the session
	update request payload as well as the callback function that is called as a
	result of the function being called. Must not be `kSbDrmSystemInvalid`.

	`ticket`: The opaque ID that allows to distinguish callbacks from multiple
	concurrent calls to SbDrmGenerateSessionUpdateRequest(), which will be passed to
	`update_request_callback` as-is. It is the responsibility of the caller to
	establish ticket uniqueness, issuing multiple requests with the same ticket may
	result in undefined behavior. The value `kSbDrmTicketInvalid` must not be used.

	`type`: The case-sensitive type of the session update request payload. Must not
	be NULL. `initialization_data`: The data for which the session update request
	payload is created. Must not be NULL. `initialization_data_size`: The size of
	the session update request payload.

	#### Declaration

	```
	void SbDrmGenerateSessionUpdateRequest(SbDrmSystem drm_system, int ticket, const char type, const void initialization_data, int initialization_data_size)
	```

	### SbDrmGetMetrics

	Get the metrics of the underlying drm system.

	When it is called on an implementation that supports drm system metrics, it
	should return a pointer containing the metrics as a blob, encoded using url safe
	base64 without padding and line wrapping, with the size of the encoded result in
	`size` on return. For example, on Android API level 28 or later, it should
	return the result of MediaDrm.getPropertyByteArray("metrics"), encoded using url
	safe base64 without padding and line wrapping. On systems using Widevine CE CDM
	with oemcrypto 16 or later, it should return the metrics retrieved via
	Cdm::getMetrics(), encoded using url safe base64 without padding and line
	wrapping. The returned pointer should remain valid and its content should remain
	unmodified until the next time this function is called on the associated
	`drm_system` or the `drm_system` is destroyed.

	When the metrics is empty on supported system, it should return a non-null
	pointer with `size` set to 0.

	It should return NULL when there is no metrics support in the underlying drm
	system, or when the drm system implementation fails to retrieve the metrics.

	`drm_system` must not be `kSbDrmSystemInvalid`. `size` must not be NULL.

	#### Declaration

	```
	const void* SbDrmGetMetrics(SbDrmSystem drm_system, int *size)
	```

	### SbDrmIsServerCertificateUpdatable

	Returns true if server certificate of `drm_system` can be updated via
	SbDrmUpdateServerCertificate(). The return value should remain the same during
	the life time of `drm_system`.

	`drm_system`: The DRM system to check if its server certificate is updatable.
	Must not be `kSbDrmSystemInvalid`.

	#### Declaration

	```
	bool SbDrmIsServerCertificateUpdatable(SbDrmSystem drm_system)
	```

	### SbDrmSystemIsValid

	Indicates whether `drm_system` is a valid SbDrmSystem.

	#### Declaration

	```
	static bool SbDrmSystemIsValid(SbDrmSystem drm)
	```

	### SbDrmTicketIsValid

	Indicates whether `ticket` is a valid ticket.

	#### Declaration

	```
	static bool SbDrmTicketIsValid(int ticket)
	```

	### SbDrmUpdateServerCertificate

	Update the server certificate of `drm_system`. The function can be called
	multiple times. It is possible that a call to it happens before the callback of
	a previous call is called. Note that this function should only be called after
	`SbDrmIsServerCertificateUpdatable` is called first and returned true.

	`drm_system`: The DRM system whose server certificate is being updated. Must not
	be `kSbDrmSystemInvalid`. `ticket`: The opaque ID that allows to distinguish
	callbacks from multiple concurrent calls to SbDrmUpdateServerCertificate(),
	which will be passed to `server_certificate_updated_callback` as-is. It is the
	responsibility of the caller to establish ticket uniqueness, issuing multiple
	requests with the same ticket may result in undefined behavior. The value
	`kSbDrmTicketInvalid` must not be used. `certificate`: Pointer to the server
	certificate data. Must not be NULL. `certificate_size`: Size of the server
	certificate data.

	#### Declaration

	```
	void SbDrmUpdateServerCertificate(SbDrmSystem drm_system, int ticket, const void *certificate, int certificate_size)
	```

	### SbDrmUpdateSession

	Update session with `key`, in `drm_system`'s key system, from the license server
	response. Calls `session_updated_callback` with `context` and whether the update
	succeeded. `context` may be used to route callbacks back to an object instance.
	The `key` must not be NULL.

	`drm_system` must not be `kSbDrmSystemInvalid`. `ticket` is the opaque ID that
	allows to distinguish callbacks from multiple concurrent calls to
	SbDrmUpdateSession(), which will be passed to `session_updated_callback` as-is.
	It is the responsibility of the caller to establish ticket uniqueness, issuing
	multiple calls with the same ticket may result in undefined behavior.

	Once the session is successfully updated, an SbPlayer or SbDecoder associated
	with that DRM key system will be able to decrypt encrypted samples.

	`drm_system`'s `session_updated_callback` may called either from the current
	thread before this function returns or from another thread. The `session_id`
	must not be NULL.

	#### Declaration

	```
	void SbDrmUpdateSession(SbDrmSystem drm_system, int ticket, const void key, int key_size, const void session_id, int session_id_size)
	```