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 ///
47 /// # Safety
48 ///
49 /// `virtual_machine` might not allow `None`.
50 #[unsafe(method(initWithVirtualMachine:))]
51 #[unsafe(method_family = init)]
52 pub unsafe fn initWithVirtualMachine(
53 this: Allocated<Self>,
54 virtual_machine: Option<&JSVirtualMachine>,
55 ) -> Option<Retained<Self>>;
56
57 #[cfg(all(feature = "JSValue", feature = "objc2-foundation"))]
58 /// Evaluate a string of JavaScript code.
59 ///
60 /// Parameter `script`: A string containing the JavaScript code to evaluate.
61 ///
62 /// Returns: The last value generated by the script.
63 ///
64 /// # Safety
65 ///
66 /// `script` might not allow `None`.
67 #[unsafe(method(evaluateScript:))]
68 #[unsafe(method_family = none)]
69 pub unsafe fn evaluateScript(&self, script: Option<&NSString>)
70 -> Option<Retained<JSValue>>;
71
72 #[cfg(all(feature = "JSValue", feature = "objc2-foundation"))]
73 /// Evaluate a string of JavaScript code, with a URL for the script's source file.
74 ///
75 /// Parameter `script`: A string containing the JavaScript code to evaluate.
76 ///
77 /// 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.
78 ///
79 /// Returns: The last value generated by the script.
80 ///
81 /// # Safety
82 ///
83 /// - `script` might not allow `None`.
84 /// - `source_url` might not allow `None`.
85 #[unsafe(method(evaluateScript:withSourceURL:))]
86 #[unsafe(method_family = none)]
87 pub unsafe fn evaluateScript_withSourceURL(
88 &self,
89 script: Option<&NSString>,
90 source_url: Option<&NSURL>,
91 ) -> Option<Retained<JSValue>>;
92
93 /// Get the JSContext that is currently executing.
94 ///
95 /// This method may be called from within an Objective-C block or method invoked
96 /// as a callback from JavaScript to retrieve the callback's context. Outside of
97 /// a callback from JavaScript this method will return nil.
98 ///
99 /// Returns: The currently executing JSContext or nil if there isn't one.
100 #[unsafe(method(currentContext))]
101 #[unsafe(method_family = none)]
102 pub unsafe fn currentContext() -> Option<Retained<JSContext>>;
103
104 #[cfg(feature = "JSValue")]
105 /// Get the JavaScript function that is currently executing.
106 ///
107 /// This method may be called from within an Objective-C block or method invoked
108 /// as a callback from JavaScript to retrieve the callback's context. Outside of
109 /// a callback from JavaScript this method will return nil.
110 ///
111 /// Returns: The currently executing JavaScript function or nil if there isn't one.
112 #[unsafe(method(currentCallee))]
113 #[unsafe(method_family = none)]
114 pub unsafe fn currentCallee() -> Option<Retained<JSValue>>;
115
116 #[cfg(feature = "JSValue")]
117 /// Get the
118 /// <code>
119 /// this
120 /// </code>
121 /// value of the currently executing method.
122 ///
123 /// This method may be called from within an Objective-C block or method invoked
124 /// as a callback from JavaScript to retrieve the callback's this value. Outside
125 /// of a callback from JavaScript this method will return nil.
126 ///
127 /// Returns: The current
128 /// <code>
129 /// this
130 /// </code>
131 /// value or nil if there isn't one.
132 #[unsafe(method(currentThis))]
133 #[unsafe(method_family = none)]
134 pub unsafe fn currentThis() -> Option<Retained<JSValue>>;
135
136 #[cfg(feature = "objc2-foundation")]
137 /// Get the arguments to the current callback.
138 ///
139 /// This method may be called from within an Objective-C block or method invoked
140 /// as a callback from JavaScript to retrieve the callback's arguments, objects
141 /// in the returned array are instances of JSValue. Outside of a callback from
142 /// JavaScript this method will return nil.
143 ///
144 /// Returns: An NSArray of the arguments nil if there is no current callback.
145 #[unsafe(method(currentArguments))]
146 #[unsafe(method_family = none)]
147 pub unsafe fn currentArguments() -> Option<Retained<NSArray>>;
148
149 #[cfg(feature = "JSValue")]
150 /// Get the global object of the context.
151 ///
152 /// This method retrieves the global object of the JavaScript execution context.
153 /// Instances of JSContext originating from WebKit will return a reference to the
154 /// WindowProxy object.
155 ///
156 /// Returns: The global object.
157 #[unsafe(method(globalObject))]
158 #[unsafe(method_family = none)]
159 pub unsafe fn globalObject(&self) -> Option<Retained<JSValue>>;
160
161 #[cfg(feature = "JSValue")]
162 /// The
163 /// <code>
164 /// exception
165 /// </code>
166 /// property may be used to throw an exception to JavaScript.
167 ///
168 /// Before a callback is made from JavaScript to an Objective-C block or method,
169 /// the prior value of the exception property will be preserved and the property
170 /// will be set to nil. After the callback has completed the new value of the
171 /// exception property will be read, and prior value restored. If the new value
172 /// of exception is not nil, the callback will result in that value being thrown.
173 ///
174 /// This property may also be used to check for uncaught exceptions arising from
175 /// API function calls (since the default behaviour of
176 /// <code>
177 /// exceptionHandler
178 /// </code>
179 /// is to
180 /// assign an uncaught exception to this property).
181 #[unsafe(method(exception))]
182 #[unsafe(method_family = none)]
183 pub unsafe fn exception(&self) -> Option<Retained<JSValue>>;
184
185 #[cfg(feature = "JSValue")]
186 /// Setter for [`exception`][Self::exception].
187 ///
188 /// # Safety
189 ///
190 /// `exception` might not allow `None`.
191 #[unsafe(method(setException:))]
192 #[unsafe(method_family = none)]
193 pub unsafe fn setException(&self, exception: Option<&JSValue>);
194
195 #[cfg(all(feature = "JSValue", feature = "block2"))]
196 /// If a call to an API function results in an uncaught JavaScript exception, the
197 /// <code>
198 /// exceptionHandler
199 /// </code>
200 /// block will be invoked. The default implementation for the
201 /// exception handler will store the exception to the exception property on
202 /// context. As a consequence the default behaviour is for uncaught exceptions
203 /// occurring within a callback from JavaScript to be rethrown upon return.
204 /// Setting this value to nil will cause all exceptions occurring
205 /// within a callback from JavaScript to be silently caught.
206 ///
207 /// # Safety
208 ///
209 /// - The returned block's argument 1 must be a valid pointer.
210 /// - The returned block's argument 2 must be a valid pointer.
211 #[unsafe(method(exceptionHandler))]
212 #[unsafe(method_family = none)]
213 pub unsafe fn exceptionHandler(
214 &self,
215 ) -> NonNull<block2::DynBlock<dyn Fn(*mut JSContext, *mut JSValue)>>;
216
217 #[cfg(all(feature = "JSValue", feature = "block2"))]
218 /// Setter for [`exceptionHandler`][Self::exceptionHandler].
219 ///
220 /// This is [copied][objc2_foundation::NSCopying::copy] when set.
221 #[unsafe(method(setExceptionHandler:))]
222 #[unsafe(method_family = none)]
223 pub unsafe fn setExceptionHandler(
224 &self,
225 exception_handler: Option<&block2::DynBlock<dyn Fn(*mut JSContext, *mut JSValue)>>,
226 );
227
228 #[cfg(feature = "JSVirtualMachine")]
229 /// All instances of JSContext are associated with a JSVirtualMachine.
230 #[unsafe(method(virtualMachine))]
231 #[unsafe(method_family = none)]
232 pub unsafe fn virtualMachine(&self) -> Option<Retained<JSVirtualMachine>>;
233
234 #[cfg(feature = "objc2-foundation")]
235 /// Name of the JSContext. Exposed when inspecting the context.
236 #[unsafe(method(name))]
237 #[unsafe(method_family = none)]
238 pub unsafe fn name(&self) -> Retained<NSString>;
239
240 #[cfg(feature = "objc2-foundation")]
241 /// Setter for [`name`][Self::name].
242 ///
243 /// This is [copied][objc2_foundation::NSCopying::copy] when set.
244 #[unsafe(method(setName:))]
245 #[unsafe(method_family = none)]
246 pub unsafe fn setName(&self, name: Option<&NSString>);
247
248 /// Controls whether this
249 ///
250 /// ```text
251 /// JSContext
252 /// ```
253 ///
254 /// is inspectable in Web Inspector. The default value is NO.
255 #[unsafe(method(isInspectable))]
256 #[unsafe(method_family = none)]
257 pub unsafe fn isInspectable(&self) -> bool;
258
259 /// Setter for [`isInspectable`][Self::isInspectable].
260 #[unsafe(method(setInspectable:))]
261 #[unsafe(method_family = none)]
262 pub unsafe fn setInspectable(&self, inspectable: bool);
263 );
264}
265
266/// Methods declared on superclass `NSObject`.
267#[cfg(feature = "objc2")]
268impl JSContext {
269 extern_methods!(
270 #[unsafe(method(new))]
271 #[unsafe(method_family = new)]
272 pub unsafe fn new() -> Retained<Self>;
273 );
274}
275
276/// SubscriptSupport.
277///
278/// Instances of JSContext implement the following methods in order to enable
279/// support for subscript access by key and index, for example:
280///
281/// ```text
282/// JSContext *context;
283/// JSValue *v = context[@"X"]; // Get value for "X" from the global object.
284/// context[@"Y"] = v; // Assign 'v' to "Y" on the global object.
285/// ```
286///
287/// An object key passed as a subscript will be converted to a JavaScript value,
288/// and then the value converted to a string used to resolve a property of the
289/// global object.
290#[cfg(feature = "objc2")]
291impl JSContext {
292 extern_methods!(
293 #[cfg(feature = "JSValue")]
294 /// Get a particular property on the global object.
295 ///
296 /// Returns: The JSValue for the global object's property.
297 ///
298 /// # Safety
299 ///
300 /// - `key` should be of the correct type.
301 /// - `key` might not allow `None`.
302 #[unsafe(method(objectForKeyedSubscript:))]
303 #[unsafe(method_family = none)]
304 pub unsafe fn objectForKeyedSubscript(
305 &self,
306 key: Option<&AnyObject>,
307 ) -> Option<Retained<JSValue>>;
308
309 #[cfg(feature = "objc2-foundation")]
310 /// Set a particular property on the global object.
311 ///
312 /// # Safety
313 ///
314 /// - `object` should be of the correct type.
315 /// - `object` might not allow `None`.
316 /// - `key` must implement NSCopying.
317 /// - `key` might not allow `None`.
318 #[unsafe(method(setObject:forKeyedSubscript:))]
319 #[unsafe(method_family = none)]
320 pub unsafe fn setObject_forKeyedSubscript(
321 &self,
322 object: Option<&AnyObject>,
323 key: Option<&NSObject>,
324 );
325 );
326}
327
328/// JSContextRefSupport.
329///
330/// These functions are for bridging between the C API and the Objective-C API.
331#[cfg(feature = "objc2")]
332impl JSContext {
333 extern_methods!(
334 #[cfg(feature = "JSBase")]
335 /// Create a JSContext, wrapping its C API counterpart.
336 ///
337 /// Returns: The JSContext equivalent of the provided JSGlobalContextRef.
338 ///
339 /// # Safety
340 ///
341 /// `js_global_context_ref` must be a valid pointer.
342 #[unsafe(method(contextWithJSGlobalContextRef:))]
343 #[unsafe(method_family = none)]
344 pub unsafe fn contextWithJSGlobalContextRef(
345 js_global_context_ref: JSGlobalContextRef,
346 ) -> Option<Retained<JSContext>>;
347
348 #[cfg(feature = "JSBase")]
349 /// Get the C API counterpart wrapped by a JSContext.
350 ///
351 /// Returns: The C API equivalent of this JSContext.
352 #[unsafe(method(JSGlobalContextRef))]
353 #[unsafe(method_family = none)]
354 pub unsafe fn JSGlobalContextRef(&self) -> JSGlobalContextRef;
355 );
356}