Reviewed by Geoff.
[WebKit-https.git] / JavaScriptCore / API / JSBase.h
1 // -*- mode: c++; c-basic-offset: 4 -*-
2 /*
3  * Copyright (C) 2006 Apple Computer, Inc.  All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  * 1. Redistributions of source code must retain the above copyright
9  *    notice, this list of conditions and the following disclaimer.
10  * 2. Redistributions in binary form must reproduce the above copyright
11  *    notice, this list of conditions and the following disclaimer in the
12  *    documentation and/or other materials provided with the distribution.
13  *
14  * THIS SOFTWARE IS PROVIDED BY APPLE COMPUTER, INC. ``AS IS'' AND ANY
15  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
17  * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL APPLE COMPUTER, INC. OR
18  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
19  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
20  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
21  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
22  * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
23  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
24  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 
25  */
26
27 #ifndef JSBase_h
28 #define JSBase_h
29
30 /* JS runtime interface types */
31 typedef struct __JSContext* JSContextRef;
32 typedef struct __JSCharBuffer* JSCharBufferRef;
33 typedef struct __JSPropertyList* JSPropertyListRef;
34 typedef struct __JSPropertyListEnumerator* JSPropertyListEnumeratorRef;
35
36 /* Base type of all JS values, and polymorphic functions on them */
37 typedef void* JSValueRef;
38
39 typedef struct __JSObject* JSObjectRef;
40
41 #ifdef __cplusplus
42 extern "C" {
43 #endif
44
45 // Returns true for successful execution, false for uncaught exception. 
46 // returnValue will contain value of last evaluated statement or exception value.
47 /*!
48   @function JSEvaluate
49   Evaluates a string of JavaScript code
50   @param context            execution context to use
51   @param thisValue          object to use as the "this" value, or NULL to use the global object as "this"
52   @param script             a string containing the script source code
53   @param sourceURL          URL to the file containing the source, or NULL - this is only used for error reporting
54   @param startingLineNumber starting line number in the source at sourceURL - this is only used for error reporting
55   @param returnValue        result of evaluation if successful, or value of exception
56   @result                   true if evaluation succeeded, false if an uncaught exception or error occured
57 */
58 bool JSEvaluate(JSContextRef context, JSValueRef thisValue, JSCharBufferRef script, JSCharBufferRef sourceURL, int startingLineNumber, JSValueRef* returnValue);
59
60 /*!
61   @function JSCheckSyntax
62   Checks for syntax errors in a string of JavaScript code
63   @param context execution context to use
64   @param script a string containing the script source code
65   @result true if the script is syntactically correct, false otherwise
66
67 */
68 bool JSCheckSyntax(JSContextRef context, JSCharBufferRef script);
69
70 // Garbage collection
71 /*!
72   @function JSGCProtect
73   Protect a JavaScript value from garbage collection; a value may be
74   protected multiple times and must be unprotected an equal number of
75   times to become collectable again.
76 */
77 void JSGCProtect(JSValueRef value);
78
79 /*!
80   @function JSGCProtect
81   Stop protecting a JavaScript value from garbage collection; a value may be
82   protected multiple times and must be unprotected an equal number of
83   times to become collectable again.
84 */
85 void JSGCUnprotect(JSValueRef value);
86
87 /*! 
88   @function JSGCCollect
89   Immediately perform a JavaScript garbage collection. JavaScript
90   values that are on the machine stack, in a register, protected, set
91   as the global object of any interpreter, or reachable from any such
92   value will not be collected. It is not normally necessary to call
93   this function directly; the JS runtime will garbage collect as
94   needed.
95 */
96 void JSGCCollect(void);
97
98 #ifdef __cplusplus
99 }
100 #endif
101
102 #endif // JSBase_h