am 640f63c2: am 3bde4594: am 0357ec78: Merge "DRM API doc scrub This change contains information contributed by Sony Corporation. Bug: 4119363" into honeycomb-mr1
* commit '640f63c2669fc9dc38b349066d4d28111655dc3f':
DRM API doc scrub This change contains information contributed by Sony Corporation. Bug: 4119363
diff --git a/docs/html/images/drm_arch.png b/docs/html/images/drm_arch.png
new file mode 100755
index 0000000..1696a97
--- /dev/null
+++ b/docs/html/images/drm_arch.png
Binary files differ
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 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;
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 @@
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);
}
}
-
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 @@
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 @@
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 @@
}
/**
- * 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 @@
}
/**
- * 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.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 @@
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 @@
}
/**
- * 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 @@
}
/**
- * 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
- * To put custom object into DrmInfo, custom object has to
- * override toString() implementation.
+ * @param key Key to add.
+ * @param value Value to add.
+ *
*/
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;
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 @@
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) {
diff --git a/drm/java/android/drm/DrmInfoRequest.java b/drm/java/android/drm/DrmInfoRequest.java
old mode 100644
new mode 100755
index 366a342..2222ae8
--- a/drm/java/android/drm/DrmInfoRequest.java
+++ b/drm/java/android/drm/DrmInfoRequest.java
@@ -20,30 +20,37 @@
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.h
/**
- * 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 @@
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 @@
}
/**
- * 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();
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 <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 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;
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.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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * Install new DRM Engine Plug-in at the runtime
+ * Installs a new DRM plug-in (agent) at runtime.
*
- * @param engineFilePath Path of the plug-in file to be installed
+ * @param engineFilePath File path to the plug-in file to be installed.
+ *
* {@hide}
*/
public void installDrmEngine(String engineFilePath) {
@@ -407,13 +415,12 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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);
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.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 @@
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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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("")
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
- * <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 @@
}
/**
- * 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 @@
}
/**
- * 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.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 @@
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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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.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 @@
}
/**
- * 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 @@
}
/**
- * 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>
* =
* constraints.getAsByteArray(DrmStore.ConstraintsColumns.EXTENDED_METADATA);<br>
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 @@
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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
+<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>
