src/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 Apr 10 14:54:41 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 <code>PP_Var</code> is of type
  48    * <code>PP_VARTYPE_RESOURCE</code>,
  49    * it will implicitly release a reference count on the
  50    * <code>PP_Resource</code> (equivalent to PPB_Core::ReleaseResource()).
  51    *
  52    * If the given var is not a refcounted object, this function will do nothing
  53    * so you can always call it no matter what the type.
  54    *
  55    * @param[in] var A <code>PP_Var</code> that will have a reference removed.
  56    */
  57   void (*Release)(struct PP_Var var);
  58   /**
  59    * VarFromUtf8() creates a string var from a string. The string must be
  60    * encoded in valid UTF-8 and is NOT NULL-terminated, the length must be
  61    * specified in <code>len</code>. It is an error if the string is not
  62    * valid UTF-8.
  63    *
  64    * If the length is 0, the <code>*data</code> pointer will not be dereferenced
  65    * and may be <code>NULL</code>. Note, however if length is 0, the
  66    * "NULL-ness" will not be preserved, as VarToUtf8() will never return
  67    * <code>NULL</code> on success, even for empty strings.
  68    *
  69    * The resulting object will be a refcounted string object. It will be
  70    * AddRef'ed for the caller. When the caller is done with it, it should be
  71    * Released.
  72    *
  73    * On error (basically out of memory to allocate the string, or input that
  74    * is not valid UTF-8), this function will return a Null var.
  75    *
  76    * @param[in] data A string
  77    * @param[in] len The length of the string.
  78    *
  79    * @return A <code>PP_Var</code> structure containing a reference counted
  80    * string object.
  81    */
  82   struct PP_Var (*VarFromUtf8)(const char* data, uint32_t len);
  83   /**
  84    * VarToUtf8() converts a string-type var to a char* encoded in UTF-8. This
  85    * string is NOT NULL-terminated. The length will be placed in
  86    * <code>*len</code>. If the string is valid but empty the return value will
  87    * be non-NULL, but <code>*len</code> will still be 0.
  88    *
  89    * If the var is not a string, this function will return NULL and
  90    * <code>*len</code> will be 0.
  91    *
  92    * The returned buffer will be valid as long as the underlying var is alive.
  93    * If the instance frees its reference, the string will be freed and the
  94    * pointer will be to arbitrary memory.
  95    *
  96    * @param[in] var A PP_Var struct containing a string-type var.
  97    * @param[in,out] len A pointer to the length of the string-type var.
  98    *
  99    * @return A char* encoded in UTF-8.
 100    */
 101   const char* (*VarToUtf8)(struct PP_Var var, uint32_t* len);
 102   /**
 103    * Converts a resource-type var to a <code>PP_Resource</code>.
 104    *
 105    * @param[in] var A <code>PP_Var</code> struct containing a resource-type var.
 106    *
 107    * @return A <code>PP_Resource</code> retrieved from the var, or 0 if the var
 108    * is not a resource. The reference count of the resource is incremented on
 109    * behalf of the caller.
 110    */
 111   PP_Resource (*VarToResource)(struct PP_Var var);
 112   /**
 113    * Creates a new <code>PP_Var</code> from a given resource. Implicitly adds a
 114    * reference count on the <code>PP_Resource</code> (equivalent to
 115    * PPB_Core::AddRefResource(resource)).
 116    *
 117    * @param[in] resource A <code>PP_Resource</code> to be wrapped in a var.
 118    *
 119    * @return A <code>PP_Var</code> created for this resource, with type
 120    * <code>PP_VARTYPE_RESOURCE</code>. The reference count of the var is set to
 121    * 1 on behalf of the caller.
 122    */
 123   struct PP_Var (*VarFromResource)(PP_Resource resource);
 124 };
 125
 126 typedef struct PPB_Var_1_2 PPB_Var;
 127
 128 struct PPB_Var_1_0 {
 129   void (*AddRef)(struct PP_Var var);
 130   void (*Release)(struct PP_Var var);
 131   struct PP_Var (*VarFromUtf8)(PP_Module module,
 132                                const char* data,
 133                                uint32_t len);
 134   const char* (*VarToUtf8)(struct PP_Var var, uint32_t* len);
 135 };
 136
 137 struct PPB_Var_1_1 {
 138   void (*AddRef)(struct PP_Var var);
 139   void (*Release)(struct PP_Var var);
 140   struct PP_Var (*VarFromUtf8)(const char* data, uint32_t len);
 141   const char* (*VarToUtf8)(struct PP_Var var, uint32_t* len);
 142 };
 143 /**
 144  * @}
 145  */
 146
 147 #endif  /* PPAPI_C_PPB_VAR_H_ */
 148