[apple/javascriptcore.git] / API / JSContextRef.h

/*
 * Copyright (C) 2006 Apple Inc.  All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY APPLE INC. ``AS IS'' AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL APPLE INC. OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
 * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

#ifndef JSContextRef_h
#define JSContextRef_h

#include <JavaScriptCore/JSObjectRef.h>
#include <JavaScriptCore/JSValueRef.h>
#include <JavaScriptCore/WebKitAvailability.h>

#ifndef __cplusplus
#include <stdbool.h>
#endif

#ifdef __cplusplus
extern "C" {
#endif

/*!
@function
@abstract Creates a JavaScript context group.
@discussion A JSContextGroup associates JavaScript contexts with one another.
 Contexts in the same group may share and exchange JavaScript objects. Sharing and/or exchanging
 JavaScript objects between contexts in different groups will produce undefined behavior.
 When objects from the same context group are used in multiple threads, explicit
 synchronization is required.
@result The created JSContextGroup.
*/
JS_EXPORT JSContextGroupRef JSContextGroupCreate() CF_AVAILABLE(10_6, 7_0);

/*!
@function
@abstract Retains a JavaScript context group.
@param group The JSContextGroup to retain.
@result A JSContextGroup that is the same as group.
*/
JS_EXPORT JSContextGroupRef JSContextGroupRetain(JSContextGroupRef group) CF_AVAILABLE(10_6, 7_0);

/*!
@function
@abstract Releases a JavaScript context group.
@param group The JSContextGroup to release.
*/
JS_EXPORT void JSContextGroupRelease(JSContextGroupRef group) CF_AVAILABLE(10_6, 7_0);

/*!
@function
@abstract Creates a global JavaScript execution context.
@discussion JSGlobalContextCreate allocates a global object and populates it with all the
 built-in JavaScript objects, such as Object, Function, String, and Array.

 In WebKit version 4.0 and later, the context is created in a unique context group.
 Therefore, scripts may execute in it concurrently with scripts executing in other contexts.
 However, you may not use values created in the context in other contexts.
@param globalObjectClass The class to use when creating the global object. Pass 
 NULL to use the default object class.
@result A JSGlobalContext with a global object of class globalObjectClass.
*/
JS_EXPORT JSGlobalContextRef JSGlobalContextCreate(JSClassRef globalObjectClass) CF_AVAILABLE(10_5, 7_0);

/*!
@function
@abstract Creates a global JavaScript execution context in the context group provided.
@discussion JSGlobalContextCreateInGroup allocates a global object and populates it with
 all the built-in JavaScript objects, such as Object, Function, String, and Array.
@param globalObjectClass The class to use when creating the global object. Pass
 NULL to use the default object class.
@param group The context group to use. The created global context retains the group.
 Pass NULL to create a unique group for the context.
@result A JSGlobalContext with a global object of class globalObjectClass and a context
 group equal to group.
*/
JS_EXPORT JSGlobalContextRef JSGlobalContextCreateInGroup(JSContextGroupRef group, JSClassRef globalObjectClass) CF_AVAILABLE(10_6, 7_0);

/*!
@function
@abstract Retains a global JavaScript execution context.
@param ctx The JSGlobalContext to retain.
@result A JSGlobalContext that is the same as ctx.
*/
JS_EXPORT JSGlobalContextRef JSGlobalContextRetain(JSGlobalContextRef ctx);

/*!
@function
@abstract Releases a global JavaScript execution context.
@param ctx The JSGlobalContext to release.
*/
JS_EXPORT void JSGlobalContextRelease(JSGlobalContextRef ctx);

/*!
@function
@abstract Gets the global object of a JavaScript execution context.
@param ctx The JSContext whose global object you want to get.
@result ctx's global object.
*/
JS_EXPORT JSObjectRef JSContextGetGlobalObject(JSContextRef ctx);

/*!
@function
@abstract Gets the context group to which a JavaScript execution context belongs.
@param ctx The JSContext whose group you want to get.
@result ctx's group.
*/
JS_EXPORT JSContextGroupRef JSContextGetGroup(JSContextRef ctx) CF_AVAILABLE(10_6, 7_0);

/*!
@function
@abstract Gets the global context of a JavaScript execution context.
@param ctx The JSContext whose global context you want to get.
@result ctx's global context.
*/
JS_EXPORT JSGlobalContextRef JSContextGetGlobalContext(JSContextRef ctx) CF_AVAILABLE(10_7, 7_0);

/*!
@function
@abstract Gets a copy of the name of a context.
@param ctx The JSGlobalContext whose name you want to get.
@result The name for ctx.
@discussion A JSGlobalContext's name is exposed for remote debugging to make it
easier to identify the context you would like to attach to.
*/
JS_EXPORT JSStringRef JSGlobalContextCopyName(JSGlobalContextRef ctx) CF_AVAILABLE(10_10, 8_0);

/*!
@function
@abstract Sets the remote debugging name for a context.
@param ctx The JSGlobalContext that you want to name.
@param name The remote debugging name to set on ctx.
*/
JS_EXPORT void JSGlobalContextSetName(JSGlobalContextRef ctx, JSStringRef name) CF_AVAILABLE(10_10, 8_0);

#ifdef __cplusplus
}
#endif

#endif /* JSContextRef_h */
Commit	Line	Data
b37bf2e1	1	/*
81345200	2	* Copyright (C) 2006 Apple Inc. All rights reserved.
b37bf2e1 A	3	*
	4	* Redistribution and use in source and binary forms, with or without
	5	* modification, are permitted provided that the following conditions
	6	* are met:
	7	* 1. Redistributions of source code must retain the above copyright
	8	* notice, this list of conditions and the following disclaimer.
	9	* 2. Redistributions in binary form must reproduce the above copyright
	10	* notice, this list of conditions and the following disclaimer in the
	11	* documentation and/or other materials provided with the distribution.
	12	*
81345200	13	* THIS SOFTWARE IS PROVIDED BY APPLE INC. ``AS IS'' AND ANY
b37bf2e1 A	14	* EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
b37bf2e1 A	15	* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
81345200	16	* PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR
b37bf2e1 A	17	* CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
	18	* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
	19	* PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
	20	* PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
	21	* OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
	22	* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
81345200	23	* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
b37bf2e1 A	24	*/
	25
	26	#ifndef JSContextRef_h
	27	#define JSContextRef_h
	28
	29	#include <JavaScriptCore/JSObjectRef.h>
	30	#include <JavaScriptCore/JSValueRef.h>
9dae56ea	31	#include <JavaScriptCore/WebKitAvailability.h>
b37bf2e1	32
9dae56ea	33	#ifndef __cplusplus
b37bf2e1	34	#include <stdbool.h>
9dae56ea	35	#endif
b37bf2e1 A	36
	37	#ifdef __cplusplus
	38	extern "C" {
	39	#endif
	40
9dae56ea A	41	/*!
	42	@function
	43	@abstract Creates a JavaScript context group.
	44	@discussion A JSContextGroup associates JavaScript contexts with one another.
	45	Contexts in the same group may share and exchange JavaScript objects. Sharing and/or exchanging
	46	JavaScript objects between contexts in different groups will produce undefined behavior.
	47	When objects from the same context group are used in multiple threads, explicit
	48	synchronization is required.
	49	@result The created JSContextGroup.
	50	*/
81345200	51	JS_EXPORT JSContextGroupRef JSContextGroupCreate() CF_AVAILABLE(10_6, 7_0);
9dae56ea A	52
	53	/*!
	54	@function
	55	@abstract Retains a JavaScript context group.
	56	@param group The JSContextGroup to retain.
	57	@result A JSContextGroup that is the same as group.
	58	*/
81345200	59	JS_EXPORT JSContextGroupRef JSContextGroupRetain(JSContextGroupRef group) CF_AVAILABLE(10_6, 7_0);
9dae56ea A	60
	61	/*!
	62	@function
	63	@abstract Releases a JavaScript context group.
	64	@param group The JSContextGroup to release.
	65	*/
81345200	66	JS_EXPORT void JSContextGroupRelease(JSContextGroupRef group) CF_AVAILABLE(10_6, 7_0);
9dae56ea	67
b37bf2e1 A	68	/*!
	69	@function
	70	@abstract Creates a global JavaScript execution context.
	71	@discussion JSGlobalContextCreate allocates a global object and populates it with all the
	72	built-in JavaScript objects, such as Object, Function, String, and Array.
9dae56ea A	73
	74	In WebKit version 4.0 and later, the context is created in a unique context group.
	75	Therefore, scripts may execute in it concurrently with scripts executing in other contexts.
	76	However, you may not use values created in the context in other contexts.
b37bf2e1 A	77	@param globalObjectClass The class to use when creating the global object. Pass
	78	NULL to use the default object class.
	79	@result A JSGlobalContext with a global object of class globalObjectClass.
	80	*/
81345200	81	JS_EXPORT JSGlobalContextRef JSGlobalContextCreate(JSClassRef globalObjectClass) CF_AVAILABLE(10_5, 7_0);
9dae56ea A	82
	83	/*!
	84	@function
	85	@abstract Creates a global JavaScript execution context in the context group provided.
	86	@discussion JSGlobalContextCreateInGroup allocates a global object and populates it with
	87	all the built-in JavaScript objects, such as Object, Function, String, and Array.
	88	@param globalObjectClass The class to use when creating the global object. Pass
	89	NULL to use the default object class.
	90	@param group The context group to use. The created global context retains the group.
	91	Pass NULL to create a unique group for the context.
	92	@result A JSGlobalContext with a global object of class globalObjectClass and a context
	93	group equal to group.
	94	*/
81345200	95	JS_EXPORT JSGlobalContextRef JSGlobalContextCreateInGroup(JSContextGroupRef group, JSClassRef globalObjectClass) CF_AVAILABLE(10_6, 7_0);
b37bf2e1 A	96
	97	/*!
	98	@function
	99	@abstract Retains a global JavaScript execution context.
	100	@param ctx The JSGlobalContext to retain.
	101	@result A JSGlobalContext that is the same as ctx.
	102	*/
	103	JS_EXPORT JSGlobalContextRef JSGlobalContextRetain(JSGlobalContextRef ctx);
	104
	105	/*!
	106	@function
	107	@abstract Releases a global JavaScript execution context.
	108	@param ctx The JSGlobalContext to release.
	109	*/
	110	JS_EXPORT void JSGlobalContextRelease(JSGlobalContextRef ctx);
	111
	112	/*!
	113	@function
	114	@abstract Gets the global object of a JavaScript execution context.
	115	@param ctx The JSContext whose global object you want to get.
	116	@result ctx's global object.
	117	*/
	118	JS_EXPORT JSObjectRef JSContextGetGlobalObject(JSContextRef ctx);
	119
9dae56ea A	120	/*!
	121	@function
	122	@abstract Gets the context group to which a JavaScript execution context belongs.
	123	@param ctx The JSContext whose group you want to get.
	124	@result ctx's group.
	125	*/
81345200 A	126	JS_EXPORT JSContextGroupRef JSContextGetGroup(JSContextRef ctx) CF_AVAILABLE(10_6, 7_0);
	127
	128	/*!
	129	@function
	130	@abstract Gets the global context of a JavaScript execution context.
	131	@param ctx The JSContext whose global context you want to get.
	132	@result ctx's global context.
	133	*/
	134	JS_EXPORT JSGlobalContextRef JSContextGetGlobalContext(JSContextRef ctx) CF_AVAILABLE(10_7, 7_0);
	135
	136	/*!
	137	@function
	138	@abstract Gets a copy of the name of a context.
	139	@param ctx The JSGlobalContext whose name you want to get.
	140	@result The name for ctx.
	141	@discussion A JSGlobalContext's name is exposed for remote debugging to make it
	142	easier to identify the context you would like to attach to.
	143	*/
	144	JS_EXPORT JSStringRef JSGlobalContextCopyName(JSGlobalContextRef ctx) CF_AVAILABLE(10_10, 8_0);
	145
	146	/*!
	147	@function
	148	@abstract Sets the remote debugging name for a context.
	149	@param ctx The JSGlobalContext that you want to name.
	150	@param name The remote debugging name to set on ctx.
	151	*/
	152	JS_EXPORT void JSGlobalContextSetName(JSGlobalContextRef ctx, JSStringRef name) CF_AVAILABLE(10_10, 8_0);
9dae56ea	153
b37bf2e1 A	154	#ifdef __cplusplus
	155	}
	156	#endif
	157
9dae56ea	158	#endif /* JSContextRef_h */