@chilkat/react-native 11.6.1

package/src/specs/Bz2.nitro.ts

@@ -0,0 +1,269 @@
+// Generated by ReactNativeNs.RnGenerator -- do not edit.
+import type { HybridObject } from 'react-native-nitro-modules'
+import type { BinData } from './BinData.nitro'
+
+/**
+ * `Bz2` provides BZip2 compression and decompression for files, memory buffers, and BinData. It can
+ * create standard .bz2 file images, decompress .bz2 content back to its original bytes, and support
+ * abortable long-running operations.
+ *
+ * For an extended overview, see [Bz2 Class
+ * Overview](https://www.chilkatsoft.com/bz2_class_overview.asp)
+ *
+ * Each `Bz2` 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 Bz2()`.
+ *
+ * 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 Bz2.abort} and assigning {@link Bz2.onPercentDone} / {@link Bz2.onProgressInfo}.
+ */
+export interface Bz2 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
+
+  /**
+   * Specifies the interval, in milliseconds, between `AbortCheck` event callbacks during supported
+   * long-running compression and decompression operations. The default is `0`, which disables
+   * `AbortCheck` callbacks.
+   *
+   * Set a positive value, such as `200`, when the application needs periodic opportunities to
+   * request cancellation. The interval is approximate; callbacks occur only while an operation is
+   * at a point where progress events can be delivered.
+   *
+   * **Cancellation workflow:** In an `AbortCheck` handler, set the callback's abort value to
+   * request termination. A synchronous method may also be cancelled from another thread by setting
+   * {@link Bz2.abortCurrent} to `_TRUE_`.
+   */
+  heartbeatMs: number
+
+  /**
+   * Set this property to `_TRUE_` to request cancellation of the compression or decompression
+   * operation currently executing on this object. Long-running operations check the request
+   * periodically; an operation that finishes quickly may complete before the request is observed.
+   *
+   * A synchronous call can be cancelled by setting this property from another thread. After
+   * cancellation is processed, Chilkat resets the property to `_FALSE_`. If no operation is
+   * running, a previously set value is cleared when the next method begins.
+   *
+   * **Cancellation is cooperative:** Setting this property requests an abort; it does not guarantee
+   * immediate termination. Check the method's return value and `LastErrorText` to determine the
+   * final outcome.
+   */
+  abortCurrent: boolean
+
+  // ---- Methods ----
+
+  /**
+   * Reads the file at `inFilename` and writes its compressed bytes as a standard BZip2 stream to
+   * the file at `toPath`. The output is conventionally given a `.bz2` extension.
+   *
+   * Both arguments must identify files, not directories. They may be absolute or relative paths,
+   * for example `data/report.txt` and `data/report.txt.bz2`.
+   *
+   * **BZip2 is a compressor, not an archive format:** A `.bz2` file represents one compressed byte
+   * stream. It does not store the original filename, directory path, timestamps, permissions, or
+   * multiple archive entries. Formats such as `.tar.bz2` first combine files in a TAR archive and
+   * then compress that TAR stream with BZip2.
+   *
+   * This call blocks the JavaScript thread until Chilkat returns; from UI code prefer
+   * {@link Bz2.compressFileAsync}.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Bz2.lastErrorText}.
+   */
+  compressFile(inFilename: string, toPath: string): void
+
+  /**
+   * Asynchronous form of {@link Bz2.compressFile}: 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 Bz2.abort} (which cancels it) and the {@link Bz2.onPercentDone} /
+   * {@link Bz2.onProgressInfo} callbacks, which report progress while it runs.
+   *
+   * The promise rejects with an Error if the call fails; the full log is in
+   * {@link Bz2.lastErrorText}.
+   */
+  compressFileAsync(inFilename: string, toPath: string): Promise<void>
+
+  /**
+   * Reads the BZip2 stream from the file at `inFilename`, decompresses it, and writes the original
+   * uncompressed bytes to the file at `toPath`.
+   *
+   * Both arguments must identify files, not directories. Chilkat does not derive the destination
+   * name from the `.bz2` filename because the BZip2 stream does not contain the original filename.
+   *
+   * **Terminology:** This method decompresses BZip2 data; it does not “unzip” a ZIP archive. A
+   * `.bz2` file normally contains a single compressed byte stream rather than a collection of named
+   * files.
+   *
+   * This call blocks the JavaScript thread until Chilkat returns; from UI code prefer
+   * {@link Bz2.uncompressFileAsync}.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Bz2.lastErrorText}.
+   */
+  uncompressFile(inFilename: string, toPath: string): void
+
+  /**
+   * Asynchronous form of {@link Bz2.uncompressFile}: 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 Bz2.abort} (which cancels it) and the {@link Bz2.onPercentDone} /
+   * {@link Bz2.onProgressInfo} callbacks, which report progress while it runs.
+   *
+   * The promise rejects with an Error if the call fails; the full log is in
+   * {@link Bz2.lastErrorText}.
+   */
+  uncompressFileAsync(inFilename: string, toPath: string): Promise<void>
+
+  /**
+   * Compresses the current contents of `bd` in place. On success, the `BinData` no longer contains
+   * the original bytes; it contains the complete standard BZip2 stream that may be saved with a
+   * `.bz2` extension.
+   *
+   * **In-place transformation:** Preserve a copy of the original data if it is still needed after
+   * this call. A BZip2 stream contains a stream header, one or more compressed blocks with
+   * integrity checks, and an end-of-stream marker. It does not contain archive filenames or
+   * directory entries.
+   *
+   * This call blocks the JavaScript thread until Chilkat returns; from UI code prefer
+   * {@link Bz2.compressBdAsync}.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Bz2.lastErrorText}.
+   */
+  compressBd(bd: BinData): void
+
+  /**
+   * Asynchronous form of {@link Bz2.compressBd}: 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 Bz2.abort} (which cancels it) and the {@link Bz2.onPercentDone} /
+   * {@link Bz2.onProgressInfo} callbacks, which report progress while it runs.
+   *
+   * The promise rejects with an Error if the call fails; the full log is in
+   * {@link Bz2.lastErrorText}.
+   */
+  compressBdAsync(bd: BinData): Promise<void>
+
+  /**
+   * Decompresses the BZip2 stream currently contained in `bd` in place. On success, the `BinData`
+   * is replaced with the original uncompressed bytes.
+   *
+   * **Input requirement:** `bd` must contain a complete, valid BZip2 stream, such as the bytes of a
+   * `.bz2` file or the output of {@link Bz2.compressBd}. This method operates on binary data and
+   * does not perform character-set conversion.
+   *
+   * This call blocks the JavaScript thread until Chilkat returns; from UI code prefer
+   * {@link Bz2.uncompressBdAsync}.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Bz2.lastErrorText}.
+   */
+  uncompressBd(bd: BinData): void
+
+  /**
+   * Asynchronous form of {@link Bz2.uncompressBd}: 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 Bz2.abort} (which cancels it) and the {@link Bz2.onPercentDone} /
+   * {@link Bz2.onProgressInfo} callbacks, which report progress while it runs.
+   *
+   * The promise rejects with an Error if the call fails; the full log is in
+   * {@link Bz2.lastErrorText}.
+   */
+  uncompressBdAsync(bd: BinData): Promise<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 Bz2.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
+}