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 /* From ppb_var_array_buffer.idl modified Thu Feb 28 09:24:06 2013. */ 7 8 #ifndef PPAPI_C_PPB_VAR_ARRAY_BUFFER_H_ 9 #define PPAPI_C_PPB_VAR_ARRAY_BUFFER_H_ 10 11 #include "ppapi/c/pp_bool.h" 12 #include "ppapi/c/pp_macros.h" 13 #include "ppapi/c/pp_stdint.h" 14 #include "ppapi/c/pp_var.h" 15 16 #define PPB_VAR_ARRAY_BUFFER_INTERFACE_1_0 "PPB_VarArrayBuffer;1.0" 17 #define PPB_VAR_ARRAY_BUFFER_INTERFACE PPB_VAR_ARRAY_BUFFER_INTERFACE_1_0 18 19 /** 20 * @file 21 * This file defines the <code>PPB_VarArrayBuffer</code> struct providing 22 * a way to interact with JavaScript ArrayBuffers. 23 */ 24 25 26 /** 27 * @addtogroup Interfaces 28 * @{ 29 */ 30 /** 31 * The <code>PPB_VarArrayBuffer</code> interface provides a way to interact 32 * with JavaScript ArrayBuffers, which represent a contiguous sequence of 33 * bytes. Use <code>PPB_Var</code> to manage the reference count for a 34 * <code>VarArrayBuffer</code>. Note that these Vars are not part of the 35 * embedding page's DOM, and can only be shared with JavaScript using the 36 * <code>PostMessage</code> and <code>HandleMessage</code> functions of 37 * <code>pp::Instance</code>. 38 */ 39 struct PPB_VarArrayBuffer_1_0 { 40 /** 41 * Create() creates a zero-initialized <code>VarArrayBuffer</code>. 42 * 43 * @param[in] size_in_bytes The size of the <code>ArrayBuffer</code> to 44 * be created. 45 * 46 * @return A <code>PP_Var</code> representing a <code>VarArrayBuffer</code> 47 * of the requested size and with a reference count of 1. 48 */ 49 struct PP_Var (*Create)(uint32_t size_in_bytes); 50 /** 51 * ByteLength() retrieves the length of the <code>VarArrayBuffer</code> in 52 * bytes. On success, <code>byte_length</code> is set to the length of the 53 * given <code>ArrayBuffer</code> var. On failure, <code>byte_length</code> 54 * is unchanged (this could happen, for instance, if the given 55 * <code>PP_Var</code> is not of type <code>PP_VARTYPE_ARRAY_BUFFER</code>). 56 * Note that ByteLength() will successfully retrieve the size of an 57 * <code>ArrayBuffer</code> even if the <code>ArrayBuffer</code> is not 58 * currently mapped. 59 * 60 * @param[in] array The <code>ArrayBuffer</code> whose length should be 61 * returned. 62 * 63 * @param[out] byte_length A variable which is set to the length of the given 64 * <code>ArrayBuffer</code> on success. 65 * 66 * @return <code>PP_TRUE</code> on success, <code>PP_FALSE</code> on failure. 67 */ 68 PP_Bool (*ByteLength)(struct PP_Var array, uint32_t* byte_length); 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 buffer for the given 72 * <code>ArrayBuffer PP_Var</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 = (char*)(array_buffer_if.Map(array_buffer_var)); 84 * uint32_t byte_length = 0; 85 * PP_Bool ok = array_buffer_if.ByteLength(array_buffer_var, &byte_length); 86 * if (!ok) 87 * return DoSomethingBecauseMyVarIsNotAnArrayBuffer(); 88 * for (uint32_t i = 0; i < byte_length; ++i) 89 * data[i] = 'A'; 90 * @endcode 91 * 92 * @param[in] array The <code>ArrayBuffer</code> whose internal buffer should 93 * be returned. 94 * 95 * @return A pointer to the internal buffer for this 96 * <code>ArrayBuffer</code>. Returns <code>NULL</code> 97 * if the given <code>PP_Var</code> is not of type 98 * <code>PP_VARTYPE_ARRAY_BUFFER</code>. 99 */ 100 void* (*Map)(struct PP_Var array); 101 /** 102 * Unmap() unmaps the given <code>ArrayBuffer</code> var from the module 103 * address space. Use this if you want to save memory but might want to call 104 * Map() to map the buffer again later. The <code>PP_Var</code> remains valid 105 * and should still be released using <code>PPB_Var</code> when you are done 106 * with the <code>ArrayBuffer</code>. 107 * 108 * @param[in] array The <code>ArrayBuffer</code> to be released. 109 */ 110 void (*Unmap)(struct PP_Var array); 111 }; 112 113 typedef struct PPB_VarArrayBuffer_1_0 PPB_VarArrayBuffer; 114 /** 115 * @} 116 */ 117 118 #endif /* PPAPI_C_PPB_VAR_ARRAY_BUFFER_H_ */ 119 120
