@chilkat/react-native 11.6.1

package/src/specs/MessageSet.nitro.ts

@@ -0,0 +1,320 @@
+// Generated by ReactNativeNs.RnGenerator -- do not edit.
+import type { HybridObject } from 'react-native-nitro-modules'
+
+/**
+ * Represent and pass sets of IMAP message identifiers.
+ *
+ * `MessageSet` represents a set of IMAP message identifiers
+ * used by `Chilkat.Imap`. It is a helper object for passing groups
+ * of messages to IMAP methods and for receiving groups of message IDs returned
+ * by IMAP search, fetch, copy, delete, or flag-related operations. A
+ * `MessageSet` may contain either UIDs or sequence numbers, and the
+ * `HasUids` setting identifies which form is being used.
+ *
+ * **IMAP message IDs**
+ *
+ * Store the identifiers used by IMAP operations, either as message UIDs or
+ * as sequence numbers.
+ *
+ * **Used by Chilkat.Imap**
+ *
+ * Pass message sets to IMAP methods that operate on multiple messages, or
+ * receive them from IMAP methods that return matching messages.
+ *
+ * **UID awareness**
+ *
+ * Use `HasUids` to indicate whether the contained identifiers
+ * are stable IMAP UIDs or mailbox-relative sequence numbers.
+ *
+ * **Add and remove IDs**
+ *
+ * Insert message identifiers, remove identifiers, check whether an ID is
+ * present, and build the exact message group needed for an IMAP operation.
+ *
+ * **Compact string formats**
+ *
+ * Load or emit compact IMAP-style message ranges such as comma-separated
+ * lists and range expressions.
+ *
+ * **Set operations**
+ *
+ * Subtract one message set from another when application logic needs to
+ * exclude already-processed or unwanted messages.
+ *
+ * **Common pattern:**
+ * Use `MessageSet` only for IMAP message identifiers, not as a
+ * general-purpose collection. Obtain a message set from an IMAP search or
+ * build one manually, confirm whether it contains UIDs or sequence numbers,
+ * then pass it to the appropriate `Chilkat.Imap` method for
+ * fetching, copying, deleting, flagging, or otherwise processing the selected
+ * messages.
+ *
+ * For an extended overview, see
+ * [MessageSet Class Overview](https://www.chilkatsoft.com/messageset_class_overview.asp).
+ *
+ * Each `MessageSet` 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 MessageSet()`.
+ */
+export interface MessageSet 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
+
+  /**
+   * Returns the number of unique message identifiers currently stored in the set. A newly created
+   * `MessageSet` has a count of `0`.
+   *
+   * The identifiers are maintained in ascending numeric order. They are interpreted as UIDs when
+   * {@link MessageSet.hasUids} is `_TRUE_`, or as sequence numbers when it is `_FALSE_`.
+   *
+   * This property is read-only.
+   */
+  readonly count: number
+
+  /**
+   * Indicates how the numeric identifiers in this message set are interpreted:
+   *
+   * - `_TRUE_` — the values are IMAP UIDs. This is the default.
+   *
+   * - `_FALSE_` — the values are mailbox-relative sequence numbers.
+   *
+   * Changing this property only changes how the existing numeric values are interpreted. It does
+   * not convert, validate, reorder, or clear the identifiers.
+   *
+   * An IMAP UID is stable only within its mailbox and while that mailbox's `UIDVALIDITY` remains
+   * unchanged. Sequence numbers are temporary and can change when messages are added or expunged.
+   *
+   * Set this property consistently before passing a manually constructed message set to an `Imap`
+   * method. The string formats produced by {@link MessageSet.toCommaSeparatedStr} and {@link
+   * MessageSet.toCompactString} contain only the numeric values and do not include this setting.
+   */
+  hasUids: boolean
+
+  // ---- Methods ----
+
+  /**
+   * Returns `_TRUE_` if the raw numeric value in `msgId` is present in the message set; otherwise,
+   * returns `_FALSE_`.
+   *
+   * The comparison is numeric only. The {@link MessageSet.hasUids} setting does not participate in
+   * the comparison.
+   */
+  containsId(msgId: number): boolean
+
+  /**
+   * Clears the identifiers currently stored in this object and loads the compact message-set
+   * representation in `str`. The existing {@link MessageSet.hasUids} setting is preserved.
+   *
+   * **Important:** The existing set is cleared before `str` is parsed. If parsing fails, the
+   * message set remains empty.
+   *
+   * An empty string succeeds and leaves the set empty. Valid identifiers are unsigned 32-bit
+   * decimal values from `1` through `4294967295`. The value `0` is not accepted. Values too large
+   * for an unsigned 32-bit integer cause the method to fail.
+   *
+   * The syntax uses commas to separate values or ranges, and a colon to specify an inclusive
+   * ascending range. A single range may contain at most 500,001 identifiers; equivalently, the
+   * ending value minus the starting value cannot exceed `500000`.
+   *
+   * **Version note:** The error-handling behavior described here was added in Chilkat version
+   * 11.6.0.
+   *
+   * Input
+   * Result
+   *
+   * | `1,2,3,4,5` |  | Loads `1,2,3,4,5`. |
+   *
+   * | `1:5` |  | Loads the inclusive range `1` through `5`. |
+   *
+   * | `1:5,8:10` |  | Loads `1,2,3,4,5,8,9,10`. |
+   *
+   * | `1,1,2,2,3` |  | Loads the unique values `1,2,3`. |
+   *
+   * | `1:5,3:7` |  | Loads the unique values `1` through `7`. |
+   *
+   * | `1,,3` |  | Empty comma-separated elements are ignored; loads `1,3`. |
+   *
+   * | `1,2,abc,4` |  | Unrecognized elements are ignored; loads `1,2,4`. |
+   *
+   * | `+1` |  | A leading plus sign is accepted; loads `1`. |
+   *
+   * Whitespace is accepted around values, commas, and colons. This includes spaces, tabs, carriage
+   * returns, and line feeds. Empty comma-separated elements and unrecognized non-numeric elements
+   * are intentionally ignored. If `str` is nonempty and no valid identifier is loaded, the method
+   * returns `_FALSE_`.
+   *
+   * Descending ranges, ranges containing `0`, wildcard ranges such as `1:*`, malformed range
+   * syntax, oversized ranges, and numeric overflow cause the method to return `_FALSE_`.
+   *
+   * On success, duplicate identifiers are removed and the resulting identifiers are stored in
+   * ascending numeric order. The serialized form contains only the numbers and does not indicate
+   * whether they are UIDs or sequence numbers.
+   *
+   * Use {@link MessageSet.toCompactString} to generate the canonical compact representation.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link MessageSet.lastErrorText}.
+   */
+  fromCompactString(str: string): void
+
+  /**
+   * Returns the message identifier at the zero-based index specified by `index`. Identifiers are
+   * returned in ascending numeric order.
+   *
+   * If `index` is negative or is greater than or equal to {@link MessageSet.count}, this method
+   * returns `0xFFFFFFFF`.
+   *
+   * **Important:** The numeric value `0xFFFFFFFF` can also be stored in the set. Check `index`
+   * against `Count` before calling this method when that value could be present.
+   */
+  getId(index: number): number
+
+  /**
+   * Adds `id` to the message set and maintains the identifiers in ascending numeric order.
+   *
+   * - If `id` is already present, no duplicate is added.
+   *
+   * - If `id` is `0`, the set is unchanged.
+   *
+   * - The value `0xFFFFFFFF` is accepted.
+   *
+   * The {@link MessageSet.hasUids} setting determines whether the stored values are interpreted as
+   * UIDs or sequence numbers.
+   */
+  insertId(id: number): void
+
+  /**
+   * Removes the identifier whose raw numeric value equals `id`. If the value is not present, the
+   * set is unchanged.
+   *
+   * The comparison is numeric only and does not depend on {@link MessageSet.hasUids}. The remaining
+   * identifiers stay in ascending numeric order.
+   */
+  removeId(id: number): void
+
+  /**
+   * Returns the unique identifiers as a comma-separated string in ascending numeric order. An empty
+   * set returns an empty string.
+   *
+   * For example, a set containing the identifiers `1` through `5` returns `1,2,3,4,5`.
+   *
+   * The returned string contains only the numeric values; it does not include the {@link
+   * MessageSet.hasUids} setting.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link MessageSet.lastErrorText}.
+   */
+  toCommaSeparatedStr(): string
+
+  /**
+   * Returns the unique identifiers in ascending numeric order using compact IMAP message-set
+   * syntax. Consecutive identifiers are represented as an inclusive range. An empty set returns an
+   * empty string.
+   *
+   * Comma-separated form
+   * Compact form
+   *
+   * | `1,2,3,4,5` |  | `1:5` |
+   *
+   * | `1,2,3,4,5,8,9,10` |  | `1:5,8:10` |
+   *
+   * | `1,3,4,5,8,9,10` |  | `1,3:5,8:10` |
+   *
+   * The returned string is canonical for the current set: identifiers are unique, sorted, and
+   * consecutive runs are compacted. It contains only the numeric values and does not include the
+   * {@link MessageSet.hasUids} setting.
+   *
+   * Use {@link MessageSet.fromCompactString} to load this format.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link MessageSet.lastErrorText}.
+   */
+  toCompactString(): string
+
+  /**
+   * Removes from this message set every identifier whose raw numeric value is present in `msgSet`.
+   * Values not present in this set are ignored.
+   *
+   * The comparison is numeric only; the {@link MessageSet.hasUids} values of the two objects are
+   * not compared. This object's `HasUids` value is preserved, and the remaining identifiers stay in
+   * ascending numeric order.
+   *
+   * Passing the same object as `msgSet` clears the set. Passing an empty set leaves this set
+   * unchanged.
+   *
+   * For meaningful IMAP results, both objects should represent identifiers of the same type and
+   * from the same mailbox.
+   */
+  subtract(msgSet: MessageSet): void
+}