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