content_decryptor_samsung.h

Go to the documentation of this file.

// Copyright 2013 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef PPAPI_CPP_CONTENT_DECRYPTOR_SAMSUNG_H_
#define PPAPI_CPP_CONTENT_DECRYPTOR_SAMSUNG_H_

#include "ppapi/c/pp_stdint.h"
#include "ppapi/c/pp_bool.h"
#include "ppapi/cpp/dev/buffer_dev.h"
#include "ppapi/cpp/resource.h"
#include "ppapi/cpp/var.h"
#include "ppapi/cpp/var_array_buffer.h"
#include "ppapi/c/samsung/pp_content_decryptor_samsung.h"


/// @file
/// This file defines API for implementing Content Decryptor functionality
/// by NaCl application. Interface is based on
/// <code>PP[PB]_ContentDecryptor_Private</code> API

namespace pp {

class InstanceHandle;

/// Content Decryptor API allowing NaCl application to receive encrypted
/// chunks formining elementary stream and deliver decrypted (but encoded)
/// chunks of elementary stream to be decoded by the browser.
class ContentDecryptor_Samsung {
 public:

  /// A constructor that creates an ContentDecryptor_Samsung bound to instance
  /// After creation decryptor must be registered using method
  /// <code>RegisterDecryptor</code> in order to be used.
  explicit ContentDecryptor_Samsung(Instance* instance);

  /// Destructor
  virtual ~ContentDecryptor_Samsung();

  // PPP_ContentDecryptor_Samsung functions exposed as virtual functions
  // for you to override.

  /// Generates a key request. key_system specifies the key or licensing system
  /// to use. type contains the MIME type of init_data. init_data is a data
  /// buffer containing data for use in generating the request.
  ///
  /// Note: <code>GenerateKeyRequest()</code> must create the session ID used in
  /// other methods on this interface. The session ID must be provided to the
  /// browser by the CDM via <code>KeyMessage()</code> on the
  /// <code>PPB_ContentDecryptor_Samsung</code> interface.
  ///
  /// @param[in] key_system The name of the key system.
  ///
  /// @param[in] type MIME type for init_data.
  ///
  /// @param[in] init_data Container specific initialization data.
  virtual void GenerateKeyRequest(const std::string& key_system,
                                  const std::string& type,
                                  VarArrayBuffer init_data) = 0;

  /// Provides a key or license to the decryptor for decrypting media data.
  ///
  /// When the CDM needs more information to complete addition of the key it
  /// will call <code>KeyMessage()</code> on the
  /// <code>PPB_ContentDecryptor_Samsung</code> interface, which the browser
  /// passes to the application. When the key is ready to use, the CDM
  /// must call call <code>KeyAdded()</code> on the
  /// <code>PPB_ContentDecryptor_Samsung</code> interface, and the browser
  /// must notify the web application.
  ///
  /// @param[in] session_id The session ID.
  ///
  /// @param[in] key Decryption key, license, or other message for
  /// the given session ID.
  ///
  /// @param[in] init_data Container specific initialization data.
  virtual void AddKey(const std::string& session_id,
                      VarArrayBuffer key,
                      VarArrayBuffer init_data) = 0;

  /// Cancels a pending key request for the specified session ID.
  ///
  /// @param[in] session_id The session ID.
  virtual void CancelKeyRequest(const std::string& session_id) = 0;

  /// Decrypts the block and returns the unencrypted block via
  /// <code>DeliverBlock()</code> on the
  /// <code>PPB_ContentDecryptor_Samsung</code> interface. The returned block
  /// contains encoded data.
  ///
  /// @param[in] resource An encrypted data block.
  ///
  /// @param[in] encrypted_block_info A <code>PP_EncryptedBlockInfo</code> that
  /// contains all auxiliary information needed for decryption of the
  /// <code>encrypted_block</code>.
  virtual void Decrypt(Buffer_Dev encrypted_buffer,
                       const PP_EncryptedBlockInfo& encrypted_block_info) = 0;

  // PPB_ContentDecryptor_Samsung methods for passing data from the decryptor
  // to the browser.

  /// The decryptor requires a key that has not been provided.
  ///
  /// Sent when the decryptor encounters encrypted content, but it does not have
  /// the key required to decrypt the data. The plugin will call this method in
  /// response to a call to the <code>Decrypt()</code> method on the
  /// <code>PPP_ContentDecryptor_Samsung<code> interface.
  ///
  /// The browser must notify the application that a key is needed, and, in
  /// response, the web application must direct the browser to call
  /// <code>AddKey()</code> on the <code>PPP_ContentDecryptor_Samsung</code>
  /// interface.
  ///
  /// @param[in] key_system The name of the key system.
  ///
  /// @param[in] session_id The session ID.
  ///
  /// @param[in] init_data Container specific initialization data.
  void NeedKey(const std::string& key_system,
               const std::string& session_id,
               VarArrayBuffer init_data);

  /// A key has been added as the result of a call to the <code>AddKey()</code>
  /// method on the <code>PPP_ContentDecryptor_Samsung</code> interface.
  ///
  /// Note: The above describes the most simple case. Depending on the key
  /// system, a series of <code>KeyMessage()</code> calls from the CDM will be
  /// sent to the browser, and then on to the web application. The web
  /// application must then provide more data to the CDM by directing the browser
  /// to pass the data to the CDM via calls to <code>AddKey()</code> on the
  /// <code>PPP_ContentDecryptor_Samsung</code> interface.
  /// The CDM must call <code>KeyAdded()</code> when the sequence is completed,
  /// and, in response, the browser must notify the web application.
  ///
  /// @param[in] key_system The name of the key system.
  ///
  /// @param[in] session_id The session ID.
  void KeyAdded(const std::string& key_system,
                const std::string& session_id);

  /// A message or request has been generated for key_system in the CDM, and
  /// must be sent to the web application.
  ///
  /// For example, when the browser invokes <code>GenerateKeyRequest()</code>
  /// on the <code>PPP_ContentDecryptor_Samsung</code> interface, the plugin
  /// must send a key message containing the key request.
  ///
  /// Note that <code>KeyMessage()</code> can be used for purposes other than
  /// responses to <code>GenerateKeyRequest()</code> calls. See also the text
  /// in the comment for <code>KeyAdded()</code>, which describes a sequence of
  /// <code>AddKey()</code> and <code>KeyMessage()</code> calls required to
  /// prepare for decryption.
  ///
  /// @param[in] key_system Tthe name of the key system.
  ///
  /// @param[in] session_id The session ID.
  ///
  /// @param[in] message Buffer containing the message.
  ///
  /// @param[in] default_url Default URL for the message.
  void KeyMessage(const std::string& key_system,
                  const std::string& session_id,
                  VarArrayBuffer message,
                  const std::string& default_url);

  /// An error occurred in a <code>PPP_ContentDecryptor_Samsung</code> method,
  /// or within the plugin implementing the interface.
  ///
  /// @param[in] key_system The name of the key system.
  ///
  /// @param[in] session_id The session ID.
  ///
  /// @param[in] media_error A MediaKeyError.
  ///
  /// @param[in] system_error A system error code.
  void KeyError(const std::string& key_system,
                const std::string& session_id,
                int32_t media_error,
                int32_t system_code);

  /// Called after the <code>Decrypt()</code> method completes to
  /// deliver decrypted_block to the browser for decoding and rendering.
  ///
  /// The plugin must not hold a reference to the encrypted buffer resource
  /// provided to <code>Decrypt()</code> when it calls this method. The browser
  /// will reuse the buffer in a subsequent <code>Decrypt()</code> call.
  ///
  /// @param[in] decrypted_block Decrypted data block.
  ///
  /// @param[in] decrypted_block_info A <code>PP_DecryptedBlockInfo</code> that
  /// contains the result code and tracking info associated with the
  /// <code>decrypted_block</code>.
  void DeliverBlock(Buffer_Dev decrypted_block,
                    const PP_DecryptedBlockInfo& decrypted_block_info);

  /// The decryptor must register itself in the Browser, so that it can be used
  /// by the Browser as Content Decryptor Module.
  ///
  /// @param[in] key_system Name of this content decryptor uder
  /// which the Browser will recognize it.
  ///
  /// @param[in] type Type of media that are supported
  /// by this content decryptor (* - means all MIME types)
  ///
  /// @return A <code>PP_Bool</code> containing containing <code>PP_TRUE</code>
  /// if the registration succeed, otherwise <code>PP_FALSE</code>.
  PP_Bool RegisterDecryptor(const std::string& key_system,
                            const std::string& type);

 private:
  InstanceHandle associated_instance_;
};

}  // namespace pp

#endif  // PPAPI_CPP_CONTENT_DECRYPTOR_SAMSUNG_H_