/*
* Copyright (C) 2014 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/*
* This file defines an NDK API.
* Do not remove methods.
* Do not change method signatures.
* Do not change the value of constants.
* Do not change the size of any of the classes defined in here.
* Do not reference types that are not part of the NDK.
* Do not #include files that aren't part of the NDK.
*/
#ifndef _NDK_MEDIA_DRM_H
#define _NDK_MEDIA_DRM_H
#include "NdkMediaError.h"
#ifdef __cplusplus
extern "C" {
#endif
#include <stdint.h>
#include <stdbool.h>
struct AMediaDrm;
typedef struct AMediaDrm AMediaDrm;
typedef struct {
const uint8_t *ptr;
size_t length;
} AMediaDrmByteArray;
typedef AMediaDrmByteArray AMediaDrmSessionId;
typedef AMediaDrmByteArray AMediaDrmScope;
typedef AMediaDrmByteArray AMediaDrmKeySetId;
typedef AMediaDrmByteArray AMediaDrmSecureStop;
typedef enum AMediaDrmEventType {
/**
* This event type indicates that the app needs to request a certificate from
* the provisioning server. The request message data is obtained using
* AMediaDrm_getProvisionRequest.
*/
EVENT_PROVISION_REQUIRED = 1,
/**
* This event type indicates that the app needs to request keys from a license
* server. The request message data is obtained using AMediaDrm_getKeyRequest.
*/
EVENT_KEY_REQUIRED = 2,
/**
* This event type indicates that the licensed usage duration for keys in a session
* has expired. The keys are no longer valid.
*/
EVENT_KEY_EXPIRED = 3,
/**
* This event may indicate some specific vendor-defined condition, see your
* DRM provider documentation for details
*/
EVENT_VENDOR_DEFINED = 4
} AMediaDrmEventType;
typedef void (*AMediaDrmEventListener)(AMediaDrm *, const AMediaDrmSessionId *sessionId,
AMediaDrmEventType eventType, int extra, const uint8_t *data, size_t dataSize);
/**
* Query if the given scheme identified by its UUID is supported on this device, and
* whether the drm plugin is able to handle the media container format specified by mimeType.
*
* uuid identifies the universal unique ID of the crypto scheme. uuid must be 16 bytes.
* mimeType is the MIME type of the media container, e.g. "video/mp4". If mimeType
* is not known or required, it can be provided as NULL.
*/
bool AMediaDrm_isCryptoSchemeSupported(const uint8_t *uuid, const char *mimeType);
/**
* Create a MediaDrm instance from a UUID
* uuid identifies the universal unique ID of the crypto scheme. uuid must be 16 bytes.
*/
AMediaDrm* AMediaDrm_createByUUID(const uint8_t *uuid);
/**
* Release a MediaDrm object
*/
void AMediaDrm_release(AMediaDrm *);
/**
* Register a callback to be invoked when an event occurs
*
* listener is the callback that will be invoked on event
*/
media_status_t AMediaDrm_setOnEventListener(AMediaDrm *, AMediaDrmEventListener listener);
/**
* Open a new session with the MediaDrm object. A session ID is returned.
*
* returns MEDIADRM_NOT_PROVISIONED_ERROR if provisioning is needed
* returns MEDIADRM_RESOURCE_BUSY_ERROR if required resources are in use
*/
media_status_t AMediaDrm_openSession(AMediaDrm *, AMediaDrmSessionId *sessionId);
/**
* Close a session on the MediaDrm object that was previously opened
* with AMediaDrm_openSession.
*/
media_status_t AMediaDrm_closeSession(AMediaDrm *, const AMediaDrmSessionId *sessionId);
typedef enum AMediaDrmKeyType {
/**
* This key request type species that the keys will be for online use, they will
* not be saved to the device for subsequent use when the device is not connected
* to a network.
*/
KEY_TYPE_STREAMING = 1,
/**
* This key request type specifies that the keys will be for offline use, they
* will be saved to the device for use when the device is not connected to a network.
*/
KEY_TYPE_OFFLINE = 2,
/**
* This key request type specifies that previously saved offline keys should be released.
*/
KEY_TYPE_RELEASE = 3
} AMediaDrmKeyType;
/**
* Data type containing {key, value} pair
*/
typedef struct AMediaDrmKeyValuePair {
const char *mKey;
const char *mValue;
} AMediaDrmKeyValue;
/**
* A key request/response exchange occurs between the app and a license server
* to obtain or release keys used to decrypt encrypted content.
* AMediaDrm_getKeyRequest is used to obtain an opaque key request byte array that
* is delivered to the license server. The opaque key request byte array is
* returned in KeyRequest.data. The recommended URL to deliver the key request to
* is returned in KeyRequest.defaultUrl.
*
* After the app has received the key request response from the server,
* it should deliver to the response to the DRM engine plugin using the method
* AMediaDrm_provideKeyResponse.
*
* scope may be a sessionId or a keySetId, depending on the specified keyType.
* When the keyType is KEY_TYPE_STREAMING or KEY_TYPE_OFFLINE, scope should be set
* to the sessionId the keys will be provided to. When the keyType is
* KEY_TYPE_RELEASE, scope should be set to the keySetId of the keys being released.
* Releasing keys from a device invalidates them for all sessions.
*
* init container-specific data, its meaning is interpreted based on the mime type
* provided in the mimeType parameter. It could contain, for example, the content
* ID, key ID or other data obtained from the content metadata that is required in
* generating the key request. init may be null when keyType is KEY_TYPE_RELEASE.
*
* initSize is the number of bytes of initData
*
* mimeType identifies the mime type of the content.
*
* keyType specifes the type of the request. The request may be to acquire keys for
* streaming or offline content, or to release previously acquired keys, which are
* identified by a keySetId.
*
* optionalParameters are included in the key request message to allow a client
* application to provide additional message parameters to the server.
*
* numOptionalParameters indicates the number of optional parameters provided
* by the caller
*
* On exit:
* 1. The keyRequest pointer will reference the opaque key request data. It
* will reside in memory owned by the AMediaDrm object, and will remain
* accessible until the next call to AMediaDrm_getKeyRequest or until the
* MediaDrm object is released.
* 2. keyRequestSize will be set to the size of the request
*
* returns MEDIADRM_NOT_PROVISIONED_ERROR if reprovisioning is needed, due to a
* problem with the device certificate.
*/
media_status_t AMediaDrm_getKeyRequest(AMediaDrm *, const AMediaDrmScope *scope,
const uint8_t *init, size_t initSize, const char *mimeType, AMediaDrmKeyType keyType,
const AMediaDrmKeyValue *optionalParameters, size_t numOptionalParameters,
const uint8_t **keyRequest, size_t *keyRequestSize);
/**
* A key response is received from the license server by the app, then it is
* provided to the DRM engine plugin using provideKeyResponse. When the
* response is for an offline key request, a keySetId is returned that can be
* used to later restore the keys to a new session with AMediaDrm_restoreKeys.
* When the response is for a streaming or release request, a null keySetId is
* returned.
*
* scope may be a sessionId or keySetId depending on the type of the
* response. Scope should be set to the sessionId