Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

am 3bde4594: am 0357ec78: Merge "DRM API doc scrub This change contains information contributed by Sony Corporation. Bug: 4119363" into honeycomb-mr1

Browse Source 
* commit '3bde4594d5794645b5f7e0ff1bf9c4a0b44161b1':
  DRM API doc scrub This change contains information contributed by Sony Corporation. Bug: 4119363
This commit is contained in:
Bill Gruber
2011-03-23 15:51:23 -07:00
committed by Android Git Automerger
parent 8346a6c273 3bde4594d5
commit 640f63c266
15 changed files with 589 additions and 466 deletions
Download Patch File Download Diff File Expand all files Collapse all files

BIN
docs/html/images/drm_arch.png Executable file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 24 KiB

23
drm/java/android/drm/DrmConvertedStatus.java Normal file → Executable file
View File

@@ -17,13 +17,11 @@
package android.drm;
/**
* This is an entity class which wraps the status of the conversion, the converted
* data/checksum data and the offset. Offset is going to be used in the case of close
* session where the agent will inform where the header and body signature should be added
*
* As a result of {@link DrmManagerClient#convertData(int, byte [])} and
* {@link DrmManagerClient#closeConvertSession(int)} an instance of DrmConvertedStatus
* would be returned.
* An entity class that wraps converted data, conversion status, and the
* offset for appending the header and body signature to the converted data. An instance of this
* class is returned by the {@link DrmManagerClient#convertData convertData()} and
* {@link DrmManagerClient#closeConvertSession closeConvertSession()} methods. The offset is provided only when a
* conversion session is closed by calling {@link DrmManagerClient#closeConvertSession closeConvertSession()}.
*
*/
public class DrmConvertedStatus {
@@ -32,16 +30,19 @@ public class DrmConvertedStatus {
public static final int STATUS_INPUTDATA_ERROR = 2;
public static final int STATUS_ERROR = 3;
/** Status code for the conversion.*/
public final int statusCode;
/** Converted data.*/
public final byte[] convertedData;
/** Offset value for the body and header signature.*/
public final int offset;
/**
* constructor to create DrmConvertedStatus object with given parameters
* Creates a <code>DrmConvertedStatus</code> object with the specified parameters.
*
* @param _statusCode Status of the conversion
* @param _convertedData Converted data/checksum data
* @param _offset Offset value
* @param _statusCode Conversion status.
* @param _convertedData Converted data.
* @param _offset Offset value for appending the header and body signature.
*/
public DrmConvertedStatus(int _statusCode, byte[] _convertedData, int _offset) {
statusCode = _statusCode;

45
drm/java/android/drm/DrmErrorEvent.java Normal file → Executable file
View File

@@ -19,70 +19,69 @@ package android.drm;
import java.util.HashMap;
/**
* This is an entity class which would be passed to caller in
* {@link DrmManagerClient.OnErrorListener#onError(DrmManagerClient, DrmErrorEvent)}
* An entity class that is passed to the
* {@link DrmManagerClient.OnErrorListener#onError onError()} callback.
*
*/
public class DrmErrorEvent extends DrmEvent {
/**
* TYPE_RIGHTS_NOT_INSTALLED, when something went wrong installing the rights.
* Something went wrong installing the rights.
*/
public static final int TYPE_RIGHTS_NOT_INSTALLED = 2001;
/**
* TYPE_RIGHTS_RENEWAL_NOT_ALLOWED, when the server rejects renewal of rights.
* The server rejected the renewal of rights.
*/
public static final int TYPE_RIGHTS_RENEWAL_NOT_ALLOWED = 2002;
/**
* TYPE_NOT_SUPPORTED, when answer from server can not be handled by the native agent.
* Response from the server cannot be handled by the DRM plug-in (agent).
*/
public static final int TYPE_NOT_SUPPORTED = 2003;
/**
* TYPE_OUT_OF_MEMORY, when memory allocation fail during renewal.
* Can in the future perhaps be used to trigger garbage collector.
* Memory allocation failed during renewal. Can in the future perhaps be used to trigger
* garbage collector.
*/
public static final int TYPE_OUT_OF_MEMORY = 2004;
/**
* TYPE_NO_INTERNET_CONNECTION, when the Internet connection is missing and no attempt
* can be made to renew rights.
* An Internet connection is not available and no attempt can be made to renew rights.
*/
public static final int TYPE_NO_INTERNET_CONNECTION = 2005;
/**
* TYPE_PROCESS_DRM_INFO_FAILED, when failed to process DrmInfo.
* Failed to process {@link DrmInfo}. This error event is sent when a
* {@link DrmManagerClient#processDrmInfo processDrmInfo()} call fails.
*/
public static final int TYPE_PROCESS_DRM_INFO_FAILED = 2006;
/**
* TYPE_REMOVE_ALL_RIGHTS_FAILED, when failed to remove all the rights objects
* associated with all DRM schemes.
* Failed to remove all the rights objects associated with all DRM schemes.
*/
public static final int TYPE_REMOVE_ALL_RIGHTS_FAILED = 2007;
/**
* TYPE_ACQUIRE_DRM_INFO_FAILED, when failed to acquire DrmInfo.
* Failed to acquire {@link DrmInfo}. This error event is sent when an
* {@link DrmManagerClient#acquireDrmInfo acquireDrmInfo()} call fails.
*/
public static final int TYPE_ACQUIRE_DRM_INFO_FAILED = 2008;
/**
* constructor to create DrmErrorEvent object with given parameters
* Creates a <code>DrmErrorEvent</code> object with the specified parameters.
*
* @param uniqueId Unique session identifier
* @param type Type of the event. It could be one of the types defined above
* @param message Message description
* @param uniqueId Unique session identifier.
* @param type Type of the event. Could be any of the event types defined above.
* @param message Message description.
*/
public DrmErrorEvent(int uniqueId, int type, String message) {
super(uniqueId, type, message);
}
/**
* constructor to create DrmErrorEvent object with given parameters
* Creates a <code>DrmErrorEvent</code> object with the specified parameters.
*
* @param uniqueId Unique session identifier
* @param type Type of the event. It could be one of the types defined above
* @param message Message description
* @param uniqueId Unique session identifier.
* @param type Type of the event. Could be any of the event types defined above.
* @param message Message description.
* @param attributes Attributes for extensible information. Could be any
* information provided by the plugin
* information provided by the plug-in.
*/
public DrmErrorEvent(int uniqueId, int type, String message,
HashMap<String, Object> attributes) {
super(uniqueId, type, message, attributes);
}
}

53
drm/java/android/drm/DrmEvent.java Normal file → Executable file
View File

@@ -19,22 +19,26 @@ package android.drm;
import java.util.HashMap;
/**
* This is the base class which would be used to notify the caller
* about any event occurred in DRM framework.
* A base class that is used to send asynchronous event information from the DRM framework.
*
*/
public class DrmEvent {
/**
* Constant field signifies that all the rights information associated with
* all DRM schemes are removed successfully
* All of the rights information associated with all DRM schemes have been successfully removed.
*/
public static final int TYPE_ALL_RIGHTS_REMOVED = 1001;
/**
* Constant field signifies that given information is processed successfully
* The given DRM information has been successfully processed.
*/
public static final int TYPE_DRM_INFO_PROCESSED = 1002;
/**
* The key that is used in the <code>attributes</code> HashMap to pass the return status.
*/
public static final String DRM_INFO_STATUS_OBJECT = "drm_info_status_object";
/**
* The key that is used in the <code>attributes</code> HashMap to pass the
* {@link DrmInfo} object.
*/
public static final String DRM_INFO_OBJECT = "drm_info_object";
private final int mUniqueId;
@@ -44,12 +48,12 @@ public class DrmEvent {
private HashMap<String, Object> mAttributes = new HashMap<String, Object>();
/**
* constructor for DrmEvent class
* Creates a <code>DrmEvent</code> object with the specified parameters.
*
* @param uniqueId Unique session identifier
* @param type Type of information
* @param message Message description
* @param attributes Attributes for extensible information
* @param uniqueId Unique session identifier.
* @param type Type of information.
* @param message Message description.
* @param attributes Attributes for extensible information.
*/
protected DrmEvent(int uniqueId, int type, String message,
HashMap<String, Object> attributes) {
@@ -66,11 +70,11 @@ public class DrmEvent {
}
/**
* constructor for DrmEvent class
* Creates a <code>DrmEvent</code> object with the specified parameters.
*
* @param uniqueId Unique session identifier
* @param type Type of information
* @param message Message description
* @param uniqueId Unique session identifier.
* @param type Type of information.
* @param message Message description.
*/
protected DrmEvent(int uniqueId, int type, String message) {
mUniqueId = uniqueId;
@@ -82,40 +86,39 @@ public class DrmEvent {
}
/**
* Returns the Unique Id associated with this object
* Retrieves the unique session identifier associated with this object.
*
* @return Unique Id
* @return The unique session identifier.
*/
public int getUniqueId() {
return mUniqueId;
}
/**
* Returns the Type of information associated with this object
* Retrieves the type of information that is associated with this object.
*
* @return Type of information
* @return The type of information.
*/
public int getType() {
return mType;
}
/**
* Returns the message description associated with this object
* Retrieves the message description associated with this object.
*
* @return message description
* @return The message description.
*/
public String getMessage() {
return mMessage;
}
/**
* Returns the attribute corresponding to the specified key
* Retrieves the attribute associated with the specified key.
*
* @return one of the attributes or null if no mapping for
* the key is found
* @return One of the attributes or null if no mapping for
* the key is found.
*/
public Object getAttribute(String key) {
return mAttributes.get(key);
}
}

70
drm/java/android/drm/DrmInfo.java Normal file → Executable file
View File

@@ -21,14 +21,13 @@ import java.util.HashMap;
import java.util.Iterator;
/**
* This is an entity class in which necessary information required to transact
* between device and online DRM server is described. DRM Framework achieves
* server registration, license acquisition and any other server related transaction
* by passing an instance of this class to {@link DrmManagerClient#processDrmInfo(DrmInfo)}.
*
* Caller can retrieve the {@link DrmInfo} instance by using
* {@link DrmManagerClient#acquireDrmInfo(DrmInfoRequest)}
* by passing {@link DrmInfoRequest} instance.
* An entity class that describes the information required to send transactions
* between a device and an online DRM server. The DRM framework achieves
* server registration, license acquisition, and any other server-related transactions
* by passing an instance of this class to {@link DrmManagerClient#processDrmInfo}.
*<p>
* The caller can retrieve the {@link DrmInfo} instance by passing a {@link DrmInfoRequest}
* instance to {@link DrmManagerClient#acquireDrmInfo}.
*
*/
public class DrmInfo {
@@ -40,11 +39,11 @@ public class DrmInfo {
private final HashMap<String, Object> mAttributes = new HashMap<String, Object>();
/**
* constructor to create DrmInfo object with given parameters
* Creates a <code>DrmInfo</code> object with the given parameters.
*
* @param infoType Type of information
* @param data Trigger data
* @param mimeType MIME type
* @param infoType The type of information.
* @param data The trigger data.
* @param mimeType The MIME type.
*/
public DrmInfo(int infoType, byte[] data, String mimeType) {
mInfoType = infoType;
@@ -53,11 +52,11 @@ public class DrmInfo {
}
/**
* constructor to create DrmInfo object with given parameters
* Creates a <code>DrmInfo</code> object with the given parameters.
*
* @param infoType Type of information
* @param path Trigger data
* @param mimeType MIME type
* @param infoType The type of information.
* @param path The trigger data.
* @param mimeType The MIME type.
*/
public DrmInfo(int infoType, String path, String mimeType) {
mInfoType = infoType;
@@ -73,67 +72,70 @@ public class DrmInfo {
}
/**
* Adds optional information as <key, value> pair to this object
* Adds optional information as key-value pairs to this object. To add a custom object
* to the <code>DrmInfo</code> object, you must override the {@link #toString} implementation.
*
* @param key Key to add.
* @param value Value to add.
*
* @param key Key to add
* @param value Value to add
* To put custom object into DrmInfo, custom object has to
* override toString() implementation.
*/
public void put(String key, Object value) {
mAttributes.put(key, value);
}
/**
* Retrieves the value of given key, if not found returns null
* Retrieves the value of a given key.
*
* @param key Key whose value to be retrieved
* @return The value or null
* @param key The key whose value is being retrieved.
*
* @return The value of the key being retrieved. Returns null if the key cannot be found.
*/
public Object get(String key) {
return mAttributes.get(key);
}
/**
* Returns Iterator object to walk through the keys associated with this instance
* Retrieves an iterator object that you can use to iterate over the keys associated with
* this <code>DrmInfo</code> object.
*
* @return Iterator object
* @return The iterator object.
*/
public Iterator<String> keyIterator() {
return mAttributes.keySet().iterator();
}
/**
* Returns Iterator object to walk through the values associated with this instance
* Retrieves an iterator object that you can use to iterate over the values associated with
* this <code>DrmInfo</code> object.
*
* @return Iterator object
* @return The iterator object.
*/
public Iterator<Object> iterator() {
return mAttributes.values().iterator();
}
/**
* Returns the trigger data associated with this object
* Retrieves the trigger data associated with this object.
*
* @return Trigger data
* @return The trigger data.
*/
public byte[] getData() {
return mData;
}
/**
* Returns the mimetype associated with this object
* Retrieves the MIME type associated with this object.
*
* @return MIME type
* @return The MIME type.
*/
public String getMimeType() {
return mMimeType;
}
/**
* Returns information type associated with this instance
* Retrieves the information type associated with this object.
*
* @return Information type
* @return The information type.
*/
public int getInfoType() {
return mInfoType;

38
drm/java/android/drm/DrmInfoEvent.java Normal file → Executable file
View File

@@ -19,58 +19,56 @@ package android.drm;
import java.util.HashMap;
/**
* This is an entity class which would be passed to caller in
* {@link DrmManagerClient.OnInfoListener#onInfo(DrmManagerClient, DrmInfoEvent)}
* An entity class that is passed to the
* {@link DrmManagerClient.OnInfoListener#onInfo onInfo()} callback.
*
*/
public class DrmInfoEvent extends DrmEvent {
/**
* TYPE_ALREADY_REGISTERED_BY_ANOTHER_ACCOUNT, when registration has been already done
* by another account ID.
* The registration has already been done by another account ID.
*/
public static final int TYPE_ALREADY_REGISTERED_BY_ANOTHER_ACCOUNT = 1;
/**
* TYPE_REMOVE_RIGHTS, when the rights needs to be removed completely.
* The rights need to be removed completely.
*/
public static final int TYPE_REMOVE_RIGHTS = 2;
/**
* TYPE_RIGHTS_INSTALLED, when the rights are downloaded and installed ok.
* The rights have been successfully downloaded and installed.
*/
public static final int TYPE_RIGHTS_INSTALLED = 3;
/**
* TYPE_WAIT_FOR_RIGHTS, rights object is on it's way to phone,
* wait before calling checkRights again.
* The rights object is being delivered to the device. You must wait before
* calling {@link DrmManagerClient#acquireRights acquireRights()} again.
*/
public static final int TYPE_WAIT_FOR_RIGHTS = 4;
/**
* TYPE_ACCOUNT_ALREADY_REGISTERED, when registration has been
* already done for the given account.
* The registration has already been done for the given account.
*/
public static final int TYPE_ACCOUNT_ALREADY_REGISTERED = 5;
/**
* TYPE_RIGHTS_REMOVED, when the rights has been removed.
* The rights have been removed.
*/
public static final int TYPE_RIGHTS_REMOVED = 6;
/**
* constructor to create DrmInfoEvent object with given parameters
* Creates a <code>DrmInfoEvent</code> object with the specified parameters.
*
* @param uniqueId Unique session identifier
* @param type Type of the event. It could be one of the types defined above
* @param message Message description
* @param uniqueId Unique session identifier.
* @param type Type of the event. Could be any of the event types defined above.
* @param message Message description.
*/
public DrmInfoEvent(int uniqueId, int type, String message) {
super(uniqueId, type, message);
}
/**
* constructor to create DrmInfoEvent object with given parameters
* Creates a <code>DrmInfoEvent</code> object with the specified parameters.
*
* @param uniqueId Unique session identifier
* @param type Type of the event. It could be one of the types defined above
* @param message Message description
* @param uniqueId Unique session identifier.
* @param type Type of the event. Could be any of the event types defined above.
* @param message Message description.
* @param attributes Attributes for extensible information. Could be any
* information provided by the plugin
* information provided by the plug-in.
*/
public DrmInfoEvent(int uniqueId, int type, String message,
HashMap<String, Object> attributes) {

61
drm/java/android/drm/DrmInfoRequest.java Normal file → Executable file
View File

@@ -20,30 +20,37 @@ import java.util.HashMap;
import java.util.Iterator;
/**
* This is an entity class used to pass required parameters to get
* the necessary information to communicate with online DRM server
*
* An instance of this class is passed to {@link DrmManagerClient#acquireDrmInfo(DrmInfoRequest)}
* to get the instance of {@link DrmInfo}
* An entity class that is used to pass information to an online DRM server. An instance of this
* class is passed to the {@link DrmManagerClient#acquireDrmInfo acquireDrmInfo()} method to get an
* instance of a {@link DrmInfo}.
*
*/
public class DrmInfoRequest {
// Changes in following constants should be in sync with DrmInfoRequest.cpp
/**
* Constants defines the type of {@link DrmInfoRequest}
* Acquires DRM server registration information.
*/
public static final int TYPE_REGISTRATION_INFO = 1;
/**
* Acquires information for unregistering the DRM server.
*/
public static final int TYPE_UNREGISTRATION_INFO = 2;
/**
* Acquires rights information.
*/
public static final int TYPE_RIGHTS_ACQUISITION_INFO = 3;
/**
* Acquires the progress of the rights acquisition.
*/
public static final int TYPE_RIGHTS_ACQUISITION_PROGRESS_INFO = 4;
/**
* Key to pass the unique id for the account or the user
* Key that is used to pass the unique session ID for the account or the user.
*/
public static final String ACCOUNT_ID = "account_id";
/**
* Key to pass the unique id used for subscription
* Key that is used to pass the unique session ID for the subscription.
*/
public static final String SUBSCRIPTION_ID = "subscription_id";
@@ -52,10 +59,10 @@ public class DrmInfoRequest {
private final HashMap<String, Object> mRequestInformation = new HashMap<String, Object>();
/**
* constructor to create DrmInfoRequest object with type and mimetype
* Creates a <code>DrmInfoRequest</code> object with type and MIME type.
*
* @param infoType Type of information
* @param mimeType MIME type
* @param infoType Type of information.
* @param mimeType MIME type.
*/
public DrmInfoRequest(int infoType, String mimeType) {
mInfoType = infoType;
@@ -63,56 +70,60 @@ public class DrmInfoRequest {
}
/**
* Returns the mimetype associated with this object
* Retrieves the MIME type associated with this object.
*
* @return MIME type
* @return The MIME type.
*/
public String getMimeType() {
return mMimeType;
}
/**
* Returns Information type associated with this instance
* Retrieves the information type associated with this object.
*
* @return Information type
* @return The information type.
*/
public int getInfoType() {
return mInfoType;
}
/**
* Adds optional information as <key, value> pair to this object.
* Adds optional information as key-value pairs to this object.
*
* @param key Key to add
* @param value Value to add
* @param key The key to add.
* @param value The value to add.
*/
public void put(String key, Object value) {
mRequestInformation.put(key, value);
}
/**
* Retrieves the value of given key, if not found returns null
* Retrieves the value of a given key.
*
* @param key Key whose value to be retrieved
* @return The value or null
* @param key The key whose value is being retrieved.
*
* @return The value of the key that is being retrieved. Returns null if the key cannot be
* found.
*/
public Object get(String key) {
return mRequestInformation.get(key);
}
/**
* Returns Iterator object to walk through the keys associated with this instance
* Retrieves an iterator object that you can use to iterate over the keys associated with
* this <code>DrmInfoRequest</code> object.
*
* @return Iterator object
* @return The iterator object.
*/
public Iterator<String> keyIterator() {
return mRequestInformation.keySet().iterator();
}
/**
* Returns Iterator object to walk through the values associated with this instance
* Retrieves an iterator object that you can use to iterate over the values associated with
* this <code>DrmInfoRequest</code> object.
*
* @return Iterator object
* @return The iterator object.
*/
public Iterator<Object> iterator() {
return mRequestInformation.values().iterator();

34
drm/java/android/drm/DrmInfoStatus.java Normal file → Executable file
View File

@@ -17,12 +17,12 @@
package android.drm;
/**
* This is an entity class which wraps the result of communication between device
* and online DRM server.
*
* As a result of {@link DrmManagerClient#processDrmInfo(DrmInfo)} an instance of DrmInfoStatus
* would be returned. This class holds {@link ProcessedData}, which could be used to instantiate
* {@link DrmRights#DrmRights(ProcessedData, String)} in license acquisition.
* An entity class that wraps the result of communication between a device and an online DRM
* server. Specifically, when the {@link DrmManagerClient#processDrmInfo processDrmInfo()} method
* is called, an instance of <code>DrmInfoStatus</code> is returned.
*<p>
* This class contains the {@link ProcessedData} object, which can be used to instantiate a
* {@link DrmRights} object during license acquisition.
*
*/
public class DrmInfoStatus {
@@ -30,18 +30,30 @@ public class DrmInfoStatus {
public static final int STATUS_OK = 1;
public static final int STATUS_ERROR = 2;
/**
* The status of the communication.
*/
public final int statusCode;
/**
* The type of DRM information processed.
*/
public final int infoType;
/**
* The MIME type of the content.
*/
public final String mimeType;
/**
* The processed data.
*/
public final ProcessedData data;
/**
* constructor to create DrmInfoStatus object with given parameters
* Creates a <code>DrmInfoStatus</code> object with the specified parameters.
*
* @param _statusCode Status of the communication
* @param _infoType Type of the DRM information processed
* @param _data The processed data
* @param _mimeType MIME type
* @param _statusCode The status of the communication.
* @param _infoType The type of the DRM information processed.
* @param _data The processed data.
* @param _mimeType The MIME type.
*/
public DrmInfoStatus(int _statusCode, int _infoType, ProcessedData _data, String _mimeType) {
statusCode = _statusCode;

348
drm/java/android/drm/DrmManagerClient.java Normal file → Executable file
View File

@@ -35,18 +35,17 @@ import java.util.ArrayList;
import java.util.HashMap;
/**
* Interface of DRM Framework.
* Java application will instantiate this class
* to access DRM agent through DRM Framework.
* The main programming interface for the DRM framework. An application must instantiate this class
* to access DRM agents through the DRM framework.
*
*/
public class DrmManagerClient {
/**
* Constant field signifies the success or no error occurred
* Indicates that a request was successful or that no error occurred.
*/
public static final int ERROR_NONE = 0;
/**
* Constant field signifies that error occurred and the reason is not known
* Indicates that an error occurred and the reason is not known.
*/
public static final int ERROR_UNKNOWN = -2000;
@@ -58,43 +57,45 @@ public class DrmManagerClient {
}
/**
* Interface definition of a callback to be invoked to communicate
* some info and/or warning about DrmManagerClient.
* Interface definition for a callback that receives status messages and warnings
* during registration and rights acquisition.
*/
public interface OnInfoListener {
/**
* Called to indicate an info or a warning.
* Called when the DRM framework sends status or warning information during registration
* and rights acquisition.
*
* @param client DrmManagerClient instance
* @param event instance which wraps reason and necessary information
* @param client The <code>DrmManagerClient</code> instance.
* @param event The {@link DrmInfoEvent} instance that wraps the status information or
* warnings.
*/
public void onInfo(DrmManagerClient client, DrmInfoEvent event);
}
/**
* Interface definition of a callback to be invoked to communicate
* the result of time consuming APIs asynchronously
* Interface definition for a callback that receives information
* about DRM processing events.
*/
public interface OnEventListener {
/**
* Called to indicate the result of asynchronous APIs.
* Called when the DRM framework sends information about a DRM processing request.
*
* @param client DrmManagerClient instance
* @param event instance which wraps type and message
* @param client The <code>DrmManagerClient</code> instance.
* @param event The {@link DrmEvent} instance that wraps the information being
* conveyed, such as the information type and message.
*/
public void onEvent(DrmManagerClient client, DrmEvent event);
}
/**
* Interface definition of a callback to be invoked to communicate
* the error occurred
* Interface definition for a callback that receives information about DRM framework errors.
*/
public interface OnErrorListener {
/**
* Called to indicate the error occurred.
* Called when the DRM framework sends error information.
*
* @param client DrmManagerClient instance
* @param event instance which wraps error type and message
* @param client The <code>DrmManagerClient</code> instance.
* @param event The {@link DrmErrorEvent} instance that wraps the error type and message.
*/
public void onError(DrmManagerClient client, DrmErrorEvent event);
}
@@ -231,9 +232,9 @@ public class DrmManagerClient {
}
/**
* To instantiate DrmManagerClient
* Creates a <code>DrmManagerClient</code>.
*
* @param context context of the caller
* @param context Context of the caller.
*/
public DrmManagerClient(Context context) {
mContext = context;
@@ -257,10 +258,10 @@ public class DrmManagerClient {
}
/**
* Register a callback to be invoked when the caller required to receive
* supplementary information.
* Registers an {@link DrmManagerClient.OnInfoListener} callback, which is invoked when the
* DRM framework sends status or warning information during registration or rights acquisition.
*
* @param infoListener
* @param infoListener Interface definition for the callback.
*/
public synchronized void setOnInfoListener(OnInfoListener infoListener) {
if (null != infoListener) {
@@ -269,10 +270,10 @@ public class DrmManagerClient {
}
/**
* Register a callback to be invoked when the caller required to receive
* the result of asynchronous APIs.
* Registers an {@link DrmManagerClient.OnEventListener} callback, which is invoked when the
* DRM framework sends information about DRM processing.
*
* @param eventListener
* @param eventListener Interface definition for the callback.
*/
public synchronized void setOnEventListener(OnEventListener eventListener) {
if (null != eventListener) {
@@ -281,10 +282,10 @@ public class DrmManagerClient {
}
/**
* Register a callback to be invoked when the caller required to receive
* error result of asynchronous APIs.
* Registers an {@link DrmManagerClient.OnErrorListener} callback, which is invoked when
* the DRM framework sends error information.
*
* @param errorListener
* @param errorListener Interface definition for the callback.
*/
public synchronized void setOnErrorListener(OnErrorListener errorListener) {
if (null != errorListener) {
@@ -293,9 +294,10 @@ public class DrmManagerClient {
}
/**
* Retrieves informations about all the plug-ins registered with DrmFramework.
* Retrieves information about all the DRM plug-ins (agents) that are registered with
* the DRM framework.
*
* @return Array of DrmEngine plug-in strings
* @return A <code>String</code> array of DRM plug-in descriptions.
*/
public String[] getAvailableDrmEngines() {
DrmSupportInfo[] supportInfos = _getAllSupportInfo(mUniqueId);
@@ -310,12 +312,13 @@ public class DrmManagerClient {
}
/**
* Get constraints information evaluated from DRM content
* Retrieves constraint information for rights-protected content.
*
* @param path Content path from where DRM constraints would be retrieved.
* @param action Actions defined in {@link DrmStore.Action}
* @return ContentValues instance in which constraints key-value pairs are embedded
* or null in case of failure
* @param path Path to the content from which you are retrieving DRM constraints.
* @param action Action defined in {@link DrmStore.Action}.
*
* @return A {@link android.content.ContentValues} instance that contains
* key-value pairs representing the constraints. Null in case of failure.
*/
public ContentValues getConstraints(String path, int action) {
if (null == path || path.equals("") || !DrmStore.Action.isValid(action)) {
@@ -325,11 +328,12 @@ public class DrmManagerClient {
}
/**
* Get metadata information from DRM content
* Retrieves metadata information for rights-protected content.
*
* @param path Content path from where DRM metadata would be retrieved.
* @return ContentValues instance in which metadata key-value pairs are embedded
* or null in case of failure
* @param path Path to the content from which you are retrieving metadata information.
*
* @return A {@link android.content.ContentValues} instance that contains
* key-value pairs representing the metadata. Null in case of failure.
*/
public ContentValues getMetadata(String path) {
if (null == path || path.equals("")) {
@@ -339,12 +343,13 @@ public class DrmManagerClient {
}
/**
* Get constraints information evaluated from DRM content
* Retrieves constraint information for rights-protected content.
*
* @param uri Content URI from where DRM constraints would be retrieved.
* @param action Actions defined in {@link DrmStore.Action}
* @return ContentValues instance in which constraints key-value pairs are embedded
* or null in case of failure
* @param uri URI for the content from which you are retrieving DRM constraints.
* @param action Action defined in {@link DrmStore.Action}.
*
* @return A {@link android.content.ContentValues} instance that contains
* key-value pairs representing the constraints. Null in case of failure.
*/
public ContentValues getConstraints(Uri uri, int action) {
if (null == uri || Uri.EMPTY == uri) {
@@ -354,11 +359,12 @@ public class DrmManagerClient {
}
/**
* Get metadata information from DRM content
* Retrieves metadata information for rights-protected content.
*
* @param uri Content URI from where DRM metadata would be retrieved.
* @return ContentValues instance in which metadata key-value pairs are embedded
* or null in case of failure
* @param uri URI for the content from which you are retrieving metadata information.
*
* @return A {@link android.content.ContentValues} instance that contains
* key-value pairs representing the constraints. Null in case of failure.
*/
public ContentValues getMetadata(Uri uri) {
if (null == uri || Uri.EMPTY == uri) {
@@ -368,18 +374,19 @@ public class DrmManagerClient {
}
/**
* Save DRM rights to specified rights path
* and make association with content path.
* Saves rights to a specified path and associates that path with the content path.
*
* <p class="note"><strong>Note:</strong> For OMA or WM-DRM, <code>rightsPath</code> and
* <code>contentPath</code> can be null.</p>
*
* <p class="note">In case of OMA or WM-DRM, rightsPath and contentPath could be null.</p>
* @param drmRights The {@link DrmRights} to be saved.
* @param rightsPath File path where rights will be saved.
* @param contentPath File path where content is saved.
*
* @param drmRights DrmRights to be saved
* @param rightsPath File path where rights to be saved
* @param contentPath File path where content was saved
* @return
* ERROR_NONE for success
* ERROR_UNKNOWN for failure
* @throws IOException if failed to save rights information in the given path
* @return ERROR_NONE for success; ERROR_UNKNOWN for failure.
*
* @throws IOException If the call failed to save rights information at the given
* <code>rightsPath</code>.
*/
public int saveRights(
DrmRights drmRights, String rightsPath, String contentPath) throws IOException {
@@ -393,9 +400,10 @@ public class DrmManagerClient {
}
/**
* Install new DRM Engine Plug-in at the runtime
* Installs a new DRM plug-in (agent) at runtime.
*
* @param engineFilePath File path to the plug-in file to be installed.
*
* @param engineFilePath Path of the plug-in file to be installed
* {@hide}
*/
public void installDrmEngine(String engineFilePath) {
@@ -407,13 +415,12 @@ public class DrmManagerClient {
}
/**
* Check whether the given mimetype or path can be handled.
* Checks whether the given MIME type or path can be handled.
*
* @param path Path of the content to be handled
* @param mimeType Mimetype of the object to be handled
* @return
* true - if the given mimeType or path can be handled
* false - cannot be handled.
* @param path Path of the content to be handled.
* @param mimeType MIME type of the object to be handled.
*
* @return True if the given MIME type or path can be handled; false if they cannot be handled.
*/
public boolean canHandle(String path, String mimeType) {
if ((null == path || path.equals("")) && (null == mimeType || mimeType.equals(""))) {
@@ -423,13 +430,12 @@ public class DrmManagerClient {
}
/**
* Check whether the given mimetype or uri can be handled.
* Checks whether the given MIME type or URI can be handled.
*
* @param uri Content URI of the data to be handled.
* @param mimeType Mimetype of the object to be handled
* @return
* true - if the given mimeType or path can be handled
* false - cannot be handled.
* @param uri URI for the content to be handled.
* @param mimeType MIME type of the object to be handled
*
* @return True if the given MIME type or URI can be handled; false if they cannot be handled.
*/
public boolean canHandle(Uri uri, String mimeType) {
if ((null == uri || Uri.EMPTY == uri) && (null == mimeType || mimeType.equals(""))) {
@@ -439,12 +445,10 @@ public class DrmManagerClient {
}
/**
* Executes given drm information based on its type
* Processes the given DRM information based on the information type.
*
* @param drmInfo Information needs to be processed
* @return
* ERROR_NONE for success
* ERROR_UNKNOWN for failure
* @param drmInfo The {@link DrmInfo} to be processed.
* @return ERROR_NONE for success; ERROR_UNKNOWN for failure.
*/
public int processDrmInfo(DrmInfo drmInfo) {
if (null == drmInfo || !drmInfo.isValid()) {
@@ -459,10 +463,12 @@ public class DrmManagerClient {
}
/**
* Retrieves necessary information for register, unregister or rights acquisition.
* Retrieves information for registering, unregistering, or acquiring rights.
*
* @param drmInfoRequest Request information to retrieve drmInfo
* @return DrmInfo Instance as a result of processing given input
* @param drmInfoRequest The {@link DrmInfoRequest} that specifies the type of DRM
* information being retrieved.
*
* @return A {@link DrmInfo} instance.
*/
public DrmInfo acquireDrmInfo(DrmInfoRequest drmInfoRequest) {
if (null == drmInfoRequest || !drmInfoRequest.isValid()) {
@@ -472,17 +478,18 @@ public class DrmManagerClient {
}
/**
* Executes given DrmInfoRequest and returns the rights information asynchronously.
* This is a utility API which consists of {@link #acquireDrmInfo(DrmInfoRequest)}
* and {@link #processDrmInfo(DrmInfo)}.
* It can be used if selected DRM agent can work with this combined sequences.
* In case of some DRM schemes, such as OMA DRM, application needs to invoke
* {@link #acquireDrmInfo(DrmInfoRequest)} and {@link #processDrmInfo(DrmInfo)}, separately.
* Processes a given {@link DrmInfoRequest} and returns the rights information asynchronously.
*<p>
* This is a utility method that consists of an
* {@link #acquireDrmInfo(DrmInfoRequest) acquireDrmInfo()} and a
* {@link #processDrmInfo(DrmInfo) processDrmInfo()} method call. This utility method can be
* used only if the selected DRM plug-in (agent) supports this sequence of calls. Some DRM
* agents, such as OMA, do not support this utility method, in which case an application must
* invoke {@link #acquireDrmInfo(DrmInfoRequest) acquireDrmInfo()} and
* {@link #processDrmInfo(DrmInfo) processDrmInfo()} separately.
*
* @param drmInfoRequest Request information to retrieve drmInfo
* @return
* ERROR_NONE for success
* ERROR_UNKNOWN for failure
* @param drmInfoRequest The {@link DrmInfoRequest} used to acquire the rights.
* @return ERROR_NONE for success; ERROR_UNKNOWN for failure.
*/
public int acquireRights(DrmInfoRequest drmInfoRequest) {
DrmInfo drmInfo = acquireDrmInfo(drmInfoRequest);
@@ -493,14 +500,14 @@ public class DrmManagerClient {
}
/**
* Retrieves the type of the protected object (content, rights, etc..)
* using specified path or mimetype. At least one parameter should be non null
* to retrieve DRM object type
* Retrieves the type of rights-protected object (for example, content object, rights
* object, and so on) using the specified path or MIME type. At least one parameter must
* be specified to retrieve the DRM object type.
*
* @param path Path of the content or null.
* @param mimeType Mimetype of the content or null.
* @return Type of the DRM content.
* @see DrmStore.DrmObjectType
* @param path Path to the content or null.
* @param mimeType MIME type of the content or null.
*
* @return An <code>int</code> that corresponds to a {@link DrmStore.DrmObjectType}.
*/
public int getDrmObjectType(String path, String mimeType) {
if ((null == path || path.equals("")) && (null == mimeType || mimeType.equals(""))) {
@@ -510,14 +517,14 @@ public class DrmManagerClient {
}
/**
* Retrieves the type of the protected object (content, rights, etc..)
* using specified uri or mimetype. At least one parameter should be non null
* to retrieve DRM object type
* Retrieves the type of rights-protected object (for example, content object, rights
* object, and so on) using the specified URI or MIME type. At least one parameter must
* be specified to retrieve the DRM object type.
*
* @param uri The content URI of the data
* @param mimeType Mimetype of the content or null.
* @return Type of the DRM content.
* @see DrmStore.DrmObjectType
* @param uri URI for the content or null.
* @param mimeType MIME type of the content or null.
*
* @return An <code>int</code> that corresponds to a {@link DrmStore.DrmObjectType}.
*/
public int getDrmObjectType(Uri uri, String mimeType) {
if ((null == uri || Uri.EMPTY == uri) && (null == mimeType || mimeType.equals(""))) {
@@ -534,10 +541,11 @@ public class DrmManagerClient {
}
/**
* Retrieves the mime type embedded inside the original content
* Retrieves the MIME type embedded in the original content.
*
* @param path Path of the protected content
* @return Mimetype of the original content, such as "video/mpeg"
* @param path Path to the rights-protected content.
*
* @return The MIME type of the original content, such as <code>video/mpeg</code>.
*/
public String getOriginalMimeType(String path) {
if (null == path || path.equals("")) {
@@ -547,10 +555,11 @@ public class DrmManagerClient {
}
/**
* Retrieves the mime type embedded inside the original content
* Retrieves the MIME type embedded in the original content.
*
* @param uri The content URI of the data
* @return Mimetype of the original content, such as "video/mpeg"
* @param uri URI of the rights-protected content.
*
* @return MIME type of the original content, such as <code>video/mpeg</code>.
*/
public String getOriginalMimeType(Uri uri) {
if (null == uri || Uri.EMPTY == uri) {
@@ -560,22 +569,22 @@ public class DrmManagerClient {
}
/**
* Check whether the given content has valid rights or not
* Checks whether the given content has valid rights.
*
* @param path Path of the protected content
* @return Status of the rights for the protected content
* @see DrmStore.RightsStatus
* @param path Path to the rights-protected content.
*
* @return An <code>int</code> representing the {@link DrmStore.RightsStatus} of the content.
*/
public int checkRightsStatus(String path) {
return checkRightsStatus(path, DrmStore.Action.DEFAULT);
}
/**
* Check whether the given content has valid rights or not
* Check whether the given content has valid rights.
*
* @param uri The content URI of the data
* @return Status of the rights for the protected content
* @see DrmStore.RightsStatus
* @param uri URI of the rights-protected content.
*
* @return An <code>int</code> representing the {@link DrmStore.RightsStatus} of the content.
*/
public int checkRightsStatus(Uri uri) {
if (null == uri || Uri.EMPTY == uri) {
@@ -585,12 +594,13 @@ public class DrmManagerClient {
}
/**
* Check whether the given content has valid rights or not for specified action.
* Checks whether the given rights-protected content has valid rights for the specified
* {@link DrmStore.Action}.
*
* @param path Path of the protected content
* @param action Action to perform
* @return Status of the rights for the protected content
* @see DrmStore.RightsStatus
* @param path Path to the rights-protected content.
* @param action The {@link DrmStore.Action} to perform.
*
* @return An <code>int</code> representing the {@link DrmStore.RightsStatus} of the content.
*/
public int checkRightsStatus(String path, int action) {
if (null == path || path.equals("") || !DrmStore.Action.isValid(action)) {
@@ -600,12 +610,13 @@ public class DrmManagerClient {
}
/**
* Check whether the given content has valid rights or not for specified action.
* Checks whether the given rights-protected content has valid rights for the specified
* {@link DrmStore.Action}.
*
* @param uri The content URI of the data
* @param action Action to perform
* @return Status of the rights for the protected content
* @see DrmStore.RightsStatus
* @param uri URI for the rights-protected content.
* @param action The {@link DrmStore.Action} to perform.
*
* @return An <code>int</code> representing the {@link DrmStore.RightsStatus} of the content.
*/
public int checkRightsStatus(Uri uri, int action) {
if (null == uri || Uri.EMPTY == uri) {
@@ -615,12 +626,11 @@ public class DrmManagerClient {
}
/**
* Removes the rights associated with the given protected content
* Removes the rights associated with the given rights-protected content.
*
* @param path Path of the protected content
* @return
* ERROR_NONE for success
* ERROR_UNKNOWN for failure
* @param path Path to the rights-protected content.
*
* @return ERROR_NONE for success; ERROR_UNKNOWN for failure.
*/
public int removeRights(String path) {
if (null == path || path.equals("")) {
@@ -630,12 +640,11 @@ public class DrmManagerClient {
}
/**
* Removes the rights associated with the given protected content
* Removes the rights associated with the given rights-protected content.
*
* @param uri The content URI of the data
* @return
* ERROR_NONE for success
* ERROR_UNKNOWN for failure
* @param uri URI for the rights-protected content.
*
* @return ERROR_NONE for success; ERROR_UNKNOWN for failure.
*/
public int removeRights(Uri uri) {
if (null == uri || Uri.EMPTY == uri) {
@@ -645,12 +654,10 @@ public class DrmManagerClient {
}
/**
* Removes all the rights information of every plug-in associated with
* DRM framework. Will be used in master reset
* Removes all the rights information of every DRM plug-in (agent) associated with
* the DRM framework. Will be used during a master reset.
*
* @return
* ERROR_NONE for success
* ERROR_UNKNOWN for failure
* @return ERROR_NONE for success; ERROR_UNKNOWN for failure.
*/
public int removeAllRights() {
int result = ERROR_UNKNOWN;
@@ -662,13 +669,14 @@ public class DrmManagerClient {
}
/**
* This API is for Forward Lock based DRM scheme.
* Each time the application tries to download a new DRM file
* which needs to be converted, then the application has to
* begin with calling this API.
* Initiates a new conversion session. An application must initiate a conversion session
* with this method each time it downloads a rights-protected file that needs to be converted.
*<p>
* This method applies only to forward-locking (copy protection) DRM schemes.
*
* @param mimeType Description/MIME type of the input data packet
* @return convert ID which will be used for maintaining convert session.
* @param mimeType MIME type of the input data packet.
*
* @return A convert ID that is used used to maintain the conversion session.
*/
public int openConvertSession(String mimeType) {
if (null == mimeType || mimeType.equals("")) {
@@ -678,16 +686,17 @@ public class DrmManagerClient {
}
/**
* Accepts and converts the input data which is part of DRM file.
* The resultant converted data and the status is returned in the DrmConvertedInfo
* object. This method will be called each time there are new block
* of data received by the application.
* Converts the input data (content) that is part of a rights-protected file. The converted
* data and status is returned in a {@link DrmConvertedStatus} object. This method should be
* called each time there is a new block of data received by the application.
*
* @param convertId Handle for the convert session
* @param inputData Input Data which need to be converted
* @return Return object contains the status of the data conversion,
* the output converted data and offset. In this case the
* application will ignore the offset information.
* @param convertId Handle for the conversion session.
* @param inputData Input data that needs to be converted.
*
* @return A {@link DrmConvertedStatus} object that contains the status of the data conversion,
* the converted data, and offset for the header and body signature. An application can
* ignore the offset because it is only relevant to the
* {@link #closeConvertSession closeConvertSession()} method.
*/
public DrmConvertedStatus convertData(int convertId, byte[] inputData) {
if (null == inputData || 0 >= inputData.length) {
@@ -697,16 +706,15 @@ public class DrmManagerClient {
}
/**
* Informs the Drm Agent when there is no more data which need to be converted
* or when an error occurs. Upon successful conversion of the complete data,
* the agent will inform that where the header and body signature
* should be added. This signature appending is needed to integrity
* protect the converted file.
* Informs the DRM plug-in (agent) that there is no more data to convert or that an error
* has occurred. Upon successful conversion of the data, the DRM agent will provide an offset
* value indicating where the header and body signature should be added. Appending the
* signature is necessary to protect the integrity of the converted file.
*
* @param convertId Handle for the convert session
* @return Return object contains the status of the data conversion,
* the header and body signature data. It also informs
* the application on which offset these signature data should be appended.
* @param convertId Handle for the conversion session.
*
* @return A {@link DrmConvertedStatus} object that contains the status of the data conversion,
* the converted data, and the offset for the header and body signature.
*/
public DrmConvertedStatus closeConvertSession(int convertId) {
return _closeConvertSession(mUniqueId, convertId);

92
drm/java/android/drm/DrmRights.java Normal file → Executable file
View File

@@ -20,14 +20,16 @@ import java.io.File;
import java.io.IOException;
/**
* This is an entity class which wraps the license information which was
* retrieved from the online DRM server.
*
* Caller can instantiate {@link DrmRights} by
* invoking {@link DrmRights#DrmRights(ProcessedData, String)}
* constructor by using the result of {@link DrmManagerClient#processDrmInfo(DrmInfo)} interface.
* Caller can also instantiate {@link DrmRights} using the file path
* which contains rights information.
* An entity class that wraps the license information retrieved from the online DRM server.
*<p>
* A caller can instantiate a {@link DrmRights} object by first invoking the
* {@link DrmManagerClient#processDrmInfo(DrmInfo)} method and then using the resulting
* {@link ProcessedData} object to invoke the {@link DrmRights#DrmRights(ProcessedData, String)}
* constructor.
*<p>
* A caller can also instantiate a {@link DrmRights} object by using the
* {@link DrmRights#DrmRights(String, String)} constructor, which takes a path to a file
* containing rights information instead of a <code>ProcessedData</code>.
*
*/
public class DrmRights {
@@ -37,10 +39,10 @@ public class DrmRights {
private String mSubscriptionId = "";
/**
* constructor to create DrmRights object with given parameters
* Creates a <code>DrmRights</code> object with the given parameters.
*
* @param rightsFilePath Path of the file containing rights data
* @param mimeType MIME type
* @param rightsFilePath Path to the file containing rights information.
* @param mimeType MIME type.
*/
public DrmRights(String rightsFilePath, String mimeType) {
File file = new File(rightsFilePath);
@@ -48,11 +50,11 @@ public class DrmRights {
}
/**
* constructor to create DrmRights object with given parameters
* Creates a <code>DrmRights</code> object with the given parameters.
*
* @param rightsFilePath Path of the file containing rights data
* @param mimeType MIME type
* @param accountId Account Id of the user
* @param rightsFilePath Path to the file containing rights information.
* @param mimeType MIME type.
* @param accountId Account ID of the user.
*/
public DrmRights(String rightsFilePath, String mimeType, String accountId) {
this(rightsFilePath, mimeType);
@@ -63,12 +65,12 @@ public class DrmRights {
}
/**
* constructor to create DrmRights object with given parameters
* Creates a <code>DrmRights</code> object with the given parameters.
*
* @param rightsFilePath Path of the file containing rights data
* @param mimeType MIME type
* @param accountId Account Id of the user
* @param subscriptionId Subscription Id of the user
* @param rightsFilePath Path to the file containing rights information.
* @param mimeType MIME type.
* @param accountId Account ID of the user.
* @param subscriptionId Subscription ID of the user.
*/
public DrmRights(
String rightsFilePath, String mimeType, String accountId, String subscriptionId) {
@@ -84,10 +86,10 @@ public class DrmRights {
}
/**
* constructor to create DrmRights object with given parameters
* Creates a <code>DrmRights</code> object with the given parameters.
*
* @param rightsFile File containing rights data
* @param mimeType MIME type
* @param rightsFile File containing rights information.
* @param mimeType MIME type.
*/
public DrmRights(File rightsFile, String mimeType) {
instantiate(rightsFile, mimeType);
@@ -104,16 +106,20 @@ public class DrmRights {
}
/**
* constructor to create DrmRights object with given parameters
* The user can pass String or binary data<p>
* Usage:<p>
* i) String(e.g. data is instance of String):<br>
* - new DrmRights(data.getBytes(), mimeType)<p>
* ii) Binary data<br>
* - new DrmRights(binaryData[], mimeType)<br>
* Creates a <code>DrmRights</code> object with the given parameters.
*<p>
* The application can pass the processed data as a <code>String</code> or as binary data.
*<p>
* The following code snippet shows how to pass the processed data as a <code>String</code>:
*<p>
* new DrmRights(data.getBytes(), mimeType)
*<p>
* The following code snippet shows how to pass the processed data as binary data:
*<p>
* new DrmRights(binaryData[], mimeType)
*
* @param data Processed data
* @param mimeType MIME type
* @param data A {@link ProcessedData} object.
* @param mimeType The MIME type.
*/
public DrmRights(ProcessedData data, String mimeType) {
mData = data.getData();
@@ -132,47 +138,45 @@ public class DrmRights {
}
/**
* Returns the rights data associated with this object
* Retrieves the rights data associated with this <code>DrmRights</code> object.
*
* @return Rights data
* @return A <code>byte</code> array representing the rights data.
*/
public byte[] getData() {
return mData;
}
/**
* Returns the mimetype associated with this object
* Retrieves the MIME type associated with this <code>DrmRights</code> object.
*
* @return MIME type
* @return The MIME type.
*/
public String getMimeType() {
return mMimeType;
}
/**
* Returns the account-id associated with this object
* Retrieves the account ID associated with this <code>DrmRights</code> object.
*
* @return Account Id
* @return The account ID.
*/
public String getAccountId() {
return mAccountId;
}
/**
* Returns the subscription-id associated with this object
* Retrieves the subscription ID associated with this <code>DrmRights</code> object.
*
* @return Subscription Id
* @return The subscription ID.
*/
public String getSubscriptionId() {
return mSubscriptionId;
}
/**
* Returns whether this instance is valid or not
* Determines whether this instance is valid or not.
*
* @return
* true if valid
* false if invalid
* @return True if valid; false if invalid.
*/
/*package*/ boolean isValid() {
return (null != mMimeType && !mMimeType.equals("")

82
drm/java/android/drm/DrmStore.java Normal file → Executable file
View File

@@ -17,91 +17,97 @@
package android.drm;
/**
* This class defines all the constants used by DRM framework
* Defines constants that are used by the DRM framework.
*
*/
public class DrmStore {
/**
* Columns representing drm constraints
* Interface definition for the columns that represent DRM constraints.
*/
public interface ConstraintsColumns {
/**
* The max repeat count
* <P>Type: INTEGER</P>
* The maximum repeat count.
* <p>
* Type: INTEGER
*/
public static final String MAX_REPEAT_COUNT = "max_repeat_count";
/**
* The remaining repeat count
* <P>Type: INTEGER</P>
* The remaining repeat count.
* <p>
* Type: INTEGER
*/
public static final String REMAINING_REPEAT_COUNT = "remaining_repeat_count";
/**
* The time before which the protected file can not be played/viewed
* <P>Type: TEXT</P>
* The time before which the rights-protected file cannot be played/viewed.
* <p>
* Type: TEXT
*/
public static final String LICENSE_START_TIME = "license_start_time";
/**
* The time after which the protected file can not be played/viewed
* <P>Type: TEXT</P>
* The time after which the rights-protected file cannot be played/viewed.
* <p>
* Type: TEXT
*/
public static final String LICENSE_EXPIRY_TIME = "license_expiry_time";
/**
* The available time for license
* <P>Type: TEXT</P>
* The available time left before the license expires.
* <p>
* Type: TEXT
*/
public static final String LICENSE_AVAILABLE_TIME = "license_available_time";
/**
* The data stream for extended metadata
* <P>Type: TEXT</P>
* The data stream for extended metadata.
* <p>
* Type: TEXT
*/
public static final String EXTENDED_METADATA = "extended_metadata";
}
/**
* Defines constants related to DRM types
* Defines DRM object types.
*/
public static class DrmObjectType {
/**
* Field specifies the unknown type
* An unknown object type.
*/
public static final int UNKNOWN = 0x00;
/**
* Field specifies the protected content type
* A rights-protected file object type.
*/
public static final int CONTENT = 0x01;
/**
* Field specifies the rights information
* A rights information object type.
*/
public static final int RIGHTS_OBJECT = 0x02;
/**
* Field specifies the trigger information
* A trigger information object type.
*/
public static final int TRIGGER_OBJECT = 0x03;
}
/**
* Defines constants related to playback
* Defines playback states for content.
*/
public static class Playback {
/**
* Constant field signifies playback start
* Playback started.
*/
public static final int START = 0x00;
/**
* Constant field signifies playback stop
* Playback stopped.
*/
public static final int STOP = 0x01;
/**
* Constant field signifies playback paused
* Playback paused.
*/
public static final int PAUSE = 0x02;
/**
* Constant field signifies playback resumed
* Playback resumed.
*/
public static final int RESUME = 0x03;
@@ -120,39 +126,39 @@ public class DrmStore {
}
/**
* Defines actions that can be performed on protected content
* Defines actions that can be performed on rights-protected content.
*/
public static class Action {
/**
* Constant field signifies that the default action
* The default action.
*/
public static final int DEFAULT = 0x00;
/**
* Constant field signifies that the content can be played
* The rights-protected content can be played.
*/
public static final int PLAY = 0x01;
/**
* Constant field signifies that the content can be set as ring tone
* The rights-protected content can be set as a ringtone.
*/
public static final int RINGTONE = 0x02;
/**
* Constant field signifies that the content can be transfered
* The rights-protected content can be transferred.
*/
public static final int TRANSFER = 0x03;
/**
* Constant field signifies that the content can be set as output
* The rights-protected content can be set as output.
*/
public static final int OUTPUT = 0x04;
/**
* Constant field signifies that preview is allowed
* The rights-protected content can be previewed.
*/
public static final int PREVIEW = 0x05;
/**
* Constant field signifies that the content can be executed
* The rights-protected content can be executed.
*/
public static final int EXECUTE = 0x06;
/**
* Constant field signifies that the content can displayed
* The rights-protected content can be displayed.
*/
public static final int DISPLAY = 0x07;
@@ -175,23 +181,23 @@ public class DrmStore {
}
/**
* Defines constants related to status of the rights
* Defines status notifications for digital rights.
*/
public static class RightsStatus {
/**
* Constant field signifies that the rights are valid
* The digital rights are valid.
*/
public static final int RIGHTS_VALID = 0x00;
/**
* Constant field signifies that the rights are invalid
* The digital rights are invalid.
*/
public static final int RIGHTS_INVALID = 0x01;
/**
* Constant field signifies that the rights are expired for the content
* The digital rights have expired.
*/
public static final int RIGHTS_EXPIRED = 0x02;
/**
* Constant field signifies that the rights are not acquired for the content
* The digital rights have not been acquired for the rights-protected content.
*/
public static final int RIGHTS_NOT_ACQUIRED = 0x03;
}

66
drm/java/android/drm/DrmSupportInfo.java Normal file → Executable file
View File

@@ -20,11 +20,11 @@ import java.util.ArrayList;
import java.util.Iterator;
/**
* This is an entity class which wraps the capability of each plug-in,
* such as mimetype's and file suffixes it could handle.
*
* Plug-in developer could return the capability of the plugin by passing
* {@link DrmSupportInfo} instance.
* An entity class that wraps the capability of each DRM plug-in (agent),
* such as the MIME type and file suffix the DRM plug-in can handle.
*<p>
* Plug-in developers can expose the capability of their plug-in by passing an instance of this
* class to an application.
*
*/
public class DrmSupportInfo {
@@ -33,47 +33,47 @@ public class DrmSupportInfo {
private String mDescription = "";
/**
* Add the mime-type to the support info such that respective plug-in is
* capable of handling the given mime-type.
* Adds the specified MIME type to the list of MIME types this DRM plug-in supports.
*
* @param mimeType MIME type
* @param mimeType MIME type that can be handles by this DRM plug-in.
*/
public void addMimeType(String mimeType) {
mMimeTypeList.add(mimeType);
}
/**
* Add the file suffix to the support info such that respective plug-in is
* capable of handling the given file suffix.
* Adds the specified file suffix to the list of file suffixes this DRM plug-in supports.
*
* @param fileSuffix File suffix which can be handled
* @param fileSuffix File suffix that can be handled by this DRM plug-in.
*/
public void addFileSuffix(String fileSuffix) {
mFileSuffixList.add(fileSuffix);
}
/**
* Returns the iterator to walk to through mime types of this object
* Retrieves an iterator object that you can use to iterate over the MIME types that
* this DRM plug-in supports.
*
* @return Iterator object
* @return The iterator object
*/
public Iterator<String> getMimeTypeIterator() {
return mMimeTypeList.iterator();
}
/**
* Returns the iterator to walk to through file suffixes of this object
* Retrieves an iterator object that you can use to iterate over the file suffixes that
* this DRM plug-in supports.
*
* @return Iterator object
* @return The iterator object.
*/
public Iterator<String> getFileSuffixIterator() {
return mFileSuffixList.iterator();
}
/**
* Set the unique description about the plugin
* Sets a description for the DRM plug-in (agent).
*
* @param description Unique description
* @param description Unique description of plug-in.
*/
public void setDescription(String description) {
if (null != description) {
@@ -82,30 +82,28 @@ public class DrmSupportInfo {
}
/**
* Returns the unique description associated with the plugin
* Retrieves the DRM plug-in (agent) description.
*
* @return Unique description
* @return The plug-in description.
*/
public String getDescriprition() {
return mDescription;
}
/**
* Overridden hash code implementation
* Overridden hash code implementation.
*
* @return Hash code value
* @return The hash code value.
*/
public int hashCode() {
return mFileSuffixList.hashCode() + mMimeTypeList.hashCode() + mDescription.hashCode();
}
/**
* Overridden equals implementation
* Overridden <code>equals</code> implementation.
*
* @param object The object to be compared
* @return
* true if equal
* false if not equal
* @param object The object to be compared.
* @return True if equal; false if not equal.
*/
public boolean equals(Object object) {
boolean result = false;
@@ -119,12 +117,10 @@ public class DrmSupportInfo {
}
/**
* Returns whether given mime-type is supported or not
* Determines whether a given MIME type is supported.
*
* @param mimeType MIME type
* @return
* true if mime type is supported
* false if mime type is not supported
* @param mimeType MIME type.
* @return True if Mime type is supported; false if MIME type is not supported.
*/
/* package */ boolean isSupportedMimeType(String mimeType) {
if (null != mimeType && !mimeType.equals("")) {
@@ -139,12 +135,10 @@ public class DrmSupportInfo {
}
/**
* Returns whether given file suffix is supported or not
* Determines whether a given file suffix is supported.
*
* @param fileSuffix File suffix
* @return
* true - if file suffix is supported
* false - if file suffix is not supported
* @param fileSuffix File suffix.
* @return True if file suffix is supported; false if file suffix is not supported.
*/
/* package */ boolean isSupportedFileSuffix(String fileSuffix) {
return mFileSuffixList.contains(fileSuffix);

24
drm/java/android/drm/DrmUtils.java Normal file → Executable file
View File

@@ -28,9 +28,11 @@ import java.util.HashMap;
import java.util.Iterator;
/**
* The utility class used in the DRM Framework. This inclueds APIs for file operations
* and ExtendedMetadataParser for parsing extended metadata BLOB in DRM constraints.
*
* A utility class that provides operations for parsing extended metadata embedded in
* DRM constraint information. If a DRM scheme has specific constraints beyond the standard
* constraints, the constraints will show up in the
* {@link DrmStore.ConstraintsColumns#EXTENDED_METADATA} key. You can use
* {@link DrmUtils.ExtendedMetadataParser} to iterate over those values.
*/
public class DrmUtils {
/* Should be used when we need to read from local file */
@@ -99,13 +101,10 @@ public class DrmUtils {
}
/**
* Get an instance of ExtendedMetadataParser to be used for parsing
* extended metadata BLOB in DRM constraints. <br>
* Gets an instance of {@link DrmUtils.ExtendedMetadataParser}, which can be used to parse
* extended metadata embedded in DRM constraint information.
*
* extendedMetadata BLOB is retrieved by specifing
* key DrmStore.ConstraintsColumns.EXTENDED_METADATA.
*
* @param extendedMetadata BLOB in which key-value pairs of extended metadata are embedded.
* @param extendedMetadata Object in which key-value pairs of extended metadata are embedded.
*
*/
public static ExtendedMetadataParser getExtendedMetadataParser(byte[] extendedMetadata) {
@@ -113,9 +112,10 @@ public class DrmUtils {
}
/**
* Utility parser to parse the extended meta-data embedded inside DRM constraints<br><br>
*
* Usage example<br>
* Utility that parses extended metadata embedded in DRM constraint information.
*<p>
* Usage example:
*<p>
* byte[] extendedMetadata<br>
* &nbsp;&nbsp;&nbsp;&nbsp; =
* constraints.getAsByteArray(DrmStore.ConstraintsColumns.EXTENDED_METADATA);<br>

34
drm/java/android/drm/ProcessedData.java Normal file → Executable file
View File

@@ -17,11 +17,11 @@
package android.drm;
/**
* This is an entity class which wraps the result of transaction between
* device and online DRM server by using {@link DrmManagerClient#processDrmInfo(DrmInfo)}
* An entity class that wraps the result of a
* {@link DrmManagerClient#processDrmInfo(DrmInfo) processDrmInfo()}
* transaction between a device and a DRM server.
*
* In license acquisition scenario this class would hold the binary data
* of rights information.
* In a license acquisition scenario this class holds the rights information in binary form.
*
*/
public class ProcessedData {
@@ -30,10 +30,10 @@ public class ProcessedData {
private String mSubscriptionId = "";
/**
* constructor to create ProcessedData object with given parameters
* Creates a <code>ProcessedData</code> object with the given parameters.
*
* @param data Rights data
* @param accountId Account Id of the user
* @param data Rights data.
* @param accountId Account ID of the user.
*/
/* package */ ProcessedData(byte[] data, String accountId) {
mData = data;
@@ -41,11 +41,11 @@ public class ProcessedData {
}
/**
* constructor to create ProcessedData object with given parameters
* Creates a <code>ProcessedData</code> object with the given parameters.
*
* @param data Rights data
* @param accountId Account Id of the user
* @param subscriptionId Subscription Id of the user
* @param data Rights data.
* @param accountId Account ID of the user.
* @param subscriptionId Subscription ID of the user.
*/
/* package */ ProcessedData(byte[] data, String accountId, String subscriptionId) {
mData = data;
@@ -54,27 +54,27 @@ public class ProcessedData {
}
/**
* Returns the processed data as a result.
* Retrieves the processed data.
*
* @return Rights data associated
* @return The rights data.
*/
public byte[] getData() {
return mData;
}
/**
* Returns the account-id associated with this object
* Retrieves the account ID associated with this object.
*
* @return Account Id associated
* @return The account ID of the user.
*/
public String getAccountId() {
return mAccountId;
}
/**
* Returns the subscription-id associated with this object
* Returns the subscription ID associated with this object.
*
* @return Subscription Id associated
* @return The subscription ID of the user.
*/
public String getSubscriptionId() {
return mSubscriptionId;

85
drm/java/android/drm/package.html Executable file
View File

@@ -0,0 +1,85 @@
<HTML>
<BODY>
<p>Provides classes for managing DRM content and determining the capabilities of DRM plugins
(agents). Common uses of the DRM API include:</p>
<ul>
<li>Determining which DRM plug-ins (agents) are installed on a device.</li>
<li>Retrieving information about specific plug-ins, such as the MIME types and file suffixes
they support.</li>
<li>Registering a user or a device with an online DRM service.</li>
<li>Retrieving license constraints for rights-protected content.</li>
<li>Checking whether a user has the proper rights to play or use rights-protected
content.</li>
<li>Associating rights-protected content with its license so you can use the
{@link android.media.MediaPlayer} API to play the content.</li>
</ul>
<h2>DRM Overview</h2>
<p>The Android platform provides an extensible DRM framework that lets applications manage
rights-protected content according to the license constraints that are associated with the
content. The DRM framework supports many DRM schemes; which DRM schemes a device supports
is up to the device manufacturer.</p>
<p>The Android DRM framework is implemented in two architectural layers (see figure below):</p>
<ul>
<li>A DRM framework API, which is exposed to applications through the Android
application framework and runs through the Dalvik VM for standard applications.</li>
<li>A native code DRM manager, which implements the DRM framework and exposes an
interface for DRM plug-ins (agents) to handle rights management and decryption for various
DRM schemes.</li>
</ul>
<img src="../../../images/drm_arch.png" alt="DRM architecture diagram" border="0"/>
<p>For application developers, the DRM framework offers an abstract, unified API that
simplifies the management of rights-protected content. The API hides the complexity of DRM
operations and allows a consistent operation mode for both rights-protected and unprotected content
across a variety of DRM schemes. For device manufacturers, content owners, and Internet digital
media providers the DRM framework’s plugin architecture provides a means of adding support for a
specific DRM scheme to the Android system.</p>
<h2>Using the DRM API</h2>
<p>In a typical DRM session, an Android application uses the DRM framework API to
instantiate a {@link android.drm.DrmManagerClient}. The application calls various methods
on the DRM client to query rights and perform other DRM-related tasks. Each
{@link android.drm.DrmManagerClient} instance has its own unique ID, so the DRM manager is able to
differentiate callers.</p>
<p>Although each DRM plug-in may require a different sequence
of API calls, the general call sequence for an application is as follows:</p>
<ul>
<li>Register the device with an online DRM service.
<p>You can do this by first using the {@link android.drm.DrmManagerClient#acquireDrmInfo
acquireDrmInfo()} method to acquire the registration information, and then using the {@link
android.drm.DrmManagerClient#processDrmInfo processDrmInfo()} method to process the
registration information.</p>
</li>
<li>Acquire the license that's associated with the rights-protected content.
<p>You can do this by first using the {@link android.drm.DrmManagerClient#acquireDrmInfo
acquireDrmInfo()} method to acquire the license information, and then using the {@link
android.drm.DrmManagerClient#processDrmInfo processDrmInfo()} method to process the
license information. You can also use the {@link
android.drm.DrmManagerClient#acquireRights acquireRights()} method.</p>
</li>
<li>Extract constraint information from the license.
<p>You can use the {@link android.drm.DrmManagerClient#getConstraints getConstraints()}
method to do this.</p>
</li>
<li>Associate the rights-protected content with its license.
<p>You can use the {@link android.drm.DrmManagerClient#saveRights saveRights()} method
to do this.</p>
</li>
</ul>
<p>After you make an association between the rights-protected content and its license,
the DRM manager automatically handles rights management for that content. Specifically, the
DRM manager will handle all further licensing checks when you attempt to play the content using
the {@link android.media.MediaPlayer} API.</p>
<p>To learn how to use the DRM API with a specific DRM plug-in, see the documentation provided
by the plug-in developer.</p>
</BODY>
</HTML>