ppapi/cpp/var_array_buffer.h

   1 // Copyright (c) 2012 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 PPAPI_CPP_VAR_ARRAY_BUFFER_H_
   6 #define PPAPI_CPP_VAR_ARRAY_BUFFER_H_
   7
   8 #include "ppapi/cpp/var.h"
   9
  10 /// @file
  11 /// This file defines the API for interacting with a JavaScript ArrayBuffer.
  12
  13 namespace pp {
  14
  15 /// <code>VarArrayBuffer</code> provides a way to interact with JavaScript
  16 /// ArrayBuffers, which represent a contiguous sequence of bytes. Note that
  17 /// these vars are not part of the embedding page's DOM, and can only be
  18 /// shared with JavaScript using the <code>PostMessage</code> and
  19 /// <code>HandleMessage</code> functions of <code>Instance</code>.
  20 class VarArrayBuffer : public Var {
  21  public:
  22   /// The default constructor constructs a <code>VarArrayBuffer</code> which is
  23   /// 0 byte long.
  24   VarArrayBuffer();
  25
  26   /// Construct a <code>VarArrayBuffer</code> given a var for which
  27   /// is_array_buffer() is true. This will refer to the same
  28   /// <code>ArrayBuffer</code> as var, but allows you to access methods
  29   /// specific to <code>VarArrayBuffer</code>.
  30   ///
  31   /// @param[in] var An <code>ArrayBuffer</code> var.
  32   explicit VarArrayBuffer(const Var& var);
  33
  34   /// Construct a new <code>VarArrayBuffer</code> which is
  35   /// <code>size_in_bytes</code> bytes long and initialized to zero.
  36   ///
  37   /// @param[in] size_in_bytes The size of the constructed
  38   /// <code>ArrayBuffer</code> in bytes.
  39   explicit VarArrayBuffer(uint32_t size_in_bytes);
  40
  41   /// Copy constructor.
  42   VarArrayBuffer(const VarArrayBuffer& buffer) : Var(buffer) {}
  43
  44   virtual ~VarArrayBuffer() {}
  45
  46   /// This function assigns one <code>VarArrayBuffer</code> to another
  47   /// <code>VarArrayBuffer</code>.
  48   ///
  49   /// @param[in] other The <code>VarArrayBuffer</code> to be assigned.
  50   ///
  51   /// @return The resulting <code>VarArrayBuffer</code>.
  52   VarArrayBuffer& operator=(const VarArrayBuffer& other);
  53
  54   /// This function assigns one <code>VarArrayBuffer</code> to another
  55   /// <code>VarArrayBuffer</code>. A Var's assignment operator is overloaded
  56   /// here so that we can check for assigning a non-ArrayBuffer var to a
  57   /// <code>VarArrayBuffer</code>.
  58   ///
  59   /// @param[in] other The <code>VarArrayBuffer</code> to be assigned.
  60   ///
  61   /// @return The resulting <code>VarArrayBuffer</code> (as a Var&).
  62   virtual Var& operator=(const Var& other);
  63
  64   /// ByteLength() retrieves the length of the <code>VarArrayBuffer</code> in
  65   /// bytes.
  66   ///
  67   /// @return The length of the <code>VarArrayBuffer</code> in bytes.
  68   uint32_t ByteLength() const;
  69
  70   /// Map() maps the <code>ArrayBuffer</code> in to the module's address space
  71   /// and returns a pointer to the beginning of the internal buffer for
  72   /// this <code>ArrayBuffer</code>. ArrayBuffers are copied when transmitted,
  73   /// so changes to the underlying memory are not automatically available to
  74   /// the embedding page.
  75   ///
  76   /// Note that calling Map() can be a relatively expensive operation. Use care
  77   /// when calling it in performance-critical code. For example, you should call
  78   /// it only once when looping over an <code>ArrayBuffer</code>.
  79   ///
  80   /// <strong>Example:</strong>
  81   ///
  82   /// @code
  83   ///   char* data = static_cast<char*>(array_buffer_var.Map());
  84   ///   uint32_t byte_length = array_buffer_var.ByteLength();
  85   ///   for (uint32_t i = 0; i < byte_length; ++i)
  86   ///     data[i] = 'A';
  87   /// @endcode
  88   ///
  89   /// @return A pointer to the internal buffer for this
  90   /// <code>ArrayBuffer</code>.
  91   void* Map();
  92
  93   /// Unmap() unmaps this <code>ArrayBuffer</code> var from the module address
  94   /// space. Use this if you want to save memory but might want to call Map()
  95   /// to map the buffer again later.
  96   void Unmap();
  97
  98  private:
  99   void ConstructWithSize(uint32_t size_in_bytes);
 100 };
 101
 102 }  // namespace pp
 103
 104 #endif  // PPAPI_CPP_VAR_ARRAY_BUFFER_H_