Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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 | |
Torne (Richard Coles) | 1e9bf3e | 2013-10-31 11:16:26 +0000 | [diff] [blame] | 6 | /* From pp_array_output.idl modified Tue Oct 22 15:09:25 2013. */ |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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. |
Torne (Richard Coles) | 1e9bf3e | 2013-10-31 11:16:26 +0000 | [diff] [blame] | 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. |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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 |
Torne (Richard Coles) | c2e0dbd | 2013-05-09 18:35:53 +0100 | [diff] [blame] | 71 | * because the plugin and browser may have different allocators. |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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 | /** |
Torne (Richard Coles) | 1e9bf3e | 2013-10-31 11:16:26 +0000 | [diff] [blame] | 105 | * A pointer to the allocation function that the browser will call. |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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 | |