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 std::vector<uint8_t>& certificate,
  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       EmeInitDataType init_data_type,
 107       const std::vector<uint8_t>& init_data,
 108       scoped_ptr<NewSessionCdmPromise> promise) = 0;
 109
 110   // Loads a session with the |session_id| provided.
 111   // Note: UpdateSession(), CloseSession() and RemoveSession() should only be
 112   //       called after the |promise| is resolved.
 113   virtual void LoadSession(SessionType session_type,
 114                            const std::string& session_id,
 115                            scoped_ptr<NewSessionCdmPromise> promise) = 0;
 116
 117   // Updates a session specified by |session_id| with |response|.
 118   virtual void UpdateSession(const std::string& session_id,
 119                              const std::vector<uint8_t>& response,
 120                              scoped_ptr<SimpleCdmPromise> promise) = 0;
 121
 122   // Closes the session specified by |session_id|. The CDM should resolve or
 123   // reject the |promise| when the call has been processed. This may be before
 124   // the session is closed. Once the session is closed, a SessionClosedCB must
 125   // also be called.
 126   virtual void CloseSession(const std::string& session_id,
 127                             scoped_ptr<SimpleCdmPromise> promise) = 0;
 128
 129   // Removes stored session data associated with the session specified by
 130   // |session_id|.
 131   virtual void RemoveSession(const std::string& session_id,
 132                              scoped_ptr<SimpleCdmPromise> promise) = 0;
 133
 134   // Returns the CdmContext associated with |this|, which must NOT be null.
 135   // Usually the CdmContext is owned by |this|. Caller needs to make sure it is
 136   // not used after |this| is destructed.
 137   virtual CdmContext* GetCdmContext() = 0;
 138
 139  protected:
 140   MediaKeys();
 141
 142  private:
 143   DISALLOW_COPY_AND_ASSIGN(MediaKeys);
 144 };
 145
 146 // Key event callbacks. See the spec for details:
 147 // https://dvcs.w3.org/hg/html-media/raw-file/default/encrypted-media/encrypted-media.html#event-summary
 148
 149 typedef base::Callback<void(const std::string& session_id,
 150                             MediaKeys::MessageType message_type,
 151                             const std::vector<uint8_t>& message,
 152                             const GURL& legacy_destination_url)>
 153     SessionMessageCB;
 154
 155 // Called when the session specified by |session_id| is closed. Note that the
 156 // CDM may close a session at any point, such as in response to a CloseSession()
 157 // call, when the session is no longer needed, or when system resources are
 158 // lost. See for details: http://w3c.github.io/encrypted-media/#session-close
 159 typedef base::Callback<void(const std::string& session_id)> SessionClosedCB;
 160
 161 typedef base::Callback<void(const std::string& session_id,
 162                             MediaKeys::Exception exception,
 163                             uint32_t system_code,
 164                             const std::string& error_message)>
 165     LegacySessionErrorCB;
 166
 167 typedef base::Callback<void(const std::string& session_id,
 168                             bool has_additional_usable_key,
 169                             CdmKeysInfo keys_info)> SessionKeysChangeCB;
 170
 171 typedef base::Callback<void(const std::string& session_id,
 172                             const base::Time& new_expiry_time)>
 173     SessionExpirationUpdateCB;
 174
 175 }  // namespace media
 176
 177 #endif  // MEDIA_BASE_MEDIA_KEYS_H_