ppapi/c/ppb_var.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 ppb_var.idl modified Thu Feb  6 13:48:33 2014. */
   7
   8 #ifndef PPAPI_C_PPB_VAR_H_
   9 #define PPAPI_C_PPB_VAR_H_
  10
  11 #include "ppapi/c/pp_bool.h"
  12 #include "ppapi/c/pp_macros.h"
  13 #include "ppapi/c/pp_module.h"
  14 #include "ppapi/c/pp_resource.h"
  15 #include "ppapi/c/pp_stdint.h"
  16 #include "ppapi/c/pp_var.h"
  17
  18 #define PPB_VAR_INTERFACE_1_0 "PPB_Var;1.0"
  19 #define PPB_VAR_INTERFACE_1_1 "PPB_Var;1.1"
  20 #define PPB_VAR_INTERFACE_1_2 "PPB_Var;1.2"
  21 #define PPB_VAR_INTERFACE PPB_VAR_INTERFACE_1_2
  22
  23 /**
  24  * @file
  25  * This file defines the <code>PPB_Var</code> struct.
  26  */
  27
  28
  29 /**
  30  * @addtogroup Interfaces
  31  * @{
  32  */
  33 /**
  34  * PPB_Var API
  35  */
  36 struct PPB_Var_1_2 {
  37   /**
  38    * AddRef() adds a reference to the given var. If this is not a refcounted
  39    * object, this function will do nothing so you can always call it no matter
  40    * what the type.
  41    *
  42    * @param[in] var A <code>PP_Var</code> that will have a reference added.
  43    */
  44   void (*AddRef)(struct PP_Var var);
  45   /**
  46    * Release() removes a reference to given var, deleting it if the internal
  47    * reference count becomes 0. If the given var is not a refcounted object,
  48    * this function will do nothing so you can always call it no matter what
  49    * the type.
  50    *
  51    * @param[in] var A <code>PP_Var</code> that will have a reference removed.
  52    */
  53   void (*Release)(struct PP_Var var);
  54   /**
  55    * VarFromUtf8() creates a string var from a string. The string must be
  56    * encoded in valid UTF-8 and is NOT NULL-terminated, the length must be
  57    * specified in <code>len</code>. It is an error if the string is not
  58    * valid UTF-8.
  59    *
  60    * If the length is 0, the <code>*data</code> pointer will not be dereferenced
  61    * and may be <code>NULL</code>. Note, however if length is 0, the
  62    * "NULL-ness" will not be preserved, as <code>VarToUtf8</code> will never
  63    * return <code>NULL</code> on success, even for empty strings.
  64    *
  65    * The resulting object will be a refcounted string object. It will be
  66    * AddRef'ed for the caller. When the caller is done with it, it should be
  67    * Released.
  68    *
  69    * On error (basically out of memory to allocate the string, or input that
  70    * is not valid UTF-8), this function will return a Null var.
  71    *
  72    * @param[in] data A string
  73    * @param[in] len The length of the string.
  74    *
  75    * @return A <code>PP_Var</code> structure containing a reference counted
  76    * string object.
  77    */
  78   struct PP_Var (*VarFromUtf8)(const char* data, uint32_t len);
  79   /**
  80    * VarToUtf8() converts a string-type var to a char* encoded in UTF-8. This
  81    * string is NOT NULL-terminated. The length will be placed in
  82    * <code>*len</code>. If the string is valid but empty the return value will
  83    * be non-NULL, but <code>*len</code> will still be 0.
  84    *
  85    * If the var is not a string, this function will return NULL and
  86    * <code>*len</code> will be 0.
  87    *
  88    * The returned buffer will be valid as long as the underlying var is alive.
  89    * If the instance frees its reference, the string will be freed and the
  90    * pointer will be to arbitrary memory.
  91    *
  92    * @param[in] var A PP_Var struct containing a string-type var.
  93    * @param[in,out] len A pointer to the length of the string-type var.
  94    *
  95    * @return A char* encoded in UTF-8.
  96    */
  97   const char* (*VarToUtf8)(struct PP_Var var, uint32_t* len);
  98   /**
  99    * Converts a resource-type var to a <code>PP_Resource</code>.
 100    *
 101    * @param[in] var A <code>PP_Var</code> struct containing a resource-type var.
 102    *
 103    * @return A <code>PP_Resource</code> retrieved from the var, or 0 if the var
 104    * is not a resource. The reference count of the resource is incremented on
 105    * behalf of the caller.
 106    */
 107   PP_Resource (*VarToResource)(struct PP_Var var);
 108   /**
 109    * Creates a new <code>PP_Var</code> from a given resource.
 110    *
 111    * @param[in] resource A <code>PP_Resource</code> to be wrapped in a var.
 112    *
 113    * @return A <code>PP_Var</code> created for this resource, with type
 114    * <code>PP_VARTYPE_RESOURCE</code>. The reference count of the var is set to
 115    * 1 on behalf of the caller.
 116    */
 117   struct PP_Var (*VarFromResource)(PP_Resource resource);
 118 };
 119
 120 typedef struct PPB_Var_1_2 PPB_Var;
 121
 122 struct PPB_Var_1_0 {
 123   void (*AddRef)(struct PP_Var var);
 124   void (*Release)(struct PP_Var var);
 125   struct PP_Var (*VarFromUtf8)(PP_Module module,
 126                                const char* data,
 127                                uint32_t len);
 128   const char* (*VarToUtf8)(struct PP_Var var, uint32_t* len);
 129 };
 130
 131 struct PPB_Var_1_1 {
 132   void (*AddRef)(struct PP_Var var);
 133   void (*Release)(struct PP_Var var);
 134   struct PP_Var (*VarFromUtf8)(const char* data, uint32_t len);
 135   const char* (*VarToUtf8)(struct PP_Var var, uint32_t* len);
 136 };
 137 /**
 138  * @}
 139  */
 140
 141 #endif  /* PPAPI_C_PPB_VAR_H_ */
 142