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 */
57typedef 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 */
103struct 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