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 Wed Dec 14 18:08:00 2011. */
   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_stdint.h"
  15 #include "ppapi/c/pp_var.h"
  16
  17 #define PPB_VAR_INTERFACE_1_0 "PPB_Var;1.0"
  18 #define PPB_VAR_INTERFACE_1_1 "PPB_Var;1.1"
  19 #define PPB_VAR_INTERFACE PPB_VAR_INTERFACE_1_1
  20
  21 /**
  22  * @file
  23  * This file defines the <code>PPB_Var</code> struct.
  24  */
  25
  26
  27 /**
  28  * @addtogroup Interfaces
  29  * @{
  30  */
  31 /**
  32  * PPB_Var API
  33  */
  34 struct PPB_Var_1_1 {
  35   /**
  36    * AddRef() adds a reference to the given var. If this is not a refcounted
  37    * object, this function will do nothing so you can always call it no matter
  38    * what the type.
  39    *
  40    * @param[in] var A <code>PP_Var</code> that will have a reference added.
  41    */
  42   void (*AddRef)(struct PP_Var var);
  43   /**
  44    * Release() removes a reference to given var, deleting it if the internal
  45    * reference count becomes 0. If the given var is not a refcounted object,
  46    * this function will do nothing so you can always call it no matter what
  47    * the type.
  48    *
  49    * @param[in] var A <code>PP_Var</code> that will have a reference removed.
  50    */
  51   void (*Release)(struct PP_Var var);
  52   /**
  53    * VarFromUtf8() creates a string var from a string. The string must be
  54    * encoded in valid UTF-8 and is NOT NULL-terminated, the length must be
  55    * specified in <code>len</code>. It is an error if the string is not
  56    * valid UTF-8.
  57    *
  58    * If the length is 0, the <code>*data</code> pointer will not be dereferenced
  59    * and may be <code>NULL</code>. Note, however if length is 0, the
  60    * "NULL-ness" will not be preserved, as <code>VarToUtf8</code> will never
  61    * return <code>NULL</code> on success, even for empty strings.
  62    *
  63    * The resulting object will be a refcounted string object. It will be
  64    * AddRef'ed for the caller. When the caller is done with it, it should be
  65    * Released.
  66    *
  67    * On error (basically out of memory to allocate the string, or input that
  68    * is not valid UTF-8), this function will return a Null var.
  69    *
  70    * @param[in] data A string
  71    * @param[in] len The length of the string.
  72    *
  73    * @return A <code>PP_Var</code> structure containing a reference counted
  74    * string object.
  75    */
  76   struct PP_Var (*VarFromUtf8)(const char* data, uint32_t len);
  77   /**
  78    * VarToUtf8() converts a string-type var to a char* encoded in UTF-8. This
  79    * string is NOT NULL-terminated. The length will be placed in
  80    * <code>*len</code>. If the string is valid but empty the return value will
  81    * be non-NULL, but <code>*len</code> will still be 0.
  82    *
  83    * If the var is not a string, this function will return NULL and
  84    * <code>*len</code> will be 0.
  85    *
  86    * The returned buffer will be valid as long as the underlying var is alive.
  87    * If the instance frees its reference, the string will be freed and the
  88    * pointer will be to arbitrary memory.
  89    *
  90    * @param[in] var A PP_Var struct containing a string-type var.
  91    * @param[in,out] len A pointer to the length of the string-type var.
  92    *
  93    * @return A char* encoded in UTF-8.
  94    */
  95   const char* (*VarToUtf8)(struct PP_Var var, uint32_t* len);
  96 };
  97
  98 typedef struct PPB_Var_1_1 PPB_Var;
  99
 100 struct PPB_Var_1_0 {
 101   void (*AddRef)(struct PP_Var var);
 102   void (*Release)(struct PP_Var var);
 103   struct PP_Var (*VarFromUtf8)(PP_Module module,
 104                                const char* data,
 105                                uint32_t len);
 106   const char* (*VarToUtf8)(struct PP_Var var, uint32_t* len);
 107 };
 108 /**
 109  * @}
 110  */
 111
 112 #endif  /* PPAPI_C_PPB_VAR_H_ */
 113