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