Home | History | Annotate | Download | only in c 
      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 Thu Mar 28 11:07:53 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.
     47  */
     48 
     49 
     50 /**
     51  * @addtogroup Typedefs
     52  * @{
     53  */
     54 typedef void* (*PP_ArrayOutput_GetDataBuffer)(void* user_data,
     55                                               uint32_t element_count,
     56                                               uint32_t element_size);
     57 /**
     58  * @}
     59  */
     60 
     61 /**
     62  * @addtogroup Structs
     63  * @{
     64  */
     65 /**
     66  * A structure that defines a way for the browser to return arrays of data
     67  * to the plugin. The browser can not allocate memory on behalf of the plugin
     68  * because the plugin and browser may have different allocators.
     69  *
     70  * Array output works by having the browser call to the plugin to allocate a
     71  * buffer, and then the browser will copy the contents of the array into that
     72  * buffer.
     73  *
     74  * In C, you would typically implement this as follows:
     75  *
     76  * @code
     77  * struct MyArrayOutput {
     78  *   void* data;
     79  *   int element_count;
     80  * };
     81  * void* MyGetDataBuffer(void* user_data, uint32_t count, uint32_t size) {
     82  *   MyArrayOutput* output = (MyArrayOutput*)user_data;
     83  *   output->element_count = count;
     84  *   if (size) {
     85  *     output->data = malloc(count * size);
     86  *     if (!output->data)  // Be careful to set size properly on malloc failure.
     87  *       output->element_count = 0;
     88  *   } else {
     89  *     output->data = NULL;
     90  *   }
     91  *   return output->data;
     92  * }
     93  * void MyFunction() {
     94  *   MyArrayOutput array = { NULL, 0 };
     95  *   PP_ArrayOutput output = { &MyGetDataBuffer, &array };
     96  *   ppb_foo->GetData(&output);
     97  * }
     98  * @endcode
     99  */
    100 struct PP_ArrayOutput {
    101   /**
    102    * A pointer to the allocation function that the browser implements.
    103    */
    104   PP_ArrayOutput_GetDataBuffer GetDataBuffer;
    105   /**
    106    * Data that is passed to the allocation function. Typically, this is used
    107    * to communicate how the data should be stored.
    108    */
    109   void* user_data;
    110 };
    111 /**
    112  * @}
    113  */
    114 
    115 #endif  /* PPAPI_C_PP_ARRAY_OUTPUT_H_ */
    116 
    117