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 */
42typedef 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]
82struct 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