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

* commit '3bde4594d5794645b5f7e0ff1bf9c4a0b44161b1':
  DRM API doc scrub This change contains information contributed by Sony Corporation. Bug: 4119363

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

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
+ * An entity class that is passed to the
- * {@link DrmManagerClient.OnErrorListener#onError(DrmManagerClient, DrmErrorEvent)}
+ * {@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.
+     * Memory allocation failed during renewal. Can in the future perhaps be used to trigger 
-     * Can in the future perhaps be used to trigger garbage collector.
+     * garbage collector.
      */
     public static final int TYPE_OUT_OF_MEMORY = 2004;
     /**
-     * TYPE_NO_INTERNET_CONNECTION, when the Internet connection is missing and no attempt
+     * An Internet connection is not available and no attempt can be made to renew rights.
-     * 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
+     * Failed to remove all the rights objects associated with all DRM schemes.
-     * 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 uniqueId Unique session identifier.
-     * @param type Type of the event. It could be one of the types defined above
+     * @param type Type of the event. Could be any of the event types defined above.
-     * @param message Message description
+     * @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 uniqueId Unique session identifier.
-     * @param type Type of the event. It could be one of the types defined above
+     * @param type Type of the event. Could be any of the event types defined above.
-     * @param message Message description
+     * @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);
     }
 }
-

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
+ * A base class that is used to send asynchronous event information from the DRM framework.
- * about any event occurred in DRM framework.
  *
  */
 public class DrmEvent {
     /**
-     * Constant field signifies that all the rights information associated with
+     * All of the rights information associated with all DRM schemes have been successfully removed.
-     * all DRM schemes are removed successfully
      */
     public static final int TYPE_ALL_RIGHTS_REMOVED = 1001;
     /**
-     * Constant field signifies that given information is processed successfully
+     * The given DRM information has been successfully processed.
      */
     public static final int TYPE_DRM_INFO_PROCESSED = 1002;
-
+    /**
+     * The key that is used in the <code>attributes</code> HashMap to pass the return status.
+     */
     public static final String DRM_INFO_STATUS_OBJECT = "drm_info_status_object";
+    /**
+     * The key that is used in the <code>attributes</code> HashMap to pass the
+     * {@link DrmInfo} object.
+     */
     public static final String DRM_INFO_OBJECT = "drm_info_object";
 
     private final int mUniqueId;
@@ -44,12 +48,12 @@ public class DrmEvent {
     private HashMap<String, Object> mAttributes = new HashMap<String, Object>();
 
     /**
-     * constructor for DrmEvent class
+     * Creates a <code>DrmEvent</code> object with the specified parameters.
      *
-     * @param uniqueId Unique session identifier
+     * @param uniqueId Unique session identifier.
-     * @param type Type of information
+     * @param type Type of information.
-     * @param message Message description
+     * @param message Message description.
-     * @param attributes Attributes for extensible information
+     * @param attributes Attributes for extensible information.
      */
     protected DrmEvent(int uniqueId, int type, String message,
                             HashMap<String, Object> attributes) {
@@ -66,11 +70,11 @@ public class DrmEvent {
     }
 
     /**
-     * constructor for DrmEvent class
+     * Creates a <code>DrmEvent</code> object with the specified parameters.
      *
-     * @param uniqueId Unique session identifier
+     * @param uniqueId Unique session identifier.
-     * @param type Type of information
+     * @param type Type of information.
-     * @param message Message description
+     * @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
+     * @return One of the attributes or null if no mapping for
-     * the key is found
+     * the key is found.
      */
     public Object getAttribute(String key) {
         return mAttributes.get(key);
     }
 }
-

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
+ * An entity class that describes the information required to send transactions
- * between device and online DRM server is described. DRM Framework achieves
+ * between a device and an online DRM server. The DRM framework achieves
- * server registration, license acquisition and any other server related transaction
+ * server registration, license acquisition, and any other server-related transactions
- * by passing an instance of this class to {@link DrmManagerClient#processDrmInfo(DrmInfo)}.
+ * by passing an instance of this class to {@link DrmManagerClient#processDrmInfo}.
- *
+ *<p>
- * Caller can retrieve the {@link DrmInfo} instance by using
+ * The caller can retrieve the {@link DrmInfo} instance by passing a {@link DrmInfoRequest}
- * {@link DrmManagerClient#acquireDrmInfo(DrmInfoRequest)}
+ * instance to {@link DrmManagerClient#acquireDrmInfo}.
- * by passing {@link DrmInfoRequest} instance.
  *
  */
 public class DrmInfo {
@@ -40,11 +39,11 @@ public class DrmInfo {
     private final HashMap<String, Object> mAttributes = new HashMap<String, Object>();
 
     /**
-     * constructor to create DrmInfo object with given parameters
+     * Creates a <code>DrmInfo</code> object with the given parameters.
      *
-     * @param infoType Type of information
+     * @param infoType The type of information.
-     * @param data Trigger data
+     * @param data The trigger data.
-     * @param mimeType MIME type
+     * @param mimeType The MIME type.
      */
     public DrmInfo(int infoType, byte[] data, String mimeType) {
         mInfoType = infoType;
@@ -53,11 +52,11 @@ public class DrmInfo {
     }
 
     /**
-     * constructor to create DrmInfo object with given parameters
+     * Creates a <code>DrmInfo</code> object with the given parameters.
      *
-     * @param infoType Type of information
+     * @param infoType The type of information.
-     * @param path Trigger data
+     * @param path The trigger data.
-     * @param mimeType MIME type
+     * @param mimeType The MIME type.
      */
     public DrmInfo(int infoType, String path, String mimeType) {
         mInfoType = infoType;
@@ -73,67 +72,70 @@ public class DrmInfo {
     }
 
     /**
-     * Adds optional information as <key, value> pair to this object
+     * Adds optional information as key-value pairs to this object. To add a custom object
+     * to the <code>DrmInfo</code> object, you must override the {@link #toString} implementation.
+     *
+     * @param key Key to add.
+     * @param value Value to add.
      *
-     * @param key Key to add
-     * @param value Value to add
-     *     To put custom object into DrmInfo, custom object has to
-     *     override toString() implementation.
      */
     public void put(String key, Object value) {
         mAttributes.put(key, value);
     }
 
     /**
-     * Retrieves the value of given key, if not found returns null
+     * Retrieves the value of a given key.
      *
-     * @param key Key whose value to be retrieved
+     * @param key The key whose value is being 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 <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;

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
+ * An entity class that is passed to the 
- * {@link DrmManagerClient.OnInfoListener#onInfo(DrmManagerClient, DrmInfoEvent)}
+ * {@link DrmManagerClient.OnInfoListener#onInfo onInfo()} callback.
  *
  */
 public class DrmInfoEvent extends DrmEvent {
     /**
-     * TYPE_ALREADY_REGISTERED_BY_ANOTHER_ACCOUNT, when registration has been already done
+     * The registration has already been done by another account ID.
-     * 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,
+     * The rights object is being delivered to the device. You must wait before
-     * wait before calling checkRights again.
+     * calling {@link DrmManagerClient#acquireRights acquireRights()} again.
      */
     public static final int TYPE_WAIT_FOR_RIGHTS = 4;
     /**
-     * TYPE_ACCOUNT_ALREADY_REGISTERED, when registration has been
+     * The registration has already been done for the given account.
-     * already 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 uniqueId Unique session identifier.
-     * @param type Type of the event. It could be one of the types defined above
+     * @param type Type of the event. Could be any of the event types defined above.
-     * @param message Message description
+     * @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 uniqueId Unique session identifier.
-     * @param type Type of the event. It could be one of the types defined above
+     * @param type Type of the event. Could be any of the event types defined above.
-     * @param message Message description
+     * @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) {

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
+ * An entity class that is used to pass information to an online DRM server. An instance of this
- * the necessary information to communicate with online DRM server
+ * class is passed to the {@link DrmManagerClient#acquireDrmInfo acquireDrmInfo()} method to get an
- *
+ * instance of a {@link DrmInfo}.
- * An instance of this class is passed to {@link DrmManagerClient#acquireDrmInfo(DrmInfoRequest)}
- * to get the instance of {@link DrmInfo}
  *
  */
 public class DrmInfoRequest {
     // Changes in following constants should be in sync with DrmInfoRequest.cpp
     /**
-     * Constants defines the type of {@link DrmInfoRequest}
+     * Acquires DRM server registration information.
      */
     public static final int TYPE_REGISTRATION_INFO = 1;
+    /**
+    * Acquires information for unregistering the DRM server.
+    */
     public static final int TYPE_UNREGISTRATION_INFO = 2;
+    /**
+    * Acquires rights information.
+    */
     public static final int TYPE_RIGHTS_ACQUISITION_INFO = 3;
+    /**
+    * Acquires the progress of the rights acquisition.
+    */
     public static final int TYPE_RIGHTS_ACQUISITION_PROGRESS_INFO = 4;
 
     /**
-     * Key to pass the unique id for the account or the user
+     * Key that is used to pass the unique session ID for the account or the user.
      */
     public static final String ACCOUNT_ID = "account_id";
 
     /**
-     * Key to pass the unique id used for subscription
+     * Key that is used to pass the unique session ID for the subscription.
      */
     public static final String SUBSCRIPTION_ID = "subscription_id";
 
@@ -52,10 +59,10 @@ public class DrmInfoRequest {
     private final HashMap<String, Object> mRequestInformation = new HashMap<String, Object>();
 
     /**
-     * constructor to create DrmInfoRequest object with type and mimetype
+     * Creates a <code>DrmInfoRequest</code> object with type and MIME type.
      *
-     * @param infoType Type of information
+     * @param infoType Type of information.
-     * @param mimeType MIME type
+     * @param mimeType MIME type.
      */
     public DrmInfoRequest(int infoType, String mimeType) {
         mInfoType = infoType;
@@ -63,56 +70,60 @@ public class DrmInfoRequest {
     }
 
     /**
-     * Returns the mimetype associated with this object
+     * Retrieves the MIME type associated with this object.
      *
-     * @return MIME type
+     * @return The MIME type.
      */
     public String getMimeType() {
         return mMimeType;
     }
 
     /**
-     * Returns Information type associated with this instance
+     * Retrieves the information type associated with this object.
      *
-     * @return Information type
+     * @return The information type.
      */
     public int getInfoType() {
         return mInfoType;
     }
 
     /**
-     * Adds optional information as <key, value> pair to this object.
+     * Adds optional information as key-value pairs to this object.
      *
-     * @param key Key to add
+     * @param key The key to add.
-     * @param value Value 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
+     * @param key The key whose value is being 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 <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();

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

drm/java/android/drm/DrmManagerClient.java

@@ -35,18 +35,17 @@ import java.util.ArrayList;
 import java.util.HashMap;
 
 /**
- * Interface of DRM Framework.
+ * The main programming interface for the DRM framework. An application must instantiate this class
- * Java application will instantiate this class
+ * to access DRM agents through the DRM framework.
- * to access DRM agent through 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
+     * Interface definition for a callback that receives status messages and warnings
-     * some info and/or warning about DrmManagerClient.
+     * 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 client The <code>DrmManagerClient</code> instance.
-         * @param event instance which wraps reason and necessary information
+         * @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
+     * Interface definition for a callback that receives information
-     * the result of time consuming APIs asynchronously
+     * 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 client The <code>DrmManagerClient</code> instance.
-         * @param event instance which wraps type and message
+         * @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
+     * Interface definition for a callback that receives information about DRM framework errors.
-     * the error occurred
      */
     public interface OnErrorListener {
         /**
-         * Called to indicate the error occurred.
+         * Called when the DRM framework sends error information.
          *
-         * @param client DrmManagerClient instance
+         * @param client The <code>DrmManagerClient</code> instance.
-         * @param event instance which wraps error type and message
+         * @param event The {@link DrmErrorEvent} instance that wraps the error type and message.
          */
         public void onError(DrmManagerClient client, DrmErrorEvent event);
     }
@@ -231,9 +232,9 @@ public class DrmManagerClient {
     }
 
     /**
-     * To instantiate DrmManagerClient
+     * Creates a <code>DrmManagerClient</code>.
      *
-     * @param context context of the caller
+     * @param context Context of the caller.
      */
     public DrmManagerClient(Context context) {
         mContext = context;
@@ -257,10 +258,10 @@ public class DrmManagerClient {
     }
 
     /**
-     * Register a callback to be invoked when the caller required to receive
+     * Registers an {@link DrmManagerClient.OnInfoListener} callback, which is invoked when the 
-     * supplementary information.
+     * 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
+     * Registers an {@link DrmManagerClient.OnEventListener} callback, which is invoked when the 
-     * the result of asynchronous APIs.
+     * 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
+     * Registers an {@link DrmManagerClient.OnErrorListener} callback, which is invoked when 
-     * error result of asynchronous APIs.
+     * the DRM framework sends error information.
      *
-     * @param errorListener
+     * @param errorListener Interface definition for the callback.
      */
     public synchronized void setOnErrorListener(OnErrorListener errorListener) {
         if (null != errorListener) {
@@ -293,9 +294,10 @@ public class DrmManagerClient {
     }
 
     /**
-     * Retrieves informations about all the plug-ins registered with DrmFramework.
+     * Retrieves information about all the DRM plug-ins (agents) that are registered with
+     * the DRM framework.
      *
-     * @return Array of DrmEngine plug-in strings
+     * @return A <code>String</code> array of DRM plug-in descriptions.
      */
     public String[] getAvailableDrmEngines() {
         DrmSupportInfo[] supportInfos = _getAllSupportInfo(mUniqueId);
@@ -310,12 +312,13 @@ public class DrmManagerClient {
     }
 
     /**
-     * Get constraints information evaluated from DRM content
+     * Retrieves constraint information for rights-protected content.
      *
-     * @param path Content path from where DRM constraints would be retrieved.
+     * @param path Path to the content from which you are retrieving DRM constraints.
-     * @param action Actions defined in {@link DrmStore.Action}
+     * @param action Action 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(String path, int action) {
         if (null == path || path.equals("") || !DrmStore.Action.isValid(action)) {
@@ -325,11 +328,12 @@ public class DrmManagerClient {
     }
 
    /**
-    * Get metadata information from DRM content
+    * Retrieves metadata information for rights-protected content.
     *
-    * @param path Content path from where DRM metadata would be retrieved.
+    * @param path Path to the content from which you are retrieving metadata information.
-    * @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 Content URI from where DRM constraints would be retrieved.
+     * @param uri URI for the content from which you are retrieving DRM constraints.
-     * @param action Actions defined in {@link DrmStore.Action}
+     * @param action Action 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.
+    * @param uri URI for the content from which you are retrieving metadata information.
-    * @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 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
+     * Saves rights to a specified path and associates that path with the content path.
-     * and make association with 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
+     * @return ERROR_NONE for success; ERROR_UNKNOWN for failure.
-     * @param rightsPath File path where rights to be saved
+     *
-     * @param contentPath File path where content was saved
+     * @throws IOException If the call failed to save rights information at the given
-     * @return
+     * <code>rightsPath</code>.
-     *     ERROR_NONE for success
-     *     ERROR_UNKNOWN for failure
-     * @throws IOException if failed to save rights information in the given path
      */
     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 path Path of the content to be handled.
-     * @param mimeType Mimetype of the object to be handled
+     * @param mimeType MIME type of the object to be handled.
-     * @return
+     *
-     *        true - if the given mimeType or path can be handled
+     * @return True if the given MIME type or path can be handled; false if they cannot be handled.
-     *        false - cannot be handled.
      */
     public boolean canHandle(String path, String mimeType) {
         if ((null == path || path.equals("")) && (null == mimeType || mimeType.equals(""))) {
@@ -423,13 +430,12 @@ public class DrmManagerClient {
     }
 
     /**
-     * Check whether the given mimetype or uri can be handled.
+     * Checks whether the given MIME type or URI can be handled.
      *
-     * @param uri Content URI of the data to be handled.
+     * @param uri URI for the content to be handled.
-     * @param mimeType Mimetype of the object to be handled
+     * @param mimeType MIME type of the object to be handled
-     * @return
+     *
-     *        true - if the given mimeType or path can be handled
+     * @return True if the given MIME type or URI can be handled; false if they cannot be handled.
-     *        false - 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
+     * @param drmInfo The {@link DrmInfo} to be processed.
-     * @return
+     * @return ERROR_NONE for success; ERROR_UNKNOWN for failure.
-     *     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
+     * @param drmInfoRequest The {@link DrmInfoRequest} that specifies the type of DRM
-     * @return DrmInfo Instance as a result of processing given input
+     * 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.
+     * Processes a given {@link DrmInfoRequest} and returns the rights information asynchronously.
-     * This is a utility API which consists of {@link #acquireDrmInfo(DrmInfoRequest)}
+     *<p>
-     * and {@link #processDrmInfo(DrmInfo)}.
+     * This is a utility method that consists of an
-     * It can be used if selected DRM agent can work with this combined sequences.
+     * {@link #acquireDrmInfo(DrmInfoRequest) acquireDrmInfo()} and a
-     * In case of some DRM schemes, such as OMA DRM, application needs to invoke
+     * {@link #processDrmInfo(DrmInfo) processDrmInfo()} method call. This utility method can be 
-     * {@link #acquireDrmInfo(DrmInfoRequest)} and {@link #processDrmInfo(DrmInfo)}, separately.
+     * 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
+     * @param drmInfoRequest The {@link DrmInfoRequest} used to acquire the rights.
-     * @return
+     * @return ERROR_NONE for success; ERROR_UNKNOWN for failure.
-     *     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..)
+     * Retrieves the type of rights-protected object (for example, content object, rights
-     * using specified path or mimetype. At least one parameter should be non null
+     * object, and so on) using the specified path or MIME type. At least one parameter must
-     * to retrieve DRM object type
+     * be specified to retrieve the DRM object type.
      *
-     * @param path Path of the content or null.
+     * @param path Path to the content or null.
-     * @param mimeType Mimetype of the content or null.
+     * @param mimeType MIME type of the content or null.
-     * @return Type of the DRM content.
+     * 
-     * @see DrmStore.DrmObjectType
+     * @return An <code>int</code> that corresponds to a {@link DrmStore.DrmObjectType}.
      */
     public int getDrmObjectType(String path, String mimeType) {
         if ((null == path || path.equals("")) && (null == mimeType || mimeType.equals(""))) {
@@ -510,14 +517,14 @@ public class DrmManagerClient {
     }
 
     /**
-     * Retrieves the type of the protected object (content, rights, etc..)
+     * Retrieves the type of rights-protected object (for example, content object, rights
-     * using specified uri or mimetype. At least one parameter should be non null
+     * object, and so on) using the specified URI or MIME type. At least one parameter must
-     * to retrieve DRM object type
+     * be specified to retrieve the DRM object type.
      *
-     * @param uri The content URI of the data
+     * @param uri URI for the content or null.
-     * @param mimeType Mimetype of the content or null.
+     * @param mimeType MIME type of the content or null.
-     * @return Type of the DRM content.
+     * 
-     * @see DrmStore.DrmObjectType
+     * @return An <code>int</code> that corresponds to a {@link DrmStore.DrmObjectType}.
      */
     public int getDrmObjectType(Uri uri, String mimeType) {
         if ((null == uri || Uri.EMPTY == uri) && (null == mimeType || mimeType.equals(""))) {
@@ -534,10 +541,11 @@ public class DrmManagerClient {
     }
 
     /**
-     * Retrieves the mime type embedded inside the original content
+     * Retrieves the MIME type embedded in the original content.
      *
-     * @param path Path of the protected content
+     * @param path Path to the rights-protected content.
-     * @return Mimetype of the original content, such as "video/mpeg"
+     *
+     * @return The MIME type of the original content, such as <code>video/mpeg</code>.
      */
     public String getOriginalMimeType(String path) {
         if (null == path || path.equals("")) {
@@ -547,10 +555,11 @@ public class DrmManagerClient {
     }
 
     /**
-     * Retrieves the mime type embedded inside the original content
+     * Retrieves the MIME type embedded in the original content.
      *
-     * @param uri The content URI of the data
+     * @param uri URI of the rights-protected content.
-     * @return Mimetype of the original content, such as "video/mpeg"
+     *
+     * @return MIME type of the original content, such as <code>video/mpeg</code>.
      */
     public String getOriginalMimeType(Uri uri) {
         if (null == uri || Uri.EMPTY == uri) {
@@ -560,22 +569,22 @@ public class DrmManagerClient {
     }
 
     /**
-     * Check whether the given content has valid rights or not
+     * Checks whether the given content has valid rights.
      *
-     * @param path Path of the protected content
+     * @param path Path to the rights-protected content.
-     * @return Status of the rights for the protected content
+     *
-     * @see DrmStore.RightsStatus
+     * @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
+     * @param uri URI of the rights-protected content.
-     * @return Status of the rights for the protected content
+     *
-     * @see DrmStore.RightsStatus
+     * @return An <code>int</code> representing the {@link DrmStore.RightsStatus} of the content.
      */
     public int checkRightsStatus(Uri uri) {
         if (null == uri || Uri.EMPTY == uri) {
@@ -585,12 +594,13 @@ public class DrmManagerClient {
     }
 
     /**
-     * Check whether the given content has valid rights or not for specified action.
+     * Checks whether the given rights-protected content has valid rights for the specified
+     * {@link DrmStore.Action}.
      *
-     * @param path Path of the protected content
+     * @param path Path to the rights-protected content.
-     * @param action Action to perform
+     * @param action The {@link DrmStore.Action} to perform.
-     * @return Status of the rights for the protected content
+     *
-     * @see DrmStore.RightsStatus
+     * @return An <code>int</code> representing the {@link DrmStore.RightsStatus} of the content.
      */
     public int checkRightsStatus(String path, int action) {
         if (null == path || path.equals("") || !DrmStore.Action.isValid(action)) {
@@ -600,12 +610,13 @@ public class DrmManagerClient {
     }
 
     /**
-     * Check whether the given content has valid rights or not for specified action.
+     * Checks whether the given rights-protected content has valid rights for the specified
+     * {@link DrmStore.Action}.
      *
-     * @param uri The content URI of the data
+     * @param uri URI for the rights-protected content.
-     * @param action Action to perform
+     * @param action The {@link DrmStore.Action} to perform.
-     * @return Status of the rights for the protected content
+     *
-     * @see DrmStore.RightsStatus
+     * @return An <code>int</code> representing the {@link DrmStore.RightsStatus} of the content.
      */
     public int checkRightsStatus(Uri uri, int action) {
         if (null == uri || Uri.EMPTY == uri) {
@@ -615,12 +626,11 @@ public class DrmManagerClient {
     }
 
     /**
-     * Removes the rights associated with the given protected content
+     * Removes the rights associated with the given rights-protected content.
      *
-     * @param path Path of the protected content
+     * @param path Path to the rights-protected content.
-     * @return
+     *
-     *     ERROR_NONE for success
+     * @return ERROR_NONE for success; ERROR_UNKNOWN for failure.
-     *     ERROR_UNKNOWN for failure
      */
     public int removeRights(String path) {
         if (null == path || path.equals("")) {
@@ -630,12 +640,11 @@ public class DrmManagerClient {
     }
 
     /**
-     * Removes the rights associated with the given protected content
+     * Removes the rights associated with the given rights-protected content.
      *
-     * @param uri The content URI of the data
+     * @param uri URI for the rights-protected content.
-     * @return
+     *
-     *     ERROR_NONE for success
+     * @return ERROR_NONE for success; ERROR_UNKNOWN for failure.
-     *     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
+     * Removes all the rights information of every DRM plug-in (agent) associated with
-     * DRM framework. Will be used in master reset
+     * the DRM framework. Will be used during a master reset.
      *
-     * @return
+     * @return ERROR_NONE for success; ERROR_UNKNOWN for failure.
-     *     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.
+     * Initiates a new conversion session. An application must initiate a conversion session
-     * Each time the application tries to download a new DRM file
+     * with this method each time it downloads a rights-protected file that needs to be converted.
-     * which needs to be converted, then the application has to
+     *<p>
-     * begin with calling this API.
+     * This method applies only to forward-locking (copy protection) DRM schemes.
      *
-     * @param mimeType Description/MIME type of the input data packet
+     * @param mimeType 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.
+     * Converts the input data (content) that is part of a rights-protected file. The converted
-     * The resultant converted data and the status is returned in the DrmConvertedInfo
+     * data and status is returned in a {@link DrmConvertedStatus} object. This method should be
-     * object. This method will be called each time there are new block
+     * called each time there is a new block of data received by the application.
-     * of data received by the application.
      *
-     * @param convertId Handle for the convert session
+     * @param convertId Handle for the conversion session.
-     * @param inputData Input Data which need to be converted
+     * @param inputData Input data that needs to be converted.
-     * @return Return object contains the status of the data conversion,
+     *
-     *         the output converted data and offset. In this case the
+     * @return A {@link DrmConvertedStatus} object that contains the status of the data conversion,
-     *         application will ignore the offset information.
+     * 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
+     * Informs the DRM plug-in (agent) that there is no more data to convert or that an error 
-     * or when an error occurs. Upon successful conversion of the complete data,
+     * has occurred. Upon successful conversion of the data, the DRM agent will provide an offset
-     * the agent will inform that where the header and body signature
+     * value indicating where the header and body signature should be added. Appending the 
-     * should be added. This signature appending is needed to integrity
+     * signature is necessary to protect the integrity of the converted file.
-     * protect the converted file.
      *
-     * @param convertId Handle for the convert session
+     * @param convertId Handle for the conversion session.
-     * @return Return object contains the status of the data conversion,
+     *
-     *     the header and body signature data. It also informs
+     * @return A {@link DrmConvertedStatus} object that contains the status of the data conversion,
-     *     the application on which offset these signature data should be appended.
+     * the converted data, and the offset for the header and body signature.
      */
     public DrmConvertedStatus closeConvertSession(int convertId) {
         return _closeConvertSession(mUniqueId, convertId);

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

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

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,
+ * An entity class that wraps the capability of each DRM plug-in (agent),
- * such as mimetype's and file suffixes it could handle.
+ * such as the MIME type and file suffix the DRM plug-in can handle.
- *
+ *<p>
- * Plug-in developer could return the capability of the plugin by passing
+ * Plug-in developers can expose the capability of their plug-in by passing an instance of this
- * {@link DrmSupportInfo} instance.
+ * 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
+     * Adds the specified MIME type to the list of MIME types this DRM plug-in supports.
-     * capable of handling the given mime-type.
      *
-     * @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
+     * Adds the specified file suffix to the list of file suffixes this DRM plug-in supports.
-     * capable of handling the given file suffix.
      *
-     * @param fileSuffix File suffix which can be handled
+     * @param fileSuffix File suffix that can be handled by this DRM plug-in.
      */
     public void addFileSuffix(String fileSuffix) {
         mFileSuffixList.add(fileSuffix);
     }
 
     /**
-     * Returns the iterator to walk to through mime types of this object
+     * Retrieves an iterator object that you can use to iterate over the MIME types that 
+     * this DRM plug-in supports.
      *
-     * @return Iterator object
+     * @return The iterator object
      */
     public Iterator<String> getMimeTypeIterator() {
         return mMimeTypeList.iterator();
     }
 
     /**
-     * Returns the iterator to walk to through file suffixes of this object
+     * Retrieves an iterator object that you can use to iterate over the file suffixes that
+     * this DRM plug-in supports.
      *
-     * @return Iterator object
+     * @return The iterator object.
      */
     public Iterator<String> getFileSuffixIterator() {
         return mFileSuffixList.iterator();
     }
 
     /**
-     * Set the unique description about the plugin
+     * Sets a description for the DRM plug-in (agent).
      *
-     * @param description Unique description
+     * @param description Unique description of plug-in.
      */
     public void setDescription(String description) {
         if (null != description) {
@@ -82,30 +82,28 @@ public class DrmSupportInfo {
     }
 
     /**
-     * Returns the unique description associated with the plugin
+     * Retrieves the DRM plug-in (agent) description.
      *
-     * @return Unique description
+     * @return The plug-in description.
      */
     public String getDescriprition() {
         return mDescription;
     }
 
     /**
-     * Overridden hash code implementation
+     * Overridden hash code implementation.
      *
-     * @return Hash code value
+     * @return The hash code value.
      */
     public int hashCode() {
         return mFileSuffixList.hashCode() + mMimeTypeList.hashCode() + mDescription.hashCode();
     }
 
     /**
-     * Overridden equals implementation
+     * Overridden <code>equals</code> implementation.
      *
-     * @param object The object to be compared
+     * @param object The object to be compared.
-     * @return
+     * @return True if equal; false if not equal.
-     *     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
+     * @param mimeType MIME type.
-     * @return
+     * @return True if Mime type is supported; false if MIME type is not supported.
-     *     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
+     * @param fileSuffix File suffix.
-     * @return
+     * @return True if file suffix is supported; false if file suffix is not supported.
-     *     true - if file suffix is supported
-     *     false - if file suffix is not supported
      */
     /* package */ boolean isSupportedFileSuffix(String fileSuffix) {
         return mFileSuffixList.contains(fileSuffix);

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
+ * A utility class that provides operations for parsing extended metadata embedded in
- * and ExtendedMetadataParser for parsing extended metadata BLOB in DRM constraints.
+ * 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
+     * Gets an instance of {@link DrmUtils.ExtendedMetadataParser}, which can be used to parse
-     * extended metadata BLOB in DRM constraints. <br>
+     * extended metadata embedded in DRM constraint information.
      *
-     * extendedMetadata BLOB is retrieved by specifing
+     * @param extendedMetadata Object in which key-value pairs of extended metadata are embedded.
-     * key DrmStore.ConstraintsColumns.EXTENDED_METADATA.
-     *
-     * @param extendedMetadata BLOB in which key-value pairs of extended metadata are embedded.
      *
      */
     public static ExtendedMetadataParser getExtendedMetadataParser(byte[] extendedMetadata) {
@@ -113,9 +112,10 @@ public class DrmUtils {
     }
 
     /**
-     * Utility parser to parse the extended meta-data embedded inside DRM constraints<br><br>
+     * Utility that parses extended metadata embedded in DRM constraint information.
-     *
+     *<p>
-     * Usage example<br>
+     * Usage example:
+     *<p>
      * byte[] extendedMetadata<br>
      * &nbsp;&nbsp;&nbsp;&nbsp; =
      *         constraints.getAsByteArray(DrmStore.ConstraintsColumns.EXTENDED_METADATA);<br>

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
+ * An entity class that wraps the result of a 
- * device and online DRM server by using {@link DrmManagerClient#processDrmInfo(DrmInfo)}
+ * {@link DrmManagerClient#processDrmInfo(DrmInfo) processDrmInfo()}
+ * transaction between a device and a DRM server.
  *
- * In license acquisition scenario this class would hold the binary data
+ * In a license acquisition scenario this class holds the rights information in binary form.
- * of rights information.
  *
  */
 public class ProcessedData {
@@ -30,10 +30,10 @@ public class ProcessedData {
     private String mSubscriptionId = "";
 
     /**
-     * constructor to create ProcessedData object with given parameters
+     * Creates a <code>ProcessedData</code> object with the given parameters.
      *
-     * @param data Rights data
+     * @param data Rights data.
-     * @param accountId Account Id of the user
+     * @param accountId Account ID of the user.
      */
     /* package */ ProcessedData(byte[] data, String accountId) {
         mData = data;
@@ -41,11 +41,11 @@ public class ProcessedData {
     }
 
     /**
-     * constructor to create ProcessedData object with given parameters
+     * Creates a <code>ProcessedData</code> object with the given parameters.
      *
-     * @param data Rights data
+     * @param data Rights data.
-     * @param accountId Account Id of the user
+     * @param accountId Account ID of the user.
-     * @param subscriptionId Subscription 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;

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>