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     SESSION_TYPE_MAX = PERSISTENT_RELEASE_MESSAGE_SESSION
  77   };
  78
  79   // Type of message being sent to the application.
  80   // Must be consistent with the values specified in the spec:
  81   // https://w3c.github.io/encrypted-media/#idl-def-MediaKeyMessageType
  82   enum MessageType {
  83     LICENSE_REQUEST,
  84     LICENSE_RENEWAL,
  85     LICENSE_RELEASE,
  86     MESSAGE_TYPE_MAX = LICENSE_RELEASE
  87   };
  88
  89   virtual ~MediaKeys();
  90
  91   // Provides a server certificate to be used to encrypt messages to the
  92   // license server.
  93   virtual void SetServerCertificate(const std::vector<uint8_t>& certificate,
  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 std::vector<uint8_t>& init_data,
 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 std::vector<uint8_t>& response,
 121                              scoped_ptr<SimpleCdmPromise> promise) = 0;
 122
 123   // Closes the session specified by |session_id|. The CDM should resolve or
 124   // reject the |promise| when the call has been processed. This may be before
 125   // the session is closed. Once the session is closed, a SessionClosedCB must
 126   // also be called.
 127   virtual void CloseSession(const std::string& session_id,
 128                             scoped_ptr<SimpleCdmPromise> promise) = 0;
 129
 130   // Removes stored session data associated with the session specified by
 131   // |session_id|.
 132   virtual void RemoveSession(const std::string& session_id,
 133                              scoped_ptr<SimpleCdmPromise> promise) = 0;
 134
 135   // Returns the CdmContext associated with |this|, which must NOT be null.
 136   // Usually the CdmContext is owned by |this|. Caller needs to make sure it is
 137   // not used after |this| is destructed.
 138   virtual CdmContext* GetCdmContext() = 0;
 139
 140  protected:
 141   MediaKeys();
 142
 143  private:
 144   DISALLOW_COPY_AND_ASSIGN(MediaKeys);
 145 };
 146
 147 // Key event callbacks. See the spec for details:
 148 // https://dvcs.w3.org/hg/html-media/raw-file/default/encrypted-media/encrypted-media.html#event-summary
 149
 150 typedef base::Callback<void(const std::string& session_id,
 151                             MediaKeys::MessageType message_type,
 152                             const std::vector<uint8_t>& message,
 153                             const GURL& legacy_destination_url)>
 154     SessionMessageCB;
 155
 156 // Called when the session specified by |session_id| is closed. Note that the
 157 // CDM may close a session at any point, such as in response to a CloseSession()
 158 // call, when the session is no longer needed, or when system resources are
 159 // lost. See for details: http://w3c.github.io/encrypted-media/#session-close
 160 typedef base::Callback<void(const std::string& session_id)> SessionClosedCB;
 161
 162 typedef base::Callback<void(const std::string& session_id,
 163                             MediaKeys::Exception exception,
 164                             uint32_t system_code,
 165                             const std::string& error_message)>
 166     LegacySessionErrorCB;
 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_