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 pp_array_output.idl modified Tue Oct 22 15:09:25 2013. */ 7 8 #ifndef PPAPI_C_PP_ARRAY_OUTPUT_H_ 9 #define PPAPI_C_PP_ARRAY_OUTPUT_H_ 10 11 #include "ppapi/c/pp_macros.h" 12 #include "ppapi/c/pp_stdint.h" 13 14 /** 15 * @file 16 * PP_ArrayOutput_GetDataBuffer is a callback function to allocate plugin 17 * memory for an array. It returns the allocated memory or null on failure. 18 * 19 * This function will be called reentrantly. This means that if you call a 20 * function PPB_Foo.GetData(&array_output), GetData will call your 21 * GetDataBuffer function before it returns. 22 * 23 * This function will be called even when returning 0-length arrays, so be sure 24 * your implementation can support that. You can return NULL for 0 length 25 * arrays and it will not be treated as a failure. 26 * 27 * You should not perform any processing in this callback, including calling 28 * other PPAPI functions, outside of allocating memory. You should not throw 29 * any exceptions. In C++, this means using "new (nothrow)" or being sure to 30 * catch any exceptions before returning. 31 * 32 * The C++ wrapper provides a convenient templatized implementation around 33 * std::vector which you should generally use instead of coding this 34 * specifically. 35 * 36 * @param user_data The pointer provided in the PP_ArrayOutput structure. This 37 * has no meaning to the browser, it is intended to be used by the 38 * implementation to figure out where to put the data. 39 * 40 * @param element_count The number of elements in the array. This will be 0 41 * if there is no data to return. 42 * 43 * @param element_size The size of each element in bytes. 44 * 45 * @return Returns a pointer to the allocated memory. On failure, returns null. 46 * You can also return null if the element_count is 0. When a non-null value is 47 * returned, the buffer must remain valid until after the callback runs. If used 48 * with a blocking callback, the buffer must remain valid until after the 49 * function returns. The plugin can then free any memory that it allocated. 50 */ 51 52 53 /** 54 * @addtogroup Typedefs 55 * @{ 56 */ 57 typedef void* (*PP_ArrayOutput_GetDataBuffer)(void* user_data, 58 uint32_t element_count, 59 uint32_t element_size); 60 /** 61 * @} 62 */ 63 64 /** 65 * @addtogroup Structs 66 * @{ 67 */ 68 /** 69 * A structure that defines a way for the browser to return arrays of data 70 * to the plugin. The browser can not allocate memory on behalf of the plugin 71 * because the plugin and browser may have different allocators. 72 * 73 * Array output works by having the browser call to the plugin to allocate a 74 * buffer, and then the browser will copy the contents of the array into that 75 * buffer. 76 * 77 * In C, you would typically implement this as follows: 78 * 79 * @code 80 * struct MyArrayOutput { 81 * void* data; 82 * int element_count; 83 * }; 84 * void* MyGetDataBuffer(void* user_data, uint32_t count, uint32_t size) { 85 * MyArrayOutput* output = (MyArrayOutput*)user_data; 86 * output->element_count = count; 87 * if (size) { 88 * output->data = malloc(count * size); 89 * if (!output->data) // Be careful to set size properly on malloc failure. 90 * output->element_count = 0; 91 * } else { 92 * output->data = NULL; 93 * } 94 * return output->data; 95 * } 96 * void MyFunction() { 97 * MyArrayOutput array = { NULL, 0 }; 98 * PP_ArrayOutput output = { &MyGetDataBuffer, &array }; 99 * ppb_foo->GetData(&output); 100 * } 101 * @endcode 102 */ 103 struct PP_ArrayOutput { 104 /** 105 * A pointer to the allocation function that the browser will call. 106 */ 107 PP_ArrayOutput_GetDataBuffer GetDataBuffer; 108 /** 109 * Data that is passed to the allocation function. Typically, this is used 110 * to communicate how the data should be stored. 111 */ 112 void* user_data; 113 }; 114 /** 115 * @} 116 */ 117 118 #endif /* PPAPI_C_PP_ARRAY_OUTPUT_H_ */ 119 120
