Mac Dev Center Mac OS X Reference Library Networking, Internet, & Web JavaScriptCore Framework Reference

Overview

Use the links in the table of contents to the left to access the documentation.

Functions

JSClassCreate

Creates a JavaScript class suitable for use with JSObjectMake.

JSClassRelease

Releases a JavaScript class.

JSClassRetain

Retains a JavaScript class.

JSObjectCallAsConstructor

Calls an object as a constructor.

JSObjectCallAsFunction

Calls an object as a function.

JSObjectCopyPropertyNames

Gets the names of an object's enumerable properties.

JSObjectDeleteProperty

Deletes a property from an object.

JSObjectGetPrivate

Gets an object's private data.

JSObjectGetProperty

Gets a property from an object.

JSObjectGetPropertyAtIndex

Gets a property from an object by numeric index.

JSObjectGetPrototype

Gets an object's prototype.

JSObjectHasProperty

Tests whether an object has a given property.

JSObjectIsConstructor

Tests whether an object can be called as a constructor.

JSObjectIsFunction

Tests whether an object can be called as a function.

JSObjectMake

Creates a JavaScript object.

JSObjectMakeArray

Creates a JavaScript Array object.

JSObjectMakeConstructor

Convenience method for creating a JavaScript constructor.

JSObjectMakeDate

Creates a JavaScript Date object, as if by invoking the built-in Date constructor.

JSObjectMakeError

Creates a JavaScript Error object, as if by invoking the built-in Error constructor.

JSObjectMakeFunction

Creates a function with a given script as its body.

JSObjectMakeFunctionWithCallback

Convenience method for creating a JavaScript function with a given callback as its implementation.

JSObjectMakeRegExp

Creates a JavaScript RegExp object, as if by invoking the built-in RegExp constructor.

JSObjectSetPrivate

Sets a pointer to private data on an object.

JSObjectSetProperty

Sets a property on an object.

JSObjectSetPropertyAtIndex

Sets a property on an object by numeric index.

JSObjectSetPrototype

Sets an object's prototype.

JSPropertyNameAccumulatorAddName

Adds a property name to a JavaScript property name accumulator.

JSPropertyNameArrayGetCount

Gets a count of the number of items in a JavaScript property name array.

JSPropertyNameArrayGetNameAtIndex

Gets a property name at a given index in a JavaScript property name array.

JSPropertyNameArrayRelease

Releases a JavaScript property name array.

JSPropertyNameArrayRetain

Retains a JavaScript property name array.

Creates a JavaScript class suitable for use with JSObjectMake.

JS_EXPORT JSClassRef JSClassCreate(
    const JSClassDefinition* definition);  

Parameters

Return Value

A JSClass with the given definition. Ownership follows the Create Rule.

Releases a JavaScript class.

JS_EXPORT void JSClassRelease(
    JSClassRef jsClass);  

Parameters

Retains a JavaScript class.

JS_EXPORT JSClassRef JSClassRetain(
    JSClassRef jsClass);  

Parameters

Return Value

A JSClass that is the same as jsClass.

Calls an object as a constructor.

JS_EXPORT JSObjectRef JSObjectCallAsConstructor(
    JSContextRef ctx,
    JSObjectRef object,
    size_t argumentCount,
    const JSValueRef arguments[],
    JSValueRef* exception);  

Parameters

Return Value

The JSObject that results from calling object as a constructor, or NULL if an exception is thrown or object is not a constructor.

Calls an object as a function.

JS_EXPORT JSValueRef JSObjectCallAsFunction(
    JSContextRef ctx,
    JSObjectRef object,
    JSObjectRef thisObject,
    size_t argumentCount,
    const JSValueRef arguments[],
    JSValueRef* exception);  

Parameters

Return Value

The JSValue that results from calling object as a function, or NULL if an exception is thrown or object is not a function.

Gets the names of an object's enumerable properties.

JS_EXPORT JSPropertyNameArrayRef JSObjectCopyPropertyNames(
    JSContextRef ctx,
    JSObjectRef object);  

Parameters

Return Value

A JSPropertyNameArray containing the names object's enumerable properties. Ownership follows the Create Rule.

Deletes a property from an object.

JS_EXPORT bool JSObjectDeleteProperty(
    JSContextRef ctx,
    JSObjectRef object,
    JSStringRef propertyName,
    JSValueRef *exception);  

Parameters

Return Value

true if the delete operation succeeds, otherwise false (for example, if the property has the kJSPropertyAttributeDontDelete attribute set).

Gets an object's private data.

JS_EXPORT void* JSObjectGetPrivate(
    JSObjectRef object);  

Parameters

Return Value

A void* that is the object's private data, if the object has private data, otherwise NULL.

Gets a property from an object.

JS_EXPORT JSValueRef JSObjectGetProperty(
    JSContextRef ctx,
    JSObjectRef object,
    JSStringRef propertyName,
    JSValueRef *exception);  

Parameters

Return Value

The property's value if object has the property, otherwise the undefined value.

Gets a property from an object by numeric index.

JS_EXPORT JSValueRef JSObjectGetPropertyAtIndex(
    JSContextRef ctx,
    JSObjectRef object,
    unsigned propertyIndex,
    JSValueRef *exception);  

Parameters

Return Value

The property's value if object has the property, otherwise the undefined value.

Discussion

Calling JSObjectGetPropertyAtIndex is equivalent to calling JSObjectGetProperty with a string containing propertyIndex, but JSObjectGetPropertyAtIndex provides optimized access to numeric properties.

Gets an object's prototype.

JS_EXPORT JSValueRef JSObjectGetPrototype(
    JSContextRef ctx,
    JSObjectRef object);  

Parameters

Return Value

A JSValue that is the object's prototype.

Tests whether an object has a given property.

JS_EXPORT bool JSObjectHasProperty(
    JSContextRef ctx,
    JSObjectRef object,
    JSStringRef propertyName);  

Parameters

Return Value

true if the object has a property whose name matches propertyName, otherwise false.

Tests whether an object can be called as a constructor.

JS_EXPORT bool JSObjectIsConstructor(
    JSContextRef ctx,
    JSObjectRef object);  

Parameters

Return Value

true if the object can be called as a constructor, otherwise false.

Tests whether an object can be called as a function.

JS_EXPORT bool JSObjectIsFunction(
    JSContextRef ctx,
    JSObjectRef object);  

Parameters

Return Value

true if the object can be called as a function, otherwise false.

Creates a JavaScript object.

JS_EXPORT JSObjectRef JSObjectMake(
    JSContextRef ctx,
    JSClassRef jsClass,
    void *data);  

Parameters

Return Value

A JSObject with the given class and private data.

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.

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.

Creates a JavaScript Array object.

JS_EXPORT JSObjectRef JSObjectMakeArray(
    JSContextRef ctx,
    size_t argumentCount,
    const JSValueRef arguments[],
    JSValueRef* exception) AVAILABLE_IN_WEBKIT_VERSION_4_0;  

Parameters

Return Value

A JSObject that is an Array.

Discussion

The behavior of this function does not exactly match the behavior of the built-in Array constructor. Specifically, if one argument is supplied, this function returns an array with one element.

Convenience method for creating a JavaScript constructor.

JS_EXPORT JSObjectRef JSObjectMakeConstructor(
    JSContextRef ctx,
    JSClassRef jsClass,
    JSObjectCallAsConstructorCallback callAsConstructor);  

Parameters

Return Value

A JSObject that is a constructor. The object's prototype will be the default object prototype.

Discussion

The default object constructor takes no arguments and constructs an object of class jsClass with no private data.

Creates a JavaScript Date object, as if by invoking the built-in Date constructor.

JS_EXPORT JSObjectRef JSObjectMakeDate(
    JSContextRef ctx,
    size_t argumentCount,
    const JSValueRef arguments[],
    JSValueRef* exception) AVAILABLE_IN_WEBKIT_VERSION_4_0;  

Parameters

Return Value

A JSObject that is a Date.

Creates a JavaScript Error object, as if by invoking the built-in Error constructor.

JS_EXPORT JSObjectRef JSObjectMakeError(
    JSContextRef ctx,
    size_t argumentCount,
    const JSValueRef arguments[],
    JSValueRef* exception) AVAILABLE_IN_WEBKIT_VERSION_4_0;  

Parameters

Return Value

A JSObject that is a Error.

Creates a function with a given script as its body.

JS_EXPORT JSObjectRef JSObjectMakeFunction(
    JSContextRef ctx,
    JSStringRef name,
    unsigned parameterCount,
    const JSStringRef parameterNames[],
    JSStringRef body,
    JSStringRef sourceURL,
    int startingLineNumber,
    JSValueRef* exception);  

Parameters

Return Value

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.

Discussion

Use this method when you want to execute a script repeatedly, to avoid the cost of re-parsing the script before each execution.

Convenience method for creating a JavaScript function with a given callback as its implementation.

JS_EXPORT JSObjectRef JSObjectMakeFunctionWithCallback(
    JSContextRef ctx,
    JSStringRef name,
    JSObjectCallAsFunctionCallback callAsFunction);  

Parameters

Return Value

A JSObject that is a function. The object's prototype will be the default function prototype.

Creates a JavaScript RegExp object, as if by invoking the built-in RegExp constructor.

JS_EXPORT JSObjectRef JSObjectMakeRegExp(
    JSContextRef ctx,
    size_t argumentCount,
    const JSValueRef arguments[],
    JSValueRef* exception) AVAILABLE_IN_WEBKIT_VERSION_4_0;  

Parameters

Return Value

A JSObject that is a RegExp.

Sets a pointer to private data on an object.

JS_EXPORT bool JSObjectSetPrivate(
    JSObjectRef object,
    void *data);  

Parameters

Return Value

true if object can store private data, otherwise false.

Discussion

The default object class does not allocate storage for private data. Only objects created with a non-NULL JSClass can store private data.

Sets a property on an object.

JS_EXPORT void JSObjectSetProperty(
    JSContextRef ctx,
    JSObjectRef object,
    JSStringRef propertyName,
    JSValueRef value,
    JSPropertyAttributes attributes,
    JSValueRef *exception);  

Parameters

Sets a property on an object by numeric index.

JS_EXPORT void JSObjectSetPropertyAtIndex(
    JSContextRef ctx,
    JSObjectRef object,
    unsigned propertyIndex,
    JSValueRef value,
    JSValueRef *exception);  

Parameters

Discussion

Calling JSObjectSetPropertyAtIndex is equivalent to calling JSObjectSetProperty with a string containing propertyIndex, but JSObjectSetPropertyAtIndex provides optimized access to numeric properties.

Sets an object's prototype.

JS_EXPORT void JSObjectSetPrototype(
    JSContextRef ctx,
    JSObjectRef object,
    JSValueRef value);  

Parameters

Adds a property name to a JavaScript property name accumulator.

JS_EXPORT void JSPropertyNameAccumulatorAddName(
    JSPropertyNameAccumulatorRef accumulator,
    JSStringRef propertyName);  

Parameters

Gets a count of the number of items in a JavaScript property name array.

JS_EXPORT size_t JSPropertyNameArrayGetCount(
    JSPropertyNameArrayRef array);  

Parameters

Return Value

An integer count of the number of names in array.

Gets a property name at a given index in a JavaScript property name array.

JS_EXPORT JSStringRef JSPropertyNameArrayGetNameAtIndex(
    JSPropertyNameArrayRef array,
    size_t index);  

Parameters

Return Value

A JSStringRef containing the property name.

Releases a JavaScript property name array.

JS_EXPORT void JSPropertyNameArrayRelease(
    JSPropertyNameArrayRef array);  

Parameters

Retains a JavaScript property name array.

JS_EXPORT JSPropertyNameArrayRef JSPropertyNameArrayRetain(
    JSPropertyNameArrayRef array);  

Parameters

Return Value

A JSPropertyNameArray that is the same as array.

Constants

kJSClassDefinitionEmpty

A JSClassDefinition structure of the current version, filled with NULL pointers and having no attributes.

A JSClassDefinition structure of the current version, filled with NULL pointers and having no attributes.

JS_EXPORT extern const JSClassDefinition kJSClassDefinitionEmpty;  

Discussion

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;

Typedefs

JSClassAttributes

A set of JSClassAttributes. Combine multiple attributes by logically ORing them together.

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.

JSObjectCallAsConstructorCallback

The callback invoked when an object is used as a constructor in a 'new' expression.

JSObjectCallAsFunctionCallback

The callback invoked when an object is called as a function.

JSObjectConvertToTypeCallback

The callback invoked when converting an object to a particular JavaScript type.

JSObjectDeletePropertyCallback

The callback invoked when deleting a property.

JSObjectFinalizeCallback

The callback invoked when an object is finalized (prepared for garbage collection). An object may be finalized on any thread.

JSObjectGetPropertyCallback

The callback invoked when getting a property's value.

JSObjectGetPropertyNamesCallback

The callback invoked when collecting the names of an object's properties.

JSObjectHasInstanceCallback

hasInstance The callback invoked when an object is used as the target of an 'instanceof' expression.

JSObjectHasPropertyCallback

The callback invoked when determining whether an object has a property.

JSObjectInitializeCallback

The callback invoked when an object is first created.

JSObjectSetPropertyCallback

The callback invoked when setting a property's value.

JSPropertyAttributes

A set of JSPropertyAttributes. Combine multiple attributes by logically ORing them together.

JSStaticFunction

This structure describes a statically declared function property.

JSStaticValue

This structure describes a statically declared value property.

A set of JSClassAttributes. Combine multiple attributes by logically ORing them together.

typedef unsigned JSClassAttributes;  

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;  

Fields

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.

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.

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);  

Parameters

Return Value

A JSObject that is the constructor's return value.

Discussion

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.

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);  

Parameters

Return Value

A JSValue that is the function's return value.

Discussion

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.

The callback invoked when converting an object to a particular JavaScript type.

typedef JSValueRef ( *JSObjectConvertToTypeCallback) (
    JSContextRef ctx,
    JSObjectRef object,
    JSType type,
    JSValueRef *exception);  

Parameters

Return Value

The objects's converted value, or NULL if the object was not converted.

Discussion

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.

The callback invoked when deleting a property.

typedef bool ( *JSObjectDeletePropertyCallback) (
    JSContextRef ctx,
    JSObjectRef object,
    JSStringRef propertyName,
    JSValueRef *exception);  

Parameters

Return Value

true if propertyName was successfully deleted, otherwise false.

Discussion

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).

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);  

Fields

Discussion

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.

The callback invoked when getting a property's value.

typedef JSValueRef ( *JSObjectGetPropertyCallback) (
    JSContextRef ctx,
    JSObjectRef object,
    JSStringRef propertyName,
    JSValueRef *exception);  

Parameters

Return Value

The property's value if object has the property, otherwise NULL.

Discussion

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.

The callback invoked when collecting the names of an object's properties.

typedef void ( *JSObjectGetPropertyNamesCallback) (
    JSContextRef ctx,
    JSObjectRef object,
    JSPropertyNameAccumulatorRef propertyNames);  

Fields

Discussion

If you named your function GetPropertyNames, you would declare it like this:

void GetPropertyNames(JSContextRef ctx, JSObjectRef object, JSPropertyNameAccumulatorRef propertyNames);

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.

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);  

Parameters

Return Value

true if possibleInstance is an instance of constructor, otherwise false.

Discussion

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.

The callback invoked when determining whether an object has a property.

typedef bool ( *JSObjectHasPropertyCallback) (
    JSContextRef ctx,
    JSObjectRef object,
    JSStringRef propertyName);  

Parameters

Return Value

true if object has the property, otherwise false.

Discussion

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.

The callback invoked when an object is first created.

typedef void ( *JSObjectInitializeCallback) (
    JSContextRef ctx,
    JSObjectRef object);  

Fields

Discussion

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.

The callback invoked when setting a property's value.

typedef bool ( *JSObjectSetPropertyCallback) (
    JSContextRef ctx,
    JSObjectRef object,
    JSStringRef propertyName,
    JSValueRef value,
    JSValueRef *exception);  

Parameters

Return Value

true if the property was set, otherwise false.

Discussion

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).

A set of JSPropertyAttributes. Combine multiple attributes by logically ORing them together.

typedef unsigned JSPropertyAttributes;  

This structure describes a statically declared function property.

typedef struct { 
    const char* const name; 
    JSObjectCallAsFunctionCallback callAsFunction; 
    JSPropertyAttributes attributes; 
} JSStaticFunction;  

Fields

This structure describes a statically declared value property.

typedef struct { 
    const char* const name; 
    JSObjectGetPropertyCallback getProperty; 
    JSObjectSetPropertyCallback setProperty; 
    JSPropertyAttributes attributes; 
} JSStaticValue;  

Fields

Enumerated Types

JSClassAttribute

JSPropertyAttribute

enum { 
    kJSClassAttributeNone = 0, 
    kJSClassAttributeNoAutomaticPrototype = 1 << 1 
};  

Constants

enum { 
    kJSPropertyAttributeNone = 0, 
    kJSPropertyAttributeReadOnly = 1 << 1, 
    kJSPropertyAttributeDontEnum = 1 << 2, 
    kJSPropertyAttributeDontDelete = 1 << 3 
};  

Constants