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
14struct 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
30struct 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
255