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 JSValueRef_h 27 #define JSValueRef_h 28 29 #include <JavaScriptCore/JSBase.h> 30 #include <JavaScriptCore/WebKitAvailability.h> 31 32 #ifndef __cplusplus 33 #include <stdbool.h> 34 #endif 35 36 /*! 37 @enum JSType 38 @abstract A constant identifying the type of a JSValue. 39 @constant kJSTypeUndefined The unique undefined value. 40 @constant kJSTypeNull The unique null value. 41 @constant kJSTypeBoolean A primitive boolean value, one of true or false. 42 @constant kJSTypeNumber A primitive number value. 43 @constant kJSTypeString A primitive string value. 44 @constant kJSTypeObject An object value (meaning that this JSValueRef is a JSObjectRef). 45 */ 46 typedef enum { 47 kJSTypeUndefined, 48 kJSTypeNull, 49 kJSTypeBoolean, 50 kJSTypeNumber, 51 kJSTypeString, 52 kJSTypeObject 53 } JSType; 54 55 #ifdef __cplusplus 56 extern "C" { 57 #endif 58 59 /*! 60 @function 61 @abstract Returns a JavaScript value's type. 62 @param ctx The execution context to use. 63 @param value The JSValue whose type you want to obtain. 64 @result A value of type JSType that identifies value's type. 65 */ 66 JS_EXPORT JSType JSValueGetType(JSContextRef ctx, JSValueRef value); 67 68 /*! 69 @function 70 @abstract Tests whether a JavaScript value's type is the undefined type. 71 @param ctx The execution context to use. 72 @param value The JSValue to test. 73 @result true if value's type is the undefined type, otherwise false. 74 */ 75 JS_EXPORT bool JSValueIsUndefined(JSContextRef ctx, JSValueRef value); 76 77 /*! 78 @function 79 @abstract Tests whether a JavaScript value's type is the null type. 80 @param ctx The execution context to use. 81 @param value The JSValue to test. 82 @result true if value's type is the null type, otherwise false. 83 */ 84 JS_EXPORT bool JSValueIsNull(JSContextRef ctx, JSValueRef value); 85 86 /*! 87 @function 88 @abstract Tests whether a JavaScript value's type is the boolean type. 89 @param ctx The execution context to use. 90 @param value The JSValue to test. 91 @result true if value's type is the boolean type, otherwise false. 92 */ 93 JS_EXPORT bool JSValueIsBoolean(JSContextRef ctx, JSValueRef value); 94 95 /*! 96 @function 97 @abstract Tests whether a JavaScript value's type is the number type. 98 @param ctx The execution context to use. 99 @param value The JSValue to test. 100 @result true if value's type is the number type, otherwise false. 101 */ 102 JS_EXPORT bool JSValueIsNumber(JSContextRef ctx, JSValueRef value); 103 104 /*! 105 @function 106 @abstract Tests whether a JavaScript value's type is the string type. 107 @param ctx The execution context to use. 108 @param value The JSValue to test. 109 @result true if value's type is the string type, otherwise false. 110 */ 111 JS_EXPORT bool JSValueIsString(JSContextRef ctx, JSValueRef value); 112 113 /*! 114 @function 115 @abstract Tests whether a JavaScript value's type is the object type. 116 @param ctx The execution context to use. 117 @param value The JSValue to test. 118 @result true if value's type is the object type, otherwise false. 119 */ 120 JS_EXPORT bool JSValueIsObject(JSContextRef ctx, JSValueRef value); 121 122 /*! 123 @function 124 @abstract Tests whether a JavaScript value is an object with a given class in its class chain. 125 @param ctx The execution context to use. 126 @param value The JSValue to test. 127 @param jsClass The JSClass to test against. 128 @result true if value is an object and has jsClass in its class chain, otherwise false. 129 */ 130 JS_EXPORT bool JSValueIsObjectOfClass(JSContextRef ctx, JSValueRef value, JSClassRef jsClass); 131 132 /* Comparing values */ 133 134 /*! 135 @function 136 @abstract Tests whether two JavaScript values are equal, as compared by the JS == operator. 137 @param ctx The execution context to use. 138 @param a The first value to test. 139 @param b The second value to test. 140 @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. 141 @result true if the two values are equal, false if they are not equal or an exception is thrown. 142 */ 143 JS_EXPORT bool JSValueIsEqual(JSContextRef ctx, JSValueRef a, JSValueRef b, JSValueRef* exception); 144 145 /*! 146 @function 147 @abstract Tests whether two JavaScript values are strict equal, as compared by the JS === operator. 148 @param ctx The execution context to use. 149 @param a The first value to test. 150 @param b The second value to test. 151 @result true if the two values are strict equal, otherwise false. 152 */ 153 JS_EXPORT bool JSValueIsStrictEqual(JSContextRef ctx, JSValueRef a, JSValueRef b); 154 155 /*! 156 @function 157 @abstract Tests whether a JavaScript value is an object constructed by a given constructor, as compared by the JS instanceof operator. 158 @param ctx The execution context to use. 159 @param value The JSValue to test. 160 @param constructor The constructor to test against. 161 @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. 162 @result true if value is an object constructed by constructor, as compared by the JS instanceof operator, otherwise false. 163 */ 164 JS_EXPORT bool JSValueIsInstanceOfConstructor(JSContextRef ctx, JSValueRef value, JSObjectRef constructor, JSValueRef* exception); 165 166 /* Creating values */ 167 168 /*! 169 @function 170 @abstract Creates a JavaScript value of the undefined type. 171 @param ctx The execution context to use. 172 @result The unique undefined value. 173 */ 174 JS_EXPORT JSValueRef JSValueMakeUndefined(JSContextRef ctx); 175 176 /*! 177 @function 178 @abstract Creates a JavaScript value of the null type. 179 @param ctx The execution context to use. 180 @result The unique null value. 181 */ 182 JS_EXPORT JSValueRef JSValueMakeNull(JSContextRef ctx); 183 184 /*! 185 @function 186 @abstract Creates a JavaScript value of the boolean type. 187 @param ctx The execution context to use. 188 @param boolean The bool to assign to the newly created JSValue. 189 @result A JSValue of the boolean type, representing the value of boolean. 190 */ 191 JS_EXPORT JSValueRef JSValueMakeBoolean(JSContextRef ctx, bool boolean); 192 193 /*! 194 @function 195 @abstract Creates a JavaScript value of the number type. 196 @param ctx The execution context to use. 197 @param number The double to assign to the newly created JSValue. 198 @result A JSValue of the number type, representing the value of number. 199 */ 200 JS_EXPORT JSValueRef JSValueMakeNumber(JSContextRef ctx, double number); 201 202 /*! 203 @function 204 @abstract Creates a JavaScript value of the string type. 205 @param ctx The execution context to use. 206 @param string The JSString to assign to the newly created JSValue. The 207 newly created JSValue retains string, and releases it upon garbage collection. 208 @result A JSValue of the string type, representing the value of string. 209 */ 210 JS_EXPORT JSValueRef JSValueMakeString(JSContextRef ctx, JSStringRef string); 211 212 /* Converting to and from JSON formatted strings */ 213 214 /*! 215 @function 216 @abstract Creates a JavaScript value from a JSON formatted string. 217 @param ctx The execution context to use. 218 @param string The JSString containing the JSON string to be parsed. 219 @result A JSValue containing the parsed value, or NULL if the input is invalid. 220 */ 221 JS_EXPORT JSValueRef JSValueMakeFromJSONString(JSContextRef ctx, JSStringRef string) AVAILABLE_AFTER_WEBKIT_VERSION_4_0; 222 223 /*! 224 @function 225 @abstract Creates a JavaScript string containing the JSON serialized representation of a JS value. 226 @param ctx The execution context to use. 227 @param value The value to serialize. 228 @param indent The number of spaces to indent when nesting. If 0, the resulting JSON will not contains newlines. The size of the indent is clamped to 10 spaces. 229 @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. 230 @result A JSString with the result of serialization, or NULL if an exception is thrown. 231 */ 232 JS_EXPORT JSStringRef JSValueCreateJSONString(JSContextRef ctx, JSValueRef value, unsigned indent, JSValueRef* exception) AVAILABLE_AFTER_WEBKIT_VERSION_4_0; 233 234 /* Converting to primitive values */ 235 236 /*! 237 @function 238 @abstract Converts a JavaScript value to boolean and returns the resulting boolean. 239 @param ctx The execution context to use. 240 @param value The JSValue to convert. 241 @result The boolean result of conversion. 242 */ 243 JS_EXPORT bool JSValueToBoolean(JSContextRef ctx, JSValueRef value); 244 245 /*! 246 @function 247 @abstract Converts a JavaScript value to number and returns the resulting number. 248 @param ctx The execution context to use. 249 @param value The JSValue to convert. 250 @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. 251 @result The numeric result of conversion, or NaN if an exception is thrown. 252 */ 253 JS_EXPORT double JSValueToNumber(JSContextRef ctx, JSValueRef value, JSValueRef* exception); 254 255 /*! 256 @function 257 @abstract Converts a JavaScript value to string and copies the result into a JavaScript string. 258 @param ctx The execution context to use. 259 @param value The JSValue to convert. 260 @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. 261 @result A JSString with the result of conversion, or NULL if an exception is thrown. Ownership follows the Create Rule. 262 */ 263 JS_EXPORT JSStringRef JSValueToStringCopy(JSContextRef ctx, JSValueRef value, JSValueRef* exception); 264 265 /*! 266 @function 267 @abstract Converts a JavaScript value to object and returns the resulting object. 268 @param ctx The execution context to use. 269 @param value The JSValue to convert. 270 @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. 271 @result The JSObject result of conversion, or NULL if an exception is thrown. 272 */ 273 JS_EXPORT JSObjectRef JSValueToObject(JSContextRef ctx, JSValueRef value, JSValueRef* exception); 274 275 /* Garbage collection */ 276 /*! 277 @function 278 @abstract Protects a JavaScript value from garbage collection. 279 @param ctx The execution context to use. 280 @param value The JSValue to protect. 281 @discussion Use this method when you want to store a JSValue in a global or on the heap, where the garbage collector will not be able to discover your reference to it. 282 283 A value may be protected multiple times and must be unprotected an equal number of times before becoming eligible for garbage collection. 284 */ 285 JS_EXPORT void JSValueProtect(JSContextRef ctx, JSValueRef value); 286 287 /*! 288 @function 289 @abstract Unprotects a JavaScript value from garbage collection. 290 @param ctx The execution context to use. 291 @param value The JSValue to unprotect. 292 @discussion A value may be protected multiple times and must be unprotected an 293 equal number of times before becoming eligible for garbage collection. 294 */ 295 JS_EXPORT void JSValueUnprotect(JSContextRef ctx, JSValueRef value); 296 297 #ifdef __cplusplus 298 } 299 #endif 300 301 #endif /* JSValueRef_h */ 302