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_ 105
