CAPI_JSClass.h

Overview

Native class definitions and instance wrappers for JavaScript.

#include <Ultralight/CAPI/CAPI_JSClass.h>

Note

This API is a preview and may still change after 2.0.

A ULJSClass defines a JavaScript class backed by native C data and callbacks. Page script can instantiate the class with new and access its prototype methods and properties, while native code can wrap existing instances for JavaScript to use.

Define a class with a constructor, a destructor, and a property, then register it on an API:

#include <stdlib.h>
 
typedef struct {
  double timeout;
} Database;
 
/* new app.Database() */
static void* DatabaseNew(void* user_data, ULJSContext ctx,
                         const ULJSValue* args, size_t argc,
                         void** out_holder,
                         ULUserDataDestroyCallback* out_destroy_holder,
                         ULJSValue* exception) {
  Database* db = (Database*)calloc(1, sizeof(Database));
  db->timeout = 30;
  return db;  /* the wrapper owns it */
}
 
static void DatabaseFree(void* user_data, void* instance) {
  free(instance);
}
 
/* db.timeout */
static ULJSValue DatabaseGetTimeout(void* user_data, ULJSContext ctx,
                                    void* instance, ULJSValue* exception) {
  return ulCreateJSValueNumber(ctx, ((Database*)instance)->timeout);
}
 
static ULJSClass g_database_class = NULL;
 
void RegisterDatabase(ULJSAPI api) {
  g_database_class = ulCreateJSClass("Database");
  ulJSClassSetConstructor(g_database_class, DatabaseNew, NULL, NULL);
  ulJSClassSetDestructor(g_database_class, DatabaseFree, NULL, NULL);
  ulJSClassAddProperty(g_database_class, "timeout", DatabaseGetTimeout, NULL,
                       NULL, NULL);
  ulJSAPIRegisterClass(api, "Database", g_database_class);
}

Page script creates an instance and reads its property:

const db = new app.Database();
db.timeout;  // 30

Defining a Class

Method and property callbacks registered on a definition receive the native instance pointer directly as a void* argument, while static methods receive no instance.

You can modify a definition only before its first use. First use happens when you register the class on a ULJSAPI with ulJSAPIRegisterClass() or wrap an instance with ulCreateJSObjectWithClass() or ulCreateJSObjectWithClassHolder().

You'll need to keep the ULJSClass handle for wrapping native instances, detaching wrappers, and looking up instance pointers.

Instance Ownership

Each native instance has at most one JavaScript wrapper for a class in any single context. Passing the same instance pointer to ulCreateJSObjectWithClass() or ulCreateJSObjectWithClassHolder() for that class in the same context returns that existing wrapper, preserving JavaScript object identity (===).

Instance ownership depends on how the wrapper is created:

• Instances created with new belong to their wrapper. Your constructor callback allocates the native instance, and the wrapper takes ownership unless you store a custom holder in out_holder.
• Passing true for adopt in ulCreateJSObjectWithClass() transfers ownership to the wrapper. Use this when native code creates an instance that JavaScript should manage.
• Passing false for adopt in ulCreateJSObjectWithClass() borrows the instance. Native code retains ownership and must keep the instance alive while its page is alive.
• Passing a holder delegates ownership to a custom cleanup callback. Use ulCreateJSObjectWithClassHolder() when ownership relies on a token that can't be reconstructed from a raw pointer.

The library destroys owned instances on the Renderer's thread during a later ulUpdate() call, after their wrapper is garbage-collected or when the page goes away. If you don't set a destructor with ulJSClassSetDestructor(), owned instances without a holder are never destroyed.

Warning

Never adopt the same instance pointer into two owning wrappers (such as across two contexts or two classes), because the library destroys it twice.

Detaching an Instance

Garbage collection runs at unpredictable times, so any class that manages a scarce native resource (such as an open file or network socket) should provide an explicit close method. Calling ulJSObjectDetachInstance() releases the native instance from its wrapper and returns the instance pointer. Later script calls to that wrapper's methods or properties throw a TypeError with code ULJS_DETACHED.

Detach an instance inside a close method to free native resources early:

#include <stdio.h>
 
static ULJSClass g_log_class = NULL;
 
/* The class destructor (ulJSClassSetDestructor()). */
static void LogFileDestroy(void* user_data, void* instance) {
  fclose((FILE*)instance);
}
 
/* logFile.close() */
static ULJSValue LogFileClose(void* user_data, ULJSContext ctx,
                              void* instance, ULJSValue this_value,
                              const ULJSValue* args, size_t argc,
                              ULJSValue* exception) {
  void* file = ulJSObjectDetachInstance(this_value, g_log_class, NULL);
  if (file)
    LogFileDestroy(NULL, file);  /* the destructor won't run for it now */
  return NULL;
}

Detach a non-owning wrapper with ulJSObjectDetachInstance() before freeing its native instance. Because each page has its own wrapper, detach the wrapper across every context the instance was passed to so script calls throw ULJS_DETACHED instead of accessing freed memory.

When native code continues using an instance after a callback returns (such as for asynchronous work), call ulJSObjectProtectInstance() to obtain a ULJSProtectedInstance token that keeps the native instance alive. While protected, the instance won't be destroyed even if its wrapper is garbage-collected, its page goes away, or ulJSObjectDetachInstance() detaches it. Once the native work finishes, pass the token to ulJSObjectUnprotectInstance() to allow cleanup during a later ulUpdate().

Note

Navigating away releases owned instances even when the page enters the back-forward cache. Calls on those instances after the page is restored throw a TypeError with code ULJS_DETACHED.

Note

For conventions on handle ownership, NULL handles, user data, and threads, see CAPI_JSValue.h.

See also

ulCreateJSClass(), ulJSAPIRegisterClass(), ulCreateJSObjectWithClass(), ulCreateJSObjectWithClassHolder(), ulJSObjectDetachInstance(), ulJSObjectProtectInstance()

Functions
ULJSClass	ulCreateJSClass (const char *name)
	Create a new, empty class definition.
void	ulDestroyJSClass (ULJSClass cls)
	Destroy a class handle (NULL-safe).
bool	ulJSClassSetConstructor (ULJSClass cls, ULJSConstructorCallback callback, void *user_data, ULUserDataDestroyCallback destroy_user_data)
	Set the constructor invoked by new.
bool	ulJSClassSetDestructor (ULJSClass cls, ULJSDestructorCallback callback, void *user_data, ULUserDataDestroyCallback destroy_user_data)
	Set the destructor that destroys instances owned by their wrappers.
bool	ulJSClassAddMethod (ULJSClass cls, const char *name, ULJSMethodCallback callback, void *user_data, ULUserDataDestroyCallback destroy_user_data, unsigned attributes)
	Add an instance method.
bool	ulJSClassAddProperty (ULJSClass cls, const char *name, ULJSPropertyGetterCallback getter, ULJSPropertySetterCallback setter, void *user_data, ULUserDataDestroyCallback destroy_user_data)
	Add an instance accessor property.
bool	ulJSClassAddStaticMethod (ULJSClass cls, const char *name, ULJSFunctionCallback callback, void *user_data, ULUserDataDestroyCallback destroy_user_data)
	Add a static method (a function on the constructor itself, eg, myApp.Database.open()).
ULJSValue	ulCreateJSObjectWithClass (ULJSContext ctx, ULJSClass cls, void *instance, bool adopt)
	Get the wrapper for a native instance, creating it if needed.
ULJSValue	ulCreateJSObjectWithClassHolder (ULJSContext ctx, ULJSClass cls, void *instance, void *holder, ULUserDataDestroyCallback destroy_holder, bool *out_holder_taken)
	Get an owning wrapper for a native instance that owns it through a holder, creating the wrapper if needed.
void *	ulJSObjectGetInstance (ULJSValue object, ULJSClass cls)
	Get the native instance behind a wrapper.
ULJSInstanceState	ulJSObjectGetInstanceState (ULJSValue object, ULJSClass cls)
	Classify a JavaScript value against a class.
void *	ulJSObjectGetInstanceHolder (ULJSValue object, ULJSClass cls)
	Get the holder a wrapper owns its instance through.
void *	ulJSObjectDetachInstance (ULJSValue object, ULJSClass cls, void **out_holder)
	Detach the native instance from its wrapper, taking back ownership.
ULJSProtectedInstance	ulJSObjectProtectInstance (ULJSValue object, ULJSClass cls)
	Keep a wrapper's native instance alive until you unprotect it.
void	ulJSObjectUnprotectInstance (ULJSProtectedInstance instance)
	Stop protecting a native instance.
bool	ulJSObjectSetExternalMemoryHint (ULJSValue object, size_t bytes)
	Tell the garbage collector how much native memory an object keeps alive.

Macros
#define	ULTRALIGHT_ULJSCLASS_DEFINED
	Opaque handle to a native class definition.

Typedefs
typedef struct C_JSClass *	ULJSClass
typedef struct C_JSProtectedInstance *	ULJSProtectedInstance
	Opaque token that keeps a native instance alive (see ulJSObjectProtectInstance()).
typedef void *(*)	ULJSConstructorCallback(void *user_data, ULJSContext ctx, const ULJSValue *args, size_t argc, void **out_holder, ULUserDataDestroyCallback *out_destroy_holder, ULJSValue *exception)
	Callback invoked when page script constructs an instance with new.
typedef void(*)	ULJSDestructorCallback(void *user_data, void *instance)
	Callback invoked to destroy an instance owned by its wrapper.
typedef ULJSValue(*)	ULJSMethodCallback(void *user_data, ULJSContext ctx, void *instance, ULJSValue this_value, const ULJSValue *args, size_t argc, ULJSValue *exception)
	Callback invoked when page script calls a method on an instance.
typedef ULJSValue(*)	ULJSPropertyGetterCallback(void *user_data, ULJSContext ctx, void *instance, ULJSValue *exception)
	Callback invoked when page script reads an accessor property of an instance.
typedef bool(*)	ULJSPropertySetterCallback(void *user_data, ULJSContext ctx, void *instance, ULJSValue value, ULJSValue *exception)
	Callback invoked when page script assigns an accessor property of an instance.

Enumerations
enum	ULJSInstanceState { kULJSInstanceState_NotAnInstance = 0 , kULJSInstanceState_Attached , kULJSInstanceState_Detached }
	How a JavaScript value relates to a class. More...

Function Documentation

ulCreateJSClass()

ULJSClass ulCreateJSClass

(

const char *

name

)

Create a new, empty class definition.

You can change the definition until its first use (registering it with a JavaScript API or wrapping an instance with it). After that, the Set and Add functions log a warning, ignore the call, and return false.

Parameters

name	The class name as a null-terminated UTF-8 string. It appears as the constructor's name and in Object.prototype.toString() output.

Returns

Returns a new ULJSClass, or NULL if name is NULL or empty. You must call ulDestroyJSClass() when finished.

ulCreateJSObjectWithClass()

ULJSValue ulCreateJSObjectWithClass	(	ULJSContext	ctx,
		ULJSClass	cls,
		void *	instance,
		bool	adopt )

Get the wrapper for a native instance, creating it if needed.

If the instance already has a wrapper for this class in this context, you get that wrapper.

Parameters

ctx	The JavaScript context.
cls	The class definition.
instance	The native instance (must not be NULL).
adopt	Pass true to have the wrapper own the instance (the class destructor then destroys it). Pass false for a non-owning wrapper. Adopting an instance whose wrapper is non-owning makes that wrapper owning. Adopting an instance that is already owned logs a warning and changes nothing.

Returns

Returns a new ULJSValue handle to the wrapper, or NULL if the context is gone or cls or instance is NULL. You must call ulDestroyJSValue() when finished.

Note

Keep an instance behind a non-owning wrapper alive until its page goes away, or call ulJSObjectDetachInstance() before you free it.

ulCreateJSObjectWithClassHolder()

ULJSValue ulCreateJSObjectWithClassHolder	(	ULJSContext	ctx,
		ULJSClass	cls,
		void *	instance,
		void *	holder,
		ULUserDataDestroyCallback	destroy_holder,
		bool *	out_holder_taken )

Get an owning wrapper for a native instance that owns it through a holder, creating the wrapper if needed.

Use this when ownership is a token you can't rebuild from the instance pointer (eg, a shared smart pointer or a managed-runtime handle). When the wrapper is garbage-collected or its page goes away, destroy_holder(holder) runs instead of the class destructor, on the Renderer's thread during a later ulUpdate().

Parameters

ctx	The JavaScript context.
cls	The class definition.
instance	The native instance (must not be NULL).
holder	The ownership token (must not be NULL).
destroy_holder	The callback that releases holder (must not be NULL).
out_holder_taken	Set to true if the wrapper took holder (a new wrapper, or a non-owning wrapper that now owns its instance). Set to false if the instance's wrapper already owns it, in which case holder is still yours to release. May be NULL.

Returns

Returns a new ULJSValue handle to the wrapper, or NULL if the context is gone or a parameter is NULL (holder is then still yours). You must call ulDestroyJSValue() when finished.

ulDestroyJSClass()

void ulDestroyJSClass

(

ULJSClass

cls

)

Destroy a class handle (NULL-safe).

The class definition itself stays alive while a JavaScript API has it registered or any of its wrappers exist.

Parameters

cls	The class definition.

ulJSClassAddMethod()

bool ulJSClassAddMethod	(	ULJSClass	cls,
		const char *	name,
		ULJSMethodCallback	callback,
		void *	user_data,
		ULUserDataDestroyCallback	destroy_user_data,
		unsigned	attributes )

Add an instance method.

The method is a function on the class prototype, shared by all instances. Adding a name that already exists replaces it.

Parameters

cls	The class definition.
name	The method name as a null-terminated UTF-8 string (required).
callback	The callback to invoke when page script calls the method (required).
user_data	Opaque user data passed to every invocation of callback.
destroy_user_data	Callback invoked exactly once to destroy user_data when the class definition is destroyed, when the method is replaced, or right away if the call is ignored (may be NULL). It may run on any thread.
attributes	A logically ORed set of ULJSPropertyAttributes flags for the method on the prototype. Pass kULJSPropertyAttributes_DontEnum for standard JavaScript class-method behavior.

Returns

Returns true if the definition changed (false if cls is NULL or already in use, or a required argument is missing).

ulJSClassAddProperty()

bool ulJSClassAddProperty	(	ULJSClass	cls,
		const char *	name,
		ULJSPropertyGetterCallback	getter,
		ULJSPropertySetterCallback	setter,
		void *	user_data,
		ULUserDataDestroyCallback	destroy_user_data )

Add an instance accessor property.

Reads call the getter and assignments call the setter, so the page always gets live native state. The property is enumerable (it appears in Object.keys() and JSON.stringify() output) and can't be deleted by script. Adding a name that already exists replaces it.

Parameters

cls	The class definition.
name	The property name as a null-terminated UTF-8 string (required).
getter	The getter callback (required).
setter	The setter callback, or NULL to make the property read-only (assignments from script then have no effect).
user_data	Opaque user data passed to every invocation of getter and setter.
destroy_user_data	Callback invoked exactly once to destroy user_data when the class definition is destroyed, when the property is replaced, or right away if the call is ignored (may be NULL). It may run on any thread.

Returns

Returns true if the definition changed (false if cls is NULL or already in use, or a required argument is missing).

ulJSClassAddStaticMethod()

bool ulJSClassAddStaticMethod	(	ULJSClass	cls,
		const char *	name,
		ULJSFunctionCallback	callback,
		void *	user_data,
		ULUserDataDestroyCallback	destroy_user_data )

Add a static method (a function on the constructor itself, eg, myApp.Database.open()).

A static method receives no instance. Adding a name that already exists replaces it.

Parameters

cls	The class definition.
name	The method name as a null-terminated UTF-8 string (required).
callback	The callback to invoke when page script calls the method (required).
user_data	Opaque user data passed to every invocation of callback.
destroy_user_data	Callback invoked exactly once to destroy user_data when the class definition is destroyed, when the method is replaced, or right away if the call is ignored (may be NULL). It may run on any thread.

Returns

Returns true if the definition changed (false if cls is NULL or already in use, or a required argument is missing).

ulJSClassSetConstructor()

bool ulJSClassSetConstructor	(	ULJSClass	cls,
		ULJSConstructorCallback	callback,
		void *	user_data,
		ULUserDataDestroyCallback	destroy_user_data )

Set the constructor invoked by new.

Without a constructor, new throws a TypeError (code ULJS_NO_CTOR). The class still works for instanceof checks, static methods, and instances you wrap with ulCreateJSObjectWithClass().

Parameters

cls	The class definition.
callback	The constructor callback.
user_data	Opaque user data passed to every invocation of callback.
destroy_user_data	Callback invoked exactly once to destroy user_data when the class definition is destroyed, when the constructor is replaced, or right away if the call is ignored (may be NULL). It may run on any thread.

Returns

Returns true if the definition changed (false if cls is NULL or already in use).

ulJSClassSetDestructor()

bool ulJSClassSetDestructor	(	ULJSClass	cls,
		ULJSDestructorCallback	callback,
		void *	user_data,
		ULUserDataDestroyCallback	destroy_user_data )

Set the destructor that destroys instances owned by their wrappers.

Instances owned through a holder (see ulCreateJSObjectWithClassHolder()) use their holder's destroy callback instead. Without a destructor, owned instances are never destroyed.

Parameters

cls	The class definition.
callback	The destructor callback.
user_data	Opaque user data passed to every invocation of callback.
destroy_user_data	Callback invoked exactly once to destroy user_data when the class definition is destroyed, when the destructor is replaced, or right away if the call is ignored (may be NULL). It may run on any thread.

Returns

Returns true if the definition changed (false if cls is NULL or already in use).

ulJSObjectDetachInstance()

void * ulJSObjectDetachInstance	(	ULJSValue	object,
		ULJSClass	cls,
		void **	out_holder )

Detach the native instance from its wrapper, taking back ownership.

Afterward, script calls to the wrapper's methods and accessors throw a TypeError (code ULJS_DETACHED), and the class destructor never runs for this wrapper. Wrapping the same instance again creates a new wrapper. Use this to build close methods, and to free an instance that a non-owning wrapper refers to.

Parameters

object	The wrapper.
cls	The class definition.
out_holder	Receives the holder if the wrapper owned its instance through one (you then own the holder), or NULL otherwise. Pass NULL to have such a holder destroyed on the Renderer's thread during a later ulUpdate() instead.

Returns

Returns the instance, or NULL if object isn't an attached instance of cls.

Note

While the instance is protected (see ulJSObjectProtectInstance()), you don't get ownership back: out_holder receives NULL, and the wrapper's holder (or the class destructor) releases the instance after the last ulJSObjectUnprotectInstance().

Warning

If the holder is the instance's only owner, destroying it destroys the instance. Pass NULL for out_holder only when you know how the wrapper was created.

ulJSObjectGetInstance()

void * ulJSObjectGetInstance	(	ULJSValue	object,
		ULJSClass	cls )

Get the native instance behind a wrapper.

Parameters

object	The wrapper.
cls	The class definition.

Returns

Returns the instance, or NULL if object isn't an attached instance of cls or its page is gone.

ulJSObjectGetInstanceHolder()

void * ulJSObjectGetInstanceHolder	(	ULJSValue	object,
		ULJSClass	cls )

Get the holder a wrapper owns its instance through.

Parameters

object	The wrapper.
cls	The class definition.

Returns

Returns the holder, or NULL if the wrapper doesn't own its instance through a holder (adopted and non-owning wrappers don't), is detached, or isn't an instance of cls. The holder stays owned by the wrapper; use ulJSObjectDetachInstance() to take it back.

ulJSObjectGetInstanceState()

ULJSInstanceState ulJSObjectGetInstanceState	(	ULJSValue	object,
		ULJSClass	cls )

Classify a JavaScript value against a class.

Use this to tell a detached wrapper (which deserves a "was detached" error) from a value that was never an instance.

Parameters

object	The value to classify.
cls	The class definition.

Returns

Returns the value's state (kULJSInstanceState_NotAnInstance if its page is gone).

ulJSObjectProtectInstance()

ULJSProtectedInstance ulJSObjectProtectInstance	(	ULJSValue	object,
		ULJSClass	cls )

Keep a wrapper's native instance alive until you unprotect it.

Use this when native code keeps using an instance after the call that received it returns (eg, a method that finishes its work later). While the instance is protected, the wrapper's ownership isn't released, even if the wrapper is garbage-collected, its page goes away, or it is detached with ulJSObjectDetachInstance(). Those still happen as usual (a detached wrapper still throws), but if one of them would have released the instance, the release waits until the last ulJSObjectUnprotectInstance() and then runs on the Renderer's thread during a later ulUpdate().

You can protect an instance more than once. Each call returns a token that you must pass to ulJSObjectUnprotectInstance() exactly once.

This differs from JSValueProtect(), which keeps a JavaScript value from being garbage-collected. Protecting an instance keeps the native instance alive, not the wrapper, and it holds across every way the wrapper can release it.

Parameters

object	The wrapper.
cls	The class definition.

Returns

Returns a token for ulJSObjectUnprotectInstance(), or NULL if object isn't an attached instance of cls or its page is gone.

Note

Call this on the Renderer's thread. A non-owning wrapper's instance stays yours to keep alive, protected or not.

ulJSObjectSetExternalMemoryHint()

bool ulJSObjectSetExternalMemoryHint	(	ULJSValue	object,
		size_t	bytes )

Tell the garbage collector how much native memory an object keeps alive.

Use this when a small wrapper keeps a large native allocation alive, so the collector accounts for its true cost. A new hint replaces the previous one, and 0 clears it. The hint goes away when the object is collected.

Parameters

object	The object (usually a class instance's wrapper).
bytes	The number of bytes of native memory the object keeps alive.

Returns

Returns true if the hint was stored, or false if the object can't hold a hint (class instances can, plain objects can't) or its page is gone.

ulJSObjectUnprotectInstance()

void ulJSObjectUnprotectInstance

(

ULJSProtectedInstance

instance

)

Stop protecting a native instance.

If the wrapper's ownership was released while the instance was protected and this was the last protection, the instance is released on the Renderer's thread during a later ulUpdate(). The token works after the wrapper's page is gone.

Parameters

instance

The token returned by ulJSObjectProtectInstance() (NULL does nothing). It is no longer valid after this call.

Note

Safe to call from any thread. While the Renderer is alive, the release runs on the Renderer's thread. After the Renderer is destroyed, it runs on the calling thread.

Macro Definition Documentation

ULTRALIGHT_ULJSCLASS_DEFINED

#define ULTRALIGHT_ULJSCLASS_DEFINED

Opaque handle to a native class definition.

See also

ulCreateJSClass(), ulDestroyJSClass()

Typedef Documentation

ULJSClass

typedef struct C_JSClass* ULJSClass

ULJSConstructorCallback

typedef void *(*) ULJSConstructorCallback(void *user_data, ULJSContext ctx, const ULJSValue *args, size_t argc, void **out_holder, ULUserDataDestroyCallback *out_destroy_holder, ULJSValue *exception)

Callback invoked when page script constructs an instance with new.

Return a new native instance. Its wrapper owns it and destroys it with the class destructor, unless you store a holder in out_holder.

Parameters

user_data	The user data supplied to ulJSClassSetConstructor().
ctx	The context the constructor belongs to. Owned by the library, valid only for the duration of the callback.
args	The constructor arguments. Owned by the library, valid only for the duration of the callback.
argc	The number of entries in args.
out_holder	Store a holder here to have the wrapper own the instance through it instead of the class destructor (as with ulCreateJSObjectWithClassHolder()). Leave it untouched to use the class destructor.
out_destroy_holder	The callback that destroys out_holder. You must store one whenever you store a holder.
exception	To fail construction with a specific error, set *exception to a handle you own (see ulCreateJSError()); ownership transfers to the library.

Returns

Return the new instance, or NULL to fail construction (page script then gets a generic Error unless you set *exception). When construction fails, the library destroys the instance you returned and the holder you stored, if any.

Note

If you return an instance whose wrapper already owns it, new returns that wrapper and the library destroys the holder you stored. If that holder is the instance's only owner, this destroys the instance too.

ULJSDestructorCallback

typedef void(*) ULJSDestructorCallback(void *user_data, void *instance)

Callback invoked to destroy an instance owned by its wrapper.

Runs once per owning wrapper, on the Renderer's thread during a later ulUpdate(), after the wrapper is garbage-collected or its page goes away. Destructions still pending when the Renderer is destroyed run during its destruction.

Parameters

user_data	The user data supplied to ulJSClassSetDestructor().
instance	The instance to destroy.

Warning

Don't call into JavaScript from this callback.

ULJSMethodCallback

typedef ULJSValue(*) ULJSMethodCallback(void *user_data, ULJSContext ctx, void *instance, ULJSValue this_value, const ULJSValue *args, size_t argc, ULJSValue *exception)

Callback invoked when page script calls a method on an instance.

Parameters

user_data	The user data supplied to ulJSClassAddMethod().
ctx	The context the wrapper belongs to. Owned by the library, valid only for the duration of the callback.
instance	The native instance (this is never NULL).
this_value	The instance's wrapper. Owned by the library, valid only for the duration of the callback.
args	The call arguments. Owned by the library, valid only for the duration of the callback.
argc	The number of entries in args.
exception	To throw an exception into JavaScript, set *exception to a handle you own; ownership transfers to the library and the return value is ignored.

Returns

Return the method's return value as a handle you own (ownership transfers to the library), or NULL for undefined.

Note

A call on a detached wrapper, or on an object that isn't an instance of the class, throws a TypeError instead of invoking the callback.

ULJSPropertyGetterCallback

typedef ULJSValue(*) ULJSPropertyGetterCallback(void *user_data, ULJSContext ctx, void *instance, ULJSValue *exception)

Callback invoked when page script reads an accessor property of an instance.

Parameters

user_data	The user data supplied to ulJSClassAddProperty().
ctx	The context the wrapper belongs to. Owned by the library, valid only for the duration of the callback.
instance	The native instance (this is never NULL).
exception	To throw an exception into JavaScript, set *exception to a handle you own; ownership transfers to the library and the return value is ignored.

Returns

Return the property's value as a handle you own (ownership transfers to the library), or NULL for undefined.

ULJSPropertySetterCallback

typedef bool(*) ULJSPropertySetterCallback(void *user_data, ULJSContext ctx, void *instance, ULJSValue value, ULJSValue *exception)

Callback invoked when page script assigns an accessor property of an instance.

Parameters

user_data	The user data supplied to ulJSClassAddProperty().
ctx	The context the wrapper belongs to. Owned by the library, valid only for the duration of the callback.
instance	The native instance (this is never NULL).
value	The assigned value. Owned by the library, valid only for the duration of the callback.
exception	To throw an exception into JavaScript, set *exception to a handle you own; ownership transfers to the library and the return value is ignored.

Returns

Return true to accept the assignment. Return false to reject it, which throws a TypeError into the page (unless you set *exception).

ULJSProtectedInstance

typedef struct C_JSProtectedInstance* ULJSProtectedInstance

Opaque token that keeps a native instance alive (see ulJSObjectProtectInstance()).

See also

ulJSObjectProtectInstance(), ulJSObjectUnprotectInstance()

Enumeration Type Documentation

ULJSInstanceState

enum ULJSInstanceState

How a JavaScript value relates to a class.

Enumerator
kULJSInstanceState_NotAnInstance	Not an instance of the class (or its page is gone).
kULJSInstanceState_Attached	A live instance (not detached).
kULJSInstanceState_Detached	An instance whose wrapper is detached.

Go to the source code of this file.