JS SetPrivate

From MDC

Sets the private data field of an object.

[edit] Syntax

JSBool JS_SetPrivate(JSContext *cx, JSObject *obj, void *data);

Name	Type	Description
cx	JSContext *	Any context.
obj	JSObject *	Object for which to set private data.
data	void *	Private data for the object. This pointer must be aligned to a 2-byte boundary.

[edit] Description

If a JSClass has the JSCLASS_HAS_PRIVATE flag, each object of that class has a private field of type void * which the application may use for any purpose. It is especially useful for storing C/C++ data that should not be directly visible to scripts. For example, a Socket class might use the private data field to store the socket handle.

JS_SetPrivate sets an object's private data field. obj must be an instance of a class that has the JSCLASS_HAS_PRIVATE flag.

Only the pointer is stored. Memory management of this field is the application's responsibility. The JavaScript engine never uses it. In particular:

• If you allocate memory for private data, you must free it, typically in a JSClass.finalize callback.
• If your class's private data contains any jsvals or other references to JavaScript objects, implement the JSClass.mark callback to ensure they are not prematurely reclaimed by the garbage collector.

On success, JS_SetPrivate returns JS_TRUE. Otherwise it returns JS_FALSE.

Use JS_GetInstancePrivate to safely extract the private data from an object. (See the warning at JS_GetPrivate.)

Never use JS_SetPrivate on an instance of a class you don't own. That object may already be using the private data field for something else; or there might not be a private data field in that object at all, in which case JS_SetPrivate would overwrite an object property. This could lead to a crash or worse.

LXR ID Search for JS_SetPrivate