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 255
