Source release 14.2.0

cdm/include/cdm.h

@@ -269,6 +269,13 @@ class CDM_EXPORT Cdm : public ITimerClient {
   // A timer interface provided by the application, independent of CDM
   // instances.
   // See Cdm::initialize().
+  // Implementations of this class only need to deal with at most one
+  // outstanding timer per IClient at a time. It is an error for setTimeout() to
+  // be called while there is already a timer running for that client. It is
+  // recommended for implementers of this class to cancel the preexisting timer
+  // and start the new timer if this erroneous situation occurs.
+  // Timers are non-repeating. If the CDM wants to repeat a timer, it will call
+  // setTimeout() again inside the timeout callback.
   class ITimer {
    public:
     // This typedef is for backward compatibility with v3.0.0.
@@ -279,7 +286,7 @@ class CDM_EXPORT Cdm : public ITimerClient {
                             IClient* client,
                             void* context) = 0;
 
-    // Cancel all timers associated with |client|.
+    // Cancel the timer associated with |client|.
     virtual void cancel(IClient *client) = 0;
 
    protected:
@@ -344,9 +351,9 @@ class CDM_EXPORT Cdm : public ITimerClient {
   // |storage| defines the storage to use for this instance.  By providing
   // different objects here for different origins, this parameter can be used to
   // provide per-origin storage. It may not be NULL.
-  // If |privacy_mode| is true, server certificates are required and will be
+  // If |privacy_mode| is true, service certificates are required and will be
   // used to encrypt messages to the license server.
-  // By using server certificates to encrypt communication with the license
+  // By using service certificates to encrypt communication with the license
   // server, device-identifying information cannot be extracted from the
   // license exchange process by an intermediate layer between the CDM and
   // the server.
@@ -358,31 +365,39 @@ class CDM_EXPORT Cdm : public ITimerClient {
 
   virtual ~Cdm() {}
 
-  // Sets up a service certificate for the CDM. It is used to encrypt
-  // outgoing messages (the ClientIdentification portion of the license and
-  // provisioning requests). It also holds the provider ID setting, used in
-  // the provisioning request.
-  // If setServiceCertificate() is not called, provider ID will not be set
-  // in the provisioning request.  If this function is not called and
-  // privacy mode is enabled, a service certificate request will be initiated
-  // as a preliminary step in the license request.
+  // The following three methods relate to service certificates. The service
+  // certificate holds the RSA public key for the server and other fields needed
+  // for provisioning. It is mandatory if privacy mode is turned on, as it
+  // is used to encrypt portions of outgoing messages.
+  // If a certificate has not been installed before generating a provisioning
+  // request, a default certificate that only works with the Widevine-hosted
+  // provisioning service will be used.
+  // It is an error to generate a license request while privacy  mode is turned
+  // on without installing a service certificate first.
+
+  // Installs a service certificate from a data buffer.
+  // This is used when the system or application already knows the certificate
+  // of the service it wishes to communicate with, either because it is baked
+  // into the software or because it was previously cached after a call to
+  // parseServiceCertificateResponse().
   virtual Status setServiceCertificate(const std::string& certificate) = 0;
 
-  // Create a Service Certificate Request message.
+  // Generate a Service Certificate Request message.
   // This is used to fetch a service certificate from the license server.
   // It is needed in cases where the system or application does not have
-  // a service certificate for the license server.
-  // The service certificate holds the RSA public key for the server and
-  // other fields needed for provisioning. It is also needed for privacy mode.
+  // a service certificate for the license server already.
   virtual Status getServiceCertificateRequest(std::string* message) = 0;
 
-  // Parse a Service Certificate Response message and extract the certificate.
+  // Parse a Service Certificate Response message, installing and extracting the
+  // certificate.
   // This is used when fetching a service certificate from the license server.
-  // The response input is the string returned by the license server
-  // (see getServiceCertificateRequest()). The service certificate is installed
-  // if no error is returned. The returned certificate string may be used in
-  // future sessions as the input to setServiceCertificate(), avoiding extra
-  // calls to the license server.
+  // A request should be generated by getServiceCertificateRequest() and sent
+  // to the license server. The server's response should be passed into this
+  // method,
+  // The service certificate is installed if no error is returned. The returned
+  // certificate string may be used in future sessions as the input to
+  // setServiceCertificate(), to avoid needing to make a call to the license
+  // server to get the certificate.
   virtual Status parseServiceCertificateResponse(const std::string& response,
                                                  std::string* certificate) = 0;