dbus-sdk/build/LocalService.d.ts

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

import { LocalObject } from './LocalObject';
import { DBus } from './DBus';
import { ObjectManagerInterface } from './lib/common/ObjectManagerInterface';
import { RunServiceOpts } from './types/RunServiceOpts';
import { RequestNameResultCode } from './lib/enums/RequestNameResultCode';
/**
 * A class representing a local DBus service.
 * This class manages a collection of objects and their associated interfaces within a DBus service.
 * It handles connecting to a DBus bus, processing incoming method calls, and managing the lifecycle
 * of the service. It serves as the top-level entity for a local DBus service implementation.
 */
export declare class LocalService {
    #private;
    /**
     * The DBus instance associated with this service.
     * Provides the connection to the DBus bus for communication and message handling.
     */
    dbus: DBus;
    /**
     * Getter for the ObjectManager interface associated with this service.
     * Provides access to the 'org.freedesktop.DBus.ObjectManager' interface on the root object,
     * if available, for managing object hierarchies.
     *
     * @returns The ObjectManagerInterface instance if found on the root object, otherwise undefined.
     */
    get objectManager(): ObjectManagerInterface | undefined;
    /**
     * Getter for the name of this local service.
     * Returns the validated service name set during construction.
     *
     * @returns The service name as a string (e.g., 'org.example.Service').
     */
    get name(): string;
    /**
     * Constructor for LocalService.
     * Initializes the service with a validated service name and adds a root object
     * to serve as the base of the object hierarchy.
     *
     * @param serviceName - The DBus service name to be validated and set (e.g., 'org.example.Service').
     * @throws {LocalServiceInvalidNameError} If the provided name does not meet DBus naming criteria.
     */
    constructor(serviceName: string);
    /**
     * Validates a DBus service name based on DBus naming rules.
     * Ensures the name is a non-empty string, within length limits, 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, hyphens) in each element.
     *
     * @param serviceName - The name to validate.
     * @returns The validated service name if it passes all checks.
     * @throws {LocalServiceInvalidNameError} If the name does not meet DBus naming criteria.
     */
    protected validateDBusServiceName(serviceName: string | any): string;
    /**
     * Formats an error to ensure it has a valid DBus error name.
     * Appends the service name as a prefix if the error name does not match DBus naming conventions.
     * If the error name still doesn't match after prefixing, defaults to a generic error name with the service prefix.
     *
     * @param error - The error to format.
     * @returns The formatted error with a valid DBus error name (e.g., 'org.example.Service.Error').
     */
    protected formatDBusError(error: Error): Error;
    /**
     * Connects to a DBus bus and starts the service.
     * Establishes a connection to the bus using the provided options, registers the method call handler
     * to process incoming requests, and requests ownership of the service name on the bus to make it
     * available for clients to interact with, using configurable flags for name request behavior.
     *
     * @param opts - Connection options for the DBus bus (e.g., socket path, TCP details) and optional flags for name request behavior.
     * @returns A Promise that resolves to a RequestNameResultCode indicating the result of the service name request.
     */
    run(opts: RunServiceOpts): Promise<RequestNameResultCode>;
    /**
     * Stops the service and disconnects from the DBus bus.
     * Releases ownership of the service name to allow other services to claim it, removes the method
     * call handler to stop processing requests, and closes the connection to the bus to clean up resources.
     *
     * @returns A Promise that resolves when the service is stopped and disconnected from the bus.
     */
    stop(): Promise<void>;
    /**
     * Adds a LocalObject to this service.
     * Associates the object with this service, linking it to the service's context for further operations,
     * and notifies the object manager of the addition if an ObjectManager interface is available on the root object.
     *
     * @param localObject - The LocalObject instance to add to this service.
     * @returns A boolean indicating whether the object was successfully added (true if added, false if already present).
     * @throws {LocalObjectPathExistsError} If an object with the same path already exists and is not the same instance.
     */
    addObject(localObject: LocalObject): boolean;
    /**
     * Removes a LocalObject from this service by instance.
     * Unlinks the object from the service to prevent further operations and notifies the object manager
     * of the removal if an ObjectManager interface is available on the root object.
     *
     * @param localObject - The LocalObject instance to remove.
     * @returns A boolean indicating whether the object was successfully removed (true if removed, false if not found).
     */
    removeObject(localObject: LocalObject): boolean;
    /**
     * Removes a LocalObject from this service by object path.
     * Unlinks the object from the service to prevent further operations and notifies the object manager
     * of the removal if an ObjectManager interface is available on the root object.
     *
     * @param localObjectPath - The path of the object to remove.
     * @returns A boolean indicating whether the object was successfully removed (true if removed, false if not found).
     */
    removeObject(localObjectPath: string): boolean;
    /**
     * Lists all objects associated with this service.
     * Provides a convenient way to inspect all objects currently linked to the service by returning
     * a record mapping object paths to their respective LocalObject instances.
     *
     * @returns A record mapping object paths to their LocalObject instances.
     */
    listObjects(): Record<string, LocalObject>;
    /**
     * Finds a LocalObject by its path.
     * Allows retrieval of a specific object by its object path with type casting for specialized object types.
     *
     * @param objectPath - The path of the object to find (e.g., '/org/example/Object').
     * @returns The LocalObject instance of the specified type if found, otherwise undefined.
     * @template T - The type of LocalObject to cast the result to (defaults to LocalObject).
     */
    findObjectByPath<T extends LocalObject = LocalObject>(objectPath: string): T | undefined;
    /**
     * Lists all object paths associated with this service.
     * Provides a quick way to retrieve just the paths of the objects for enumeration purposes.
     *
     * @returns An array of object paths as strings.
     */
    listObjectPaths(): string[];
}
//# sourceMappingURL=LocalService.d.ts.map