dbus-sdk/build/lib/DBusBufferEncoder.d.ts

A Node.js SDK for interacting with DBus, enabling seamless service calling and exposure with TypeScript support

import { DBusMessageEndianness } from './enums/DBusMessageEndianness';
import { DBusSignedValue } from './DBusSignedValue';
/**
 * A class for encoding data into a binary buffer following the DBus wire format.
 * Supports various DBus data types with proper alignment and endianness handling.
 * This class provides methods to encode basic types (e.g., integers, strings) and
 * container types (e.g., arrays, structs) as per the DBus specification.
 */
export declare class DBusBufferEncoder {
    /**
     * The endianness used for encoding DBus messages.
     * Defaults to little-endian (LE) as it is the most common in DBus implementations.
     * Determines the byte order for multi-byte values in the message.
     */
    readonly endianness: DBusMessageEndianness;
    /**
     * The binary buffer where encoded DBus data is stored.
     * This holds the raw bytes that are built during encoding operations.
     */
    protected buffer: Buffer;
    /**
     * Constructor for DBusBufferEncoder.
     * Initializes the encoder with the specified endianness and an optional initial buffer.
     * Optionally aligns the buffer to a specified boundary if provided.
     *
     * @param endianness - The byte order for encoding (little-endian or big-endian, default: Little Endian).
     * @param initBuffer - An initial buffer to start with, if any (default: empty buffer).
     * @param alignment - An initial alignment requirement, if specified, to align the buffer start.
     */
    constructor(endianness?: DBusMessageEndianness, initBuffer?: Buffer, alignment?: number);
    /**
     * Aligns the buffer to the specified byte boundary.
     * Adds padding bytes (zeros) to ensure the buffer length meets the alignment requirement,
     * which is necessary for certain DBus data types.
     *
     * @param alignment - The byte boundary to align to (e.g., 1, 2, 4, 8).
     * @returns The instance itself for method chaining.
     * @protected
     */
    protected align(alignment: number): this;
    /**
     * Encodes a BYTE type value into the buffer.
     * BYTE is an 8-bit unsigned integer with no specific alignment requirement (1-byte alignment).
     *
     * @param value - The byte value to encode (0-255).
     * @returns The instance itself for method chaining.
     */
    writeByte(value: number): this;
    /**
     * Encodes a BOOLEAN type value into the buffer.
     * BOOLEAN is stored as a 32-bit unsigned integer (0 for false, 1 for true) and requires 4-byte alignment.
     *
     * @param value - The boolean value to encode (true or false).
     * @returns The instance itself for method chaining.
     */
    writeBoolean(value: boolean): this;
    /**
     * Encodes an INT16 type value into the buffer.
     * INT16 is a 16-bit signed integer and requires 2-byte alignment.
     *
     * @param value - The 16-bit signed integer value to encode.
     * @returns The instance itself for method chaining.
     */
    writeInt16(value: number): this;
    /**
     * Encodes a UINT16 type value into the buffer.
     * UINT16 is a 16-bit unsigned integer and requires 2-byte alignment.
     *
     * @param value - The 16-bit unsigned integer value to encode.
     * @returns The instance itself for method chaining.
     */
    writeUInt16(value: number): this;
    /**
     * Encodes an INT32 type value into the buffer.
     * INT32 is a 32-bit signed integer and requires 4-byte alignment.
     *
     * @param value - The 32-bit signed integer value to encode.
     * @returns The instance itself for method chaining.
     */
    writeInt32(value: number): this;
    /**
     * Encodes a UINT32 type value into the buffer.
     * UINT32 is a 32-bit unsigned integer and requires 4-byte alignment.
     *
     * @param value - The 32-bit unsigned integer value to encode.
     * @returns The instance itself for method chaining.
     */
    writeUInt32(value: number): this;
    /**
     * Encodes an INT64 type value into the buffer.
     * INT64 is a 64-bit signed integer and requires 8-byte alignment.
     *
     * @param value - The 64-bit signed integer value to encode, provided as a bigint.
     * @returns The instance itself for method chaining.
     */
    writeInt64(value: bigint): this;
    /**
     * Encodes a UINT64 type value into the buffer.
     * UINT64 is a 64-bit unsigned integer and requires 8-byte alignment.
     *
     * @param value - The 64-bit unsigned integer value to encode, provided as a bigint.
     * @returns The instance itself for method chaining.
     */
    writeUInt64(value: bigint): this;
    /**
     * Encodes a DOUBLE type value into the buffer.
     * DOUBLE is a 64-bit double-precision floating-point number and requires 8-byte alignment.
     *
     * @param value - The double-precision floating-point value to encode.
     * @returns The instance itself for method chaining.
     */
    writeDouble(value: number): this;
    /**
     * Encodes a UNIX_FD type value into the buffer.
     * UNIX_FD is a 32-bit unsigned integer representing a file descriptor index and requires 4-byte alignment.
     *
     * @param fdIndex - The file descriptor index to encode.
     * @returns The instance itself for method chaining.
     */
    writeUnixFD(fdIndex: number): this;
    /**
     * Encodes a STRING type value into the buffer.
     * STRING consists of a 32-bit length field followed by UTF-8 encoded characters and a null terminator.
     * The length field requires 4-byte alignment.
     *
     * @param value - The string value to encode.
     * @returns The instance itself for method chaining.
     */
    writeString(value: string): this;
    /**
     * Encodes an OBJECT_PATH type value into the buffer.
     * OBJECT_PATH is a string with specific formatting rules, stored like STRING with a 32-bit length field.
     * The length field requires 4-byte alignment.
     *
     * @param value - The object path string to encode.
     * @returns The instance itself for method chaining.
     * @throws {ObjectPathError} If the object path does not conform to DBus specification formatting rules.
     */
    writeObjectPath(value: string): this;
    /**
     * Encodes a SIGNATURE type value into the buffer.
     * SIGNATURE is a string of type codes with a 1-byte length field and no specific alignment requirement.
     *
     * @param value - The signature string to encode.
     * @returns The instance itself for method chaining.
     * @throws {SignatureError} If the signature length exceeds the maximum allowed (255 bytes).
     */
    writeSignature(value: string): this;
    /**
     * Encodes an ARRAY type value into the buffer.
     * ARRAY starts with a 32-bit length field (total byte length of array data) and requires 4-byte alignment.
     * Additional alignment may be needed for specific array element types (e.g., dictionary entries).
     *
     * @param signedValues - Array elements, each associated with a signature as DBusSignedValue instances.
     * @param arrayItemSignature - Optional signature of array elements to determine additional alignment needs.
     * @returns The instance itself for method chaining.
     */
    writeArray(signedValues: DBusSignedValue[], arrayItemSignature?: string): this;
    /**
     * Encodes a STRUCT type value into the buffer.
     * STRUCT is a sequence of fields and requires 8-byte alignment at the start.
     *
     * @param signedValues - Struct fields, each associated with a signature as DBusSignedValue instances.
     * @returns The instance itself for method chaining.
     */
    writeStruct(signedValues: DBusSignedValue[]): this;
    /**
     * Encodes a DICT_ENTRY type value into the buffer.
     * DICT_ENTRY is a key-value pair used in dictionaries and requires 8-byte alignment at the start.
     *
     * @param signedValues - Dictionary entry as a key-value pair, must contain exactly two elements (key and value), each as a DBusSignedValue.
     * @returns The instance itself for method chaining.
     * @throws {SignatureError} If the dictionary entry does not contain exactly two elements.
     */
    writeDictEntry(signedValues: DBusSignedValue[]): this;
    /**
     * Encodes a VARIANT type value into the buffer.
     * VARIANT is a dynamic type container with a signature field followed by data, requiring no specific alignment (1-byte alignment).
     *
     * @param signedValue - Variant value, associated with a signature as a DBusSignedValue.
     * @returns The instance itself for method chaining.
     */
    writeVariant(signedValue: DBusSignedValue): this;
    /**
     * Builds the complete signature string for a given signed value.
     * Recursively handles nested structures like arrays, structs, dictionaries, and variants.
     *
     * @param signedValue - The signed value to build a signature for.
     * @returns The complete signature string representing the type structure of the value.
     * @throws {SignatureError} If the signature cannot be built due to invalid or unsupported types.
     * @private
     */
    private buildSignature;
    /**
     * Encodes a value based on its DBus type signature.
     * Routes the encoding to the appropriate method based on the signature of the provided DBusSignedValue.
     *
     * @param signedValue - The value to encode, associated with a DBus signature as a DBusSignedValue.
     * @returns The instance itself for method chaining.
     * @throws {SignatureError} If the type signature is unsupported.
     */
    writeSignedValue(signedValue: DBusSignedValue): this;
    /**
     * Retrieves the current encoded buffer.
     * Returns the buffer containing all data encoded so far.
     *
     * @returns The current buffer with encoded data.
     */
    getBuffer(): Buffer;
    /**
     * Encodes a value or set of values based on a DBus signature.
     * Parses the input value(s) into DBusSignedValue instances based on the signature and encodes them into the buffer.
     *
     * @param signature - The DBus signature defining the type(s) of the value(s) to encode.
     * @param value - The value(s) to encode, can be raw data or already wrapped as DBusSignedValue(s).
     * @param debug - If true, logs the parsed DBusSignedValue instances for debugging purposes (default: false).
     * @returns The encoded buffer containing the data.
     */
    encode(signature: string, value: any | DBusSignedValue | DBusSignedValue[], debug?: boolean): Buffer;
}
//# sourceMappingURL=DBusBufferEncoder.d.ts.map