ppapi/c/pp_array_output.h

   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