API/JSContextRef.h

   1 /*
   2  * Copyright (C) 2006 Apple Computer, 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 COMPUTER, 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 COMPUTER, 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 @result The created JSContextGroup.
  50 */
  51 JS_EXPORT JSContextGroupRef JSContextGroupCreate() AVAILABLE_IN_WEBKIT_VERSION_4_0;
  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 */
  59 JS_EXPORT JSContextGroupRef JSContextGroupRetain(JSContextGroupRef group) AVAILABLE_IN_WEBKIT_VERSION_4_0;
  60
  61 /*!
  62 @function
  63 @abstract Releases a JavaScript context group.
  64 @param group The JSContextGroup to release.
  65 */
  66 JS_EXPORT void JSContextGroupRelease(JSContextGroupRef group) AVAILABLE_IN_WEBKIT_VERSION_4_0;
  67
  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.
  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.
  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 */
  81 JS_EXPORT JSGlobalContextRef JSGlobalContextCreate(JSClassRef globalObjectClass) AVAILABLE_WEBKIT_VERSION_3_0_AND_LATER;
  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 */
  95 JS_EXPORT JSGlobalContextRef JSGlobalContextCreateInGroup(JSContextGroupRef group, JSClassRef globalObjectClass) AVAILABLE_IN_WEBKIT_VERSION_4_0;
  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
 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 */
 126 JS_EXPORT JSContextGroupRef JSContextGetGroup(JSContextRef ctx) AVAILABLE_IN_WEBKIT_VERSION_4_0;
 127
 128 #ifdef __cplusplus
 129 }
 130 #endif
 131
 132 #endif /* JSContextRef_h */