src/ppapi/api/pp_array_output.idl

   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 };