@chilkat/react-native 11.6.1

package/src/specs/EmailBundle.nitro.ts

@@ -0,0 +1,334 @@
+// Generated by ReactNativeNs.RnGenerator -- do not edit.
+import type { HybridObject } from 'react-native-nitro-modules'
+import type { Email } from './Email.nitro'
+import type { JsonObject } from './JsonObject.nitro'
+
+/**
+ * Hold, search, sort, remove, save, and reload groups of email messages.
+ *
+ * `EmailBundle` is a container for multiple
+ * `Email` objects. It is commonly returned by mail-related
+ * operations and can also be built manually by adding individual email
+ * messages. The class provides a simple way to work with groups of messages:
+ * retrieve emails by index, search for a matching email, sort by common email
+ * fields, remove messages, clear the bundle, and serialize or reload the
+ * collection as XML.
+ *
+ * **Email collection**
+ *
+ * Store multiple `Email` objects together after
+ * receiving, loading, filtering, or manually building a message set.
+ *
+ * **Retrieve messages**
+ *
+ * Use the message count and indexed access methods to retrieve individual
+ * emails for inspection, processing, saving, or sending.
+ *
+ * **Search within the bundle**
+ *
+ * Locate a specific email in the collection when application logic needs
+ * to find a matching message.
+ *
+ * **Sort messages**
+ *
+ * Sort the bundle by date, sender, recipient, or subject to organize
+ * messages before processing or display.
+ *
+ * **Remove or clear emails**
+ *
+ * Remove individual messages by object or index, or clear the entire
+ * bundle when the collection is no longer needed.
+ *
+ * **Save and reload**
+ *
+ * Serialize the bundle to XML and reload it later, or load task results
+ * that return an email bundle.
+ *
+ * **Common pattern:**
+ * Receive or build a bundle of `Email` objects, loop from
+ * `0` to `MessageCount - 1`, retrieve each message with
+ * `EmailAt`, and then inspect, save, sort, remove, or process each
+ * email as needed. Use `EmailBundle` for the group and
+ * `Email` for the individual message contents.
+ *
+ * For an extended overview, see
+ * [EmailBundle Class Overview](https://www.chilkatsoft.com/emailbundle_class_overview.asp).
+ *
+ * Each `EmailBundle` 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 EmailBundle()`.
+ */
+export interface EmailBundle 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 `Email` objects currently contained in the bundle.
+   *
+   * Valid zero-based indexes range from `0` through `MessageCount - 1`.
+   *
+   * This property is read-only.
+   */
+  readonly messageCount: number
+
+  // ---- Methods ----
+
+  /**
+   * Adds an independent copy of the `Email` object in `email` to the end of this in-memory bundle.
+   *
+   * The bundle does not retain a reference to `email` and does not take ownership of the supplied
+   * object. Changes made to `email` after this method returns do not affect the copy stored in the
+   * bundle, and changes to the stored copy do not affect `email`.
+   *
+   * The same `Email` object may be added more than once. Each call adds another independent copy
+   * and increases the {@link EmailBundle.messageCount} property by one.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link EmailBundle.lastErrorText}.
+   */
+  addEmail(email: Email): void
+
+  /**
+   * Serializes the entire email bundle to Chilkat XML and returns the XML document as a string.
+   *
+   * The XML contains the bundle and its individual `Email` objects. It can be loaded into another
+   * `EmailBundle` by calling {@link EmailBundle.loadXmlString}.
+   *
+   * This is Chilkat's XML representation of an email bundle; it is not an RFC 822/MIME message.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link EmailBundle.lastErrorText}.
+   */
+  getXml(): string
+
+  /**
+   * Loads an email bundle from the local filesystem path specified by `path`. The path may be
+   * absolute or relative; a filename alone refers to a file in the current working directory.
+   *
+   * The file should contain Chilkat email-bundle XML previously produced by {@link
+   * EmailBundle.saveXml} or {@link EmailBundle.getXml}.
+   *
+   * The emails loaded from `path` are appended to the emails already in the bundle. Existing emails
+   * are not removed or replaced.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link EmailBundle.lastErrorText}.
+   */
+  loadXml(path: string): void
+
+  /**
+   * Loads an email bundle from the Chilkat XML string in `xmlStr`.
+   *
+   * The XML is typically obtained from {@link EmailBundle.getXml} or read from a file created by
+   * {@link EmailBundle.saveXml}.
+   *
+   * The emails loaded from `xmlStr` are appended to the emails already in the bundle. Existing
+   * emails are not removed or replaced.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link EmailBundle.lastErrorText}.
+   */
+  loadXmlString(xmlStr: string): void
+
+  /**
+   * Removes the first email in this in-memory bundle that matches `email`.
+   *
+   * Chilkat first searches for an email having the same UIDL as `email`. If no email with a
+   * matching UIDL is found, it searches for the first email having the same `Message-ID` header
+   * field value. Only the first matching email is removed.
+   *
+   * `email` may be an independent copy obtained from {@link EmailBundle.emailAt}.
+   *
+   * **Note:** This method changes only the local bundle. It does not delete a message from a POP3
+   * or IMAP server.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link EmailBundle.lastErrorText}.
+   */
+  removeEmail(email: Email): void
+
+  /**
+   * Removes the email at the zero-based index in `index`.
+   *
+   * Valid indexes range from `0` through `
0 - 1`.
+   *
+   * **Note:** This method changes only the local bundle. It does not delete a message from a mail
+   * server.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link EmailBundle.lastErrorText}.
+   */
+  removeEmailByIndex(index: number): void
+
+  /**
+   * Serializes the bundle and each contained `Email` to Chilkat XML, then writes the XML document
+   * to the local filesystem path specified by `path`. The path may be absolute or relative; a
+   * filename alone writes to the current working directory.
+   *
+   * Reload the saved bundle by calling {@link EmailBundle.loadXml}. Use {@link EmailBundle.getXml}
+   * when the XML is needed in memory rather than in a file.
+   *
+   * The saved file is a Chilkat email-bundle serialization, not an RFC 822/MIME message file.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link EmailBundle.lastErrorText}.
+   */
+  saveXml(path: string): void
+
+  /**
+   * Sorts the emails in this bundle by each `Email` object's `EmailDate` property.
+   *
+   * Set `ascending` to `true` to sort in ascending order, from oldest to newest. Set `ascending` to
+   * `false` to sort in descending order, from newest to oldest.
+   *
+   * The operation changes the order of the emails in the in-memory collection.
+   */
+  sortByDate(ascending: boolean): void
+
+  /**
+   * Sorts the emails in this bundle by the full value of each email's `To` header field.
+   *
+   * The comparisons are case-sensitive. Set `ascending` to `true` for ascending order or `false`
+   * for descending order. The operation changes the order of the emails in the in-memory
+   * collection.
+   */
+  sortByRecipient(ascending: boolean): void
+
+  /**
+   * Sorts the emails in this bundle by the full content of each email's `From` header field.
+   *
+   * Set `ascending` to `true` for ascending order or `false` for descending order. The operation
+   * changes the order of the emails in the in-memory collection.
+   */
+  sortBySender(ascending: boolean): void
+
+  /**
+   * Sorts the emails in this bundle by subject.
+   *
+   * Set `ascending` to `true` for ascending order or `false` for descending order. The operation
+   * changes the order of the emails in the in-memory collection.
+   */
+  sortBySubject(ascending: boolean): void
+
+  /**
+   * Finds the first email in the bundle whose MIME header field matches the search criteria
+   * specified by the `JsonObject` in `json`.
+   *
+   * At this time, a search may specify only one MIME header field. Use the following JSON format:
+   *
+   * ```
+   * {
+   *   "header": {
+   *     "name": "Subject",
+   *     "value": "Dinner on Wednesday?",
+   *     "caseInsensitive": true
+   *   }
+   * }
+   * ```
+   *
+   * `header.name` specifies the MIME header field name, and `header.value` specifies the complete
+   * field value to match. The field value must match exactly; this is not a substring, wildcard, or
+   * regular-expression search. Set `header.caseInsensitive` to `true` for a case-insensitive
+   * comparison or `false` for a case-sensitive comparison.
+   *
+   * When a match is found, `email` receives the first matching email.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link EmailBundle.lastErrorText}.
+   */
+  findEmail(json: JsonObject, email: Email): void
+
+  /**
+   * Copies the email at the zero-based index in `index` into the `Email` object in `email`.
+   *
+   * Valid indexes range from `0` through `
0 - 1`. The first email is at index `0`.
+   *
+   * `email` receives an independent copy. Changes made to `email` do not modify the email stored in
+   * the bundle.
+   *
+   * **Note:** This is an in-memory operation and does not communicate with a mail server.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link EmailBundle.lastErrorText}.
+   */
+  emailAt(index: number, email: Email): void
+
+  /**
+   * Removes and discards all emails from this in-memory bundle.
+   *
+   * After this method returns, {@link EmailBundle.messageCount} is `0`. No messages are deleted
+   * from any mail server.
+   */
+  clear(): void
+}