|
ADC Home > Reference Library > Reference > Carbon > Internet & Web > JavaScriptCore Framework Reference
|
JSObjectRef.h |
| Includes: |
JSClassCreate |
Creates a JavaScript class suitable for use with JSObjectMake.
JSClassRef JSClassCreate( const JSClassDefinition *definition);
definitionA JSClass with the given definition. Ownership follows the Create Rule.
JSClassRelease |
Releases a JavaScript class.
void JSClassRelease( JSClassRef jsClass);
jsClassJSClassRetain |
Retains a JavaScript class.
JSClassRef JSClassRetain( JSClassRef jsClass);
jsClassA JSClass that is the same as jsClass.
JSObjectCallAsConstructor |
Calls an object as a constructor.
JSObjectRef JSObjectCallAsConstructor( JSContextRef ctx, JSObjectRef object, size_t argumentCount, const JSValueRef arguments[], JSValueRef *exception);
ctxobjectargumentCountargumentsexceptionThe JSObject that results from calling object as a constructor, or NULL if an exception is thrown or object is not a constructor.
JSObjectCallAsFunction |
Calls an object as a function.
JSValueRef JSObjectCallAsFunction( JSContextRef ctx, JSObjectRef object, JSObjectRef thisObject, size_t argumentCount, const JSValueRef arguments[], JSValueRef *exception);
ctxobjectthisObjectargumentCountargumentsexceptionThe JSValue that results from calling object as a function, or NULL if an exception is thrown or object is not a function.
JSObjectCopyPropertyNames |
Gets the names of an object's enumerable properties.
JSPropertyNameArrayRef JSObjectCopyPropertyNames( JSContextRef ctx, JSObjectRef object);
ctxobjectA JSPropertyNameArray containing the names object's enumerable properties.
JSObjectDeleteProperty |
Deletes a property from an object.
bool JSObjectDeleteProperty( JSContextRef ctx, JSObjectRef object, JSStringRef propertyName, JSValueRef *exception);
ctxobjectpropertyNameexceptiontrue if the delete operation succeeds, otherwise false (for example, if the property has the kJSPropertyAttributeDontDelete attribute set).
JSObjectGetPrivate |
Gets an object's private data.
void* JSObjectGetPrivate( JSObjectRef object);
objectA void* that is the object's private data, if the object has private data, otherwise NULL.
JSObjectGetProperty |
Gets a property from an object.
JSValueRef JSObjectGetProperty( JSContextRef ctx, JSObjectRef object, JSStringRef propertyName, JSValueRef *exception);
ctxobjectpropertyNameexceptionThe property's value if object has the property, otherwise the undefined value.
JSObjectGetPropertyAtIndex |
Gets a property from an object by numeric index.
JSValueRef JSObjectGetPropertyAtIndex( JSContextRef ctx, JSObjectRef object, unsigned propertyIndex, JSValueRef *exception);
ctxobjectpropertyIndexexceptionThe property's value if object has the property, otherwise the undefined value.
Calling JSObjectGetPropertyAtIndex is equivalent to calling JSObjectGetProperty with a string containing propertyIndex, but JSObjectGetPropertyAtIndex provides optimized access to numeric properties.
JSObjectGetPrototype |
Gets an object's prototype.
JSValueRef JSObjectGetPrototype( JSContextRef ctx, JSObjectRef object);
ctxobjectA JSValue that is the object's prototype.
JSObjectHasProperty |
Tests whether an object has a given property.
bool JSObjectHasProperty( JSContextRef ctx, JSObjectRef object, JSStringRef propertyName);
objectpropertyNametrue if the object has a property whose name matches propertyName, otherwise false.
JSObjectIsConstructor |
Tests whether an object can be called as a constructor.
bool JSObjectIsConstructor( JSContextRef ctx, JSObjectRef object);
ctxobjecttrue if the object can be called as a constructor, otherwise false.
JSObjectIsFunction |
Tests whether an object can be called as a function.
bool JSObjectIsFunction( JSContextRef ctx, JSObjectRef object);
ctxobjecttrue if the object can be called as a function, otherwise false.
JSObjectMake |
Creates a JavaScript object.
JSObjectRef JSObjectMake( JSContextRef ctx, JSClassRef jsClass, void *data);
ctxjsClassdataA JSObject with the given class and private data.
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.
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.
JSObjectMakeConstructor |
Convenience method for creating a JavaScript constructor.
JSObjectRef JSObjectMakeConstructor( JSContextRef ctx, JSClassRef jsClass, JSObjectCallAsConstructorCallback callAsConstructor);
ctxjsClasscallAsConstructorA JSObject that is a constructor. The object's prototype will be the default object prototype.
The default object constructor takes no arguments and constructs an object of class jsClass with no private data.
JSObjectMakeFunction |
Creates a function with a given script as its body.
JSObjectRef JSObjectMakeFunction( JSContextRef ctx, JSStringRef name, unsigned parameterCount, const JSStringRef parameterNames[], JSStringRef body, JSStringRef sourceURL, int startingLineNumber, JSValueRef *exception);
ctxnameparameterCountparameterNamesbodysourceURLstartingLineNumberexceptionA 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.
Use this method when you want to execute a script repeatedly, to avoid the cost of re-parsing the script before each execution.
JSObjectMakeFunctionWithCallback |
Convenience method for creating a JavaScript function with a given callback as its implementation.
JSObjectRef JSObjectMakeFunctionWithCallback( JSContextRef ctx, JSStringRef name, JSObjectCallAsFunctionCallback callAsFunction);
ctxnamecallAsFunctionA JSObject that is a function. The object's prototype will be the default function prototype.
JSObjectSetPrivate |
Sets a pointer to private data on an object.
bool JSObjectSetPrivate( JSObjectRef object, void *data);
objectdatatrue if object can store private data, otherwise false.
The default object class does not allocate storage for private data. Only objects created with a non-NULL JSClass can store private data.
JSObjectSetProperty |
Sets a property on an object.
void JSObjectSetProperty( JSContextRef ctx, JSObjectRef object, JSStringRef propertyName, JSValueRef value, JSPropertyAttributes attributes, JSValueRef *exception);
ctxobjectpropertyNamevalueexceptionattributesJSObjectSetPropertyAtIndex |
Sets a property on an object by numeric index.
void JSObjectSetPropertyAtIndex( JSContextRef ctx, JSObjectRef object, unsigned propertyIndex, JSValueRef value, JSValueRef *exception);
ctxobjectpropertyIndexvalueexceptionCalling JSObjectSetPropertyAtIndex is equivalent to calling JSObjectSetProperty with a string containing propertyIndex, but JSObjectSetPropertyAtIndex provides optimized access to numeric properties.
JSObjectSetPrototype |
Sets an object's prototype.
void JSObjectSetPrototype( JSContextRef ctx, JSObjectRef object, JSValueRef value);
ctxobjectvalueJSPropertyNameAccumulatorAddName |
Adds a property name to a JavaScript property name accumulator.
void JSPropertyNameAccumulatorAddName( JSPropertyNameAccumulatorRef accumulator, JSStringRef propertyName);
accumulatorpropertyNameJSPropertyNameArrayGetCount |
Gets a count of the number of items in a JavaScript property name array.
size_t JSPropertyNameArrayGetCount( JSPropertyNameArrayRef array);
arrayAn integer count of the number of names in array.
JSPropertyNameArrayGetNameAtIndex |
Gets a property name at a given index in a JavaScript property name array.
JSStringRef JSPropertyNameArrayGetNameAtIndex( JSPropertyNameArrayRef array, size_t index);
arrayindexA JSStringRef containing the property name.
JSPropertyNameArrayRelease |
Releases a JavaScript property name array.
void JSPropertyNameArrayRelease( JSPropertyNameArrayRef array);
arrayJSPropertyNameArrayRetain |
Retains a JavaScript property name array.
JSPropertyNameArrayRef JSPropertyNameArrayRetain( JSPropertyNameArrayRef array);
arrayA JSPropertyNameArray that is the same as array.
kJSClassDefinitionEmpty |
A JSClassDefinition structure of the current version, filled with NULL pointers and having no attributes.
extern const JSClassDefinition kJSClassDefinitionEmpty;
Use this constant as a convenience when creating class definitions. For example, to create a class definition with only a finalize method:
JSClassDefinition definition = kJSClassDefinitionEmpty;
definition.finalize = Finalize;
JSClassAttributes |
A set of JSClassAttributes. Combine multiple attributes by logically ORing them together.
typedef unsigned JSClassAttributes;
JSClassDefinition |
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.
typedef struct { int version; // current (and only) version is 0 JSClassAttributes attributes; const char *className; JSClassRef parentClass; const JSStaticValue *staticValues; const JSStaticFunction *staticFunctions; JSObjectInitializeCallback initialize; JSObjectFinalizeCallback finalize; JSObjectHasPropertyCallback hasProperty; JSObjectGetPropertyCallback getProperty; JSObjectSetPropertyCallback setProperty; JSObjectDeletePropertyCallback deleteProperty; JSObjectGetPropertyNamesCallback getPropertyNames; JSObjectCallAsFunctionCallback callAsFunction; JSObjectCallAsConstructorCallback callAsConstructor; JSObjectHasInstanceCallback hasInstance; JSObjectConvertToTypeCallback convertToType; } JSClassDefinition;
version- The version number of this structure. The current version is 0.
attributes- A logically ORed set of JSClassAttributes to give to the class.
className- A null-terminated UTF8 string containing the class's name.
parentClass- A JSClass to set as the class's parent class. Pass NULL use the default object class.
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.
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.
initialize- The callback invoked when an object is first created. Use this callback to initialize the object.
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.
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.
getProperty- The callback invoked when getting a property's value.
setProperty- The callback invoked when setting a property's value.
deleteProperty- The callback invoked when deleting a property.
getPropertyNames- The callback invoked when collecting the names of an object's properties.
callAsFunction- The callback invoked when an object is called as a function.
hasInstance- The callback invoked when an object is used as the target of an 'instanceof' expression.
callAsConstructor- The callback invoked when an object is used as a constructor in a 'new' expression.
convertToType- The callback invoked when converting an object to a particular JavaScript type.
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.
If you named your getter function "GetX" and your setter function "SetX", you would declare a JSStaticValue array containing "X" like this:
JSStaticValue StaticValueArray[] = {
{ "X", GetX, SetX, kJSPropertyAttributeNone },
{ 0, 0, 0, 0 }
};
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.
A NULL callback specifies that the default object callback should substitute, except in the case of hasProperty, where it specifies that getProperty should substitute.
JSObjectCallAsConstructorCallback |
The callback invoked when an object is used as a constructor in a 'new' expression.
typedef JSObjectRef ( *JSObjectCallAsConstructorCallback) ( JSContextRef ctx, JSObjectRef constructor, size_t argumentCount, const JSValueRef arguments[], JSValueRef *exception);
ctx- The execution context to use.
constructor- A JSObject that is the constructor being called.
argumentCount- An integer count of the number of arguments in arguments.
arguments- A JSValue array of the arguments passed to the function.
exception- A pointer to a JSValueRef in which to return an exception, if any.
A JSObject that is the constructor's return value.
If you named your function CallAsConstructor, you would declare it like this:
JSObjectRef CallAsConstructor(JSContextRef ctx, JSObjectRef constructor, size_t argumentCount, const JSValueRef arguments[], JSValueRef* exception);
If your callback were invoked by the JavaScript expression 'new myConstructor()', constructor would be set to myConstructor.
If this callback is NULL, using your object as a constructor in a 'new' expression will throw an exception.
JSObjectCallAsFunctionCallback |
The callback invoked when an object is called as a function.
typedef JSValueRef ( *JSObjectCallAsFunctionCallback) ( JSContextRef ctx, JSObjectRef function, JSObjectRef thisObject, size_t argumentCount, const JSValueRef arguments[], JSValueRef *exception);
ctx- The execution context to use.
function- A JSObject that is the function being called.
thisObject- A JSObject that is the 'this' variable in the function's scope.
argumentCount- An integer count of the number of arguments in arguments.
arguments- A JSValue array of the arguments passed to the function.
exception- A pointer to a JSValueRef in which to return an exception, if any.
A JSValue that is the function's return value.
If you named your function CallAsFunction, you would declare it like this:
JSValueRef CallAsFunction(JSContextRef ctx, JSObjectRef function, JSObjectRef thisObject, size_t argumentCount, const JSValueRef arguments[], JSValueRef* exception);
If your callback were invoked by the JavaScript expression 'myObject.myFunction()', function would be set to myFunction, and thisObject would be set to myObject.
If this callback is NULL, calling your object as a function will throw an exception.
JSObjectConvertToTypeCallback |
The callback invoked when converting an object to a particular JavaScript type.
typedef JSValueRef ( *JSObjectConvertToTypeCallback) ( JSContextRef ctx, JSObjectRef object, JSType type, JSValueRef *exception);
ctx- The execution context to use.
object- The JSObject to convert.
type- A JSType specifying the JavaScript type to convert to.
exception- A pointer to a JSValueRef in which to return an exception, if any.
The objects's converted value, or NULL if the object was not converted.
If you named your function ConvertToType, you would declare it like this:
JSValueRef ConvertToType(JSContextRef ctx, JSObjectRef object, JSType type, JSValueRef* exception);
If this function returns false, the conversion request forwards to object's parent class chain (which includes the default object class).
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.
JSObjectDeletePropertyCallback |
The callback invoked when deleting a property.
typedef bool ( *JSObjectDeletePropertyCallback) ( JSContextRef ctx, JSObjectRef object, JSStringRef propertyName, JSValueRef *exception);
ctx- The execution context to use.
object- The JSObject in which to delete the property.
propertyName- A JSString containing the name of the property to delete.
exception- A pointer to a JSValueRef in which to return an exception, if any.
true if propertyName was successfully deleted, otherwise false.
If you named your function DeleteProperty, you would declare it like this:
bool DeleteProperty(JSContextRef ctx, JSObjectRef object, JSStringRef propertyName, JSValueRef* exception);
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).
JSObjectFinalizeCallback |
The callback invoked when an object is finalized (prepared for garbage collection). An object may be finalized on any thread.
typedef void ( *JSObjectFinalizeCallback) ( JSObjectRef object);
object- The JSObject being finalized.
If you named your function Finalize, you would declare it like this:
void Finalize(JSObjectRef object);
The finalize callback is called on the most derived class first, and the least
derived class (the parent class) last.
You must not call any function that may cause a garbage collection or an allocation
of a garbage collected object from within a JSObjectFinalizeCallback. This includes
all functions that have a JSContextRef parameter.
JSObjectGetPropertyCallback |
The callback invoked when getting a property's value.
typedef JSValueRef ( *JSObjectGetPropertyCallback) ( JSContextRef ctx, JSObjectRef object, JSStringRef propertyName, JSValueRef *exception);
ctx- The execution context to use.
object- The JSObject to search for the property.
propertyName- A JSString containing the name of the property to get.
exception- A pointer to a JSValueRef in which to return an exception, if any.
The property's value if object has the property, otherwise NULL.
If you named your function GetProperty, you would declare it like this:
JSValueRef GetProperty(JSContextRef ctx, JSObjectRef object, JSStringRef propertyName, JSValueRef* exception);
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.
JSObjectGetPropertyNamesCallback |
The callback invoked when collecting the names of an object's properties.
typedef void ( *JSObjectGetPropertyNamesCallback) ( JSContextRef ctx, JSObjectRef object, JSPropertyNameAccumulatorRef propertyNames);
ctx- The execution context to use.
object- The JSObject whose property names are being collected.
propertyNames- A JavaScript property name accumulator in which to accumulate the names of object's properties.
If you named your function GetPropertyNames, you would declare it like this:
void GetPropertyNames(JSContextRef ctx, JSObjectRef object, JSPropertyNameAccumulatorRef accumulator);
Property name accumulators are used by JSObjectCopyPropertyNames and JavaScript for...in loops.
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.
JSObjectHasInstanceCallback |
hasInstance The callback invoked when an object is used as the target of an 'instanceof' expression.
typedef bool ( *JSObjectHasInstanceCallback) ( JSContextRef ctx, JSObjectRef constructor, JSValueRef possibleInstance, JSValueRef *exception);
ctx- The execution context to use.
constructor- The JSObject that is the target of the 'instanceof' expression.
possibleInstance- The JSValue being tested to determine if it is an instance of constructor.
exception- A pointer to a JSValueRef in which to return an exception, if any.
true if possibleInstance is an instance of constructor, otherwise false.
If you named your function HasInstance, you would declare it like this:
bool HasInstance(JSContextRef ctx, JSObjectRef constructor, JSValueRef possibleInstance, JSValueRef* exception);
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.
If this callback is NULL, 'instanceof' expressions that target your object will return false.
Standard JavaScript practice calls for objects that implement the callAsConstructor callback to implement the hasInstance callback as well.
JSObjectHasPropertyCallback |
The callback invoked when determining whether an object has a property.
typedef bool ( *JSObjectHasPropertyCallback) ( JSContextRef ctx, JSObjectRef object, JSStringRef propertyName);
ctx- The execution context to use.
object- The JSObject to search for the property.
propertyName- A JSString containing the name of the property look up.
true if object has the property, otherwise false.
If you named your function HasProperty, you would declare it like this:
bool HasProperty(JSContextRef ctx, JSObjectRef object, JSStringRef propertyName);
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.
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.
If this callback is NULL, the getProperty callback will be used to service hasProperty requests.
JSObjectInitializeCallback |
The callback invoked when an object is first created.
typedef void ( *JSObjectInitializeCallback) ( JSContextRef ctx, JSObjectRef object);
ctx- The execution context to use.
object- The JSObject being created.
If you named your function Initialize, you would declare it like this:
void Initialize(JSContextRef ctx, JSObjectRef object);
Unlike the other object callbacks, the initialize callback is called on the least
derived class (the parent class) first, and the most derived class last.
JSObjectSetPropertyCallback |
The callback invoked when setting a property's value.
typedef bool ( *JSObjectSetPropertyCallback) ( JSContextRef ctx, JSObjectRef object, JSStringRef propertyName, JSValueRef value, JSValueRef *exception);
ctx- The execution context to use.
object- The JSObject on which to set the property's value.
propertyName- A JSString containing the name of the property to set.
value- A JSValue to use as the property's value.
exception- A pointer to a JSValueRef in which to return an exception, if any.
true if the property was set, otherwise false.
If you named your function SetProperty, you would declare it like this:
bool SetProperty(JSContextRef ctx, JSObjectRef object, JSStringRef propertyName, JSValueRef value, JSValueRef* exception);
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).
JSPropertyAttributes |
A set of JSPropertyAttributes. Combine multiple attributes by logically ORing them together.
typedef unsigned JSPropertyAttributes;
JSStaticFunction |
This structure describes a statically declared function property.
typedef struct { const char *const name; JSObjectCallAsFunctionCallback callAsFunction; JSPropertyAttributes attributes; } JSStaticFunction;
name- A null-terminated UTF8 string containing the property's name.
callAsFunction- A JSObjectCallAsFunctionCallback to invoke when the property is called as a function.
attributes- A logically ORed set of JSPropertyAttributes to give to the property.
JSStaticValue |
This structure describes a statically declared value property.
typedef struct { const char *const name; JSObjectGetPropertyCallback getProperty; JSObjectSetPropertyCallback setProperty; JSPropertyAttributes attributes; } JSStaticValue;
name- A null-terminated UTF8 string containing the property's name.
getProperty- A JSObjectGetPropertyCallback to invoke when getting the property's value.
setProperty- A JSObjectSetPropertyCallback to invoke when setting the property's value. May be NULL if the ReadOnly attribute is set.
attributes- A logically ORed set of JSPropertyAttributes to give to the property.
JSClassAttribute |
enum { kJSClassAttributeNone = 0, kJSClassAttributeNoAutomaticPrototype = 1 << 1 };
kJSClassAttributeNone- Specifies that a class has no special attributes.
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.
JSPropertyAttribute |
enum { kJSPropertyAttributeNone = 0, kJSPropertyAttributeReadOnly = 1 << 1, kJSPropertyAttributeDontEnum = 1 << 2, kJSPropertyAttributeDontDelete = 1 << 3 };
kJSPropertyAttributeNone- Specifies that a property has no special attributes.
kJSPropertyAttributeReadOnly- Specifies that a property is read-only.
kJSPropertyAttributeDontEnum- Specifies that a property should not be enumerated by JSPropertyEnumerators and JavaScript for...in loops.
kJSPropertyAttributeDontDelete- Specifies that the delete operation should fail on a property.
|