dbus-sdk/build/lib/DBusBufferDecoder.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';
import { DataType } from '../types/DataType';
import { DBusTypeClass } from './DBusTypeClass';
/**
 * A decoder for reading DBus data from a binary buffer, following the DBus wire format.
 * Supports various DBus data types with proper alignment and endianness handling.
 * This class provides methods to decode basic types (e.g., integers, strings) and
 * container types (e.g., arrays, structs) as per the DBus specification.
 */
export declare class DBusBufferDecoder {
    /**
     * The endianness of the buffer data (Little Endian or Big Endian).
     * Default is Little Endian (LE) as specified by DBusMessageEndianness.LE,
     * which determines how multi-byte values are read from the buffer.
     */
    readonly endianness: DBusMessageEndianness;
    /**
     * Auto convert BigInt type to Number type
     * @protected
     */
    protected readonly convertBigIntToNumber: boolean;
    /**
     * The binary buffer containing the DBus data to be decoded.
     * This holds the raw bytes that the decoder reads from during operation.
     */
    protected buffer: Buffer;
    /**
     * The current reading position (offset) in the buffer.
     * Incremented as data is read from the buffer, tracking the progress of decoding.
     */
    protected offset: number;
    /**
     * Creates a new DBusBufferDecoder instance.
     * Initializes the decoder with the specified endianness and buffer,
     * optionally setting the initial offset for reading.
     *
     * @param endianness - The endianness to use for reading multi-byte values (default: Little Endian).
     * @param buffer - The binary buffer containing the DBus data to decode.
     * @param offset - The initial offset to start reading from (default: 0).
     * @param convertBigIntToNumber - Convert bigint value to number (default: false)
     */
    constructor(endianness: DBusMessageEndianness | undefined, buffer: Buffer, offset?: number, convertBigIntToNumber?: boolean);
    /**
     * Aligns the current offset to the specified byte boundary.
     * This ensures that data reads start at the correct position as per DBus alignment rules,
     * adding padding bytes to the offset if necessary.
     *
     * @param alignment - The byte boundary to align to (e.g., 1, 2, 4, 8).
     * @returns The instance itself for method chaining.
     * @throws {AlignmentError} If the aligned offset would exceed the buffer length.
     * @protected
     */
    protected align(alignment: number): this;
    /**
     * Reads a BYTE type value from the buffer.
     * BYTE is an 8-bit unsigned integer with no specific alignment requirement (1-byte alignment).
     *
     * @returns The byte value (0-255) wrapped in a DBusSignedValue instance with signature 'y'.
     * @throws {ReadBufferError} If there are not enough bytes left in the buffer to read a BYTE.
     */
    readByte(): DBusSignedValue;
    /**
     * Reads a BOOLEAN type value from the buffer.
     * BOOLEAN is stored as a 32-bit unsigned integer (0 for false, 1 for true) and requires 4-byte alignment.
     *
     * @returns The boolean value (true or false) wrapped in a DBusSignedValue instance with signature 'b'.
     * @throws {ReadBufferError} If there are not enough bytes left in the buffer to read a BOOLEAN.
     * @throws {InvalidValueError} If the read value is neither 0 nor 1.
     */
    readBoolean(): DBusSignedValue;
    /**
     * Reads an INT16 type value from the buffer.
     * INT16 is a 16-bit signed integer and requires 2-byte alignment.
     *
     * @returns The 16-bit signed integer value wrapped in a DBusSignedValue instance with signature 'n'.
     * @throws {ReadBufferError} If there are not enough bytes left in the buffer to read an INT16.
     */
    readInt16(): DBusSignedValue;
    /**
     * Reads a UINT16 type value from the buffer.
     * UINT16 is a 16-bit unsigned integer and requires 2-byte alignment.
     *
     * @returns The 16-bit unsigned integer value wrapped in a DBusSignedValue instance with signature 'q'.
     * @throws {ReadBufferError} If there are not enough bytes left in the buffer to read a UINT16.
     */
    readUInt16(): DBusSignedValue;
    /**
     * Reads an INT32 type value from the buffer.
     * INT32 is a 32-bit signed integer and requires 4-byte alignment.
     *
     * @returns The 32-bit signed integer value wrapped in a DBusSignedValue instance with signature 'i'.
     * @throws {ReadBufferError} If there are not enough bytes left in the buffer to read an INT32.
     */
    readInt32(): DBusSignedValue;
    /**
     * Reads a UINT32 type value from the buffer.
     * UINT32 is a 32-bit unsigned integer and requires 4-byte alignment.
     *
     * @returns The 32-bit unsigned integer value wrapped in a DBusSignedValue instance with signature 'u'.
     * @throws {ReadBufferError} If there are not enough bytes left in the buffer to read a UINT32.
     */
    readUInt32(): DBusSignedValue;
    /**
     * Reads an INT64 type value from the buffer.
     * INT64 is a 64-bit signed integer and requires 8-byte alignment.
     *
     * @returns The 64-bit signed integer value as a bigint wrapped in a DBusSignedValue instance with signature 'x'.
     * @throws {ReadBufferError} If there are not enough bytes left in the buffer to read an INT64.
     */
    readInt64(): DBusSignedValue;
    /**
     * Reads a UINT64 type value from the buffer.
     * UINT64 is a 64-bit unsigned integer and requires 8-byte alignment.
     *
     * @returns The 64-bit unsigned integer value as a bigint wrapped in a DBusSignedValue instance with signature 't'.
     * @throws {ReadBufferError} If there are not enough bytes left in the buffer to read a UINT64.
     */
    readUInt64(): DBusSignedValue;
    /**
     * Reads a DOUBLE type value from the buffer.
     * DOUBLE is a 64-bit double-precision floating-point number and requires 8-byte alignment.
     *
     * @returns The double-precision floating-point value wrapped in a DBusSignedValue instance with signature 'd'.
     * @throws {ReadBufferError} If there are not enough bytes left in the buffer to read a DOUBLE.
     */
    readDouble(): DBusSignedValue;
    /**
     * Reads a UNIX_FD type value from the buffer.
     * UNIX_FD is a 32-bit unsigned integer representing a file descriptor index and requires 4-byte alignment.
     *
     * @returns The file descriptor index wrapped in a DBusSignedValue instance with signature 'h'.
     * @throws {ReadBufferError} If there are not enough bytes left in the buffer to read a UNIX_FD.
     */
    readUnixFD(): DBusSignedValue;
    /**
     * Reads a STRING type value from 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.
     *
     * @returns The string value wrapped in a DBusSignedValue instance with signature 's'.
     * @throws {ReadBufferError} If there are not enough bytes left in the buffer to read the STRING length or content.
     * @throws {ReadBufferError} If the null terminator is not found or is invalid.
     */
    readString(): DBusSignedValue;
    /**
     * Reads an OBJECT_PATH type value from 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.
     *
     * @returns The object path as a string wrapped in a DBusSignedValue instance with signature 'o'.
     * @throws {ReadBufferError} If there are not enough bytes left in the buffer to read the OBJECT_PATH length or content.
     * @throws {ReadBufferError} If the null terminator is not found or is invalid.
     */
    readObjectPath(): DBusSignedValue;
    /**
     * Reads a SIGNATURE type value from the buffer.
     * SIGNATURE is a string of type codes with a 1-byte length field and no specific alignment requirement.
     *
     * @returns The signature as a string wrapped in a DBusSignedValue instance with signature 'g'.
     * @throws {ReadBufferError} If there are not enough bytes left in the buffer to read the SIGNATURE length or content.
     * @throws {ReadBufferError} If the null terminator is not found or is invalid.
     */
    readSignature(): DBusSignedValue;
    /**
     * Reads an ARRAY type value from the buffer.
     * ARRAY starts with a 32-bit length field (total byte length of array data) and requires 4-byte alignment.
     * Elements are read within a sub-buffer to isolate alignment.
     *
     * @param elementType - The DataType of the array elements, required for parsing elements.
     * @returns The array of elements wrapped in a DBusSignedValue instance with signature 'a{elementType}'.
     * @throws {ReadBufferError} If there are not enough bytes left in the buffer to read the ARRAY length or content.
     */
    readArray(elementType: DataType): DBusSignedValue;
    /**
     * Reads a STRUCT type value from the buffer.
     * STRUCT is a sequence of fields and requires 8-byte alignment at the start.
     *
     * @param fieldTypes - The DataType array representing the types of struct fields.
     * @returns The struct value as an array of fields wrapped in a DBusSignedValue instance with signature '('.
     * @throws {SignatureError} If field types are not provided or empty.
     */
    readStruct(fieldTypes?: DataType[]): DBusSignedValue;
    /**
     * Reads a DICT_ENTRY type value from the buffer.
     * DICT_ENTRY is a key-value pair used in dictionaries and requires 8-byte alignment at the start.
     *
     * @param keyType - The DataType representing the key type of the dictionary entry.
     * @param valueType - The DataType representing the value type of the dictionary entry.
     * @returns The dictionary entry value as a key-value pair wrapped in a DBusSignedValue instance with signature '{'.
     * @throws {SignatureError} If key or value types are not provided.
     */
    readDictEntry(keyType?: DataType, valueType?: DataType): DBusSignedValue;
    /**
     * Reads a VARIANT type value from the buffer.
     * VARIANT is a dynamic type container with a signature field followed by data, no specific alignment required.
     *
     * @returns The variant value wrapped in a DBusSignedValue instance with signature 'v'.
     * @throws {ReadBufferError} If there are not enough bytes left in the buffer to read the VARIANT signature or content.
     * @throws {SignatureError} If the variant signature does not describe exactly one type.
     */
    readVariant(): DBusSignedValue;
    /**
     * Reads a single value from the buffer based on the provided DataType.
     * Dispatches the reading to the appropriate method based on the type signature.
     * Handles both basic and container types recursively.
     *
     * @param type - The DataType describing the type to read from the buffer.
     * @returns The value wrapped in a DBusSignedValue instance with the appropriate signature.
     * @throws {SignatureError} If the type is unsupported or has invalid child types for containers.
     */
    readSignedValue(type: DataType): DBusSignedValue;
    /**
     * Reads multiple values from the buffer based on the provided signature string.
     * The signature is parsed into DataType(s), and values are read accordingly, then converted to DBusTypeClass instances.
     *
     * @param signature - The DBus signature string describing the type(s) to read (e.g., 'is' for integer and string).
     * @returns An array of DBusTypeClass instances representing the read values.
     * @throws {SignatureError} If the signature is empty or invalid.
     */
    toSignedValues(signature: string): DBusTypeClass[];
    /**
     * Decodes values from the buffer based on the provided signature and optionally converts them to plain JavaScript values or typed DBusTypeClass instances.
     * This method can unwrap DBusSignedValue instances into raw values for easier use or return typed instances for further processing.
     *
     * @param signature - The DBus signature string describing the type(s) to read (e.g., 'is' for integer and string).
     * @param typed - If true, returns an array of DBusTypeClass instances; if false, returns plain JavaScript values (default: false).
     * @returns An array of either plain JavaScript values or DBusTypeClass instances, based on the typed parameter.
     * @throws {SignatureError} If the signature is empty or invalid.
     */
    decode(signature: string, typed?: boolean): any[];
}
//# sourceMappingURL=DBusBufferDecoder.d.ts.map