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 JSBase_h
27#define JSBase_h
28
29#ifndef __cplusplus
30#include <stdbool.h>
31#endif
32
33#ifdef __OBJC__
34#import <Foundation/Foundation.h>
35#endif
36
37/* JavaScript engine interface */
38
39/*! @typedef JSContextGroupRef A group that associates JavaScript contexts with one another. Contexts in the same group may share and exchange JavaScript objects. */
40typedef const struct OpaqueJSContextGroup* JSContextGroupRef;
41
42/*! @typedef JSContextRef A JavaScript execution context. Holds the global object and other execution state. */
43typedef const struct OpaqueJSContext* JSContextRef;
44
45/*! @typedef JSGlobalContextRef A global JavaScript execution context. A JSGlobalContext is a JSContext. */
46typedef struct OpaqueJSContext* JSGlobalContextRef;
47
48/*! @typedef JSStringRef A UTF16 character buffer. The fundamental string representation in JavaScript. */
49typedef struct OpaqueJSString* JSStringRef;
50
51/*! @typedef JSClassRef A JavaScript class. Used with JSObjectMake to construct objects with custom behavior. */
52typedef struct OpaqueJSClass* JSClassRef;
53
54/*! @typedef JSPropertyNameArrayRef An array of JavaScript property names. */
55typedef struct OpaqueJSPropertyNameArray* JSPropertyNameArrayRef;
56
57/*! @typedef JSPropertyNameAccumulatorRef An ordered set used to collect the names of a JavaScript object's properties. */
58typedef struct OpaqueJSPropertyNameAccumulator* JSPropertyNameAccumulatorRef;
59
60/*! @typedef JSTypedArrayBytesDeallocator A function used to deallocate bytes passed to a Typed Array constructor. The function should take two arguments. The first is a pointer to the bytes that were originally passed to the Typed Array constructor. The second is a pointer to additional information desired at the time the bytes are to be freed. */
61typedef void (*JSTypedArrayBytesDeallocator)(void* bytes, void* deallocatorContext);
62
63/* JavaScript data types */
64
65/*! @typedef JSValueRef A JavaScript value. The base type for all JavaScript values, and polymorphic functions on them. */
66typedef const struct OpaqueJSValue* JSValueRef;
67
68/*! @typedef JSObjectRef A JavaScript object. A JSObject is a JSValue. */
69typedef struct OpaqueJSValue* JSObjectRef;
70
71/* Clang's __has_declspec_attribute emulation */
72/* https://clang.llvm.org/docs/LanguageExtensions.html#has-declspec-attribute */
73
74#ifndef __has_declspec_attribute
75#define __has_declspec_attribute(x) 0
76#endif
77
78/* JavaScript symbol exports */
79/* These rules should stay the same as in WebKit/Shared/API/c/WKDeclarationSpecifiers.h */
80
81#undef JS_EXPORT
82#if defined(JS_NO_EXPORT)
83#define JS_EXPORT
84#elif defined(WIN32) || defined(_WIN32) || defined(__CC_ARM) || defined(__ARMCC__) || (__has_declspec_attribute(dllimport) && __has_declspec_attribute(dllexport))
85#if defined(BUILDING_JavaScriptCore) || defined(STATICALLY_LINKED_WITH_JavaScriptCore)
86#define JS_EXPORT __declspec(dllexport)
87#else
88#define JS_EXPORT __declspec(dllimport)
89#endif
90#elif defined(__GNUC__)
91#define JS_EXPORT __attribute__((visibility("default")))
92#else /* !defined(JS_NO_EXPORT) */
93#define JS_EXPORT
94#endif /* defined(JS_NO_EXPORT) */
95
96#ifdef __cplusplus
97extern "C" {
98#endif
99
100/* Script Evaluation */
101
102/*!
103@function JSEvaluateScript
104@abstract Evaluates a string of JavaScript.
105@param ctx The execution context to use.
106@param script A JSString containing the script to evaluate.
107@param thisObject The object to use as "this," or NULL to use the global object as "this."
108@param sourceURL A JSString containing a URL for the script's source file. This is used by debuggers and when reporting exceptions. Pass NULL if you do not care to include source file information.
109@param startingLineNumber An integer value specifying the script's starting line number in the file located at sourceURL. This is only used when reporting exceptions. The value is one-based, so the first line is line 1 and invalid values are clamped to 1.
110@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
111@result The JSValue that results from evaluating script, or NULL if an exception is thrown.
112*/
113JS_EXPORT JSValueRef JSEvaluateScript(JSContextRef ctx, JSStringRef script, JSObjectRef thisObject, JSStringRef sourceURL, int startingLineNumber, JSValueRef* exception);
114
115/*!
116@function JSCheckScriptSyntax
117@abstract Checks for syntax errors in a string of JavaScript.
118@param ctx The execution context to use.
119@param script A JSString containing the script to check for syntax errors.
120@param sourceURL A JSString containing a URL for the script's source file. This is only used when reporting exceptions. Pass NULL if you do not care to include source file information in exceptions.
121@param startingLineNumber An integer value specifying the script's starting line number in the file located at sourceURL. This is only used when reporting exceptions. The value is one-based, so the first line is line 1 and invalid values are clamped to 1.
122@param exception A pointer to a JSValueRef in which to store a syntax error exception, if any. Pass NULL if you do not care to store a syntax error exception.
123@result true if the script is syntactically correct, otherwise false.
124*/
125JS_EXPORT bool JSCheckScriptSyntax(JSContextRef ctx, JSStringRef script, JSStringRef sourceURL, int startingLineNumber, JSValueRef* exception);
126
127/*!
128@function JSGarbageCollect
129@abstract Performs a JavaScript garbage collection.
130@param ctx The execution context to use.
131@discussion JavaScript values that are on the machine stack, in a register,
132 protected by JSValueProtect, set as the global object of an execution context,
133 or reachable from any such value will not be collected.
134
135 During JavaScript execution, you are not required to call this function; the
136 JavaScript engine will garbage collect as needed. JavaScript values created
137 within a context group are automatically destroyed when the last reference
138 to the context group is released.
139*/
140JS_EXPORT void JSGarbageCollect(JSContextRef ctx);
141
142#ifdef __cplusplus
143}
144#endif
145
146/* Enable the Objective-C API for platforms with a modern runtime. NOTE: This is duplicated in VM.h. */
147#if !defined(JSC_OBJC_API_ENABLED)
148#if (defined(__clang__) && defined(__APPLE__) && ((defined(__MAC_OS_X_VERSION_MIN_REQUIRED) && !defined(__i386__)) || (defined(TARGET_OS_IPHONE) && TARGET_OS_IPHONE)))
149#define JSC_OBJC_API_ENABLED 1
150#else
151#define JSC_OBJC_API_ENABLED 0
152#endif
153#endif
154
155#endif /* JSBase_h */
156