homebridge-plugin-utils/dist/service.d.ts

Opinionated utilities to provide common capabilities and create rich configuration webUI experiences for Homebridge plugins.

import { HAP, PlatformAccessory, Service, WithUUID } from "homebridge";
import { Nullable } from "./util.js";
/**
 * Utility method that either creates a new service on an accessory, if needed, or returns an existing one. It optionally executes a callback to initialize a new
 * instance of a service, if needed. Additionally, the various name characteristics of the service will be set to the specified name, optionally adding them as needed.
 * @param hap             - HAP instance associated with the Homebridge plugin.
 * @param accessory       - Homebridge accessory to check.
 * @param serviceType     - Service type that is being instantiated or retrieved.
 * @param name            - Name to be displayed to the end user for this service.
 * @param subtype         - Service subtype, if needed.
 * @param onServiceCreate - Callback to be used when a new service is created. It is not called when an existing service is found.
 *
 * @returns Returns the created or retrieved service, `null` otherwise.
 *
 * @remarks `onServiceCreate` is called with the newly created service as an argument to allow the caller to optionally configure it.
 *
 * @category Accessory
 */
export declare function acquireService(hap: HAP, accessory: PlatformAccessory, serviceType: WithUUID<typeof Service>, name: string, subtype?: string, onServiceCreate?: (svc: Service) => void): Nullable<Service>;
/**
 * Validate whether a service should exist, removing it if needed.
 * @param accessory       - Homebridge accessory to check.
 * @param serviceType     - Service type that is being instantiated or retrieved.
 * @param validate        - Function to be used to test whether a service should exist or not.
 * @param subtype         - Service subtype, if needed.
 *
 * @returns Returns `true` if the service is valid, will remove the service and return `false` otherwise.
 *
 * @remarks `validate` is called with an argument of `true` if the service currently exists on the accessory and `false` otherwise.
 *
 * @category Accessory
 */
export declare function validService(accessory: PlatformAccessory, serviceType: WithUUID<typeof Service>, validate: (hasService: boolean) => boolean, subtype?: string): boolean;