dbus-sdk/build/LocalInterface.d.ts

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

import { DefineMethodOpts } from './types/DefineMethodOpts';
import { DefinePropertyOpts } from './types/DefinePropertyOpts';
import { DefineSignalOpts } from './types/DefineSignalOpts';
import { IntrospectInterface } from './types/IntrospectInterface';
import { DBus } from './DBus';
import { LocalObject } from './LocalObject';
import { DBusSignedValue } from './lib/DBusSignedValue';
/**
 * A class representing a local DBus interface.
 * This class enables the definition of methods, properties, and signals for a local DBus service,
 * facilitating the creation of custom interfaces. It manages name validation, introspection data,
 * and interactions with DBus for handling method calls, property access, and signal emission.
 */
export declare class LocalInterface {
    #private;
    /**
     * The LocalObject instance associated with this interface, if any.
     * Links the interface to a specific object within a DBus service for contextual operations.
     */
    object: LocalObject | undefined;
    /**
     * Getter for the DBus instance associated with this interface's object.
     * Provides access to the DBus connection for operations such as emitting signals or sending messages.
     *
     * @returns The DBus instance if the associated object is defined and connected, otherwise undefined.
     */
    get dbus(): DBus | undefined;
    /**
     * Getter for the name of this interface.
     * Returns the validated interface name set during construction.
     *
     * @returns The interface name as a string (e.g., 'org.example.MyInterface').
     */
    get name(): string;
    /**
     * Constructor for LocalInterface.
     * Initializes the interface with a validated name, ensuring it adheres to DBus naming rules
     * as specified in the DBus protocol documentation.
     *
     * @param interfaceName - The name of the interface to be validated and set (e.g., 'org.example.MyInterface').
     * @throws {LocalInterfaceInvalidNameError} If the provided name does not meet DBus naming criteria.
     */
    constructor(interfaceName: string);
    /**
     * Validates a DBus interface name based on DBus naming rules.
     * Ensures the name is a non-empty string, within length limits (255 bytes), contains at least two elements
     * separated by dots, does not start or end with a dot, avoids consecutive dots, and uses
     * only allowed characters (letters, digits, underscores) in each element.
     *
     * @param interfaceName - The name to validate.
     * @returns The validated interface name if it passes all checks.
     * @throws {LocalInterfaceInvalidNameError} If the name does not meet DBus naming criteria.
     */
    protected validateDBusInterfaceName(interfaceName: string | any): string;
    /**
     * Validates a DBus method name based on DBus naming rules.
     * Ensures the name is a non-empty string, within length limits (255 bytes), does not start with a digit,
     * and uses only allowed characters (letters, digits, underscores) as per DBus conventions.
     *
     * @param methodName - The name to validate.
     * @returns The validated method name if it passes all checks.
     * @throws {LocalInterfaceInvalidMethodNameError} If the name does not meet DBus naming criteria.
     */
    protected validateDBusMethodName(methodName: string | any): string;
    /**
     * Validates a DBus property name based on DBus naming rules.
     * Ensures the name is a non-empty string, within length limits (255 bytes), does not start with a digit,
     * and uses only allowed characters (letters, digits, underscores) as per DBus conventions.
     *
     * @param propertyName - The name to validate.
     * @returns The validated property name if it passes all checks.
     * @throws {LocalInterfaceInvalidPropertyNameError} If the name does not meet DBus naming criteria.
     */
    protected validateDBusPropertyName(propertyName: string | any): string;
    /**
     * Validates a DBus signal name based on DBus naming rules.
     * Ensures the name is a non-empty string, within length limits (255 bytes), does not start with a digit,
     * and uses only allowed characters (letters, digits, underscores) as per DBus conventions.
     *
     * @param signalName - The name to validate.
     * @returns The validated signal name if it passes all checks.
     * @throws {LocalInterfaceInvalidSignalNameError} If the name does not meet DBus naming criteria.
     */
    protected validateDBusSignalName(signalName: string | any): string;
    /**
     * Sets the LocalObject associated with this interface.
     * Links the interface to a specific object within a DBus service, providing context for operations
     * such as signal emission or property access on a specific object path.
     *
     * @param localObject - The LocalObject to associate with this interface, or undefined to clear the association.
     * @returns The instance of this LocalInterface for method chaining.
     */
    setObject(localObject: LocalObject | undefined): this;
    /**
     * Getter for the introspection data of this interface.
     * Provides metadata about the interface's methods, properties, and signals in a format suitable
     * for DBus introspection, allowing clients to discover the capabilities of this interface.
     *
     * @returns An IntrospectInterface object containing the name, methods, properties, and signals defined for this interface.
     */
    get introspectInterface(): IntrospectInterface;
    /**
     * Defines a new method for this interface.
     * Configures a method with specified input and output arguments and an implementation function,
     * validates the method name against DBus naming rules, and updates introspection data for discovery.
     *
     * @param opts - Options for defining the method, including name, input/output arguments, and the method implementation.
     * @returns The instance of this LocalInterface for method chaining.
     * @throws {LocalInterfaceMethodDefinedError} If a method with the same name is already defined.
     * @throws {LocalInterfaceInvalidMethodNameError} If the method name does not meet DBus naming criteria.
     */
    defineMethod(opts: DefineMethodOpts): this;
    /**
     * Removes a defined method from this interface.
     * Deletes the method from the internal record and removes its associated introspection data.
     *
     * @param name - The name of the method to remove.
     * @returns The instance of this LocalInterface for method chaining.
     */
    removeMethod(name: string): this;
    /**
     * Defines a new property for this interface.
     * Configures a property with a specified type, determines access mode (read, write, read-write) based on provided
     * getter/setter functions, and supports emitting property change signals if configured via options.
     * Updates introspection data for discovery and sets up asynchronous change notifications via setImmediate.
     *
     * @param opts - Options for defining the property, including name, type, access mode, getter/setter functions, and change emission settings.
     * @returns The instance of this LocalInterface for method chaining.
     * @throws {LocalInterfacePropertyDefinedError} If a property with the same name is already defined.
     * @throws {LocalInterfaceInvalidPropertyNameError} If the property name does not meet DBus naming criteria.
     */
    defineProperty(opts: DefinePropertyOpts): this;
    /**
     * Removes a defined property from this interface.
     * Deletes the property from the internal record and removes its associated introspection data.
     *
     * @param name - The name of the property to remove.
     * @returns The instance of this LocalInterface for method chaining.
     */
    removeProperty(name: string): this;
    /**
     * Defines a new signal for this interface.
     * Configures a signal with specified arguments and associates it with an EventEmitter for emission.
     * When the signal is triggered, it is sent over the DBus connection if the interface is associated
     * with an object and a DBus connection is available.
     *
     * @param opts - Options for defining the signal, including name, arguments, and associated event emitter.
     * @returns The instance of this LocalInterface for method chaining.
     * @throws {LocalInterfaceSignalDefinedError} If a signal with the same name is already defined.
     * @throws {LocalInterfaceInvalidSignalNameError} If the signal name does not meet DBus naming criteria.
     */
    defineSignal(opts: DefineSignalOpts): this;
    /**
     * Removes a defined signal from this interface.
     * Deletes the signal from the internal record, removes its listener from the associated event emitter,
     * and updates the introspection data by removing the signal's metadata.
     *
     * @param name - The name of the signal to remove.
     * @returns The instance of this LocalInterface for method chaining.
     */
    removeSignal(name: string): this;
    /**
     * Calls a defined method on this interface.
     * Executes the method implementation with the provided arguments after validating the input signature
     * to ensure compatibility with the defined method signature.
     *
     * @param name - The name of the method to call.
     * @param payloadSignature - The signature of the input arguments provided (e.g., 'si' for string and integer).
     * @param args - The arguments to pass to the method.
     * @returns A Promise resolving to an object containing the method's output signature (if defined) and result.
     * @throws {DBusError} If the method is not found or if the input signature does not match the expected signature.
     */
    callMethod(name: string, payloadSignature: string | undefined, ...args: any[]): Promise<{
        signature?: string;
        result: any;
    }>;
    /**
     * Sets the value of a defined property on this interface.
     * Validates the value against the property's signature by encoding and decoding it to ensure type compatibility
     * before invoking the setter function to update the property.
     *
     * @param name - The name of the property to set.
     * @param value - The value to set for the property.
     * @returns void
     * @throws {DBusError} If the property is not found, the value signature does not match the expected type,
     *                     or the property is read-only (no setter defined).
     */
    setProperty(name: string, value: any): void;
    /**
     * Gets the value of a defined property on this interface.
     * Retrieves the current value by invoking the getter function if available, returning it as a raw value.
     *
     * @param name - The name of the property to get.
     * @returns The property value as returned by the getter function.
     * @throws {DBusError} If the property is not found or is write-only (no getter defined).
     */
    getProperty(name: string): any;
    /**
     * Gets the value of a defined property as a DBusSignedValue on this interface.
     * Retrieves the property value using getProperty and parses it into a DBusSignedValue with the correct signature,
     * ensuring it is suitable for DBus operations like method replies or signal data.
     *
     * @param name - The name of the property to get.
     * @returns A DBusSignedValue instance representing the property value with its associated signature.
     * @throws {DBusError} If the property is not found or is write-only (no getter defined).
     */
    getPropertySignedValue(name: string): DBusSignedValue;
    /**
     * Gets all managed properties as a record of DBusSignedValue objects.
     * Iterates through all defined property names on this interface and retrieves their current values
     * as DBusSignedValue instances, providing a comprehensive view of the interface's properties.
     *
     * @returns A record mapping property names to their corresponding DBusSignedValue instances.
     */
    getManagedProperties(): Record<string, DBusSignedValue>;
    /**
     * Lists the names of all defined methods on this interface.
     * Provides a convenient way to inspect the available methods for introspection or debugging purposes.
     *
     * @returns An array of method names as strings.
     */
    methodNames(): string[];
    /**
     * Lists the names of all defined properties on this interface.
     * Provides a convenient way to inspect the available properties for introspection or debugging purposes.
     *
     * @returns An array of property names as strings.
     */
    propertyNames(): string[];
    /**
     * Lists the names of all defined signals on this interface.
     * Provides a convenient way to inspect the available signals for introspection or debugging purposes.
     *
     * @returns An array of signal names as strings.
     */
    signalNames(): string[];
}
//# sourceMappingURL=LocalInterface.d.ts.map