1  /*
  2   * Copyright (C) 2006 Apple Inc.  All rights reserved.
  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   *
 13   * THIS SOFTWARE IS PROVIDED BY APPLE INC. ``AS IS'' AND ANY
 14   * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 15   * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 16   * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL APPLE INC. OR
 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
 23   * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 24   */
 25  
 26  #ifndef JSContextRef_h
 27  #define JSContextRef_h
 28  
 29  #include <JavaScriptCore/JSObjectRef.h>
 30  #include <JavaScriptCore/JSValueRef.h>
 31  #include <JavaScriptCore/WebKitAvailability.h>
 32  
 33  #ifndef __cplusplus
 34  #include <stdbool.h>
 35  #endif
 36  
 37  #ifdef __cplusplus
 38  extern "C" {
 39  #endif
 40  
 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  
 50   A JSContextGroup may need to run deferred tasks on a run loop, such as garbage collection
 51   or resolving WebAssembly compilations. By default, calling JSContextGroupCreate will use
 52   the run loop of the thread it was called on. Currently, there is no API to change a
 53   JSContextGroup's run loop once it has been created.
 54  @result The created JSContextGroup.
 55  */
 56  JS_EXPORT JSContextGroupRef JSContextGroupCreate(void) JSC_API_AVAILABLE(macos(10.6), ios(7.0));
 57  
 58  /*!
 59  @function
 60  @abstract Retains a JavaScript context group.
 61  @param group The JSContextGroup to retain.
 62  @result A JSContextGroup that is the same as group.
 63  */
 64  JS_EXPORT JSContextGroupRef JSContextGroupRetain(JSContextGroupRef group) JSC_API_AVAILABLE(macos(10.6), ios(7.0));
 65  
 66  /*!
 67  @function
 68  @abstract Releases a JavaScript context group.
 69  @param group The JSContextGroup to release.
 70  */
 71  JS_EXPORT void JSContextGroupRelease(JSContextGroupRef group) JSC_API_AVAILABLE(macos(10.6), ios(7.0));
 72  
 73  /*!
 74  @function
 75  @abstract Creates a global JavaScript execution context.
 76  @discussion JSGlobalContextCreate allocates a global object and populates it with all the
 77   built-in JavaScript objects, such as Object, Function, String, and Array.
 78  
 79   In WebKit version 4.0 and later, the context is created in a unique context group.
 80   Therefore, scripts may execute in it concurrently with scripts executing in other contexts.
 81   However, you may not use values created in the context in other contexts.
 82  @param globalObjectClass The class to use when creating the global object. Pass 
 83   NULL to use the default object class.
 84  @result A JSGlobalContext with a global object of class globalObjectClass.
 85  */
 86  JS_EXPORT JSGlobalContextRef JSGlobalContextCreate(JSClassRef globalObjectClass) JSC_API_AVAILABLE(macos(10.5), ios(7.0));
 87  
 88  /*!
 89  @function
 90  @abstract Creates a global JavaScript execution context in the context group provided.
 91  @discussion JSGlobalContextCreateInGroup allocates a global object and populates it with
 92   all the built-in JavaScript objects, such as Object, Function, String, and Array.
 93  @param globalObjectClass The class to use when creating the global object. Pass
 94   NULL to use the default object class.
 95  @param group The context group to use. The created global context retains the group.
 96   Pass NULL to create a unique group for the context.
 97  @result A JSGlobalContext with a global object of class globalObjectClass and a context
 98   group equal to group.
 99  */
100  JS_EXPORT JSGlobalContextRef JSGlobalContextCreateInGroup(JSContextGroupRef group, JSClassRef globalObjectClass) JSC_API_AVAILABLE(macos(10.6), ios(7.0));
101  
102  /*!
103  @function
104  @abstract Retains a global JavaScript execution context.
105  @param ctx The JSGlobalContext to retain.
106  @result A JSGlobalContext that is the same as ctx.
107  */
108  JS_EXPORT JSGlobalContextRef JSGlobalContextRetain(JSGlobalContextRef ctx);
109  
110  /*!
111  @function
112  @abstract Releases a global JavaScript execution context.
113  @param ctx The JSGlobalContext to release.
114  */
115  JS_EXPORT void JSGlobalContextRelease(JSGlobalContextRef ctx);
116  
117  /*!
118  @function
119  @abstract Gets the global object of a JavaScript execution context.
120  @param ctx The JSContext whose global object you want to get.
121  @result ctx's global object.
122  */
123  JS_EXPORT JSObjectRef JSContextGetGlobalObject(JSContextRef ctx);
124  
125  /*!
126  @function
127  @abstract Gets the context group to which a JavaScript execution context belongs.
128  @param ctx The JSContext whose group you want to get.
129  @result ctx's group.
130  */
131  JS_EXPORT JSContextGroupRef JSContextGetGroup(JSContextRef ctx) JSC_API_AVAILABLE(macos(10.6), ios(7.0));
132  
133  /*!
134  @function
135  @abstract Gets the global context of a JavaScript execution context.
136  @param ctx The JSContext whose global context you want to get.
137  @result ctx's global context.
138  */
139  JS_EXPORT JSGlobalContextRef JSContextGetGlobalContext(JSContextRef ctx) JSC_API_AVAILABLE(macos(10.7), ios(7.0));
140  
141  /*!
142  @function
143  @abstract Gets a copy of the name of a context.
144  @param ctx The JSGlobalContext whose name you want to get.
145  @result The name for ctx.
146  @discussion A JSGlobalContext's name is exposed for remote debugging to make it
147  easier to identify the context you would like to attach to.
148  */
149  JS_EXPORT JSStringRef JSGlobalContextCopyName(JSGlobalContextRef ctx) JSC_API_AVAILABLE(macos(10.10), ios(8.0));
150  
151  /*!
152  @function
153  @abstract Sets the remote debugging name for a context.
154  @param ctx The JSGlobalContext that you want to name.
155  @param name The remote debugging name to set on ctx.
156  */
157  JS_EXPORT void JSGlobalContextSetName(JSGlobalContextRef ctx, JSStringRef name) JSC_API_AVAILABLE(macos(10.10), ios(8.0));
158  
159  #ifdef __cplusplus
160  }
161  #endif
162  
163  #endif /* JSContextRef_h */