From 0e092f806b0a4b81785a52da8ba22d2d47087de5 Mon Sep 17 00:00:00 2001 From: Bill Gruber Date: Thu, 17 Mar 2011 16:04:18 -0700 Subject: DRM API doc scrub This change contains information contributed by Sony Corporation. Bug: 4119363 Change-Id: I6f565c15d512d675993dc65f7fee19bd3d0bc0fa --- drm/java/android/drm/DrmConvertedStatus.java | 23 +- drm/java/android/drm/DrmErrorEvent.java | 45 ++-- drm/java/android/drm/DrmEvent.java | 53 ++-- drm/java/android/drm/DrmInfo.java | 70 +++--- drm/java/android/drm/DrmInfoEvent.java | 38 ++- drm/java/android/drm/DrmInfoRequest.java | 61 +++-- drm/java/android/drm/DrmInfoStatus.java | 34 ++- drm/java/android/drm/DrmManagerClient.java | 348 ++++++++++++++------------- drm/java/android/drm/DrmRights.java | 92 +++---- drm/java/android/drm/DrmStore.java | 82 ++++--- drm/java/android/drm/DrmSupportInfo.java | 66 +++-- drm/java/android/drm/DrmUtils.java | 24 +- drm/java/android/drm/ProcessedData.java | 34 +-- drm/java/android/drm/package.html | 85 +++++++ 14 files changed, 589 insertions(+), 466 deletions(-) mode change 100644 => 100755 drm/java/android/drm/DrmConvertedStatus.java mode change 100644 => 100755 drm/java/android/drm/DrmErrorEvent.java mode change 100644 => 100755 drm/java/android/drm/DrmEvent.java mode change 100644 => 100755 drm/java/android/drm/DrmInfo.java mode change 100644 => 100755 drm/java/android/drm/DrmInfoEvent.java mode change 100644 => 100755 drm/java/android/drm/DrmInfoRequest.java mode change 100644 => 100755 drm/java/android/drm/DrmInfoStatus.java mode change 100644 => 100755 drm/java/android/drm/DrmManagerClient.java mode change 100644 => 100755 drm/java/android/drm/DrmRights.java mode change 100644 => 100755 drm/java/android/drm/DrmStore.java mode change 100644 => 100755 drm/java/android/drm/DrmSupportInfo.java mode change 100644 => 100755 drm/java/android/drm/DrmUtils.java mode change 100644 => 100755 drm/java/android/drm/ProcessedData.java create mode 100755 drm/java/android/drm/package.html (limited to 'drm/java') diff --git a/drm/java/android/drm/DrmConvertedStatus.java b/drm/java/android/drm/DrmConvertedStatus.java old mode 100644 new mode 100755 index f200552..cecb135 --- a/drm/java/android/drm/DrmConvertedStatus.java +++ b/drm/java/android/drm/DrmConvertedStatus.java @@ -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 DrmConvertedStatus 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; diff --git a/drm/java/android/drm/DrmErrorEvent.java b/drm/java/android/drm/DrmErrorEvent.java old mode 100644 new mode 100755 index 7cc9a87..2cb82e6 --- a/drm/java/android/drm/DrmErrorEvent.java +++ b/drm/java/android/drm/DrmErrorEvent.java @@ -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 DrmErrorEvent 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 DrmErrorEvent 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 attributes) { super(uniqueId, type, message, attributes); } } - diff --git a/drm/java/android/drm/DrmEvent.java b/drm/java/android/drm/DrmEvent.java old mode 100644 new mode 100755 index eba458b..4053eb3 --- a/drm/java/android/drm/DrmEvent.java +++ b/drm/java/android/drm/DrmEvent.java @@ -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 attributes 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 attributes 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 mAttributes = new HashMap(); /** - * constructor for DrmEvent class + * Creates a DrmEvent 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 attributes) { @@ -66,11 +70,11 @@ public class DrmEvent { } /** - * constructor for DrmEvent class + * Creates a DrmEvent 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); } } - diff --git a/drm/java/android/drm/DrmInfo.java b/drm/java/android/drm/DrmInfo.java old mode 100644 new mode 100755 index 7d3fbf1..8812bfe --- a/drm/java/android/drm/DrmInfo.java +++ b/drm/java/android/drm/DrmInfo.java @@ -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}. + *

+ * 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 mAttributes = new HashMap(); /** - * constructor to create DrmInfo object with given parameters + * Creates a DrmInfo 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 DrmInfo 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 pair to this object + * Adds optional information as key-value pairs to this object. To add a custom object + * to the DrmInfo 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 The key whose value is being retrieved. * - * @param key Key whose value to be retrieved - * @return The value or null + * @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 DrmInfo object. * - * @return Iterator object + * @return The iterator object. */ public Iterator 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 DrmInfo object. * - * @return Iterator object + * @return The iterator object. */ public Iterator 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; diff --git a/drm/java/android/drm/DrmInfoEvent.java b/drm/java/android/drm/DrmInfoEvent.java old mode 100644 new mode 100755 index 190199a..67aa0a9 --- a/drm/java/android/drm/DrmInfoEvent.java +++ b/drm/java/android/drm/DrmInfoEvent.java @@ -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 DrmInfoEvent 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 DrmInfoEvent 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 attributes) { diff --git a/drm/java/android/drm/DrmInfoRequest.java b/drm/java/android/drm/DrmInfoRequest.java old mode 100644 new mode 100755 index a5a799c..9f86f5f --- a/drm/java/android/drm/DrmInfoRequest.java +++ b/drm/java/android/drm/DrmInfoRequest.java @@ -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 mRequestInformation = new HashMap(); /** - * constructor to create DrmInfoRequest object with type and mimetype + * Creates a DrmInfoRequest 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 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 The key whose value is being retrieved. * - * @param key Key whose value to be retrieved - * @return The value or null + * @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 DrmInfoRequest object. * - * @return Iterator object + * @return The iterator object. */ public Iterator 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 DrmInfoRequest object. * - * @return Iterator object + * @return The iterator object. */ public Iterator iterator() { return mRequestInformation.values().iterator(); diff --git a/drm/java/android/drm/DrmInfoStatus.java b/drm/java/android/drm/DrmInfoStatus.java old mode 100644 new mode 100755 index b37ea51..b04694b --- a/drm/java/android/drm/DrmInfoStatus.java +++ b/drm/java/android/drm/DrmInfoStatus.java @@ -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 DrmInfoStatus is returned. + *

+ * 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 DrmInfoStatus 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; diff --git a/drm/java/android/drm/DrmManagerClient.java b/drm/java/android/drm/DrmManagerClient.java old mode 100644 new mode 100755 index f7479b5..f3a0343 --- a/drm/java/android/drm/DrmManagerClient.java +++ b/drm/java/android/drm/DrmManagerClient.java @@ -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 DrmManagerClient 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 DrmManagerClient 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 DrmManagerClient 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 DrmManagerClient. * - * @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 String 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 Path to the content from which you are retrieving metadata information. * - * @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 + * @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 URI for the content from which you are retrieving DRM constraints. + * @param action Action defined in {@link DrmStore.Action}. * - * @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 + * @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. + * + *

Note: For OMA or WM-DRM, rightsPath and + * contentPath can be null.

+ * + * @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. * - *

In case of OMA or WM-DRM, rightsPath and contentPath could be null.

+ * @return ERROR_NONE for success; ERROR_UNKNOWN for failure. * - * @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 + * @throws IOException If the call failed to save rights information at the given + * rightsPath. */ 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 MIME type of the object to 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. + * @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 URI for the content to be handled. + * @param mimeType MIME type of the object to 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. + * @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. + *

+ * 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 int 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 int 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 to the rights-protected content. * - * @param path Path of the protected content - * @return Mimetype of the original content, such as "video/mpeg" + * @return The MIME type of the original content, such as video/mpeg. */ 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 video/mpeg. */ 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 to the rights-protected content. * - * @param path Path of the protected content - * @return Status of the rights for the protected content - * @see DrmStore.RightsStatus + * @return An int 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 URI of the rights-protected content. * - * @param uri The content URI of the data - * @return Status of the rights for the protected content - * @see DrmStore.RightsStatus + * @return An int 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 int 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 URI for the rights-protected content. + * @param action The {@link DrmStore.Action} to perform. * - * @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 + * @return An int 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 URI for the rights-protected content. * - * @param uri The content URI of the data - * @return - * ERROR_NONE for success - * ERROR_UNKNOWN for failure + * @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. + *

+ * This method applies only to forward-locking (copy protection) DRM schemes. + * + * @param mimeType MIME type of the input data packet. * - * @param mimeType Description/MIME type of the input data packet - * @return convert ID which will be used for maintaining convert session. + * @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 conversion session. * - * @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. + * @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); diff --git a/drm/java/android/drm/DrmRights.java b/drm/java/android/drm/DrmRights.java old mode 100644 new mode 100755 index 103af07..5907956 --- a/drm/java/android/drm/DrmRights.java +++ b/drm/java/android/drm/DrmRights.java @@ -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. + *

+ * 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. + *

+ * 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 ProcessedData. * */ public class DrmRights { @@ -37,10 +39,10 @@ public class DrmRights { private String mSubscriptionId = ""; /** - * constructor to create DrmRights object with given parameters + * Creates a DrmRights 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 DrmRights 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 DrmRights 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 DrmRights 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

- * Usage:

- * i) String(e.g. data is instance of String):
- * - new DrmRights(data.getBytes(), mimeType)

- * ii) Binary data
- * - new DrmRights(binaryData[], mimeType)
+ * Creates a DrmRights object with the given parameters. + *

+ * The application can pass the processed data as a String or as binary data. + *

+ * The following code snippet shows how to pass the processed data as a String: + *

+ * new DrmRights(data.getBytes(), mimeType) + *

+ * The following code snippet shows how to pass the processed data as binary data: + *

+ * 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 DrmRights object. * - * @return Rights data + * @return A byte array representing the rights data. */ public byte[] getData() { return mData; } /** - * Returns the mimetype associated with this object + * Retrieves the MIME type associated with this DrmRights 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 DrmRights 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 DrmRights 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("") diff --git a/drm/java/android/drm/DrmStore.java b/drm/java/android/drm/DrmStore.java old mode 100644 new mode 100755 index 44df90c..ae311de --- a/drm/java/android/drm/DrmStore.java +++ b/drm/java/android/drm/DrmStore.java @@ -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 - *

Type: INTEGER

+ * The maximum repeat count. + *

+ * Type: INTEGER */ public static final String MAX_REPEAT_COUNT = "max_repeat_count"; /** - * The remaining repeat count - *

Type: INTEGER

+ * The remaining repeat count. + *

+ * Type: INTEGER */ public static final String REMAINING_REPEAT_COUNT = "remaining_repeat_count"; /** - * The time before which the protected file can not be played/viewed - *

Type: TEXT

+ * The time before which the rights-protected file cannot be played/viewed. + *

+ * Type: TEXT */ public static final String LICENSE_START_TIME = "license_start_time"; /** - * The time after which the protected file can not be played/viewed - *

Type: TEXT

+ * The time after which the rights-protected file cannot be played/viewed. + *

+ * Type: TEXT */ public static final String LICENSE_EXPIRY_TIME = "license_expiry_time"; /** - * The available time for license - *

Type: TEXT

+ * The available time left before the license expires. + *

+ * Type: TEXT */ public static final String LICENSE_AVAILABLE_TIME = "license_available_time"; /** - * The data stream for extended metadata - *

Type: TEXT

+ * The data stream for extended metadata. + *

+ * 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; } diff --git a/drm/java/android/drm/DrmSupportInfo.java b/drm/java/android/drm/DrmSupportInfo.java old mode 100644 new mode 100755 index 0886af8..720c545 --- a/drm/java/android/drm/DrmSupportInfo.java +++ b/drm/java/android/drm/DrmSupportInfo.java @@ -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. + *

+ * 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 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 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 equals 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); diff --git a/drm/java/android/drm/DrmUtils.java b/drm/java/android/drm/DrmUtils.java old mode 100644 new mode 100755 index 8903485..dc5f1fa --- a/drm/java/android/drm/DrmUtils.java +++ b/drm/java/android/drm/DrmUtils.java @@ -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.
- * - * extendedMetadata BLOB is retrieved by specifing - * key DrmStore.ConstraintsColumns.EXTENDED_METADATA. + * Gets an instance of {@link DrmUtils.ExtendedMetadataParser}, which can be used to parse + * extended metadata embedded in DRM constraint information. * - * @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

- * - * Usage example
+ * Utility that parses extended metadata embedded in DRM constraint information. + *

+ * Usage example: + *

* byte[] extendedMetadata
*      = * constraints.getAsByteArray(DrmStore.ConstraintsColumns.EXTENDED_METADATA);
diff --git a/drm/java/android/drm/ProcessedData.java b/drm/java/android/drm/ProcessedData.java old mode 100644 new mode 100755 index 579264f..06e03e7 --- a/drm/java/android/drm/ProcessedData.java +++ b/drm/java/android/drm/ProcessedData.java @@ -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 ProcessedData 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 ProcessedData 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; diff --git a/drm/java/android/drm/package.html b/drm/java/android/drm/package.html new file mode 100755 index 0000000..161d6e0 --- /dev/null +++ b/drm/java/android/drm/package.html @@ -0,0 +1,85 @@ + + +

Provides classes for managing DRM content and determining the capabilities of DRM plugins +(agents). Common uses of the DRM API include:

+
    +
  • Determining which DRM plug-ins (agents) are installed on a device.
    • +
  • Retrieving information about specific plug-ins, such as the MIME types and file suffixes + they support.
    • +
  • Registering a user or a device with an online DRM service.
    • +
  • Retrieving license constraints for rights-protected content.
    • +
  • Checking whether a user has the proper rights to play or use rights-protected + content.
    • +
  • Associating rights-protected content with its license so you can use the + {@link android.media.MediaPlayer} API to play the content.
    • +
+ +

DRM Overview

+ +

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.

+ +

The Android DRM framework is implemented in two architectural layers (see figure below):

+
    +
  • A DRM framework API, which is exposed to applications through the Android +application framework and runs through the Dalvik VM for standard applications.
    • +
  • 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.
    • +
+ +DRM architecture diagram + +

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.

+ +

Using the DRM API

+ +

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.

+ +

Although each DRM plug-in may require a different sequence +of API calls, the general call sequence for an application is as follows:

+ +
    +
  • Register the device with an online DRM service. +

    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.

    +
    • +
  • Acquire the license that's associated with the rights-protected content. +

    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.

    +
    • +
  • Extract constraint information from the license. +

    You can use the {@link android.drm.DrmManagerClient#getConstraints getConstraints()} + method to do this.

    +
    • +
  • Associate the rights-protected content with its license. +

    You can use the {@link android.drm.DrmManagerClient#saveRights saveRights()} method + to do this.

    +
    • +
+ +

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.

+ +

To learn how to use the DRM API with a specific DRM plug-in, see the documentation provided +by the plug-in developer.

+ + -- cgit v1.1