@chilkat/react-native 11.6.1

package/src/specs/Dns.nitro.ts

@@ -0,0 +1,271 @@
+// Generated by ReactNativeNs.RnGenerator -- do not edit.
+import type { HybridObject } from 'react-native-nitro-modules'
+import type { JsonObject } from './JsonObject.nitro'
+
+/**
+ * Configure DNS resolution and query DNS records directly from Chilkat.
+ *
+ * `Dns` is a focused class for DNS configuration and DNS
+ * record querying. It allows applications to control the nameservers used by
+ * Chilkat, query common DNS record types into JSON, configure DNS-over-TLS
+ * preference, set DNS query timeouts, and obtain useful diagnostics through
+ * `LastErrorText`.
+ *
+ * **DNS record queries**
+ *
+ * Query common DNS record types and receive structured JSON results that
+ * are easy to inspect or pass to other application logic.
+ *
+ * **Nameserver control**
+ *
+ * Configure the nameservers Chilkat uses instead of relying only on the
+ * operating system's default DNS configuration.
+ *
+ * **DNS-over-TLS preference**
+ *
+ * Prefer DNS-over-TLS when appropriate for applications that need encrypted
+ * DNS lookups.
+ *
+ * **Timeout settings**
+ *
+ * Control how long DNS queries may wait before failing, which is useful for
+ * responsive applications and troubleshooting.
+ *
+ * **Application-wide behavior**
+ *
+ * Nameserver settings affect DNS resolution across Chilkat classes, not
+ * only the current `Dns` object.
+ *
+ * **Diagnostics**
+ *
+ * Use `LastErrorText` to troubleshoot DNS configuration,
+ * lookup failures, timeout problems, or nameserver connectivity issues.
+ *
+ * **Common pattern:**
+ * Use `Dns` either to perform direct DNS lookups, or to configure
+ * the DNS behavior used by Chilkat as a whole. Because nameserver changes can
+ * affect DNS resolution across Chilkat classes, treat them as application-wide
+ * configuration rather than object-local state.
+ *
+ * For an extended overview, see
+ * [Dns Class Overview](https://www.chilkatsoft.com/dns_class_overview.asp).
+ *
+ * Each `Dns` 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 Dns()`.
+ *
+ * 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 Dns.abort} and assigning {@link Dns.onPercentDone} / {@link Dns.onProgressInfo}.
+ */
+export interface Dns 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
+
+  /**
+   * The number of nameservers currently being used by Chilkat for DNS queries in all
+   * objects/classes, such as for HTTP, Email, FTP, SSH, etc.
+   *
+   * This property is read-only.
+   */
+  readonly numNameservers: number
+
+  /**
+   * The interval in milliseconds between each `AbortCheck` event callback, which enables an
+   * application to abort certain method calls before they complete. **By default, HeartbeatMs is
+   * set to **`0`**, meaning no AbortCheck event callbacks will trigger.**
+   */
+  heartbeatMs: number
+
+  /**
+   * The maxiumum number of milliseconds to wait for the answer to a DNS query. A value of 0 is to
+   * wait indefinitely (no timeout). It's not a good idea to specify 0 (infinite timeout) or a value
+   * less than 1000 (1 second). The default value is 10000 milliseconds.
+   */
+  maxWaitMs: number
+
+  /**
+   * Specifies the TLS preference.  Possible values are:
+   *
+   * - 0 = No TLS
+   *
+   * - 1 = Prefer TLS if possible.
+   *
+   * - 2 = Require TLS
+   *
+   * The default value is 0. If TLS is preferred then DNS nameservers with TLS capability will be
+   * tried first. If none succeed, then UDP/TCP will be tried. If TLS is required, then only TLS
+   * capable nameservers will be tried and all DNS queries will use TLS.
+   *
+   * Note: To use TLS, your application needs to first specify nameservers by calling AddNameserver
+   * once per nameserver with the supportsTls argument set to `true`.
+   */
+  tlsPref: number
+
+  /**
+   * This is a catch-all property to be used for uncommon needs. This property defaults to the empty
+   * string and should typically remain empty.
+   */
+  uncommonOptions: string
+
+  // ---- Methods ----
+
+  /**
+   * Returns the IP address of the Nth nameserver currently used by Chilkat for DNS queries and
+   * domain to IP address lookups. The `index` specifies the index of the nameserver. The 1st
+   * nameserver is at `index` 0.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Dns.lastErrorText}.
+   */
+  getNameserver(index: number): string
+
+  /**
+   * Performs an DNS query for `domain` and returns the answer in `answer`. The type of DNS query is
+   * specified in `recordType` and can be A, AAAA, ALIAS, CAA, MX, NS, SOA, TXT. Additional record
+   * types can be added as needed.
+   *
+   * This call blocks the JavaScript thread until Chilkat returns; from UI code prefer
+   * {@link Dns.queryAsync}.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Dns.lastErrorText}.
+   */
+  query(recordType: string, domain: string, answer: JsonObject): void
+
+  /**
+   * Asynchronous form of {@link Dns.query}: 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 Dns.abort} (which cancels it) and the {@link Dns.onPercentDone} /
+   * {@link Dns.onProgressInfo} callbacks, which report progress while it runs.
+   *
+   * The promise rejects with an Error if the call fails; the full log is in
+   * {@link Dns.lastErrorText}.
+   */
+  queryAsync(recordType: string, domain: string, answer: JsonObject): Promise<void>
+
+  /**
+   * Adds a new nameserver to the collection of nameservers used by Chilkat for DNS queries and
+   * domain to IP address lookups. The `ipAddr` specifies the IPv4 address of the nameserver. The
+   * `supportsTls` indicates if the namserver supports DoT (DNS over TLS. DoT uses port 853 for
+   * encrypted DNS communication.) If the TlsPreference property is set to 1 or 2, then Chilkat will
+   * use TLS nameservers.
+   */
+  addNameserver(ipAddr: string, supportsTls: boolean): void
+
+  /**
+   * Removes a nameserver from the collection of nameservers used by Chilkat. The `ipAddr` is the
+   * IPv4 address of the nameserver to be removed.
+   */
+  removeNameserver(ipAddr: string): void
+
+  /**
+   * Removes all nameservers from the collection of nameservers used by Chilkat. An application can
+   * call this method to reset to 0 nameservers before adding new nameservers. If a DNS domain to IP
+   * address resolution is needed by Chilkat, then the auto-assigned nameserver IP addresses will be
+   * automaticaly restored.
+   */
+  removeAllNameservers(): void
+
+  /**
+   * Adds the default (auto-assigned) nameservers to the collection of nameservers used by Chilkat
+   * for DNS queries and domain to IP address lookups.
+   */
+  addDefaultNameservers(): 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 Dns.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
+}