Overview

JavaScript context and value handles for interacting with page script in C.

#include <Ultralight/CAPI/CAPI_JSValue.h>

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

This header provides the core types and functions of the JavaScript C API. You'll use its context and value handles to call page functions and exchange data with scripts running in a View.

The rules documented in this header hold across every JavaScript C header in the library.

This example calls a function on the page and destroys every handle afterward:

void ShowGreeting(ULView view) {
  ULJSContext ctx = ulViewGetJSContext(view);
  ULJSValue global = ulJSContextGetGlobalObject(ctx);
  ULJSValue fn = ulJSObjectGetProperty(global, "ShowMessage", NULL);
  ULJSValue arg = ulCreateJSValueStringFromCString(ctx, "Howdy!");
  ULJSValue exception = NULL;
  ULJSValue result = ulJSFunctionCall(fn, NULL, &arg, 1, &exception);
 
  if (exception)
    ulDestroyJSValue(exception); /* the page threw */
 
  ulDestroyJSValue(result);
  ulDestroyJSValue(arg);
  ulDestroyJSValue(fn);
  ulDestroyJSValue(global);
  ulDestroyJSContext(ctx);
}

Contexts and Values

The JavaScript C API organizes script execution around these handle types:

A ULJSContext represents the JavaScript environment of one page in one frame. Call ulViewGetJSContext() to obtain the context for a View's main frame. Each page navigation creates a new context, so you'll need to fetch a fresh handle after each navigation.
A ULJSValue represents a single live JavaScript value. Holding a handle keeps the value from being garbage-collected.

Handle Ownership and Destruction

Handle ownership determines who destroys a handle:

You destroy every handle a library function returns. This includes each intermediate handle in a chained property read.
The library destroys handles passed into your callbacks. Arguments, this_value, and ctx stay valid only during the callback (call ulCreateJSValueRef() or ulCreateJSContextRef() to keep one longer).
You destroy handles you pass into library functions. The library only borrows them during the call.
The library destroys handles your callback returns or stores in *exception.

Page Navigations and Handle Lifetimes

A handle never keeps its underlying page alive. When a page navigates away, its frame is removed, or its View is destroyed, every handle from that page enters the gone state.

Calls on NULL or on a handle whose page is gone fail safely without crashing. You'll still need to destroy those handles to prevent memory leaks.

To check whether a handle can still interact with its page, call ulJSValueIsAlive() or ulJSContextIsAlive(). Both functions return false for NULL handles as well as handles whose page is gone, so check whether a handle is NULL first if you need to distinguish between the two states.

Type Conversions

Conversion functions like ulJSValueToNumber(), ulJSValueToString(), and ulJSValueToBoolean() follow JavaScript's coercion rules rather than strict type checks. Converting an object can run page script by calling its valueOf() or toString() method.

To enforce strict conversions without coercion, call ulJSValueGetType() first to check the value's type.

This function shows how to perform a strict type check before reading a number versus relying on coercion:

void ReadLevel(ULJSValue player) {
  /* player.level is the string "7" */
  ULJSValue level = ulJSObjectGetProperty(player, "level", NULL);
 
  double strict = 0;  /* stays 0 (not a number) */
  if (ulJSValueGetType(level) == kULJSType_Number)
    ulJSValueToNumber(level, &strict, NULL);
 
  double loose = 0;
  ulJSValueToNumber(level, &loose, NULL);  /* 7 (JavaScript's rules) */
 
  ulDestroyJSValue(level);
}

Error Handling

Functions that can encounter JavaScript exceptions accept a ULJSValue* exception out-parameter. Pass NULL if you don't need exception details. When an operation throws, the library populates the parameter with an owned ULJSValue handle that you must destroy.

Passing a NULL handle or calling a function on a handle whose page is gone leaves exception untouched. Check whether the handle is alive to distinguish a missing page from a script exception.

To inspect an error, pass the exception handle to ulJSValueGetErrorDetails(). It populates a ULJSErrorDetails struct with the error's line and column numbers, along with owned string handles for the message, source URL, and stack trace. Release the string handles with ulJSErrorDetailsRelease().

For errors created by the library, inspect the code property on the error object to check what went wrong without parsing the message text. Standard error codes are defined in <Ultralight/js/Error.h>.

Threading Rules

You must call functions in this header on the Renderer's thread, unless a function's documentation states otherwise.

You can perform these operations from any thread, including a finalizer thread:

Release handles using ulDestroyJSValue() or ulDestroyJSContext().
Keep a reference using ulCreateJSValueRef() or ulCreateJSContextRef(). Callback arguments are the exception (retain them during the callback on the Renderer's thread).
Check liveness using ulJSValueIsAlive() or ulJSContextIsAlive(). Off the Renderer's thread, the result may already be out of date by the time your code acts on it.

Native Functions and User Data

Call ulCreateJSFunction() to create a JavaScript function that invokes a native ULJSFunctionCallback.

You can pass application state in user_data along with a destroy_user_data cleanup callback. The library runs destroy_user_data exactly once on the Renderer's thread when the function is garbage-collected or if function creation fails. Inside destroy_user_data, you must not call any library functions other than destroying handles.

Note: A value belongs to the page that created it and can't cross to another page unless both pages are frames of the same top-level page sharing the exact same origin. Operations that receive a value from an incompatible page fail with a TypeError whose code is ULJS_CROSS_CONTEXT (see <Ultralight/js/Value.h>).

See also: ulViewGetJSContext(), ulJSValueGetErrorDetails(), <Ultralight/js/Value.h>, <Ultralight/js/Context.h>

Classes
struct	ULJSErrorDetails
	Details of a JavaScript error, filled by ulJSValueGetErrorDetails(). More...

Functions
ULJSContext	ulCreateJSContextRef (ULJSContext ctx)
	Create a new handle to the same context.
void	ulDestroyJSContext (ULJSContext ctx)
	Destroy a context handle (NULL-safe).
bool	ulJSContextIsAlive (ULJSContext ctx)
	Whether or not the context is still alive.
ULJSValue	ulJSContextGetGlobalObject (ULJSContext ctx)
	Get the context's global object.
ULJSValue	ulJSContextEvaluate (ULJSContext ctx, ULString script, const char source_url, ULJSValue exception)
	Run a script in the context.
JSContextRef	ulJSContextGetJSContextRef (ULJSContext ctx)
	Get the JavaScriptCore JSContextRef, for use with the JavaScriptCore C API.
ULJSValue	ulCreateJSValueUndefined (ULJSContext ctx)
	Create a JavaScript undefined value.
ULJSValue	ulCreateJSValueNull (ULJSContext ctx)
	Create a JavaScript null value.
ULJSValue	ulCreateJSValueBoolean (ULJSContext ctx, bool value)
	Create a JavaScript boolean value.
ULJSValue	ulCreateJSValueNumber (ULJSContext ctx, double value)
	Create a JavaScript number value.
ULJSValue	ulCreateJSValueString (ULJSContext ctx, ULString value)
	Create a JavaScript string value from a ULString.
ULJSValue	ulCreateJSValueStringFromCString (ULJSContext ctx, const char *value)
	Create a JavaScript string value from a null-terminated UTF-8 string.
ULJSValue	ulCreateJSValueStringUTF8 (ULJSContext ctx, const char *bytes, size_t length)
	Create a JavaScript string value from UTF-8 bytes with an explicit length.
ULJSValue	ulCreateJSValueFromJSON (ULJSContext ctx, ULString json, ULJSValue *exception)
	Create a JavaScript value by parsing JSON text.
ULJSValue	ulCreateJSError (ULJSContext ctx, ULJSErrorType type, const char *message)
	Create a JavaScript error object of the given type.
ULJSValue	ulCreateJSMarshalError (ULJSContext ctx, const char binding_path, size_t arg_number, const char value_path, const char *expected, ULJSValue got)
	Create a JavaScript TypeError for a value that didn't convert to the type a binding expected.
ULJSValue	ulCreateJSValueRef (ULJSValue value)
	Create a new handle to the same JavaScript value.
void	ulDestroyJSValue (ULJSValue value)
	Destroy a value handle (NULL-safe).
ULJSType	ulJSValueGetType (ULJSValue value)
	Get the type of a JavaScript value.
bool	ulJSValueIsArray (ULJSValue value)
	Whether or not the value is an Array.
bool	ulJSValueIsCallable (ULJSValue value)
	Whether or not the value can be called (see ulJSFunctionCall()).
bool	ulJSValueIsFunction (ULJSValue value)
	Whether or not the value is a function.
bool	ulJSValueIsPromise (ULJSValue value)
	Whether or not the value is a Promise.
bool	ulJSValueIsAlive (ULJSValue value)
	Whether or not the value's page is still alive.
void	ulJSValueReportUnobservedException (ULJSValue exception)
	Log a JavaScript exception that your code received but never read.
ULJSContext	ulJSValueGetContext (ULJSValue value)
	Get the context a value belongs to.
bool	ulJSValueToBoolean (ULJSValue value, bool *result)
	Convert to a boolean using JavaScript's rules (this never runs script).
bool	ulJSValueToNumber (ULJSValue value, double result, ULJSValue exception)
	Convert to a number using JavaScript's rules.
ULString	ulJSValueToString (ULJSValue value, ULJSValue *exception)
	Convert to a string using JavaScript's rules.
bool	ulJSValueGetUTF8 (ULJSValue value, char buffer, size_t capacity, size_t out_length, ULJSValue *exception)
	Convert to a string using JavaScript's rules and write it as UTF-8 into your buffer.
ULString	ulJSValueToJSON (ULJSValue value, unsigned indent, ULJSValue *exception)
	Convert to JSON text like JSON.stringify() does.
ULJSValue	ulCreateJSObject (ULJSContext ctx)
	Create a new empty JavaScript object.
ULJSValue	ulCreateJSArray (ULJSContext ctx, const ULJSValue *elements, size_t count)
	Create a new JavaScript Array from a list of values.
ULJSValue	ulCreateJSObjectWithProperties (ULJSContext ctx, const char const names, const ULJSValue values, size_t count, ULJSValue exception)
	Create a new JavaScript object with a set of properties.
ULJSValue	ulJSObjectGetProperty (ULJSValue object, const char name, ULJSValue exception)
	Get a property of an object (own or inherited).
bool	ulJSObjectHasProperty (ULJSValue object, const char name, ULJSValue exception)
	Whether or not an object has a property (own or inherited).
bool	ulJSObjectGetProperties (ULJSValue object, const char const names, size_t count, ULJSValue out_values, ULJSValue exception)
	Get several properties of an object in one call.
bool	ulJSObjectSetProperty (ULJSValue object, const char name, ULJSValue value, unsigned attributes, ULJSValue exception)
	Set a property of an object.
ULJSValue	ulJSObjectGetPropertyAtIndex (ULJSValue object, size_t index, ULJSValue *exception)
	Get a property by numeric index (see ulJSObjectGetProperty()).
bool	ulJSObjectSetPropertyAtIndex (ULJSValue object, size_t index, ULJSValue value, ULJSValue *exception)
	Set a property by numeric index (see ulJSObjectSetProperty()).
bool	ulJSObjectGetOwnEntries (ULJSValue object, ULString out_names, ULJSValue out_values, size_t capacity, size_t out_count, ULJSValue exception)
	Get the names and values of an object's own enumerable properties in one call.
ULJSValue	ulJSFunctionCall (ULJSValue function, ULJSValue this_value, const ULJSValue args, size_t argc, ULJSValue exception)
	Call a JavaScript function.
ULJSValue	ulCreateJSFunction (ULJSContext ctx, const char name, ULJSFunctionCallback callback, void user_data, ULUserDataDestroyCallback destroy_user_data)
	Create a JavaScript function that calls a native callback.
bool	ulJSValueGetErrorDetails (ULJSValue error, ULJSErrorDetails *details)
	Get the type, message, source location, and stack trace of an error in one call.
void	ulJSErrorDetailsRelease (ULJSErrorDetails *details)
	Destroy the strings a ulJSValueGetErrorDetails() call stored in details and reset them to NULL.
size_t	ulJSTypedArrayGetLength (ULJSValue typed_array)
	Get the number of elements in a typed array.
size_t	ulJSArrayBufferGetByteLength (ULJSValue array_buffer)
	Get the length of an ArrayBuffer in bytes.

Macros
#define	ULJS_HANDLE_TYPES_DEFINED

Typedefs
typedef struct C_JSContext *	ULJSContext
	Opaque handle to a JavaScript context (the script environment of the page in one frame).
typedef struct C_JSValue *	ULJSValue
	Opaque handle to a JavaScript value.
typedef ULJSValue(*)	ULJSFunctionCallback(void user_data, ULJSContext ctx, ULJSValue this_value, const ULJSValue args, size_t argc, ULJSValue *exception)
	Callback invoked when JavaScript calls a function created with ulCreateJSFunction().

Enumerations
enum	ULJSType { kULJSType_Invalid = 0 , kULJSType_Undefined , kULJSType_Null , kULJSType_Boolean , kULJSType_Number , kULJSType_String , kULJSType_Symbol , kULJSType_Object , kULJSType_BigInt = 8 , kULJSType_Count }
	The type of a JavaScript value. More...
enum	ULJSPropertyAttributes { kULJSPropertyAttributes_None = 0 , kULJSPropertyAttributes_ReadOnly = 1 << 1 , kULJSPropertyAttributes_DontEnum = 1 << 2 , kULJSPropertyAttributes_DontDelete = 1 << 3 }
	Attribute flags for a new property (see ulJSObjectSetProperty() and ulJSClassAddMethod()). More...
enum	ULJSErrorType { kULJSErrorType_Error = 0 , kULJSErrorType_TypeError , kULJSErrorType_RangeError , kULJSErrorType_SyntaxError , kULJSErrorType_ReferenceError }
	The type of a JavaScript error, matching the standard error constructors. More...

Function Documentation

◆ ulCreateJSArray()

ULJSValue ulCreateJSArray	(	ULJSContext	ctx,
		const ULJSValue *	elements,
		size_t	count )

Create a new JavaScript Array from a list of values.

Parameters

ctx	The context to create the array in.
elements	The element handles (they remain yours; a NULL entry becomes undefined). May be NULL when count is 0.
count	The number of entries in elements.

Returns: Returns a new ULJSValue handle (NULL if the context or an element's page is gone). You must call ulDestroyJSValue() when finished.

Note: An element from another page is refused unless both pages are frames of the same top-level page with exactly the same origin. The call then returns NULL (and logs a diagnostic).

◆ ulCreateJSContextRef()

ULJSContext ulCreateJSContextRef ( ULJSContext ctx )

Create a new handle to the same context.

Parameters

ctx	The context handle to reference.

Returns: Returns a new ULJSContext handle. You must call ulDestroyJSContext() when finished.

Note: Safe to call from any thread.

◆ ulCreateJSError()

ULJSValue ulCreateJSError	(	ULJSContext	ctx,
		ULJSErrorType	type,
		const char *	message )

Create a JavaScript error object of the given type.

Use this to throw from a callback (through its exception out-parameter) or to reject a promise.

Parameters

ctx	The context to create the error in.
type	The error type (TypeError, RangeError, and so on).
message	The error's message as a null-terminated UTF-8 string.

Returns: Returns a new ULJSValue handle (NULL if the context is gone or message is NULL). You must call ulDestroyJSValue() when finished.

◆ ulCreateJSFunction()

ULJSValue ulCreateJSFunction	(	ULJSContext	ctx,
		const char *	name,
		ULJSFunctionCallback	callback,
		void *	user_data,
		ULUserDataDestroyCallback	destroy_user_data )

Create a JavaScript function that calls a native callback.

The function is a real function object (it inherits from Function.prototype, so bind, call, and apply work on it).

Parameters

ctx	The context to create the function in.
name	The function's name as a null-terminated UTF-8 string (NULL for "anonymous").
callback	The callback to invoke when the function is called.
user_data	Opaque user data passed to every call of callback.
destroy_user_data	Callback invoked exactly once to destroy user_data on the Renderer's thread after the function is garbage collected, or right away if the function can't be created (may be NULL).

Returns: Returns a new ULJSValue handle (NULL if the context is gone or callback is NULL). You must call ulDestroyJSValue() when finished.

◆ ulCreateJSMarshalError()

ULJSValue ulCreateJSMarshalError	(	ULJSContext	ctx,
		const char *	binding_path,
		size_t	arg_number,
		const char *	value_path,
		const char *	expected,
		ULJSValue	got )

Create a JavaScript TypeError for a value that didn't convert to the type a binding expected.

The message has the same form as the library's own conversion errors:

myApp.fs.readFile: argument 2: expected string, got number
myApp.setConfig: argument 1 (volume): expected number, got 'loud'
myApp.volume: expected number, got null

The error's code property is "ULJS_BAD_ARG", so page script can check the kind of error without parsing the message.

Parameters

ctx	The context to create the error in.
binding_path	The binding's full dot-separated path, root included (eg, "myApp.fs.readFile").
arg_number	The 1-based position of the argument that failed, or 0 when the failure isn't tied to an argument (eg, a property assignment).
value_path	Where the failing value is inside the argument (eg, "volume" or "items[2].name"), or NULL when the whole argument failed.
expected	A short description of the expected type (eg, "string", "number[]", or "'Small' \| 'Large'").
got	The value that failed to convert (NULL reads as undefined). It remains yours. A string is quoted in the message (shortened if it's long); any other value is described by its type.

Returns: Returns a new ULJSValue handle (NULL if the context is gone or a required parameter is NULL). You must call ulDestroyJSValue() when finished.

◆ ulCreateJSObject()

ULJSValue ulCreateJSObject ( ULJSContext ctx )

Create a new empty JavaScript object.

Parameters

ctx	The context to create the object in.

Returns: Returns a new ULJSValue handle (NULL if the context is gone). You must call ulDestroyJSValue() when finished.

◆ ulCreateJSObjectWithProperties()

ULJSValue ulCreateJSObjectWithProperties	(	ULJSContext	ctx,
		const char const	names,
		const ULJSValue *	values,
		size_t	count,
		ULJSValue *	exception )

Create a new JavaScript object with a set of properties.

The properties are defined like an object literal's, so a name like __proto__ becomes an ordinary property instead of setting the prototype.

Parameters

ctx	The context to create the object in.
names	The property names as null-terminated UTF-8 strings (a NULL entry makes the call fail and return NULL).
values	The property values (they remain yours; a NULL entry becomes undefined).
count	The number of entries in names and values.
exception	A pointer to a ULJSValue in which to store an exception, if any. Pass NULL if you don't care about exceptions. If set, you own the stored handle.

Returns: Returns a new ULJSValue handle (NULL on an exception or if the context or a value's page is gone). You must call ulDestroyJSValue() when finished.

Note: A value from another page is refused unless both pages are frames of the same top-level page with exactly the same origin. The call then stores a TypeError whose code is "ULJS_CROSS_CONTEXT" in exception and returns NULL.

◆ ulCreateJSValueBoolean()

ULJSValue ulCreateJSValueBoolean	(	ULJSContext	ctx,
		bool	value )

Create a JavaScript boolean value.

Parameters

ctx	The context to create the value in.
value	The boolean to store.

Returns: Returns a new ULJSValue handle (NULL if the context is gone). You must call ulDestroyJSValue() when finished.

◆ ulCreateJSValueFromJSON()

ULJSValue ulCreateJSValueFromJSON	(	ULJSContext	ctx,
		ULString	json,
		ULJSValue *	exception )

Create a JavaScript value by parsing JSON text.

Parameters

ctx	The context to create the value in.
json	The JSON text.
exception	A pointer to a ULJSValue in which to store an exception, if any. Pass NULL if you don't care about exceptions. If set, you own the stored handle.

Returns: Returns a new ULJSValue handle, or NULL if the JSON is invalid (a SyntaxError is stored in exception) or the context is gone. You must call ulDestroyJSValue() when finished.

◆ ulCreateJSValueNull()

ULJSValue ulCreateJSValueNull ( ULJSContext ctx )

Create a JavaScript null value.

Parameters

ctx	The context to create the value in.

Returns: Returns a new ULJSValue handle (NULL if the context is gone). You must call ulDestroyJSValue() when finished.

◆ ulCreateJSValueNumber()

ULJSValue ulCreateJSValueNumber	(	ULJSContext	ctx,
		double	value )

Create a JavaScript number value.

Parameters

ctx	The context to create the value in.
value	The number to store.

Returns: Returns a new ULJSValue handle (NULL if the context is gone). You must call ulDestroyJSValue() when finished.

◆ ulCreateJSValueRef()

ULJSValue ulCreateJSValueRef ( ULJSValue value )

Create a new handle to the same JavaScript value.

Use this to keep a value you received in a callback after the callback returns.

Parameters

value The value handle to reference.

Returns: Returns a new ULJSValue handle. You must call ulDestroyJSValue() when finished.

Note: Safe to call from any thread, except for a handle passed to your callback: call it during that callback (on the Renderer's thread).

◆ ulCreateJSValueString()

ULJSValue ulCreateJSValueString	(	ULJSContext	ctx,
		ULString	value )

Create a JavaScript string value from a ULString.

Parameters

ctx	The context to create the value in.
value	The string to store.

Returns: Returns a new ULJSValue handle (NULL if the context is gone or value is NULL). You must call ulDestroyJSValue() when finished.

◆ ulCreateJSValueStringFromCString()

ULJSValue ulCreateJSValueStringFromCString	(	ULJSContext	ctx,
		const char *	value )

Create a JavaScript string value from a null-terminated UTF-8 string.

Parameters

ctx	The context to create the value in.
value	The null-terminated UTF-8 string to store.

Returns: Returns a new ULJSValue handle (NULL if the context is gone or value is NULL). You must call ulDestroyJSValue() when finished.

◆ ulCreateJSValueStringUTF8()

ULJSValue ulCreateJSValueStringUTF8	(	ULJSContext	ctx,
		const char *	bytes,
		size_t	length )

Create a JavaScript string value from UTF-8 bytes with an explicit length.

The bytes don't need a null terminator and may contain null characters. Invalid UTF-8 becomes U+FFFD.

Parameters

ctx	The context to create the value in.
bytes	The UTF-8 bytes (may be NULL when length is 0).
length	The number of bytes.

Returns: Returns a new ULJSValue handle (NULL if the context is gone). You must call ulDestroyJSValue() when finished.

◆ ulCreateJSValueUndefined()

ULJSValue ulCreateJSValueUndefined ( ULJSContext ctx )

Create a JavaScript undefined value.

Parameters

ctx	The context to create the value in.

Returns: Returns a new ULJSValue handle (NULL if the context is gone). You must call ulDestroyJSValue() when finished.

◆ ulDestroyJSContext()

void ulDestroyJSContext ( ULJSContext ctx )

Destroy a context handle (NULL-safe).

This doesn't affect the context itself.

Parameters

ctx	The context handle to destroy.

Note: Safe to call from any thread, including a managed runtime's finalizer thread.

◆ ulDestroyJSValue()

void ulDestroyJSValue ( ULJSValue value )

Destroy a value handle (NULL-safe).

Parameters

value The value handle to destroy.

Note: Safe to call from any thread, including a managed runtime's finalizer thread.

◆ ulJSArrayBufferGetByteLength()

size_t ulJSArrayBufferGetByteLength ( ULJSValue array_buffer )

Get the length of an ArrayBuffer in bytes.

The ArrayBuffer can still be detached afterwards.

Unlike reading the ArrayBuffer's byteLength property, this never runs script.

Parameters

array_buffer The ArrayBuffer.

Returns: Returns the byte length (0 for a detached ArrayBuffer, a value that isn't an ArrayBuffer, or a NULL handle or one whose page is gone).

◆ ulJSContextEvaluate()

ULJSValue ulJSContextEvaluate	(	ULJSContext	ctx,
		ULString	script,
		const char *	source_url,
		ULJSValue *	exception )

Run a script in the context.

Parameters

ctx	The context handle.
script	The script.
source_url	A URL for the script as a null-terminated UTF-8 string, used in error reports (may be NULL).
exception	A pointer to a ULJSValue in which to store an exception, if any. Pass NULL if you don't care about exceptions. If set, you own the stored handle.

Returns: Returns the script's completion value (you must call ulDestroyJSValue() when finished), or NULL if the script throws or the context is gone.

◆ ulJSContextGetGlobalObject()

ULJSValue ulJSContextGetGlobalObject ( ULJSContext ctx )

Get the context's global object.

Parameters

ctx	The context handle.

Returns: Returns a handle to the global object (NULL if the context is gone). You must call ulDestroyJSValue() when finished.

◆ ulJSContextGetJSContextRef()

JSContextRef ulJSContextGetJSContextRef ( ULJSContext ctx )

Get the JavaScriptCore JSContextRef, for use with the JavaScriptCore C API.

Parameters

ctx	The context handle.

Returns: Returns the JSContextRef (NULL if the context is gone).

Warning: Use it only on the Renderer's thread, and don't store it.

◆ ulJSContextIsAlive()

bool ulJSContextIsAlive ( ULJSContext ctx )

Whether or not the context is still alive.

A context goes away when its page navigates away, its frame is removed, or its View or Renderer is destroyed.

Parameters

ctx	The context handle.

Returns: Returns true if the context is valid (false for a NULL handle or one whose page is gone).

Note: Safe to call from any thread, but off the Renderer's thread the result may already be out of date when you act on it.

◆ ulJSErrorDetailsRelease()

void ulJSErrorDetailsRelease ( ULJSErrorDetails * details )

Destroy the strings a ulJSValueGetErrorDetails() call stored in details and reset them to NULL.

Parameters

details The details to release (NULL does nothing).

Note: Safe to call from any thread.

◆ ulJSFunctionCall()

ULJSValue ulJSFunctionCall	(	ULJSValue	function,
		ULJSValue	this_value,
		const ULJSValue *	args,
		size_t	argc,
		ULJSValue *	exception )

Call a JavaScript function.

Parameters

function	The function to call.
this_value	The this value for the call (NULL uses the global object).
args	The arguments (they remain yours; a NULL entry passes undefined).
argc	The number of entries in args.
exception	A pointer to a ULJSValue in which to store an exception, if any. Pass NULL if you don't care about exceptions. If set, you own the stored handle.

Returns: Returns the function's return value (you must call ulDestroyJSValue() when finished), or NULL if the call throws, function can't be called, or a handle is NULL or its page is gone.

Note: A this_value or argument from another page is refused unless both pages are frames of the same top-level page with exactly the same origin. The call then stores a TypeError whose code is "ULJS_CROSS_CONTEXT" in exception and returns NULL.

◆ ulJSObjectGetOwnEntries()

bool ulJSObjectGetOwnEntries	(	ULJSValue	object,
		ULString *	out_names,
		ULJSValue *	out_values,
		size_t	capacity,
		size_t *	out_count,
		ULJSValue *	exception )

Get the names and values of an object's own enumerable properties in one call.

Inherited properties aren't included. Call it twice: first with capacity 0 to get the count, then with buffers of that size. If the object gains properties between the calls (a getter can run script), the second call reports a larger count, so repeat with more room.

Parameters

object	The object handle.
out_names	An array of capacity slots that receives the property names. You must destroy each one with ulDestroyString().
out_values	An array of capacity slots that receives the property values. You must destroy each one with ulDestroyJSValue().
capacity	The number of slots in out_names and out_values (0 to query the count).
out_count	Receives the total number of own enumerable properties even when it exceeds capacity (required).
exception	A pointer to a ULJSValue in which to store an exception, if any. Pass NULL if you don't care about exceptions. If set, you own the stored handle.

Returns: Returns true if the first min(capacity, *out_count) entries were stored. Returns false (and stores nothing) if a getter throws, the handle is NULL or its page is gone, or out_count is NULL.

Warning: A getter that changes the object during the call can cause entries to be skipped or repeated.

◆ ulJSObjectGetProperties()

bool ulJSObjectGetProperties	(	ULJSValue	object,
		const char const	names,
		size_t	count,
		ULJSValue *	out_values,
		ULJSValue *	exception )

Get several properties of an object in one call.

Parameters

object	The object handle.
names	The property names as null-terminated UTF-8 strings (a NULL entry makes the call fail).
count	The number of entries in names and out_values.
out_values	An array of count slots that receives the values (undefined for a missing property). On success you must destroy each one with ulDestroyJSValue(). On failure nothing is stored.
exception	A pointer to a ULJSValue in which to store an exception, if any. Pass NULL if you don't care about exceptions. If set, you own the stored handle.

Returns: Returns true on success. Returns false if a getter throws or the handle is NULL or its page is gone.

◆ ulJSObjectGetProperty()

ULJSValue ulJSObjectGetProperty	(	ULJSValue	object,
		const char *	name,
		ULJSValue *	exception )

Get a property of an object (own or inherited).

Parameters

object	The object handle.
name	The property name as a null-terminated UTF-8 string.
exception	A pointer to a ULJSValue in which to store an exception, if any. Pass NULL if you don't care about exceptions. If set, you own the stored handle.

Returns: Returns the property value (undefined if there's no such property), or NULL if a getter throws or the handle is NULL or its page is gone. You must call ulDestroyJSValue() when finished.

◆ ulJSObjectGetPropertyAtIndex()

ULJSValue ulJSObjectGetPropertyAtIndex	(	ULJSValue	object,
		size_t	index,
		ULJSValue *	exception )

Get a property by numeric index (see ulJSObjectGetProperty()).

Parameters

object	The object handle.
index	The property index.
exception	A pointer to a ULJSValue in which to store an exception, if any. Pass NULL if you don't care about exceptions. If set, you own the stored handle.

Returns: Returns the property value (undefined if there's no such property), or NULL if a getter throws or the handle is NULL or its page is gone. You must call ulDestroyJSValue() when finished.

◆ ulJSObjectHasProperty()

bool ulJSObjectHasProperty	(	ULJSValue	object,
		const char *	name,
		ULJSValue *	exception )

Whether or not an object has a property (own or inherited).

Unlike ulJSObjectGetProperty(), this returns true for a property set to undefined and false for a missing one. It doesn't run getters.

Parameters

object	The object handle.
name	The property name as a null-terminated UTF-8 string.
exception	A pointer to a ULJSValue in which to store an exception, if any. Pass NULL if you don't care about exceptions. If set, you own the stored handle.

Returns: Returns whether the property exists. Returns false if the check throws (eg, in a Proxy's has handler) or the handle is NULL or its page is gone.

◆ ulJSObjectSetProperty()

bool ulJSObjectSetProperty	(	ULJSValue	object,
		const char *	name,
		ULJSValue	value,
		unsigned	attributes,
		ULJSValue *	exception )

Set a property of an object.

Parameters

object	The object handle.
name	The property name as a null-terminated UTF-8 string.
value	The value to assign (it remains yours; NULL assigns undefined).
attributes	ULJSPropertyAttributes flags combined with \|. They only apply if this creates the property; pass kULJSPropertyAttributes_None for a normal assignment.
exception	A pointer to a ULJSValue in which to store an exception, if any. Pass NULL if you don't care about exceptions. If set, you own the stored handle.

Returns: Returns true on success. Returns false if a setter throws or the handle is NULL or its page is gone.

Note: Like an assignment in non-strict JavaScript, a write the object refuses (a frozen object, or a read-only property) is silently ignored and still returns true.

Note: A value from another page is refused unless both pages are frames of the same top-level page with exactly the same origin. The call then stores a TypeError whose code is "ULJS_CROSS_CONTEXT" in exception and returns false.

◆ ulJSObjectSetPropertyAtIndex()

bool ulJSObjectSetPropertyAtIndex	(	ULJSValue	object,
		size_t	index,
		ULJSValue	value,
		ULJSValue *	exception )

Set a property by numeric index (see ulJSObjectSetProperty()).

Parameters

object	The object handle.
index	The property index.
value	The value to assign (it remains yours; NULL assigns undefined).
exception	A pointer to a ULJSValue in which to store an exception, if any. Pass NULL if you don't care about exceptions. If set, you own the stored handle.

Returns: Returns true on success. Returns false if a setter throws or the handle is NULL or its page is gone.

Note: A value from another page is refused unless both pages are frames of the same top-level page with exactly the same origin. The call then stores a TypeError whose code is "ULJS_CROSS_CONTEXT" in exception and returns false.

◆ ulJSTypedArrayGetLength()

size_t ulJSTypedArrayGetLength ( ULJSValue typed_array )

Get the number of elements in a typed array.

The ArrayBuffer can still be detached afterwards.

Unlike reading the array's length property, this never runs script.

Parameters

typed_array The typed array.

Returns: Returns the element count (0 for a detached typed array, a value that isn't a typed array, or a NULL handle or one whose page is gone).

See also: ulJSTypedArrayGetInfo() in <Ultralight/CAPI/CAPI_JSBuffer.h>, which also gives you the bytes (the ArrayBuffer cannot be detached afterwards).

◆ ulJSValueGetContext()

ULJSContext ulJSValueGetContext ( ULJSValue value )

Get the context a value belongs to.

The context may already be gone (see ulJSContextIsAlive()).

Parameters

value The value handle.

Returns: Returns a new ULJSContext handle (NULL only for a NULL value). You must call ulDestroyJSContext() when finished.

Note: Safe to call from any thread.

◆ ulJSValueGetErrorDetails()

bool ulJSValueGetErrorDetails	(	ULJSValue	error,
		ULJSErrorDetails *	details )

Get the type, message, source location, and stack trace of an error in one call.

Use this on an exception from any function with an exception out-parameter. A thrown value that isn't an error object (eg, a thrown string) reports kULJSErrorType_Error, its string form as the message, and no source location or stack.

Parameters

error	The error value.
details	Receives the details. Every field is reset first, so it's safe to pass to ulJSErrorDetailsRelease() whatever this returns.

Returns: Returns true on success. Returns false if details is NULL, or for a NULL handle or one whose page is gone.

Note: Getting the message of a value that isn't an error object converts it to a string, which can run script (its toString() method).

◆ ulJSValueGetType()

ULJSType ulJSValueGetType ( ULJSValue value )

Get the type of a JavaScript value.

Parameters

value The value handle.

Returns: Returns the value's type (kULJSType_Invalid for a NULL handle or one whose page is gone).

◆ ulJSValueGetUTF8()

bool ulJSValueGetUTF8	(	ULJSValue	value,
		char *	buffer,
		size_t	capacity,
		size_t *	out_length,
		ULJSValue *	exception )

Convert to a string using JavaScript's rules and write it as UTF-8 into your buffer.

For a string value, a good pattern is a small stack buffer first, then a heap buffer of *out_length bytes if the text didn't fit. For any other value, each call converts it again (running any toString() method again), so convert once with ulJSValueToString() instead.

Parameters

value	The value handle.
buffer	The destination buffer (may be NULL when capacity is 0, to query the length).
capacity	The buffer size in bytes.
out_length	Receives the full UTF-8 length in bytes even when it exceeds capacity (no null terminator is written or counted).
exception	A pointer to a ULJSValue in which to store an exception, if any. Pass NULL if you don't care about exceptions. If set, you own the stored handle.

Returns: Returns true if the whole string was written. Returns false if the buffer was too small (check *out_length), the conversion throws, or the handle is NULL or its page is gone.

Note: Null characters in the string are kept. Unpaired UTF-16 surrogates become U+FFFD.

◆ ulJSValueIsAlive()

bool ulJSValueIsAlive ( ULJSValue value )

Whether or not the value's page is still alive.

Parameters

value The value handle.

Returns: Returns true if the handle is valid (false for a NULL handle or one whose page is gone).

Note: Safe to call from any thread, but off the Renderer's thread the result may already be out of date when you act on it.

◆ ulJSValueIsArray()

bool ulJSValueIsArray ( ULJSValue value )

Whether or not the value is an Array.

Parameters

value The value handle.

Returns: Returns true for an Array (false for a NULL handle or one whose page is gone).

◆ ulJSValueIsCallable()

bool ulJSValueIsCallable ( ULJSValue value )

Whether or not the value can be called (see ulJSFunctionCall()).

Parameters

value The value handle.

Returns: Returns true if the value can be called (false for a NULL handle or one whose page is gone).

◆ ulJSValueIsFunction()

bool ulJSValueIsFunction ( ULJSValue value )

Whether or not the value is a function.

Parameters

value The value handle.

Returns: Returns true for a function (false for a NULL handle or one whose page is gone).

Note: A few callable objects aren't functions (eg, the constructor of a native class). Use ulJSValueIsCallable() to check whether you can call a value.

◆ ulJSValueIsPromise()

bool ulJSValueIsPromise ( ULJSValue value )

Whether or not the value is a Promise.

This has no side effects: the promise isn't marked as handled.

Parameters

value The value handle.

Returns: Returns true for a Promise (false for a NULL handle or one whose page is gone).

◆ ulJSValueReportUnobservedException()

void ulJSValueReportUnobservedException ( ULJSValue exception )

Log a JavaScript exception that your code received but never read.

When JavaScript diagnostics are on (see ulJSAPISetDiagnostics()), this logs the exception's type, message, and stack to the Logger and, if the page is still alive, to the page's console. Otherwise it does nothing. A language binding built on this API can call it when a dropped result held an exception (the C++ js::Error does this in its destructor).

Parameters

exception The exception (NULL for no report). The handle isn't consumed.

Note: Safe to call from any thread. Off the Renderer's thread the log line has no details of the exception.

◆ ulJSValueToBoolean()

bool ulJSValueToBoolean	(	ULJSValue	value,
		bool *	result )

Convert to a boolean using JavaScript's rules (this never runs script).

Parameters

value	The value handle.
result	Receives the boolean.

Returns: Returns true on success (false for a NULL handle or one whose page is gone).

◆ ulJSValueToJSON()

ULString ulJSValueToJSON	(	ULJSValue	value,
		unsigned	indent,
		ULJSValue *	exception )

Convert to JSON text like JSON.stringify() does.

Parameters

value	The value handle.
indent	The number of spaces to indent each level by (0 for compact output, at most 10).
exception	A pointer to a ULJSValue in which to store an exception, if any. Pass NULL if you don't care about exceptions. If set, you own the stored handle.

Returns: Returns a string you must destroy with ulDestroyString(). Returns NULL if a toJSON() method or a getter throws, if the value has no JSON form (undefined, a function, or a Symbol; exception is left unchanged), or for a NULL handle or one whose page is gone.

◆ ulJSValueToNumber()

bool ulJSValueToNumber	(	ULJSValue	value,
		double *	result,
		ULJSValue *	exception )

Convert to a number using JavaScript's rules.

Parameters

value	The value handle.
result	Receives the number.
exception	A pointer to a ULJSValue in which to store an exception, if any. Pass NULL if you don't care about exceptions. If set, you own the stored handle.

Returns: Returns true on success. Returns false if the conversion throws (eg, a valueOf() method throws or the value is a Symbol), or for a NULL handle or one whose page is gone.

◆ ulJSValueToString()

ULString ulJSValueToString	(	ULJSValue	value,
		ULJSValue *	exception )

Convert to a string using JavaScript's rules.

Parameters

value	The value handle.
exception	A pointer to a ULJSValue in which to store an exception, if any. Pass NULL if you don't care about exceptions. If set, you own the stored handle.

Returns: Returns a string you must destroy with ulDestroyString(), or NULL if the conversion throws or the handle is NULL or its page is gone.

Macro Definition Documentation

◆ ULJS_HANDLE_TYPES_DEFINED

#define ULJS_HANDLE_TYPES_DEFINED

Typedef Documentation

◆ ULJSContext

typedef struct C_JSContext* ULJSContext

Opaque handle to a JavaScript context (the script environment of the page in one frame).

See also: ulViewGetJSContext(), ulCreateJSContextRef(), ulDestroyJSContext()

◆ ULJSFunctionCallback

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

Callback invoked when JavaScript calls a function created with ulCreateJSFunction().

The callback can call back into JavaScript (eg, evaluate scripts or call functions).

Parameters

user_data	The user data passed to ulCreateJSFunction().
ctx	The calling context (owned by the library, valid only during the callback; call ulCreateJSContextRef() to keep it).
this_value	The call's this value (owned by the library, valid only during the callback).
args	The arguments (owned by the library, valid only during the callback; call ulCreateJSValueRef() to keep one).
argc	The number of entries in args.
exception	To throw an exception into JavaScript, set *exception to a handle you own. The library takes ownership and ignores the return value.

Returns: Return the function's result as a handle you own (the library takes ownership), or NULL for undefined.

Note: Invoked on the Renderer's thread while script is running.

Note: A returned or thrown value whose page is gone reaches script as undefined. One from another page (unless both pages are frames of the same top-level page with exactly the same origin) makes the call throw a TypeError whose code is "ULJS_CROSS_CONTEXT".

◆ ULJSValue

typedef struct C_JSValue* ULJSValue

Opaque handle to a JavaScript value.

While a handle exists, its value can't be garbage collected.

See also: ulCreateJSValueRef(), ulDestroyJSValue()

Enumeration Type Documentation

◆ ULJSErrorType

enum ULJSErrorType

The type of a JavaScript error, matching the standard error constructors.

Enumerator
kULJSErrorType_Error	A plain Error.
kULJSErrorType_TypeError
kULJSErrorType_RangeError
kULJSErrorType_SyntaxError
kULJSErrorType_ReferenceError

◆ ULJSPropertyAttributes

enum ULJSPropertyAttributes

Attribute flags for a new property (see ulJSObjectSetProperty() and ulJSClassAddMethod()).

Enumerator
kULJSPropertyAttributes_None	No flags (a normal property).
kULJSPropertyAttributes_ReadOnly	Script can't change its value.
kULJSPropertyAttributes_DontEnum	Hidden from for...in and Object.keys.
kULJSPropertyAttributes_DontDelete	Script can't delete it.

◆ ULJSType

enum ULJSType

The type of a JavaScript value.

The values stay the same across releases. Later versions may add types, so handle a value you don't know (eg, with a default case).

Enumerator
kULJSType_Invalid	A NULL handle or one whose page is gone.
kULJSType_Undefined
kULJSType_Null
kULJSType_Boolean
kULJSType_Number
kULJSType_String
kULJSType_Symbol
kULJSType_Object
kULJSType_BigInt
kULJSType_Count	The number of types (not a type).

Go to the source code of this file.

Overview

Contexts and Values

Handle Ownership and Destruction

Page Navigations and Handle Lifetimes

Type Conversions

Error Handling

Threading Rules

Native Functions and User Data

Classes

Functions

Macros

Typedefs

Enumerations

Function Documentation

◆ ulCreateJSArray()

◆ ulCreateJSContextRef()

◆ ulCreateJSError()

◆ ulCreateJSFunction()

◆ ulCreateJSMarshalError()

◆ ulCreateJSObject()

◆ ulCreateJSObjectWithProperties()

◆ ulCreateJSValueBoolean()

◆ ulCreateJSValueFromJSON()

◆ ulCreateJSValueNull()

◆ ulCreateJSValueNumber()

◆ ulCreateJSValueRef()

◆ ulCreateJSValueString()

◆ ulCreateJSValueStringFromCString()

◆ ulCreateJSValueStringUTF8()

◆ ulCreateJSValueUndefined()

◆ ulDestroyJSContext()

◆ ulDestroyJSValue()

◆ ulJSArrayBufferGetByteLength()

◆ ulJSContextEvaluate()

◆ ulJSContextGetGlobalObject()

◆ ulJSContextGetJSContextRef()

◆ ulJSContextIsAlive()

◆ ulJSErrorDetailsRelease()

◆ ulJSFunctionCall()

◆ ulJSObjectGetOwnEntries()

◆ ulJSObjectGetProperties()

◆ ulJSObjectGetProperty()

◆ ulJSObjectGetPropertyAtIndex()

◆ ulJSObjectHasProperty()

◆ ulJSObjectSetProperty()

◆ ulJSObjectSetPropertyAtIndex()

◆ ulJSTypedArrayGetLength()

◆ ulJSValueGetContext()

◆ ulJSValueGetErrorDetails()

◆ ulJSValueGetType()

◆ ulJSValueGetUTF8()

◆ ulJSValueIsAlive()

◆ ulJSValueIsArray()

◆ ulJSValueIsCallable()

◆ ulJSValueIsFunction()

◆ ulJSValueIsPromise()

◆ ulJSValueReportUnobservedException()

◆ ulJSValueToBoolean()

◆ ulJSValueToJSON()

◆ ulJSValueToNumber()

◆ ulJSValueToString()

Macro Definition Documentation

◆ ULJS_HANDLE_TYPES_DEFINED

Typedef Documentation

◆ ULJSContext

◆ ULJSFunctionCallback

◆ ULJSValue

Enumeration Type Documentation

◆ ULJSErrorType

◆ ULJSPropertyAttributes

◆ ULJSType