media/base/media_keys.h

   1 // Copyright 2013 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef MEDIA_BASE_MEDIA_KEYS_H_
   6 #define MEDIA_BASE_MEDIA_KEYS_H_
   7
   8 #include <string>
   9 #include <vector>
  10
  11 #include "base/basictypes.h"
  12 #include "base/callback.h"
  13 #include "base/memory/scoped_ptr.h"
  14 #include "base/memory/scoped_vector.h"
  15 #include "media/base/media_export.h"
  16 #include "url/gurl.h"
  17
  18 namespace base {
  19 class Time;
  20 }
  21
  22 namespace media {
  23
  24 class CdmContext;
  25 struct CdmKeyInformation;
  26
  27 template <typename... T>
  28 class CdmPromiseTemplate;
  29
  30 typedef CdmPromiseTemplate<std::string> NewSessionCdmPromise;
  31 typedef CdmPromiseTemplate<> SimpleCdmPromise;
  32 typedef ScopedVector<CdmKeyInformation> CdmKeysInfo;
  33
  34 // Performs media key operations.
  35 //
  36 // All key operations are called on the renderer thread. Therefore, these calls
  37 // should be fast and nonblocking; key events should be fired asynchronously.
  38 class MEDIA_EXPORT MediaKeys{
  39  public:
  40   // Reported to UMA, so never reuse a value!
  41   // Must be kept in sync with blink::WebMediaPlayerClient::MediaKeyErrorCode
  42   // (enforced in webmediaplayer_impl.cc).
  43   // TODO(jrummell): Can this be moved to proxy_decryptor as it should only be
  44   // used by the prefixed EME code?
  45   enum KeyError {
  46     kUnknownError = 1,
  47     kClientError,
  48     // The commented v0.1b values below have never been used.
  49     // kServiceError,
  50     kOutputError = 4,
  51     // kHardwareChangeError,
  52     // kDomainError,
  53     kMaxKeyError  // Must be last and greater than any legit value.
  54   };
  55
  56   // Must be a superset of cdm::MediaKeyException.
  57   enum Exception {
  58     NOT_SUPPORTED_ERROR,
  59     INVALID_STATE_ERROR,
  60     INVALID_ACCESS_ERROR,
  61     QUOTA_EXCEEDED_ERROR,
  62     UNKNOWN_ERROR,
  63     CLIENT_ERROR,
  64     OUTPUT_ERROR,
  65     EXCEPTION_MAX = OUTPUT_ERROR
  66   };
  67
  68   // Type of license required when creating/loading a session.
  69   // Must be consistent with the values specified in the spec:
  70   // https://w3c.github.io/encrypted-media/#idl-def-MediaKeySessionType
  71   enum SessionType {
  72     TEMPORARY_SESSION,
  73     PERSISTENT_LICENSE_SESSION,
  74     PERSISTENT_RELEASE_MESSAGE_SESSION
  75   };
  76
  77   // Type of message being sent to the application.
  78   // Must be consistent with the values specified in the spec:
  79   // https://w3c.github.io/encrypted-media/#idl-def-MediaKeyMessageType
  80   enum MessageType {
  81     LICENSE_REQUEST,
  82     LICENSE_RENEWAL,
  83     LICENSE_RELEASE,
  84     MESSAGE_TYPE_MAX = LICENSE_RELEASE
  85   };
  86
  87   virtual ~MediaKeys();
  88
  89   // Provides a server certificate to be used to encrypt messages to the
  90   // license server.
  91   virtual void SetServerCertificate(const uint8* certificate_data,
  92                                     int certificate_data_length,
  93                                     scoped_ptr<SimpleCdmPromise> promise) = 0;
  94
  95   // Creates a session with |session_type|. Then generates a request with the
  96   // |init_data_type| and |init_data|.
  97   // Note:
  98   // 1. The session ID will be provided when the |promise| is resolved.
  99   // 2. The generated request should be returned through a SessionMessageCB,
 100   //    which must be AFTER the |promise| is resolved. Otherwise, the session ID
 101   //    in the callback will not be recognized.
 102   // 3. UpdateSession(), CloseSession() and RemoveSession() should only be
 103   //    called after the |promise| is resolved.
 104   virtual void CreateSessionAndGenerateRequest(
 105       SessionType session_type,
 106       const std::string& init_data_type,
 107       const uint8* init_data,
 108       int init_data_length,
 109       scoped_ptr<NewSessionCdmPromise> promise) = 0;
 110
 111   // Loads a session with the |session_id| provided.
 112   // Note: UpdateSession(), CloseSession() and RemoveSession() should only be
 113   //       called after the |promise| is resolved.
 114   virtual void LoadSession(SessionType session_type,
 115                            const std::string& session_id,
 116                            scoped_ptr<NewSessionCdmPromise> promise) = 0;
 117
 118   // Updates a session specified by |session_id| with |response|.
 119   virtual void UpdateSession(const std::string& session_id,
 120                              const uint8* response,
 121                              int response_length,
 122                              scoped_ptr<SimpleCdmPromise> promise) = 0;
 123
 124   // Closes the session specified by |session_id|. The CDM should resolve or
 125   // reject the |promise| when the call has been processed. This may be before
 126   // the session is closed. Once the session is closed, a SessionClosedCB must
 127   // also be called.
 128   virtual void CloseSession(const std::string& session_id,
 129                             scoped_ptr<SimpleCdmPromise> promise) = 0;
 130
 131   // Removes stored session data associated with the session specified by
 132   // |session_id|.
 133   virtual void RemoveSession(const std::string& session_id,
 134                              scoped_ptr<SimpleCdmPromise> promise) = 0;
 135
 136   // Returns the CdmContext associated with |this|, which must NOT be null.
 137   // Usually the CdmContext is owned by |this|. Caller needs to make sure it is
 138   // not used after |this| is destructed.
 139   virtual CdmContext* GetCdmContext() = 0;
 140
 141  protected:
 142   MediaKeys();
 143
 144  private:
 145   DISALLOW_COPY_AND_ASSIGN(MediaKeys);
 146 };
 147
 148 // Key event callbacks. See the spec for details:
 149 // https://dvcs.w3.org/hg/html-media/raw-file/default/encrypted-media/encrypted-media.html#event-summary
 150
 151 typedef base::Callback<void(const std::string& session_id,
 152                             MediaKeys::MessageType message_type,
 153                             const std::vector<uint8>& message,
 154                             const GURL& legacy_destination_url)>
 155     SessionMessageCB;
 156
 157 // Called when the session specified by |session_id| is closed. Note that the
 158 // CDM may close a session at any point, such as in response to a CloseSession()
 159 // call, when the session is no longer needed, or when system resources are
 160 // lost. See for details: http://w3c.github.io/encrypted-media/#session-close
 161 typedef base::Callback<void(const std::string& session_id)> SessionClosedCB;
 162
 163 typedef base::Callback<void(const std::string& session_id,
 164                             MediaKeys::Exception exception,
 165                             uint32 system_code,
 166                             const std::string& error_message)> SessionErrorCB;
 167
 168 typedef base::Callback<void(const std::string& session_id,
 169                             bool has_additional_usable_key,
 170                             CdmKeysInfo keys_info)> SessionKeysChangeCB;
 171
 172 typedef base::Callback<void(const std::string& session_id,
 173                             const base::Time& new_expiry_time)>
 174     SessionExpirationUpdateCB;
 175
 176 }  // namespace media
 177
 178 #endif  // MEDIA_BASE_MEDIA_KEYS_H_