JSObjectRef.h
1 /* 2 * Copyright (C) 2006-2019 Apple Inc. All rights reserved. 3 * Copyright (C) 2008 Kelvin W Sherlock (ksherlock@gmail.com) 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions 7 * are met: 8 * 1. Redistributions of source code must retain the above copyright 9 * notice, this list of conditions and the following disclaimer. 10 * 2. Redistributions in binary form must reproduce the above copyright 11 * notice, this list of conditions and the following disclaimer in the 12 * documentation and/or other materials provided with the distribution. 13 * 14 * THIS SOFTWARE IS PROVIDED BY APPLE INC. ``AS IS'' AND ANY 15 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 17 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR 18 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 19 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 20 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 21 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY 22 * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 23 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 24 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25 */ 26 27 #ifndef JSObjectRef_h 28 #define JSObjectRef_h 29 30 #include <JavaScriptCore/JSBase.h> 31 #include <JavaScriptCore/JSValueRef.h> 32 #include <JavaScriptCore/WebKitAvailability.h> 33 34 #ifndef __cplusplus 35 #include <stdbool.h> 36 #endif 37 #include <stddef.h> /* for size_t */ 38 39 #ifdef __cplusplus 40 extern "C" { 41 #endif 42 43 /*! 44 @enum JSPropertyAttribute 45 @constant kJSPropertyAttributeNone Specifies that a property has no special attributes. 46 @constant kJSPropertyAttributeReadOnly Specifies that a property is read-only. 47 @constant kJSPropertyAttributeDontEnum Specifies that a property should not be enumerated by JSPropertyEnumerators and JavaScript for...in loops. 48 @constant kJSPropertyAttributeDontDelete Specifies that the delete operation should fail on a property. 49 */ 50 enum { 51 kJSPropertyAttributeNone = 0, 52 kJSPropertyAttributeReadOnly = 1 << 1, 53 kJSPropertyAttributeDontEnum = 1 << 2, 54 kJSPropertyAttributeDontDelete = 1 << 3 55 }; 56 57 /*! 58 @typedef JSPropertyAttributes 59 @abstract A set of JSPropertyAttributes. Combine multiple attributes by logically ORing them together. 60 */ 61 typedef unsigned JSPropertyAttributes; 62 63 /*! 64 @enum JSClassAttribute 65 @constant kJSClassAttributeNone Specifies that a class has no special attributes. 66 @constant kJSClassAttributeNoAutomaticPrototype Specifies that a class should not automatically generate a shared prototype for its instance objects. Use kJSClassAttributeNoAutomaticPrototype in combination with JSObjectSetPrototype to manage prototypes manually. 67 */ 68 enum { 69 kJSClassAttributeNone = 0, 70 kJSClassAttributeNoAutomaticPrototype = 1 << 1 71 }; 72 73 /*! 74 @typedef JSClassAttributes 75 @abstract A set of JSClassAttributes. Combine multiple attributes by logically ORing them together. 76 */ 77 typedef unsigned JSClassAttributes; 78 79 /*! 80 @typedef JSObjectInitializeCallback 81 @abstract The callback invoked when an object is first created. 82 @param ctx The execution context to use. 83 @param object The JSObject being created. 84 @discussion If you named your function Initialize, you would declare it like this: 85 86 void Initialize(JSContextRef ctx, JSObjectRef object); 87 88 Unlike the other object callbacks, the initialize callback is called on the least 89 derived class (the parent class) first, and the most derived class last. 90 */ 91 typedef void 92 (*JSObjectInitializeCallback) (JSContextRef ctx, JSObjectRef object); 93 94 /*! 95 @typedef JSObjectFinalizeCallback 96 @abstract The callback invoked when an object is finalized (prepared for garbage collection). An object may be finalized on any thread. 97 @param object The JSObject being finalized. 98 @discussion If you named your function Finalize, you would declare it like this: 99 100 void Finalize(JSObjectRef object); 101 102 The finalize callback is called on the most derived class first, and the least 103 derived class (the parent class) last. 104 105 You must not call any function that may cause a garbage collection or an allocation 106 of a garbage collected object from within a JSObjectFinalizeCallback. This includes 107 all functions that have a JSContextRef parameter. 108 */ 109 typedef void 110 (*JSObjectFinalizeCallback) (JSObjectRef object); 111 112 /*! 113 @typedef JSObjectHasPropertyCallback 114 @abstract The callback invoked when determining whether an object has a property. 115 @param ctx The execution context to use. 116 @param object The JSObject to search for the property. 117 @param propertyName A JSString containing the name of the property look up. 118 @result true if object has the property, otherwise false. 119 @discussion If you named your function HasProperty, you would declare it like this: 120 121 bool HasProperty(JSContextRef ctx, JSObjectRef object, JSStringRef propertyName); 122 123 If this function returns false, the hasProperty request forwards to object's statically declared properties, then its parent class chain (which includes the default object class), then its prototype chain. 124 125 This callback enables optimization in cases where only a property's existence needs to be known, not its value, and computing its value would be expensive. 126 127 If this callback is NULL, the getProperty callback will be used to service hasProperty requests. 128 */ 129 typedef bool 130 (*JSObjectHasPropertyCallback) (JSContextRef ctx, JSObjectRef object, JSStringRef propertyName); 131 132 /*! 133 @typedef JSObjectGetPropertyCallback 134 @abstract The callback invoked when getting a property's value. 135 @param ctx The execution context to use. 136 @param object The JSObject to search for the property. 137 @param propertyName A JSString containing the name of the property to get. 138 @param exception A pointer to a JSValueRef in which to return an exception, if any. 139 @result The property's value if object has the property, otherwise NULL. 140 @discussion If you named your function GetProperty, you would declare it like this: 141 142 JSValueRef GetProperty(JSContextRef ctx, JSObjectRef object, JSStringRef propertyName, JSValueRef* exception); 143 144 If this function returns NULL, the get request forwards to object's statically declared properties, then its parent class chain (which includes the default object class), then its prototype chain. 145 */ 146 typedef JSValueRef 147 (*JSObjectGetPropertyCallback) (JSContextRef ctx, JSObjectRef object, JSStringRef propertyName, JSValueRef* exception); 148 149 /*! 150 @typedef JSObjectSetPropertyCallback 151 @abstract The callback invoked when setting a property's value. 152 @param ctx The execution context to use. 153 @param object The JSObject on which to set the property's value. 154 @param propertyName A JSString containing the name of the property to set. 155 @param value A JSValue to use as the property's value. 156 @param exception A pointer to a JSValueRef in which to return an exception, if any. 157 @result true if the property was set, otherwise false. 158 @discussion If you named your function SetProperty, you would declare it like this: 159 160 bool SetProperty(JSContextRef ctx, JSObjectRef object, JSStringRef propertyName, JSValueRef value, JSValueRef* exception); 161 162 If this function returns false, the set request forwards to object's statically declared properties, then its parent class chain (which includes the default object class). 163 */ 164 typedef bool 165 (*JSObjectSetPropertyCallback) (JSContextRef ctx, JSObjectRef object, JSStringRef propertyName, JSValueRef value, JSValueRef* exception); 166 167 /*! 168 @typedef JSObjectDeletePropertyCallback 169 @abstract The callback invoked when deleting a property. 170 @param ctx The execution context to use. 171 @param object The JSObject in which to delete the property. 172 @param propertyName A JSString containing the name of the property to delete. 173 @param exception A pointer to a JSValueRef in which to return an exception, if any. 174 @result true if propertyName was successfully deleted, otherwise false. 175 @discussion If you named your function DeleteProperty, you would declare it like this: 176 177 bool DeleteProperty(JSContextRef ctx, JSObjectRef object, JSStringRef propertyName, JSValueRef* exception); 178 179 If this function returns false, the delete request forwards to object's statically declared properties, then its parent class chain (which includes the default object class). 180 */ 181 typedef bool 182 (*JSObjectDeletePropertyCallback) (JSContextRef ctx, JSObjectRef object, JSStringRef propertyName, JSValueRef* exception); 183 184 /*! 185 @typedef JSObjectGetPropertyNamesCallback 186 @abstract The callback invoked when collecting the names of an object's properties. 187 @param ctx The execution context to use. 188 @param object The JSObject whose property names are being collected. 189 @param propertyNames A JavaScript property name accumulator in which to accumulate the names of object's properties. 190 @discussion If you named your function GetPropertyNames, you would declare it like this: 191 192 void GetPropertyNames(JSContextRef ctx, JSObjectRef object, JSPropertyNameAccumulatorRef propertyNames); 193 194 Property name accumulators are used by JSObjectCopyPropertyNames and JavaScript for...in loops. 195 196 Use JSPropertyNameAccumulatorAddName to add property names to accumulator. A class's getPropertyNames callback only needs to provide the names of properties that the class vends through a custom getProperty or setProperty callback. Other properties, including statically declared properties, properties vended by other classes, and properties belonging to object's prototype, are added independently. 197 */ 198 typedef void 199 (*JSObjectGetPropertyNamesCallback) (JSContextRef ctx, JSObjectRef object, JSPropertyNameAccumulatorRef propertyNames); 200 201 /*! 202 @typedef JSObjectCallAsFunctionCallback 203 @abstract The callback invoked when an object is called as a function. 204 @param ctx The execution context to use. 205 @param function A JSObject that is the function being called. 206 @param thisObject A JSObject that is the 'this' variable in the function's scope. 207 @param argumentCount An integer count of the number of arguments in arguments. 208 @param arguments A JSValue array of the arguments passed to the function. 209 @param exception A pointer to a JSValueRef in which to return an exception, if any. 210 @result A JSValue that is the function's return value. 211 @discussion If you named your function CallAsFunction, you would declare it like this: 212 213 JSValueRef CallAsFunction(JSContextRef ctx, JSObjectRef function, JSObjectRef thisObject, size_t argumentCount, const JSValueRef arguments[], JSValueRef* exception); 214 215 If your callback were invoked by the JavaScript expression 'myObject.myFunction()', function would be set to myFunction, and thisObject would be set to myObject. 216 217 If this callback is NULL, calling your object as a function will throw an exception. 218 */ 219 typedef JSValueRef 220 (*JSObjectCallAsFunctionCallback) (JSContextRef ctx, JSObjectRef function, JSObjectRef thisObject, size_t argumentCount, const JSValueRef arguments[], JSValueRef* exception); 221 222 /*! 223 @typedef JSObjectCallAsConstructorCallback 224 @abstract The callback invoked when an object is used as a constructor in a 'new' expression. 225 @param ctx The execution context to use. 226 @param constructor A JSObject that is the constructor being called. 227 @param argumentCount An integer count of the number of arguments in arguments. 228 @param arguments A JSValue array of the arguments passed to the function. 229 @param exception A pointer to a JSValueRef in which to return an exception, if any. 230 @result A JSObject that is the constructor's return value. 231 @discussion If you named your function CallAsConstructor, you would declare it like this: 232 233 JSObjectRef CallAsConstructor(JSContextRef ctx, JSObjectRef constructor, size_t argumentCount, const JSValueRef arguments[], JSValueRef* exception); 234 235 If your callback were invoked by the JavaScript expression 'new myConstructor()', constructor would be set to myConstructor. 236 237 If this callback is NULL, using your object as a constructor in a 'new' expression will throw an exception. 238 */ 239 typedef JSObjectRef 240 (*JSObjectCallAsConstructorCallback) (JSContextRef ctx, JSObjectRef constructor, size_t argumentCount, const JSValueRef arguments[], JSValueRef* exception); 241 242 /*! 243 @typedef JSObjectHasInstanceCallback 244 @abstract hasInstance The callback invoked when an object is used as the target of an 'instanceof' expression. 245 @param ctx The execution context to use. 246 @param constructor The JSObject that is the target of the 'instanceof' expression. 247 @param possibleInstance The JSValue being tested to determine if it is an instance of constructor. 248 @param exception A pointer to a JSValueRef in which to return an exception, if any. 249 @result true if possibleInstance is an instance of constructor, otherwise false. 250 @discussion If you named your function HasInstance, you would declare it like this: 251 252 bool HasInstance(JSContextRef ctx, JSObjectRef constructor, JSValueRef possibleInstance, JSValueRef* exception); 253 254 If your callback were invoked by the JavaScript expression 'someValue instanceof myObject', constructor would be set to myObject and possibleInstance would be set to someValue. 255 256 If this callback is NULL, 'instanceof' expressions that target your object will return false. 257 258 Standard JavaScript practice calls for objects that implement the callAsConstructor callback to implement the hasInstance callback as well. 259 */ 260 typedef bool 261 (*JSObjectHasInstanceCallback) (JSContextRef ctx, JSObjectRef constructor, JSValueRef possibleInstance, JSValueRef* exception); 262 263 /*! 264 @typedef JSObjectConvertToTypeCallback 265 @abstract The callback invoked when converting an object to a particular JavaScript type. 266 @param ctx The execution context to use. 267 @param object The JSObject to convert. 268 @param type A JSType specifying the JavaScript type to convert to. 269 @param exception A pointer to a JSValueRef in which to return an exception, if any. 270 @result The objects's converted value, or NULL if the object was not converted. 271 @discussion If you named your function ConvertToType, you would declare it like this: 272 273 JSValueRef ConvertToType(JSContextRef ctx, JSObjectRef object, JSType type, JSValueRef* exception); 274 275 If this function returns false, the conversion request forwards to object's parent class chain (which includes the default object class). 276 277 This function is only invoked when converting an object to number or string. An object converted to boolean is 'true.' An object converted to object is itself. 278 */ 279 typedef JSValueRef 280 (*JSObjectConvertToTypeCallback) (JSContextRef ctx, JSObjectRef object, JSType type, JSValueRef* exception); 281 282 /*! 283 @struct JSStaticValue 284 @abstract This structure describes a statically declared value property. 285 @field name A null-terminated UTF8 string containing the property's name. 286 @field getProperty A JSObjectGetPropertyCallback to invoke when getting the property's value. 287 @field setProperty A JSObjectSetPropertyCallback to invoke when setting the property's value. May be NULL if the ReadOnly attribute is set. 288 @field attributes A logically ORed set of JSPropertyAttributes to give to the property. 289 */ 290 typedef struct { 291 const char* name; 292 JSObjectGetPropertyCallback getProperty; 293 JSObjectSetPropertyCallback setProperty; 294 JSPropertyAttributes attributes; 295 } JSStaticValue; 296 297 /*! 298 @struct JSStaticFunction 299 @abstract This structure describes a statically declared function property. 300 @field name A null-terminated UTF8 string containing the property's name. 301 @field callAsFunction A JSObjectCallAsFunctionCallback to invoke when the property is called as a function. 302 @field attributes A logically ORed set of JSPropertyAttributes to give to the property. 303 */ 304 typedef struct { 305 const char* name; 306 JSObjectCallAsFunctionCallback callAsFunction; 307 JSPropertyAttributes attributes; 308 } JSStaticFunction; 309 310 /*! 311 @struct JSClassDefinition 312 @abstract This structure contains properties and callbacks that define a type of object. All fields other than the version field are optional. Any pointer may be NULL. 313 @field version The version number of this structure. The current version is 0. 314 @field attributes A logically ORed set of JSClassAttributes to give to the class. 315 @field className A null-terminated UTF8 string containing the class's name. 316 @field parentClass A JSClass to set as the class's parent class. Pass NULL use the default object class. 317 @field staticValues A JSStaticValue array containing the class's statically declared value properties. Pass NULL to specify no statically declared value properties. The array must be terminated by a JSStaticValue whose name field is NULL. 318 @field staticFunctions A JSStaticFunction array containing the class's statically declared function properties. Pass NULL to specify no statically declared function properties. The array must be terminated by a JSStaticFunction whose name field is NULL. 319 @field initialize The callback invoked when an object is first created. Use this callback to initialize the object. 320 @field finalize The callback invoked when an object is finalized (prepared for garbage collection). Use this callback to release resources allocated for the object, and perform other cleanup. 321 @field hasProperty The callback invoked when determining whether an object has a property. If this field is NULL, getProperty is called instead. The hasProperty callback enables optimization in cases where only a property's existence needs to be known, not its value, and computing its value is expensive. 322 @field getProperty The callback invoked when getting a property's value. 323 @field setProperty The callback invoked when setting a property's value. 324 @field deleteProperty The callback invoked when deleting a property. 325 @field getPropertyNames The callback invoked when collecting the names of an object's properties. 326 @field callAsFunction The callback invoked when an object is called as a function. 327 @field hasInstance The callback invoked when an object is used as the target of an 'instanceof' expression. 328 @field callAsConstructor The callback invoked when an object is used as a constructor in a 'new' expression. 329 @field convertToType The callback invoked when converting an object to a particular JavaScript type. 330 @discussion The staticValues and staticFunctions arrays are the simplest and most efficient means for vending custom properties. Statically declared properties autmatically service requests like getProperty, setProperty, and getPropertyNames. Property access callbacks are required only to implement unusual properties, like array indexes, whose names are not known at compile-time. 331 332 If you named your getter function "GetX" and your setter function "SetX", you would declare a JSStaticValue array containing "X" like this: 333 334 JSStaticValue StaticValueArray[] = { 335 { "X", GetX, SetX, kJSPropertyAttributeNone }, 336 { 0, 0, 0, 0 } 337 }; 338 339 Standard JavaScript practice calls for storing function objects in prototypes, so they can be shared. The default JSClass created by JSClassCreate follows this idiom, instantiating objects with a shared, automatically generating prototype containing the class's function objects. The kJSClassAttributeNoAutomaticPrototype attribute specifies that a JSClass should not automatically generate such a prototype. The resulting JSClass instantiates objects with the default object prototype, and gives each instance object its own copy of the class's function objects. 340 341 A NULL callback specifies that the default object callback should substitute, except in the case of hasProperty, where it specifies that getProperty should substitute. 342 343 It is not possible to use JS subclassing with objects created from a class definition that sets callAsConstructor by default. Subclassing is supported via the JSObjectMakeConstructor function, however. 344 */ 345 typedef struct { 346 int version; /* current (and only) version is 0 */ 347 JSClassAttributes attributes; 348 349 const char* className; 350 JSClassRef parentClass; 351 352 const JSStaticValue* staticValues; 353 const JSStaticFunction* staticFunctions; 354 355 JSObjectInitializeCallback initialize; 356 JSObjectFinalizeCallback finalize; 357 JSObjectHasPropertyCallback hasProperty; 358 JSObjectGetPropertyCallback getProperty; 359 JSObjectSetPropertyCallback setProperty; 360 JSObjectDeletePropertyCallback deleteProperty; 361 JSObjectGetPropertyNamesCallback getPropertyNames; 362 JSObjectCallAsFunctionCallback callAsFunction; 363 JSObjectCallAsConstructorCallback callAsConstructor; 364 JSObjectHasInstanceCallback hasInstance; 365 JSObjectConvertToTypeCallback convertToType; 366 } JSClassDefinition; 367 368 /*! 369 @const kJSClassDefinitionEmpty 370 @abstract A JSClassDefinition structure of the current version, filled with NULL pointers and having no attributes. 371 @discussion Use this constant as a convenience when creating class definitions. For example, to create a class definition with only a finalize method: 372 373 JSClassDefinition definition = kJSClassDefinitionEmpty; 374 definition.finalize = Finalize; 375 */ 376 JS_EXPORT extern const JSClassDefinition kJSClassDefinitionEmpty; 377 378 /*! 379 @function 380 @abstract Creates a JavaScript class suitable for use with JSObjectMake. 381 @param definition A JSClassDefinition that defines the class. 382 @result A JSClass with the given definition. Ownership follows the Create Rule. 383 */ 384 JS_EXPORT JSClassRef JSClassCreate(const JSClassDefinition* definition); 385 386 /*! 387 @function 388 @abstract Retains a JavaScript class. 389 @param jsClass The JSClass to retain. 390 @result A JSClass that is the same as jsClass. 391 */ 392 JS_EXPORT JSClassRef JSClassRetain(JSClassRef jsClass); 393 394 /*! 395 @function 396 @abstract Releases a JavaScript class. 397 @param jsClass The JSClass to release. 398 */ 399 JS_EXPORT void JSClassRelease(JSClassRef jsClass); 400 401 /*! 402 @function 403 @abstract Creates a JavaScript object. 404 @param ctx The execution context to use. 405 @param jsClass The JSClass to assign to the object. Pass NULL to use the default object class. 406 @param data A void* to set as the object's private data. Pass NULL to specify no private data. 407 @result A JSObject with the given class and private data. 408 @discussion The default object class does not allocate storage for private data, so you must provide a non-NULL jsClass to JSObjectMake if you want your object to be able to store private data. 409 410 data is set on the created object before the intialize methods in its class chain are called. This enables the initialize methods to retrieve and manipulate data through JSObjectGetPrivate. 411 */ 412 JS_EXPORT JSObjectRef JSObjectMake(JSContextRef ctx, JSClassRef jsClass, void* data); 413 414 /*! 415 @function 416 @abstract Convenience method for creating a JavaScript function with a given callback as its implementation. 417 @param ctx The execution context to use. 418 @param name A JSString containing the function's name. This will be used when converting the function to string. Pass NULL to create an anonymous function. 419 @param callAsFunction The JSObjectCallAsFunctionCallback to invoke when the function is called. 420 @result A JSObject that is a function. The object's prototype will be the default function prototype. 421 */ 422 JS_EXPORT JSObjectRef JSObjectMakeFunctionWithCallback(JSContextRef ctx, JSStringRef name, JSObjectCallAsFunctionCallback callAsFunction); 423 424 /*! 425 @function 426 @abstract Convenience method for creating a JavaScript constructor. 427 @param ctx The execution context to use. 428 @param jsClass A JSClass that is the class your constructor will assign to the objects its constructs. jsClass will be used to set the constructor's .prototype property, and to evaluate 'instanceof' expressions. Pass NULL to use the default object class. 429 @param callAsConstructor A JSObjectCallAsConstructorCallback to invoke when your constructor is used in a 'new' expression. Pass NULL to use the default object constructor. 430 @result A JSObject that is a constructor. The object's prototype will be the default object prototype. 431 @discussion The default object constructor takes no arguments and constructs an object of class jsClass with no private data. If the constructor is inherited via JS subclassing and the value returned from callAsConstructor was created with jsClass, then the returned object will have it's prototype overridden to the derived class's prototype. 432 */ 433 JS_EXPORT JSObjectRef JSObjectMakeConstructor(JSContextRef ctx, JSClassRef jsClass, JSObjectCallAsConstructorCallback callAsConstructor); 434 435 /*! 436 @function 437 @abstract Creates a JavaScript Array object. 438 @param ctx The execution context to use. 439 @param argumentCount An integer count of the number of arguments in arguments. 440 @param arguments A JSValue array of data to populate the Array with. Pass NULL if argumentCount is 0. 441 @param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception. 442 @result A JSObject that is an Array. 443 @discussion The behavior of this function does not exactly match the behavior of the built-in Array constructor. Specifically, if one argument 444 is supplied, this function returns an array with one element. 445 */ 446 JS_EXPORT JSObjectRef JSObjectMakeArray(JSContextRef ctx, size_t argumentCount, const JSValueRef arguments[], JSValueRef* exception) JSC_API_AVAILABLE(macos(10.6), ios(7.0)); 447 448 /*! 449 @function 450 @abstract Creates a JavaScript Date object, as if by invoking the built-in Date constructor. 451 @param ctx The execution context to use. 452 @param argumentCount An integer count of the number of arguments in arguments. 453 @param arguments A JSValue array of arguments to pass to the Date Constructor. Pass NULL if argumentCount is 0. 454 @param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception. 455 @result A JSObject that is a Date. 456 */ 457 JS_EXPORT JSObjectRef JSObjectMakeDate(JSContextRef ctx, size_t argumentCount, const JSValueRef arguments[], JSValueRef* exception) JSC_API_AVAILABLE(macos(10.6), ios(7.0)); 458 459 /*! 460 @function 461 @abstract Creates a JavaScript Error object, as if by invoking the built-in Error constructor. 462 @param ctx The execution context to use. 463 @param argumentCount An integer count of the number of arguments in arguments. 464 @param arguments A JSValue array of arguments to pass to the Error Constructor. Pass NULL if argumentCount is 0. 465 @param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception. 466 @result A JSObject that is an Error. 467 */ 468 JS_EXPORT JSObjectRef JSObjectMakeError(JSContextRef ctx, size_t argumentCount, const JSValueRef arguments[], JSValueRef* exception) JSC_API_AVAILABLE(macos(10.6), ios(7.0)); 469 470 /*! 471 @function 472 @abstract Creates a JavaScript RegExp object, as if by invoking the built-in RegExp constructor. 473 @param ctx The execution context to use. 474 @param argumentCount An integer count of the number of arguments in arguments. 475 @param arguments A JSValue array of arguments to pass to the RegExp Constructor. Pass NULL if argumentCount is 0. 476 @param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception. 477 @result A JSObject that is a RegExp. 478 */ 479 JS_EXPORT JSObjectRef JSObjectMakeRegExp(JSContextRef ctx, size_t argumentCount, const JSValueRef arguments[], JSValueRef* exception) JSC_API_AVAILABLE(macos(10.6), ios(7.0)); 480 481 /*! 482 @function 483 @abstract Creates a JavaScript promise object by invoking the provided executor. 484 @param ctx The execution context to use. 485 @param resolve A pointer to a JSObjectRef in which to store the resolve function for the new promise. Pass NULL if you do not care to store the resolve callback. 486 @param reject A pointer to a JSObjectRef in which to store the reject function for the new promise. Pass NULL if you do not care to store the reject callback. 487 @param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception. 488 @result A JSObject that is a promise or NULL if an exception occurred. 489 */ 490 JS_EXPORT JSObjectRef JSObjectMakeDeferredPromise(JSContextRef ctx, JSObjectRef* resolve, JSObjectRef* reject, JSValueRef* exception) JSC_API_AVAILABLE(macos(10.15), ios(13.0)); 491 492 /*! 493 @function 494 @abstract Creates a function with a given script as its body. 495 @param ctx The execution context to use. 496 @param name A JSString containing the function's name. This will be used when converting the function to string. Pass NULL to create an anonymous function. 497 @param parameterCount An integer count of the number of parameter names in parameterNames. 498 @param parameterNames A JSString array containing the names of the function's parameters. Pass NULL if parameterCount is 0. 499 @param body A JSString containing the script to use as the function's body. 500 @param sourceURL A JSString containing a URL for the script's source file. This is only used when reporting exceptions. Pass NULL if you do not care to include source file information in exceptions. 501 @param startingLineNumber An integer value specifying the script's starting line number in the file located at sourceURL. This is only used when reporting exceptions. The value is one-based, so the first line is line 1 and invalid values are clamped to 1. 502 @param exception A pointer to a JSValueRef in which to store a syntax error exception, if any. Pass NULL if you do not care to store a syntax error exception. 503 @result A JSObject that is a function, or NULL if either body or parameterNames contains a syntax error. The object's prototype will be the default function prototype. 504 @discussion Use this method when you want to execute a script repeatedly, to avoid the cost of re-parsing the script before each execution. 505 */ 506 JS_EXPORT JSObjectRef JSObjectMakeFunction(JSContextRef ctx, JSStringRef name, unsigned parameterCount, const JSStringRef parameterNames[], JSStringRef body, JSStringRef sourceURL, int startingLineNumber, JSValueRef* exception); 507 508 /*! 509 @function 510 @abstract Gets an object's prototype. 511 @param ctx The execution context to use. 512 @param object A JSObject whose prototype you want to get. 513 @result A JSValue that is the object's prototype. 514 */ 515 JS_EXPORT JSValueRef JSObjectGetPrototype(JSContextRef ctx, JSObjectRef object); 516 517 /*! 518 @function 519 @abstract Sets an object's prototype. 520 @param ctx The execution context to use. 521 @param object The JSObject whose prototype you want to set. 522 @param value A JSValue to set as the object's prototype. 523 */ 524 JS_EXPORT void JSObjectSetPrototype(JSContextRef ctx, JSObjectRef object, JSValueRef value); 525 526 /*! 527 @function 528 @abstract Tests whether an object has a given property. 529 @param object The JSObject to test. 530 @param propertyName A JSString containing the property's name. 531 @result true if the object has a property whose name matches propertyName, otherwise false. 532 */ 533 JS_EXPORT bool JSObjectHasProperty(JSContextRef ctx, JSObjectRef object, JSStringRef propertyName); 534 535 /*! 536 @function 537 @abstract Gets a property from an object. 538 @param ctx The execution context to use. 539 @param object The JSObject whose property you want to get. 540 @param propertyName A JSString containing the property's name. 541 @param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception. 542 @result The property's value if object has the property, otherwise the undefined value. 543 */ 544 JS_EXPORT JSValueRef JSObjectGetProperty(JSContextRef ctx, JSObjectRef object, JSStringRef propertyName, JSValueRef* exception); 545 546 /*! 547 @function 548 @abstract Sets a property on an object. 549 @param ctx The execution context to use. 550 @param object The JSObject whose property you want to set. 551 @param propertyName A JSString containing the property's name. 552 @param value A JSValueRef to use as the property's value. 553 @param attributes A logically ORed set of JSPropertyAttributes to give to the property. 554 @param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception. 555 */ 556 JS_EXPORT void JSObjectSetProperty(JSContextRef ctx, JSObjectRef object, JSStringRef propertyName, JSValueRef value, JSPropertyAttributes attributes, JSValueRef* exception); 557 558 /*! 559 @function 560 @abstract Deletes a property from an object. 561 @param ctx The execution context to use. 562 @param object The JSObject whose property you want to delete. 563 @param propertyName A JSString containing the property's name. 564 @param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception. 565 @result true if the delete operation succeeds, otherwise false (for example, if the property has the kJSPropertyAttributeDontDelete attribute set). 566 */ 567 JS_EXPORT bool JSObjectDeleteProperty(JSContextRef ctx, JSObjectRef object, JSStringRef propertyName, JSValueRef* exception); 568 569 /*! 570 @function 571 @abstract Tests whether an object has a given property using a JSValueRef as the property key. 572 @param object The JSObject to test. 573 @param propertyKey A JSValueRef containing the property key to use when looking up the property. 574 @param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception. 575 @result true if the object has a property whose name matches propertyKey, otherwise false. 576 @discussion This function is the same as performing "propertyKey in object" from JavaScript. 577 */ 578 JS_EXPORT bool JSObjectHasPropertyForKey(JSContextRef ctx, JSObjectRef object, JSValueRef propertyKey, JSValueRef* exception) JSC_API_AVAILABLE(macos(10.15), ios(13.0)); 579 580 /*! 581 @function 582 @abstract Gets a property from an object using a JSValueRef as the property key. 583 @param ctx The execution context to use. 584 @param object The JSObject whose property you want to get. 585 @param propertyKey A JSValueRef containing the property key to use when looking up the property. 586 @param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception. 587 @result The property's value if object has the property key, otherwise the undefined value. 588 @discussion This function is the same as performing "object[propertyKey]" from JavaScript. 589 */ 590 JS_EXPORT JSValueRef JSObjectGetPropertyForKey(JSContextRef ctx, JSObjectRef object, JSValueRef propertyKey, JSValueRef* exception) JSC_API_AVAILABLE(macos(10.15), ios(13.0)); 591 592 /*! 593 @function 594 @abstract Sets a property on an object using a JSValueRef as the property key. 595 @param ctx The execution context to use. 596 @param object The JSObject whose property you want to set. 597 @param propertyKey A JSValueRef containing the property key to use when looking up the property. 598 @param value A JSValueRef to use as the property's value. 599 @param attributes A logically ORed set of JSPropertyAttributes to give to the property. 600 @param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception. 601 @discussion This function is the same as performing "object[propertyKey] = value" from JavaScript. 602 */ 603 JS_EXPORT void JSObjectSetPropertyForKey(JSContextRef ctx, JSObjectRef object, JSValueRef propertyKey, JSValueRef value, JSPropertyAttributes attributes, JSValueRef* exception) JSC_API_AVAILABLE(macos(10.15), ios(13.0)); 604 605 /*! 606 @function 607 @abstract Deletes a property from an object using a JSValueRef as the property key. 608 @param ctx The execution context to use. 609 @param object The JSObject whose property you want to delete. 610 @param propertyKey A JSValueRef containing the property key to use when looking up the property. 611 @param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception. 612 @result true if the delete operation succeeds, otherwise false (for example, if the property has the kJSPropertyAttributeDontDelete attribute set). 613 @discussion This function is the same as performing "delete object[propertyKey]" from JavaScript. 614 */ 615 JS_EXPORT bool JSObjectDeletePropertyForKey(JSContextRef ctx, JSObjectRef object, JSValueRef propertyKey, JSValueRef* exception) JSC_API_AVAILABLE(macos(10.15), ios(13.0)); 616 617 /*! 618 @function 619 @abstract Gets a property from an object by numeric index. 620 @param ctx The execution context to use. 621 @param object The JSObject whose property you want to get. 622 @param propertyIndex An integer value that is the property's name. 623 @param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception. 624 @result The property's value if object has the property, otherwise the undefined value. 625 @discussion Calling JSObjectGetPropertyAtIndex is equivalent to calling JSObjectGetProperty with a string containing propertyIndex, but JSObjectGetPropertyAtIndex provides optimized access to numeric properties. 626 */ 627 JS_EXPORT JSValueRef JSObjectGetPropertyAtIndex(JSContextRef ctx, JSObjectRef object, unsigned propertyIndex, JSValueRef* exception); 628 629 /*! 630 @function 631 @abstract Sets a property on an object by numeric index. 632 @param ctx The execution context to use. 633 @param object The JSObject whose property you want to set. 634 @param propertyIndex The property's name as a number. 635 @param value A JSValue to use as the property's value. 636 @param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception. 637 @discussion Calling JSObjectSetPropertyAtIndex is equivalent to calling JSObjectSetProperty with a string containing propertyIndex, but JSObjectSetPropertyAtIndex provides optimized access to numeric properties. 638 */ 639 JS_EXPORT void JSObjectSetPropertyAtIndex(JSContextRef ctx, JSObjectRef object, unsigned propertyIndex, JSValueRef value, JSValueRef* exception); 640 641 /*! 642 @function 643 @abstract Gets an object's private data. 644 @param object A JSObject whose private data you want to get. 645 @result A void* that is the object's private data, if the object has private data, otherwise NULL. 646 */ 647 JS_EXPORT void* JSObjectGetPrivate(JSObjectRef object); 648 649 /*! 650 @function 651 @abstract Sets a pointer to private data on an object. 652 @param object The JSObject whose private data you want to set. 653 @param data A void* to set as the object's private data. 654 @result true if object can store private data, otherwise false. 655 @discussion The default object class does not allocate storage for private data. Only objects created with a non-NULL JSClass can store private data. 656 */ 657 JS_EXPORT bool JSObjectSetPrivate(JSObjectRef object, void* data); 658 659 /*! 660 @function 661 @abstract Tests whether an object can be called as a function. 662 @param ctx The execution context to use. 663 @param object The JSObject to test. 664 @result true if the object can be called as a function, otherwise false. 665 */ 666 JS_EXPORT bool JSObjectIsFunction(JSContextRef ctx, JSObjectRef object); 667 668 /*! 669 @function 670 @abstract Calls an object as a function. 671 @param ctx The execution context to use. 672 @param object The JSObject to call as a function. 673 @param thisObject The object to use as "this," or NULL to use the global object as "this." 674 @param argumentCount An integer count of the number of arguments in arguments. 675 @param arguments A JSValue array of arguments to pass to the function. Pass NULL if argumentCount is 0. 676 @param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception. 677 @result The JSValue that results from calling object as a function, or NULL if an exception is thrown or object is not a function. 678 */ 679 JS_EXPORT JSValueRef JSObjectCallAsFunction(JSContextRef ctx, JSObjectRef object, JSObjectRef thisObject, size_t argumentCount, const JSValueRef arguments[], JSValueRef* exception); 680 681 /*! 682 @function 683 @abstract Tests whether an object can be called as a constructor. 684 @param ctx The execution context to use. 685 @param object The JSObject to test. 686 @result true if the object can be called as a constructor, otherwise false. 687 */ 688 JS_EXPORT bool JSObjectIsConstructor(JSContextRef ctx, JSObjectRef object); 689 690 /*! 691 @function 692 @abstract Calls an object as a constructor. 693 @param ctx The execution context to use. 694 @param object The JSObject to call as a constructor. 695 @param argumentCount An integer count of the number of arguments in arguments. 696 @param arguments A JSValue array of arguments to pass to the constructor. Pass NULL if argumentCount is 0. 697 @param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception. 698 @result The JSObject that results from calling object as a constructor, or NULL if an exception is thrown or object is not a constructor. 699 */ 700 JS_EXPORT JSObjectRef JSObjectCallAsConstructor(JSContextRef ctx, JSObjectRef object, size_t argumentCount, const JSValueRef arguments[], JSValueRef* exception); 701 702 /*! 703 @function 704 @abstract Gets the names of an object's enumerable properties. 705 @param ctx The execution context to use. 706 @param object The object whose property names you want to get. 707 @result A JSPropertyNameArray containing the names object's enumerable properties. Ownership follows the Create Rule. 708 */ 709 JS_EXPORT JSPropertyNameArrayRef JSObjectCopyPropertyNames(JSContextRef ctx, JSObjectRef object); 710 711 /*! 712 @function 713 @abstract Retains a JavaScript property name array. 714 @param array The JSPropertyNameArray to retain. 715 @result A JSPropertyNameArray that is the same as array. 716 */ 717 JS_EXPORT JSPropertyNameArrayRef JSPropertyNameArrayRetain(JSPropertyNameArrayRef array); 718 719 /*! 720 @function 721 @abstract Releases a JavaScript property name array. 722 @param array The JSPropetyNameArray to release. 723 */ 724 JS_EXPORT void JSPropertyNameArrayRelease(JSPropertyNameArrayRef array); 725 726 /*! 727 @function 728 @abstract Gets a count of the number of items in a JavaScript property name array. 729 @param array The array from which to retrieve the count. 730 @result An integer count of the number of names in array. 731 */ 732 JS_EXPORT size_t JSPropertyNameArrayGetCount(JSPropertyNameArrayRef array); 733 734 /*! 735 @function 736 @abstract Gets a property name at a given index in a JavaScript property name array. 737 @param array The array from which to retrieve the property name. 738 @param index The index of the property name to retrieve. 739 @result A JSStringRef containing the property name. 740 */ 741 JS_EXPORT JSStringRef JSPropertyNameArrayGetNameAtIndex(JSPropertyNameArrayRef array, size_t index); 742 743 /*! 744 @function 745 @abstract Adds a property name to a JavaScript property name accumulator. 746 @param accumulator The accumulator object to which to add the property name. 747 @param propertyName The property name to add. 748 */ 749 JS_EXPORT void JSPropertyNameAccumulatorAddName(JSPropertyNameAccumulatorRef accumulator, JSStringRef propertyName); 750 751 #ifdef __cplusplus 752 } 753 #endif 754 755 #endif /* JSObjectRef_h */