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.
  38  */
  39 typedef mem_t PP_ArrayOutput_GetDataBuffer([inout] mem_t user_data,
  40                                            [in] uint32_t element_count,
  41                                            [in] uint32_t element_size);
  42
  43 /**
  44  * A structure that defines a way for the browser to return arrays of data
  45  * to the plugin. The browser can not allocate memory on behalf of the plugin
  46  * becaues the plugin and browser may have different allocators.
  47  *
  48  * Array output works by having the browser call to the plugin to allocate a
  49  * buffer, and then the browser will copy the contents of the array into that
  50  * buffer.
  51  *
  52  * In C, you would typically implement this as follows:
  53  *
  54  * @code
  55  * struct MyArrayOutput {
  56  *   void* data;
  57  *   int element_count;
  58  * };
  59  * void* MyGetDataBuffer(void* user_data, uint32_t count, uint32_t size) {
  60  *   MyArrayOutput* output = (MyArrayOutput*)user_data;
  61  *   output->element_count = count;
  62  *   if (size) {
  63  *     output->data = malloc(count * size);
  64  *     if (!output->data)  // Be careful to set size properly on malloc failure.
  65  *       output->element_count = 0;
  66  *   } else {
  67  *     output->data = NULL;
  68  *   }
  69  *   return output->data;
  70  * }
  71  * void MyFunction() {
  72  *   MyArrayOutput array = { NULL, 0 };
  73  *   PP_ArrayOutput output = { &MyGetDataBuffer, &array };
  74  *   ppb_foo->GetData(&output);
  75  * }
  76  * @endcode
  77  */
  78 [passByValue]
  79 struct PP_ArrayOutput {
  80   /**
  81    * A pointer to the allocation function that the browser implements.
  82    */
  83   PP_ArrayOutput_GetDataBuffer GetDataBuffer;
  84
  85   /**
  86    * Data that is passed to the allocation function. Typically, this is used
  87    * to communicate how the data should be stored.
  88    */
  89   mem_t user_data;
  90 };