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