objc2_javascript_core/generated/JSContext.rs
1//! This file has been automatically generated by `objc2`'s `header-translator`.
2//! DO NOT EDIT
3use core::ffi::*;
4use core::ptr::NonNull;
5#[cfg(feature = "objc2")]
6use objc2::__framework_prelude::*;
7#[cfg(feature = "objc2-foundation")]
8use objc2_foundation::*;
9
10use crate::*;
11
12#[cfg(feature = "objc2")]
13extern_class!(
14 /// A JSContext is a JavaScript execution environment. All
15 /// JavaScript execution takes place within a context, and all JavaScript values
16 /// are tied to a context.
17 ///
18 /// See also [Apple's documentation](https://developer.apple.com/documentation/javascriptcore/jscontext?language=objc)
19 #[unsafe(super(NSObject))]
20 #[derive(Debug, PartialEq, Eq, Hash)]
21 #[cfg(feature = "objc2")]
22 pub struct JSContext;
23);
24
25#[cfg(feature = "objc2")]
26extern_conformance!(
27 unsafe impl NSObjectProtocol for JSContext {}
28);
29
30#[cfg(feature = "objc2")]
31impl JSContext {
32 extern_methods!(
33 /// Create a JSContext.
34 ///
35 /// Returns: The new context.
36 #[unsafe(method(init))]
37 #[unsafe(method_family = init)]
38 pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>;
39
40 #[cfg(feature = "JSVirtualMachine")]
41 /// Create a JSContext in the specified virtual machine.
42 ///
43 /// Parameter `virtualMachine`: The JSVirtualMachine in which the context will be created.
44 ///
45 /// Returns: The new context.
46 #[unsafe(method(initWithVirtualMachine:))]
47 #[unsafe(method_family = init)]
48 pub unsafe fn initWithVirtualMachine(
49 this: Allocated<Self>,
50 virtual_machine: Option<&JSVirtualMachine>,
51 ) -> Option<Retained<Self>>;
52
53 #[cfg(all(feature = "JSValue", feature = "objc2-foundation"))]
54 /// Evaluate a string of JavaScript code.
55 ///
56 /// Parameter `script`: A string containing the JavaScript code to evaluate.
57 ///
58 /// Returns: The last value generated by the script.
59 #[unsafe(method(evaluateScript:))]
60 #[unsafe(method_family = none)]
61 pub unsafe fn evaluateScript(&self, script: Option<&NSString>)
62 -> Option<Retained<JSValue>>;
63
64 #[cfg(all(feature = "JSValue", feature = "objc2-foundation"))]
65 /// Evaluate a string of JavaScript code, with a URL for the script's source file.
66 ///
67 /// Parameter `script`: A string containing the JavaScript code to evaluate.
68 ///
69 /// Parameter `sourceURL`: A URL for the script's source file. Used by debuggers and when reporting exceptions. This parameter is informative only: it does not change the behavior of the script.
70 ///
71 /// Returns: The last value generated by the script.
72 #[unsafe(method(evaluateScript:withSourceURL:))]
73 #[unsafe(method_family = none)]
74 pub unsafe fn evaluateScript_withSourceURL(
75 &self,
76 script: Option<&NSString>,
77 source_url: Option<&NSURL>,
78 ) -> Option<Retained<JSValue>>;
79
80 /// Get the JSContext that is currently executing.
81 ///
82 /// This method may be called from within an Objective-C block or method invoked
83 /// as a callback from JavaScript to retrieve the callback's context. Outside of
84 /// a callback from JavaScript this method will return nil.
85 ///
86 /// Returns: The currently executing JSContext or nil if there isn't one.
87 #[unsafe(method(currentContext))]
88 #[unsafe(method_family = none)]
89 pub unsafe fn currentContext() -> Option<Retained<JSContext>>;
90
91 #[cfg(feature = "JSValue")]
92 /// Get the JavaScript function that is currently executing.
93 ///
94 /// This method may be called from within an Objective-C block or method invoked
95 /// as a callback from JavaScript to retrieve the callback's context. Outside of
96 /// a callback from JavaScript this method will return nil.
97 ///
98 /// Returns: The currently executing JavaScript function or nil if there isn't one.
99 #[unsafe(method(currentCallee))]
100 #[unsafe(method_family = none)]
101 pub unsafe fn currentCallee() -> Option<Retained<JSValue>>;
102
103 #[cfg(feature = "JSValue")]
104 /// Get the
105 /// <code>
106 /// this
107 /// </code>
108 /// value of the currently executing method.
109 ///
110 /// This method may be called from within an Objective-C block or method invoked
111 /// as a callback from JavaScript to retrieve the callback's this value. Outside
112 /// of a callback from JavaScript this method will return nil.
113 ///
114 /// Returns: The current
115 /// <code>
116 /// this
117 /// </code>
118 /// value or nil if there isn't one.
119 #[unsafe(method(currentThis))]
120 #[unsafe(method_family = none)]
121 pub unsafe fn currentThis() -> Option<Retained<JSValue>>;
122
123 #[cfg(feature = "objc2-foundation")]
124 /// Get the arguments to the current callback.
125 ///
126 /// This method may be called from within an Objective-C block or method invoked
127 /// as a callback from JavaScript to retrieve the callback's arguments, objects
128 /// in the returned array are instances of JSValue. Outside of a callback from
129 /// JavaScript this method will return nil.
130 ///
131 /// Returns: An NSArray of the arguments nil if there is no current callback.
132 #[unsafe(method(currentArguments))]
133 #[unsafe(method_family = none)]
134 pub unsafe fn currentArguments() -> Option<Retained<NSArray>>;
135
136 #[cfg(feature = "JSValue")]
137 /// Get the global object of the context.
138 ///
139 /// This method retrieves the global object of the JavaScript execution context.
140 /// Instances of JSContext originating from WebKit will return a reference to the
141 /// WindowProxy object.
142 ///
143 /// Returns: The global object.
144 #[unsafe(method(globalObject))]
145 #[unsafe(method_family = none)]
146 pub unsafe fn globalObject(&self) -> Option<Retained<JSValue>>;
147
148 #[cfg(feature = "JSValue")]
149 /// The
150 /// <code>
151 /// exception
152 /// </code>
153 /// property may be used to throw an exception to JavaScript.
154 ///
155 /// Before a callback is made from JavaScript to an Objective-C block or method,
156 /// the prior value of the exception property will be preserved and the property
157 /// will be set to nil. After the callback has completed the new value of the
158 /// exception property will be read, and prior value restored. If the new value
159 /// of exception is not nil, the callback will result in that value being thrown.
160 ///
161 /// This property may also be used to check for uncaught exceptions arising from
162 /// API function calls (since the default behaviour of
163 /// <code>
164 /// exceptionHandler
165 /// </code>
166 /// is to
167 /// assign an uncaught exception to this property).
168 #[unsafe(method(exception))]
169 #[unsafe(method_family = none)]
170 pub unsafe fn exception(&self) -> Option<Retained<JSValue>>;
171
172 #[cfg(feature = "JSValue")]
173 /// Setter for [`exception`][Self::exception].
174 #[unsafe(method(setException:))]
175 #[unsafe(method_family = none)]
176 pub unsafe fn setException(&self, exception: Option<&JSValue>);
177
178 #[cfg(all(feature = "JSValue", feature = "block2"))]
179 /// If a call to an API function results in an uncaught JavaScript exception, the
180 /// <code>
181 /// exceptionHandler
182 /// </code>
183 /// block will be invoked. The default implementation for the
184 /// exception handler will store the exception to the exception property on
185 /// context. As a consequence the default behaviour is for uncaught exceptions
186 /// occurring within a callback from JavaScript to be rethrown upon return.
187 /// Setting this value to nil will cause all exceptions occurring
188 /// within a callback from JavaScript to be silently caught.
189 #[unsafe(method(exceptionHandler))]
190 #[unsafe(method_family = none)]
191 pub unsafe fn exceptionHandler(
192 &self,
193 ) -> NonNull<block2::DynBlock<dyn Fn(*mut JSContext, *mut JSValue)>>;
194
195 #[cfg(all(feature = "JSValue", feature = "block2"))]
196 /// Setter for [`exceptionHandler`][Self::exceptionHandler].
197 #[unsafe(method(setExceptionHandler:))]
198 #[unsafe(method_family = none)]
199 pub unsafe fn setExceptionHandler(
200 &self,
201 exception_handler: Option<&block2::DynBlock<dyn Fn(*mut JSContext, *mut JSValue)>>,
202 );
203
204 #[cfg(feature = "JSVirtualMachine")]
205 /// All instances of JSContext are associated with a JSVirtualMachine.
206 #[unsafe(method(virtualMachine))]
207 #[unsafe(method_family = none)]
208 pub unsafe fn virtualMachine(&self) -> Option<Retained<JSVirtualMachine>>;
209
210 #[cfg(feature = "objc2-foundation")]
211 /// Name of the JSContext. Exposed when inspecting the context.
212 #[unsafe(method(name))]
213 #[unsafe(method_family = none)]
214 pub unsafe fn name(&self) -> Retained<NSString>;
215
216 #[cfg(feature = "objc2-foundation")]
217 /// Setter for [`name`][Self::name].
218 #[unsafe(method(setName:))]
219 #[unsafe(method_family = none)]
220 pub unsafe fn setName(&self, name: Option<&NSString>);
221
222 /// Controls whether this
223 ///
224 /// ```text
225 /// JSContext
226 /// ```
227 ///
228 /// is inspectable in Web Inspector. The default value is NO.
229 #[unsafe(method(isInspectable))]
230 #[unsafe(method_family = none)]
231 pub unsafe fn isInspectable(&self) -> bool;
232
233 /// Setter for [`isInspectable`][Self::isInspectable].
234 #[unsafe(method(setInspectable:))]
235 #[unsafe(method_family = none)]
236 pub unsafe fn setInspectable(&self, inspectable: bool);
237 );
238}
239
240/// Methods declared on superclass `NSObject`.
241#[cfg(feature = "objc2")]
242impl JSContext {
243 extern_methods!(
244 #[unsafe(method(new))]
245 #[unsafe(method_family = new)]
246 pub unsafe fn new() -> Retained<Self>;
247 );
248}
249
250/// SubscriptSupport.
251/// Instances of JSContext implement the following methods in order to enable
252/// support for subscript access by key and index, for example:
253///
254/// ```text
255/// JSContext *context;
256/// JSValue *v = context[@"X"]; // Get value for "X" from the global object.
257/// context[@"Y"] = v; // Assign 'v' to "Y" on the global object.
258/// ```
259///
260/// An object key passed as a subscript will be converted to a JavaScript value,
261/// and then the value converted to a string used to resolve a property of the
262/// global object.
263#[cfg(feature = "objc2")]
264impl JSContext {
265 extern_methods!(
266 #[cfg(feature = "JSValue")]
267 /// Get a particular property on the global object.
268 ///
269 /// Returns: The JSValue for the global object's property.
270 #[unsafe(method(objectForKeyedSubscript:))]
271 #[unsafe(method_family = none)]
272 pub unsafe fn objectForKeyedSubscript(
273 &self,
274 key: Option<&AnyObject>,
275 ) -> Option<Retained<JSValue>>;
276
277 #[cfg(feature = "objc2-foundation")]
278 /// Set a particular property on the global object.
279 #[unsafe(method(setObject:forKeyedSubscript:))]
280 #[unsafe(method_family = none)]
281 pub unsafe fn setObject_forKeyedSubscript(
282 &self,
283 object: Option<&AnyObject>,
284 key: Option<&NSObject>,
285 );
286 );
287}
288
289/// JSContextRefSupport.
290/// These functions are for bridging between the C API and the Objective-C API.
291#[cfg(feature = "objc2")]
292impl JSContext {
293 extern_methods!(
294 #[cfg(feature = "JSBase")]
295 /// Create a JSContext, wrapping its C API counterpart.
296 ///
297 /// Returns: The JSContext equivalent of the provided JSGlobalContextRef.
298 #[unsafe(method(contextWithJSGlobalContextRef:))]
299 #[unsafe(method_family = none)]
300 pub unsafe fn contextWithJSGlobalContextRef(
301 js_global_context_ref: JSGlobalContextRef,
302 ) -> Option<Retained<JSContext>>;
303
304 #[cfg(feature = "JSBase")]
305 /// Get the C API counterpart wrapped by a JSContext.
306 ///
307 /// Returns: The C API equivalent of this JSContext.
308 #[unsafe(method(JSGlobalContextRef))]
309 #[unsafe(method_family = none)]
310 pub unsafe fn JSGlobalContextRef(&self) -> JSGlobalContextRef;
311 );
312}