ppapi/cpp/var_array_buffer.h

// Copyright (c) 2012 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_VAR_ARRAY_BUFFER_H_
#define PPAPI_CPP_VAR_ARRAY_BUFFER_H_

#include "ppapi/cpp/var.h"

/// @file
/// This file defines the API for interacting with a JavaScript ArrayBuffer.

namespace pp {

/// <code>VarArrayBuffer</code> provides a way to interact with JavaScript
/// ArrayBuffers, which represent a contiguous sequence of bytes. Note that
/// these vars are not part of the embedding page's DOM, and can only be
/// shared with JavaScript using the <code>PostMessage</code> and
/// <code>HandleMessage</code> functions of <code>Instance</code>.
class VarArrayBuffer : public Var {
 public:
  /// The default constructor constructs a <code>VarArrayBuffer</code> which is
  /// 0 byte long.
  VarArrayBuffer();

  /// Construct a <code>VarArrayBuffer</code> given a var for which
  /// is_array_buffer() is true. This will refer to the same
  /// <code>ArrayBuffer</code> as var, but allows you to access methods
  /// specific to <code>VarArrayBuffer</code>.
  ///
  /// @param[in] var An <code>ArrayBuffer</code> var.
  explicit VarArrayBuffer(const Var& var);

  /// Construct a new <code>VarArrayBuffer</code> which is
  /// <code>size_in_bytes</code> bytes long and initialized to zero.
  ///
  /// @param[in] size_in_bytes The size of the constructed
  /// <code>ArrayBuffer</code> in bytes.
  explicit VarArrayBuffer(uint32_t size_in_bytes);

  /// Copy constructor.
  VarArrayBuffer(const VarArrayBuffer& buffer) : Var(buffer) {}

  virtual ~VarArrayBuffer() {}

  /// This function assigns one <code>VarArrayBuffer</code> to another
  /// <code>VarArrayBuffer</code>.
  ///
  /// @param[in] other The <code>VarArrayBuffer</code> to be assigned.
  ///
  /// @return The resulting <code>VarArrayBuffer</code>.
  VarArrayBuffer& operator=(const VarArrayBuffer& other);

  /// This function assigns one <code>VarArrayBuffer</code> to another
  /// <code>VarArrayBuffer</code>. A Var's assignment operator is overloaded
  /// here so that we can check for assigning a non-ArrayBuffer var to a
  /// <code>VarArrayBuffer</code>.
  ///
  /// @param[in] other The <code>VarArrayBuffer</code> to be assigned.
  ///
  /// @return The resulting <code>VarArrayBuffer</code> (as a Var&).
  virtual Var& operator=(const Var& other);

  /// ByteLength() retrieves the length of the <code>VarArrayBuffer</code> in
  /// bytes.
  ///
  /// @return The length of the <code>VarArrayBuffer</code> in bytes.
  uint32_t ByteLength() const;

  /// Map() maps the <code>ArrayBuffer</code> in to the module's address space
  /// and returns a pointer to the beginning of the internal buffer for
  /// this <code>ArrayBuffer</code>. ArrayBuffers are copied when transmitted,
  /// so changes to the underlying memory are not automatically available to
  /// the embedding page.
  ///
  /// Note that calling Map() can be a relatively expensive operation. Use care
  /// when calling it in performance-critical code. For example, you should call
  /// it only once when looping over an <code>ArrayBuffer</code>.
  ///
  /// <strong>Example:</strong>
  ///
  /// @code
  ///   char* data = static_cast<char*>(array_buffer_var.Map());
  ///   uint32_t byte_length = array_buffer_var.ByteLength();
  ///   for (uint32_t i = 0; i < byte_length; ++i)
  ///     data[i] = 'A';
  /// @endcode
  ///
  /// @return A pointer to the internal buffer for this
  /// <code>ArrayBuffer</code>.
  void* Map();

  /// Unmap() unmaps this <code>ArrayBuffer</code> var from the module address
  /// space. Use this if you want to save memory but might want to call Map()
  /// to map the buffer again later.
  void Unmap();

 private:
  void ConstructWithSize(uint32_t size_in_bytes);
};

}  // namespace pp

#endif  // PPAPI_CPP_VAR_ARRAY_BUFFER_H_