@chilkat/react-native 11.6.1

package/src/specs/Js.nitro.ts

@@ -0,0 +1,263 @@
+// Generated by ReactNativeNs.RnGenerator -- do not edit.
+import type { HybridObject } from 'react-native-nitro-modules'
+import type { JsonObject } from './JsonObject.nitro'
+import type { StringBuilder } from './StringBuilder.nitro'
+
+/**
+ * Execute sandboxed JavaScript inside an application with controlled access to Chilkat features.
+ *
+ * Use `Js` when an application needs to execute JavaScript
+ * internally while retaining control over what the script is allowed to access.
+ * By default, scripts run in a closed sandbox with the JavaScript language and
+ * standard library available, but without filesystem, network, or Chilkat
+ * class access unless the host application explicitly enables those
+ * capabilities.
+ *
+ * **Embedded JavaScript engine**
+ *
+ * Run JavaScript code from inside the host application without launching an
+ * external scripting process.
+ *
+ * **Sandboxed by default**
+ *
+ * Start from a restricted execution environment and selectively expose only
+ * the capabilities the script should use.
+ *
+ * **Enable Chilkat classes**
+ *
+ * Allow scripts to use selected Chilkat classes when the host application
+ * wants JavaScript to perform controlled Chilkat operations.
+ *
+ * **Filesystem restrictions**
+ *
+ * Optionally restrict filesystem access so scripts can read or write only
+ * within approved locations.
+ *
+ * **Script input and output**
+ *
+ * Execute JavaScript, pass data through the host-controlled environment,
+ * and retrieve results or diagnostics from the script run.
+ *
+ * **Controlled automation**
+ *
+ * Use JavaScript as an embedded extension language for application-defined
+ * workflows while keeping host resources protected.
+ *
+ * **Common pattern:**
+ * Create a `Js` object, load or provide the JavaScript code, enable
+ * only the Chilkat classes and filesystem locations the script is permitted to
+ * use, run the script, and inspect the result or diagnostic output. Use
+ * `Js` when the application needs scriptability with a
+ * security boundary controlled by the host.
+ *
+ * For an extended overview, see
+ * [Js Class Overview](https://www.chilkatsoft.com/js_class_overview.asp).
+ * Also see
+ * [About the Js JavaScript Engine](https://www.chilkatsoft.com/chilkat_javascript_engine.asp).
+ *
+ * **Third-Party Notice**
+ * This software includes portions of the QuickJS JavaScript engine.
+ * Copyright © 2017–2024 Fabrice Bellard.
+ * Licensed under the MIT License.
+ * The Chilkat Js engine was originally derived from QuickJS, but has been
+ * extensively modified.
+ *
+ * Each `Js` instance owns a native Chilkat object. It is released when the JavaScript object is
+ * garbage collected, or immediately by `dispose()`; any use after `dispose()` throws.
+ * Create one with `new Js()`.
+ *
+ * Methods that can take a while (network, files, compression, key generation) also have an
+ * `...Async` form returning a `Promise`; it runs on a native worker thread so the UI keeps
+ * rendering. While such a call is pending, every other call on this object throws, except
+ * {@link Js.abort} and assigning {@link Js.onPercentDone} / {@link Js.onProgressInfo}.
+ */
+export interface Js extends HybridObject<{ ios: 'c++', android: 'c++' }> {
+  // ---- Properties ----
+
+  /**
+   * Provides HTML-formatted information about the last called method or property. If a method call
+   * fails or behaves unexpectedly, check this property for details. Note that information is
+   * available regardless of the method call's success.
+   *
+   * This property is read-only.
+   */
+  readonly lastErrorHtml: string
+
+  /**
+   * Provides plain text information about the last called method or property. If a method call
+   * fails or behaves unexpectedly, check this property for details. Note that information is
+   * available regardless of the method call's success.
+   *
+   * This property is read-only.
+   */
+  readonly lastErrorText: string
+
+  /**
+   * Provides XML-formatted information about the last called method or property. If a method call
+   * fails or behaves unexpectedly, check this property for details. Note that information is
+   * available regardless of the method call's success.
+   *
+   * This property is read-only.
+   */
+  readonly lastErrorXml: string
+
+  /**
+   * Version of the component/library, such as "10.1.0"
+   *
+   * This property is read-only.
+   */
+  readonly version: string
+
+  /**
+   * If set to a file path, this property logs the LastErrorText of each Chilkat method or property
+   * call to the specified file. This logging helps identify the context and history of Chilkat
+   * calls leading up to any crash or hang, aiding in debugging.
+   *
+   * Enabling the VerboseLogging property provides more detailed information.
+   *
+   * This property is mainly used for debugging rare instances where a Chilkat method call causes a
+   * hang or crash, which should generally not happen.
+   *
+   * Possible causes of hangs include:
+   *
+   * - A timeout property set to 0, indicating an infinite timeout.
+   *
+   * - A hang occurring within an event callback in the application code.
+   *
+   * - An internal bug in the Chilkat code causing the hang.
+   */
+  debugLogFilePath: string
+
+  /**
+   * If set to `true`, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may
+   * contain more verbose information. The default value is `false`. Verbose logging should only be
+   * used for debugging. The potentially large quantity of logged information may adversely affect
+   * peformance.
+   */
+  verboseLogging: boolean
+
+  /**
+   * Indicates the success or failure of the most recent method call: `true` means success, `false`
+   * means failure. This property remains unchanged by property setters or getters. This method is
+   * present to address challenges in checking for null or Nothing returns in certain programming
+   * languages. Note: This property does not apply to methods that return integer values or to
+   * boolean-returning methods where the boolean does not indicate success or failure.
+   */
+  lastMethodSuccess: boolean
+
+  /**
+   * Specify a timeout in seconds to prevent JavaScript from running indefinitely, such as in an
+   * infinite loop. By default, the value is 0, meaning no timeout is set and infinite loops will
+   * continue forever.
+   */
+  timeoutSeconds: number
+
+  // ---- Methods ----
+
+  /**
+   * Run `jscript` as a script.  Return output and errors in `resultJson`.
+   *
+   * This call blocks the JavaScript thread until Chilkat returns; from UI code prefer
+   * {@link Js.evalAsync}.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Js.lastErrorText}.
+   */
+  eval(jscript: StringBuilder, resultJson: JsonObject): void
+
+  /**
+   * Asynchronous form of {@link Js.eval}: the same call on a native worker thread,
+   * settling on the JavaScript thread. While it is pending, other calls on this object throw,
+   * except {@link Js.abort} (which cancels it) and the {@link Js.onPercentDone} /
+   * {@link Js.onProgressInfo} callbacks, which report progress while it runs.
+   *
+   * The promise rejects with an Error if the call fails; the full log is in
+   * {@link Js.lastErrorText}.
+   */
+  evalAsync(jscript: StringBuilder, resultJson: JsonObject): Promise<void>
+
+  /**
+   * Returns the console output in `sb` from the last call to {@link Js.eval}.
+   */
+  consoleOutputSb(sb: StringBuilder): void
+
+  /**
+   * Calls a JavaScript function. The function name and arguments are passed in `funcJson`. The
+   * result is returned in `resultJson`.
+   *
+   * This call blocks the JavaScript thread until Chilkat returns; from UI code prefer
+   * {@link Js.callFunctionAsync}.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Js.lastErrorText}.
+   */
+  callFunction(funcJson: JsonObject, resultJson: JsonObject): void
+
+  /**
+   * Asynchronous form of {@link Js.callFunction}: the same call on a native worker thread,
+   * settling on the JavaScript thread. While it is pending, other calls on this object throw,
+   * except {@link Js.abort} (which cancels it) and the {@link Js.onPercentDone} /
+   * {@link Js.onProgressInfo} callbacks, which report progress while it runs.
+   *
+   * The promise rejects with an Error if the call fails; the full log is in
+   * {@link Js.lastErrorText}.
+   */
+  callFunctionAsync(funcJson: JsonObject, resultJson: JsonObject): Promise<void>
+
+  /**
+   * Sets sandbox related permissions for Chilkat objects. The `chilkatClassName` is the name of the
+   * Chilkat class (case-insensitive), such as `Http`, `Rest`, `"MailMan"`, `"Ftp2"`, `"Ssh"`, etc.
+   * The `chilkatClassName` can also be set to `"all"` to apply the permission to all Chilkat
+   * classes.
+   *
+   * Possible values for `permission` are:
+   *
+   * - `disable` - Your JavaScript code is not allowed to create an instance of the Chilkat class. A
+   *   JavaScript exception is thrown when trying to create a Chilkat object of a class that is
+   *   disabled.
+   *
+   * - `sandbox` - Objects for the Chilkat class can be instantiated in JavaScript, but they have no
+   *   read or write access to the local filesystem.
+   *
+   * - `readOnly` - Objects for the Chilkat class can be instantiated in JavaScript and have
+   *   read-only access to the local filesystem.
+   *
+   * - `writeOnly` - Objects for the Chilkat class can be instantiated in JavaScript and have
+   *   write-only access to the local filesystem.
+   *
+   * - `readWrite` - Objects for the Chilkat class can be instantiated in JavaScript and have
+   *   read/write access to the local filesystem.
+   *
+   * By default, all Chilkat classes are **disabled**. Your application must enable `"all"` or
+   * specific Chilkat classes before calling {@link Js.eval} or {@link Js.callFunction}.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Js.lastErrorText}.
+   */
+  setCkPermission(chilkatClassName: string, permission: string): void
+
+  // ---- Events (ReactNativeGen_DESIGN.md §6) ----
+
+  /**
+   * Called with the percent completed (0..100) while a long-running method runs, when Chilkat
+   * can measure progress. Runs on the JavaScript thread, so it is only useful with the
+   * `...Async` methods (during a synchronous call the thread is busy and the events arrive
+   * after it returns). Assign `undefined` to remove.
+   */
+  onPercentDone?: (pctDone: number) => void
+
+  /**
+   * Called with a name/value pair of progress information while a long-running method runs
+   * (what is reported depends on the class and method). Runs on the JavaScript thread; see
+   * {@link Js.onPercentDone}. Assign `undefined` to remove.
+   */
+  onProgressInfo?: (name: string, value: string) => void
+
+  /**
+   * Requests that the pending `...Async` call on this object stop at its next progress check.
+   * The promise then rejects with Chilkat's abort error. Chilkat checks at least every
+   * `heartbeatMs` milliseconds on the classes that have that property, so set it (e.g. 250)
+   * for a responsive cancel. Harmless when nothing is pending.
+   */
+  abort(): void
+}