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 6 /** 7 * This file defines the <code>PPB_VarArrayBuffer</code> struct providing 8 * a way to interact with JavaScript ArrayBuffers. 9 */ 10 11 label Chrome { 12 M18 = 1.0 13 }; 14 15 /** 16 * The <code>PPB_VarArrayBuffer</code> interface provides a way to interact 17 * with JavaScript ArrayBuffers, which represent a contiguous sequence of 18 * bytes. Use <code>PPB_Var</code> to manage the reference count for a 19 * <code>VarArrayBuffer</code>. Note that these Vars are not part of the 20 * embedding page's DOM, and can only be shared with JavaScript using the 21 * <code>PostMessage</code> and <code>HandleMessage</code> functions of 22 * <code>pp::Instance</code>. 23 */ 24 [macro="PPB_VAR_ARRAY_BUFFER_INTERFACE"] 25 interface PPB_VarArrayBuffer { 26 /** 27 * Create() creates a zero-initialized <code>VarArrayBuffer</code>. 28 * 29 * @param[in] size_in_bytes The size of the <code>ArrayBuffer</code> to 30 * be created. 31 * 32 * @return A <code>PP_Var</code> representing a <code>VarArrayBuffer</code> 33 * of the requested size and with a reference count of 1. 34 */ 35 PP_Var Create([in] uint32_t size_in_bytes); 36 37 /** 38 * ByteLength() retrieves the length of the <code>VarArrayBuffer</code> in 39 * bytes. On success, <code>byte_length</code> is set to the length of the 40 * given <code>ArrayBuffer</code> var. On failure, <code>byte_length</code> 41 * is unchanged (this could happen, for instance, if the given 42 * <code>PP_Var</code> is not of type <code>PP_VARTYPE_ARRAY_BUFFER</code>). 43 * Note that ByteLength() will successfully retrieve the size of an 44 * <code>ArrayBuffer</code> even if the <code>ArrayBuffer</code> is not 45 * currently mapped. 46 * 47 * @param[in] array The <code>ArrayBuffer</code> whose length should be 48 * returned. 49 * 50 * @param[out] byte_length A variable which is set to the length of the given 51 * <code>ArrayBuffer</code> on success. 52 * 53 * @return <code>PP_TRUE</code> on success, <code>PP_FALSE</code> on failure. 54 */ 55 PP_Bool ByteLength([in] PP_Var array, [out] uint32_t byte_length); 56 57 /** 58 * Map() maps the <code>ArrayBuffer</code> in to the module's address space 59 * and returns a pointer to the beginning of the buffer for the given 60 * <code>ArrayBuffer PP_Var</code>. ArrayBuffers are copied when transmitted, 61 * so changes to the underlying memory are not automatically available to 62 * the embedding page. 63 * 64 * Note that calling Map() can be a relatively expensive operation. Use care 65 * when calling it in performance-critical code. For example, you should call 66 * it only once when looping over an <code>ArrayBuffer</code>. 67 * 68 * <strong>Example:</strong> 69 * 70 * @code 71 * char* data = (char*)(array_buffer_if.Map(array_buffer_var)); 72 * uint32_t byte_length = 0; 73 * PP_Bool ok = array_buffer_if.ByteLength(array_buffer_var, &byte_length); 74 * if (!ok) 75 * return DoSomethingBecauseMyVarIsNotAnArrayBuffer(); 76 * for (uint32_t i = 0; i < byte_length; ++i) 77 * data[i] = 'A'; 78 * @endcode 79 * 80 * @param[in] array The <code>ArrayBuffer</code> whose internal buffer should 81 * be returned. 82 * 83 * @return A pointer to the internal buffer for this 84 * <code>ArrayBuffer</code>. Returns <code>NULL</code> 85 * if the given <code>PP_Var</code> is not of type 86 * <code>PP_VARTYPE_ARRAY_BUFFER</code>. 87 */ 88 mem_t Map([in] PP_Var array); 89 90 /** 91 * Unmap() unmaps the given <code>ArrayBuffer</code> var from the module 92 * address space. Use this if you want to save memory but might want to call 93 * Map() to map the buffer again later. The <code>PP_Var</code> remains valid 94 * and should still be released using <code>PPB_Var</code> when you are done 95 * with the <code>ArrayBuffer</code>. 96 * 97 * @param[in] array The <code>ArrayBuffer</code> to be released. 98 */ 99 void Unmap([in] PP_Var array); 100 }; 101 102
