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