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