Starboard Module Reference: drm.h

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

Enums

SbDrmKeyStatus

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

Values

  • kSbDrmKeyStatusUsable
  • kSbDrmKeyStatusExpired
  • kSbDrmKeyStatusReleased
  • kSbDrmKeyStatusRestricted
  • kSbDrmKeyStatusDownscaled
  • kSbDrmKeyStatusPending
  • kSbDrmKeyStatusError

Structs

SbDrmSampleInfo

All the optional information needed per sample for encrypted samples.

Members

Members
uint8_t
initialization_vector[16]
The Initialization Vector needed to decrypt this sample.
int
initialization_vector_size
uint8_t
identifier[16]
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.
const
SbDrmSubSampleMapping* 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

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.

SbDrmSystem

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

Functions

SbDrmCloseSession

Description

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

Declaration and definitions

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

#include "starboard/drm.h"

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

Parameters

Parameters
SbDrmSystem
drm_system
const void*
session_id
int
session_id_size

SbDrmCreateSystem

Description

Creates a new DRM system that can be used when constructing an SbPlayer or an SbDecoder.
This function returns kSbDrmSystemInvalid if key_system is unsupported.
Also see the documentation of SbDrmGenerateSessionUpdateRequest() and SbDrmUpdateSession() for more details.

Declaration and definitions

SB_EXPORT SbDrmSystem
SbDrmCreateSystem(const char* key_system,
                  void* context,
                  SbDrmSessionUpdateRequestFunc update_request_callback,
                  SbDrmSessionUpdatedFunc session_updated_callback);

#include "starboard/drm.h"

SbDrmSystem SbDrmCreateSystem(
    const char* key_system,
    void* context,
    SbDrmSessionUpdateRequestFunc update_request_callback,
    SbDrmSessionUpdatedFunc session_updated_callback) {
  return kSbDrmSystemInvalid;
}

Parameters

Parameters
const char*
key_system
The DRM key system to be created. The value should be in the form of "com.example.somesystem" as suggested by https://w3c.github.io/encrypted-media/#key-system. All letters in the value should be lowercase and will be matched exactly with known DRM key systems of the platform.
void*
context
A value passed when any of this function's callback parameters are called.
SbDrmSessionUpdateRequestFunc
update_request_callback
A function that is called every time after SbDrmGenerateSessionUpdateRequest() is called.
SbDrmSessionUpdatedFunc
session_updated_callback
A function that is called every time after SbDrmUpdateSession() is called.

SbDrmDestroySystem

Description

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.

Declaration and definitions

SB_EXPORT void SbDrmDestroySystem(SbDrmSystem drm_system);

#include "starboard/drm.h"

void SbDrmDestroySystem(SbDrmSystem drm_system) {
}

Parameters

Parameters
SbDrmSystem
drm_system
The DRM system to be destroyed.

SbDrmGenerateSessionUpdateRequest

Description

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 distinguish callbacks from multiple concurrent calls to SbDrmGenerateSessionUpdateRequest(), and/or 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.

Declaration and definitions

SB_EXPORT void SbDrmGenerateSessionUpdateRequest(
    SbDrmSystem drm_system,
    const char* type,
    const void* initialization_data,
    int initialization_data_size);

#include "starboard/drm.h"

void SbDrmGenerateSessionUpdateRequest(SbDrmSystem drm_system,
                                       const char* type,
                                       const void* initialization_data,
                                       int initialization_data_size) {
}

Parameters

Parameters
SbDrmSystem
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.
const char*
type
The case-sensitive type of the session update request payload.
const void*
initialization_data
The data for which the session update request payload is created.
int
initialization_data_size
The size of the session update request payload.

SbDrmGetKeyCount

Description

Returns the number of keys installed in drm_system.

Declaration

SB_EXPORT int SbDrmGetKeyCount(SbDrmSystem drm_system);

Parameters

Parameters
SbDrmSystem
drm_system
The system for which the number of installed keys is retrieved.

SbDrmGetKeyStatus

Description

Gets out_key, out_key_size, and out_status for the key with index in drm_system. Returns whether a key is installed at index. If not, the output parameters, which all must not be NULL, will not be modified.

Declaration

SB_EXPORT bool SbDrmGetKeyStatus(SbDrmSystem drm_system,
                                 const void* session_id,
                                 int session_id_size,
                                 int index,
                                 void** out_key,
                                 int* out_key_size,
                                 SbDrmKeyStatus* out_status);

Parameters

Parameters
SbDrmSystem
drm_system
const void*
session_id
int
session_id_size
int
index
void**
out_key
int*
out_key_size
SbDrmKeyStatus*
out_status

SbDrmRemoveAllKeys

Description

Removes all installed keys for drm_system. Any outstanding session update requests are also invalidated.

Declaration

SB_EXPORT void SbDrmRemoveAllKeys(SbDrmSystem drm_system);

Parameters

Parameters
SbDrmSystem
drm_system
The DRM system for which keys should be removed.

SbDrmSystemIsValid

Description

Indicates whether drm_system is a valid SbDrmSystem.

Declaration

static SB_C_FORCE_INLINE bool SbDrmSystemIsValid(SbDrmSystem drm) {
  return drm != kSbDrmSystemInvalid;
}

Parameters

Parameters
SbDrmSystem
drm

SbDrmUpdateSession

Description

Update session with key, in drm_system's key system, from the license server response. request must be the corresponding returned request from SbDrmGenerateSessionUpdateRequest(). Calls session_updated_callback with context and whether the update succeeded. context may be used to distinguish callbacks from multiple concurrent calls to SbDrmUpdateSession(), and/or to route callbacks back to an object instance.
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.

Declaration and definitions

SB_EXPORT void SbDrmUpdateSession(SbDrmSystem drm_system,
                                  const void* key,
                                  int key_size,
                                  const void* session_id,
                                  int session_id_size);

#include "starboard/drm.h"

void SbDrmUpdateSession(SbDrmSystem drm_system,
                        const void* key,
                        int key_size,
                        const void* session_id,
                        int session_id_size) {
}

Parameters

Parameters
SbDrmSystem
drm_system
const void*
key
int
key_size
const void*
session_id
int
session_id_size