ppapi/c/dev/ppb_var_deprecated.h

   1 /* Copyright (c) 2010 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 #ifndef PPAPI_C_PPB_VAR_DEPRECATED_H_
   6 #define PPAPI_C_PPB_VAR_DEPRECATED_H_
   7
   8 #include "ppapi/c/dev/deprecated_bool.h"
   9 #include "ppapi/c/pp_instance.h"
  10 #include "ppapi/c/pp_module.h"
  11 #include "ppapi/c/pp_stdint.h"
  12 #include "ppapi/c/pp_var.h"
  13
  14 struct PPP_Class_Deprecated;
  15
  16 #define PPB_VAR_DEPRECATED_INTERFACE_0_3 "PPB_Var(Deprecated);0.3"
  17 #define PPB_VAR_DEPRECATED_INTERFACE PPB_VAR_DEPRECATED_INTERFACE_0_3
  18
  19 /**
  20  * @file
  21  * Defines the PPB_Var_Deprecated struct.
  22  * See http://code.google.com/p/ppapi/wiki/InterfacingWithJavaScript
  23  * for general information on using this interface.
  24  * {PENDING: Should the generated doc really be pointing to methods?}
  25  *
  26  * @addtogroup PPB
  27  * @{
  28  */
  29
  30 struct PPB_Var_Deprecated {
  31   /**
  32    * Adds a reference to the given var. If this is not a refcounted object,
  33    * this function will do nothing so you can always call it no matter what the
  34    * type.
  35    */
  36   void (*AddRef)(struct PP_Var var);
  37
  38   /**
  39    * Removes a reference to given var, deleting it if the internal refcount
  40    * becomes 0. If the given var is not a refcounted object, this function will
  41    * do nothing so you can always call it no matter what the type.
  42    */
  43   void (*Release)(struct PP_Var var);
  44
  45   /**
  46    * Creates a string var from a string. The string must be encoded in valid
  47    * UTF-8 and is NOT NULL-terminated, the length must be specified in |len|.
  48    * It is an error if the string is not valid UTF-8.
  49    *
  50    * If the length is 0, the |data| pointer will not be dereferenced and may
  51    * be NULL. Note, however, that if you do this, the "NULL-ness" will not be
  52    * preserved, as VarToUtf8 will never return NULL on success, even for empty
  53    * strings.
  54    *
  55    * The resulting object will be a refcounted string object. It will be
  56    * AddRef()ed for the caller. When the caller is done with it, it should be
  57    * Release()d.
  58    *
  59    * On error (basically out of memory to allocate the string, or input that
  60    * is not valid UTF-8), this function will return a Null var.
  61    */
  62   struct PP_Var (*VarFromUtf8)(PP_Module module,
  63                                const char* data, uint32_t len);
  64
  65   /**
  66    * Converts a string-type var to a char* encoded in UTF-8. This string is NOT
  67    * NULL-terminated. The length will be placed in |*len|. If the string is
  68    * valid but empty the return value will be non-NULL, but |*len| will still
  69    * be 0.
  70    *
  71    * If the var is not a string, this function will return NULL and |*len| will
  72    * be 0.
  73    *
  74    * The returned buffer will be valid as long as the underlying var is alive.
  75    * If the plugin frees its reference, the string will be freed and the pointer
  76    * will be to random memory.
  77    */
  78   const char* (*VarToUtf8)(struct PP_Var var, uint32_t* len);
  79
  80   /**
  81    * Returns true if the property with the given name exists on the given
  82    * object, false if it does not. Methods are also counted as properties.
  83    *
  84    * The name can either be a string or an integer var. It is an error to pass
  85    * another type of var as the name.
  86    *
  87    * If you pass an invalid name or object, the exception will be set (if it is
  88    * non-NULL, and the return value will be false).
  89    */
  90   bool (*HasProperty)(struct PP_Var object,
  91                       struct PP_Var name,
  92                       struct PP_Var* exception);
  93
  94   /**
  95    * Identical to HasProperty, except that HasMethod additionally checks if the
  96    * property is a function.
  97    */
  98   bool (*HasMethod)(struct PP_Var object,
  99                     struct PP_Var name,
 100                     struct PP_Var* exception);
 101
 102   /**
 103    * Returns the value of the given property. If the property doesn't exist, the
 104    * exception (if non-NULL) will be set and a "Void" var will be returned.
 105    */
 106   struct PP_Var (*GetProperty)(struct PP_Var object,
 107                                struct PP_Var name,
 108                                struct PP_Var* exception);
 109
 110   /**
 111    * Retrieves all property names on the given object. Property names include
 112    * methods.
 113    *
 114    * If there is a failure, the given exception will be set (if it is non-NULL).
 115    * On failure, |*properties| will be set to NULL and |*property_count| will be
 116    * set to 0.
 117    *
 118    * A pointer to the array of property names will be placesd in |*properties|.
 119    * The caller is responsible for calling Release() on each of these properties
 120    * (as per normal refcounted memory management) as well as freeing the array
 121    * pointer with PPB_Core.MemFree().
 122    *
 123    * This function returns all "enumerable" properties. Some JavaScript
 124    * properties are "hidden" and these properties won't be retrieved by this
 125    * function, yet you can still set and get them.
 126    *
 127    * Example:
 128    * <pre>  uint32_t count;
 129    *   PP_Var* properties;
 130    *   ppb_var.GetAllPropertyNames(object, &count, &properties);
 131    *
 132    *   ...use the properties here...
 133    *
 134    *   for (uint32_t i = 0; i < count; i++)
 135    *     ppb_var.Release(properties[i]);
 136    *   ppb_core.MemFree(properties); </pre>
 137    */
 138   void (*GetAllPropertyNames)(struct PP_Var object,
 139                               uint32_t* property_count,
 140                               struct PP_Var** properties,
 141                               struct PP_Var* exception);
 142
 143   /**
 144    * Sets the property with the given name on the given object. The exception
 145    * will be set, if it is non-NULL, on failure.
 146    */
 147   void (*SetProperty)(struct PP_Var object,
 148                       struct PP_Var name,
 149                       struct PP_Var value,
 150                       struct PP_Var* exception);
 151
 152   /**
 153    * Removes the given property from the given object. The property name must
 154    * be an string or integer var, using other types will throw an exception
 155    * (assuming the exception pointer is non-NULL).
 156    */
 157   void (*RemoveProperty)(struct PP_Var object,
 158                          struct PP_Var name,
 159                          struct PP_Var* exception);
 160
 161   // TODO(brettw) need native array access here.
 162
 163   /**
 164    * Invoke the function |method_name| on the given object. If |method_name|
 165    * is a Null var, the default method will be invoked, which is how you can
 166    * invoke function objects.
 167    *
 168    * Unless it is type Null, |method_name| must be a string. Unlike other
 169    * Var functions, integer lookup is not supported since you can't call
 170    * functions on integers in JavaScript.
 171    *
 172    * Pass the arguments to the function in order in the |argv| array, and the
 173    * number of arguments in the |argc| parameter. |argv| can be NULL if |argc|
 174    * is zero.
 175    *
 176    * Example:
 177    *   Call(obj, VarFromUtf8("DoIt"), 0, NULL, NULL) = obj.DoIt() in JavaScript.
 178    *   Call(obj, PP_MakeNull(), 0, NULL, NULL) = obj() in JavaScript.
 179    */
 180   struct PP_Var (*Call)(struct PP_Var object,
 181                         struct PP_Var method_name,
 182                         uint32_t argc,
 183                         struct PP_Var* argv,
 184                         struct PP_Var* exception);
 185
 186   /**
 187    * Invoke the object as a constructor.
 188    *
 189    * For example, if |object| is |String|, this is like saying |new String| in
 190    * JavaScript.
 191    */
 192   struct PP_Var (*Construct)(struct PP_Var object,
 193                              uint32_t argc,
 194                              struct PP_Var* argv,
 195                              struct PP_Var* exception);
 196
 197   /**
 198    * If the object is an instance of the given class, then this method returns
 199    * true and sets *object_data to the value passed to CreateObject provided
 200    * object_data is non-NULL. Otherwise, this method returns false.
 201    */
 202   bool (*IsInstanceOf)(struct PP_Var var,
 203                        const struct PPP_Class_Deprecated* object_class,
 204                        void** object_data);
 205
 206   /**
 207    * Creates an object that the plugin implements. The plugin supplies a
 208    * pointer to the class interface it implements for that object, and its
 209    * associated internal data that represents that object. This object data
 210    * must be unique among all "live" objects.
 211    *
 212    * The returned object will have a reference count of 1. When the reference
 213    * count reached 0, the class' Destruct function wlil be called.
 214    *
 215    * On failure, this will return a null var. This probably means the module
 216    * was invalid.
 217    *
 218    * Example: Say we're implementing a "Point" object.
 219    * <pre>  void PointDestruct(void* object) {
 220    *     delete (Point*)object;
 221    *   }
 222    *
 223    *   const PPP_Class_Deprecated point_class = {
 224    *     ... all the other class functions go here ...
 225    *     &PointDestruct
 226    *   };
 227    *
 228    *    * The plugin's internal object associated with the point.
 229    *   class Point {
 230    *     ...
 231    *   };
 232    *
 233    *   PP_Var MakePoint(int x, int y) {
 234    *     return CreateObject(&point_class, new Point(x, y));
 235    *   }</pre>
 236    */
 237   struct PP_Var (*CreateObject)(PP_Instance instance,
 238                                 const struct PPP_Class_Deprecated* object_class,
 239                                 void* object_data);
 240
 241   // Like CreateObject but takes a module. This will be deleted when all callers
 242   // can be changed to use the PP_Instance CreateObject one.
 243   struct PP_Var (*CreateObjectWithModuleDeprecated)(
 244       PP_Module module,
 245       const struct PPP_Class_Deprecated* object_class,
 246       void* object_data);
 247 };
 248
 249 /**
 250  * @}
 251  * End addtogroup PPB
 252  */
 253 #endif  /* PPAPI_C_PPB_VAR_DEPRECATED_H_ */
 254