@chilkat/react-native 11.6.1

package/src/specs/Prng.nitro.ts

@@ -0,0 +1,348 @@
+// Generated by ReactNativeNs.RnGenerator -- do not edit.
+import type { HybridObject } from 'react-native-nitro-modules'
+import type { BinData } from './BinData.nitro'
+
+/**
+ * Generate random bytes, encoded values, passwords, and application identifiers.
+ *
+ * Use `Prng` when an application needs random bytes or
+ * random text values for cryptographic or application-level purposes. The class
+ * can seed itself automatically from the system entropy source, accept
+ * additional entropy from the application, and produce random data as raw
+ * bytes, encoded strings, passwords, integers, booleans, GUID-style values, or
+ * higher-level identifiers such as Firebase Push IDs.
+ *
+ * **Random bytes**
+ *
+ * Generate random byte data for keys, IVs, nonces, salts, tokens, test
+ * data, or protocol-specific binary values.
+ *
+ * **Encoded random strings**
+ *
+ * Produce random values encoded as Base64, hex, URL-safe text, or other
+ * supported encodings when binary data must be represented as text.
+ *
+ * **Password generation**
+ *
+ * Create random passwords using configurable character sets and length
+ * requirements.
+ *
+ * **Entropy input**
+ *
+ * Allow the PRNG to seed from the system entropy source and optionally add
+ * application-provided entropy.
+ *
+ * **Random application values**
+ *
+ * Generate random integers, booleans, GUID-style values, and other
+ * convenient random outputs for application logic.
+ *
+ * **Firebase Push IDs**
+ *
+ * Create Firebase-style push IDs for applications that need sortable,
+ * client-generated identifiers.
+ *
+ * **Common pattern:**
+ * Use `Prng` to create random material in the form required by the
+ * caller: bytes for cryptographic inputs, encoded strings for tokens or API
+ * values, passwords for user-facing credentials, or Firebase Push IDs for
+ * sortable identifiers. For cryptographic workflows, generate enough random
+ * bytes for the algorithm or protocol and avoid reducing randomness by
+ * truncating or reformatting values incorrectly.
+ *
+ * For an extended overview, see
+ * [Prng Class Overview](https://www.chilkatsoft.com/prng_class_overview.asp).
+ *
+ * Each `Prng` 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 Prng()`.
+ */
+export interface Prng 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
+
+  /**
+   * Selects the pseudo-random number generator used by this object. The only supported value is
+   * `fortuna`, which is also the default. Chilkat's Fortuna implementation uses AES-256 for
+   * generation and SHA-256 in its entropy-processing and reseeding design.
+   *
+   * **Compatibility note:** Assigning any value other than `fortuna` is ignored. Applications
+   * should normally leave this property unchanged.
+   */
+  prngName: string
+
+  // ---- Methods ----
+
+  /**
+   * Adds caller-supplied seed material to the PRNG. `ARG1` contains the bytes in the text encoding
+   * named by `ARG2`, such as `hex`, `base64`, or `ascii`. For Fortuna, the decoded bytes are
+   * incorporated into the internal entropy pools and become available to later reseeding.
+   *
+   * This method is optional and is not the normal way an application obtains entropy for the PRNG.
+   * It may be called more than once and at any point during the lifetime of the object. It returns
+   * `true` when the input is decoded and accepted, or `false` if the encoding is invalid or another
+   * error occurs.
+   *
+   * **Automatic system seeding:** If no entropy has been added before the first request for random
+   * output, Chilkat automatically obtains 32 bytes from the platform's cryptographic system entropy
+   * source to seed the PRNG. This is the normal and recommended mode of operation. Call
+   * `AddEntropy` only when the application has additional trustworthy entropy to contribute or
+   * deliberately needs deterministic seeding for testing.
+   *
+   * **Repeatable tests:** A fresh `Prng` object can be seeded with the same deterministic values to
+   * reproduce the same output sequence, provided the same entropy calls and random-generation calls
+   * occur in the same order. Predictable seed material is appropriate only for tests and debugging.
+   * Do not use it for real keys, nonces, passwords, or tokens.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Prng.lastErrorText}.
+   */
+  addEntropy(entropy: string, encoding: string): void
+
+  /**
+   * Exports a Base64-encoded value derived from the PRNG's accumulated entropy pools. The internal
+   * pools are rehashed for export so the returned value is not a direct disclosure of the generator
+   * state.
+   *
+   * The returned value can be persisted and supplied to `ImportEntropy` when a later process
+   * starts. For language bindings in which this method directly returns a string, check
+   * `LastMethodSuccess` before using the result.
+   *
+   * **Seed-file guidance:** Imported entropy can improve startup behavior, but it should not be the
+   * only seed used indefinitely. After importing, also allow Chilkat to obtain fresh
+   * operating-system entropy. Protect persisted entropy from unauthorized modification and
+   * accidental reuse across cloned systems.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Prng.lastErrorText}.
+   */
+  exportEntropy(): string
+
+  /**
+   * Generates a Firebase-compatible push ID. A push ID is a 20-character identifier built from a
+   * 48-bit millisecond timestamp followed by 72 bits of randomness, encoded with Firebase's ordered
+   * 64-character alphabet.
+   *
+   * The timestamp prefix makes push IDs sort approximately by creation time, while the random
+   * portion makes collisions highly unlikely across independent clients. For language bindings in
+   * which this method directly returns a string, check `LastMethodSuccess` before using the result.
+   *
+   * **Not a secret:** A push ID is an identifier, not an authentication token. Its prefix reveals
+   * approximate creation time, and uniqueness is probabilistic rather than an absolute guarantee.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Prng.lastErrorText}.
+   */
+  firebasePushId(): string
+
+  /**
+   * Generates `ARG1` random bytes and returns those bytes as text using the encoding named by
+   * `ARG2`, such as `hex`, `base64`, or `base64url`. `ARG1` is the number of binary bytes before
+   * text encoding; it is not the number of output characters.
+   *
+   * If no entropy has been added before the first request for random output, Chilkat automatically
+   * obtains 32 bytes from the platform's cryptographic system entropy source to seed the PRNG.
+   *
+   * For language bindings in which this method directly returns a string, check `LastMethodSuccess`
+   * before using the result.
+   *
+   * **Encoding does not add entropy:** Hex, Base64, and other encodings represent the same random
+   * bytes in different textual forms. Choose `numBytes` from the security requirement of the key,
+   * nonce, salt, or token—not from the desired text length.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Prng.lastErrorText}.
+   */
+  genRandom(numBytes: number, encoding: string): string
+
+  /**
+   * Requests `ARG1` bytes from the platform's cryptographic system entropy source and returns them
+   * using the text encoding named by `ARG2`. This obtains system-provided random seed material
+   * directly; it is different from asking the Fortuna generator to expand its current state with
+   * `GenRandom`.
+   *
+   * For seeding this PRNG, 32 bytes normally provide the full 256-bit seed input expected by the
+   * implementation. Applications may request another amount when a protocol specifically requires
+   * raw bytes from the system source.
+   *
+   * For language bindings in which this method directly returns a string, check `LastMethodSuccess`
+   * before using the result.
+   *
+   * **Usually unnecessary:** The simplest secure use is to call a random-generation method
+   * directly. If no entropy was added explicitly, Chilkat automatically obtains 32 bytes of system
+   * entropy on the first generation request.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Prng.lastErrorText}.
+   */
+  getEntropy(numBytes: number, encoding: string): string
+
+  /**
+   * Imports the Base64-encoded entropy value previously returned by `ExportEntropy`. The imported
+   * material is supplied to the PRNG for use in its entropy and reseeding process.
+   *
+   * Returns `true` if the value is valid and imported successfully. Returns `false` if it cannot be
+   * decoded or imported; check `LastErrorText` for details.
+   *
+   * **Recommended startup sequence:** Import persisted entropy before the first random-generation
+   * call, then mix in fresh system entropy or allow the first generation call to perform Chilkat's
+   * automatic system seeding.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Prng.lastErrorText}.
+   */
+  importEntropy(entropy: string): void
+
+  /**
+   * Returns a pseudorandom integer in the inclusive range from `ARG1` through `ARG2`. For example,
+   * `RandomInt(4, 8)` can return 4, 5, 6, 7, or 8.
+   *
+   * The caller should ensure that `ARG1` is less than or equal to `ARG2`.
+   *
+   * **Cryptographic material:** Use `GenRandom`, `GenRandomBytes`, or `GenRandomBd` when a protocol
+   * requires an exact number of random bytes. Do not assemble keys or nonces from decimal random
+   * integers unless the protocol explicitly defines that representation.
+   */
+  randomInt(low: number, high: number): number
+
+  /**
+   * Generates a password of exactly `ARG1` characters while applying the requested composition
+   * rules:
+   *
+   * ArgumentEffect
+   *
+   * | `ARG2` |  | When `true`, require at least one digit from `0-9`. |
+   *
+   * | `ARG3` | | When `true`, require at least one lowercase and at least one uppercase US-ASCII
+   * letter. |
+   *
+   * | `ARG4` | | When nonempty, require at least one character from this supplied set, such as
+   * `!@#$%`. |
+   *
+   * | `ARG5` | | Exclude every listed character from the generated password. This is useful for
+   * ambiguous characters such as `iIlL1oO0`. |
+   *
+   * The requested length must be large enough to satisfy all enabled requirements, and exclusions
+   * must not remove every usable character from a required category. For language bindings in which
+   * this method directly returns a string, check `LastMethodSuccess` before using the result.
+   *
+   * **Password policy note:** Longer randomly generated passwords generally provide more security
+   * than short passwords with many composition rules. Also ensure the receiving system accepts
+   * every character that may be generated.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Prng.lastErrorText}.
+   */
+  randomPassword(length: number, mustIncludeDigit: boolean, upperAndLowercase: boolean, mustHaveOneOf: string, excludeChars: string): string
+
+  /**
+   * Generates a string of exactly `ARG1` characters. The remaining arguments select the character
+   * categories placed in the source alphabet:
+   *
+   * ArgumentWhen `true`
+   *
+   * | `ARG2` |  | Include digits `0-9`. |
+   *
+   * | `ARG3` |  | Include lowercase ASCII letters `a-z`. |
+   *
+   * | `ARG4` |  | Include uppercase ASCII letters `A-Z`. |
+   *
+   * At least one character category must be enabled. The flags define the pool from which each
+   * character is chosen; they do not guarantee that every enabled category appears in a particular
+   * result.
+   *
+   * **Requirement-aware passwords:** Use `RandomPassword` instead when the result must contain at
+   * least one digit, both uppercase and lowercase letters, or a required special character.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Prng.lastErrorText}.
+   */
+  randomString(length: number, bDigits: boolean, bLower: boolean, bUpper: boolean): string
+
+  /**
+   * Generates `ARG1` random bytes and appends them to the existing contents of the `BinData` object
+   * passed in `ARG2`. The destination is not cleared before the bytes are added.
+   *
+   * If no entropy has been added before the first request for random output, Chilkat automatically
+   * obtains 32 bytes from the platform's cryptographic system entropy source to seed the PRNG.
+   *
+   * Returns `true` on success or `false` on failure.
+   *
+   * **Appending behavior:** Call `BinData.Clear` first when the destination should contain only the
+   * newly generated bytes.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Prng.lastErrorText}.
+   */
+  genRandomBd(numBytes: number, bd: BinData): void
+}