9.06 kBTypeScriptView Raw
1import { Service } from "../Service";
2/**
3 * A ControllerServiceMap represents all services used by a Controller.
4 * It is up to the Controller to choose unique and persistent names for its services.
5 *
6 * @group Controller API
7 */
8export interface ControllerServiceMap {
9 [name: string]: Service | undefined;
10}
11/**
12 * ControllerType is basically a string uniquely identifying the type of {@link Controller}.
13 * An {@link Accessory} only allows one type of {@link Controller} to be configured.
14 *
15 * There are predefined types {@link DefaultControllerType} for all controller implementations provided by hap-nodejs.
16 * You can define custom ControllerTypes if you wish to, but be careful that it does not collide with any known definitions.
17 * @group Controller API
18 */
19export type ControllerType = string | DefaultControllerType;
20/**
21 * @group Controller API
22 */
23export declare const enum DefaultControllerType {
24 CAMERA = "camera",// or doorbell
25 REMOTE = "remote",
26 TV = "tv",
27 ROUTER = "router",
28 LOCK = "lock",
29 CHARACTERISTIC_TRANSITION = "characteristic-transition"
30}
31/**
32 * @group Controller API
33 */
34export type ControllerIdentifier = string | ControllerType;
35/**
36 * @group Controller API
37 */
38export type StateChangeDelegate = () => void;
39/**
40 * @group Controller API
41 */
42export interface ControllerConstructor {
43 new (): Controller;
44}
45/**
46 * A Controller represents a somewhat more complex arrangement of multiple services which together form a accessory
47 * like for example cameras, remotes, tvs or routers.
48 * Controllers implementing this interface are capable of being serialized and thus stored on and recreated from disk.
49 * Meaning services, characteristic configurations and optionally additional controller states can be persistently saved.
50 * As a result, implementors of this interface need to follow strict guidelines on how to initialize their
51 * services and characteristics.
52 *
53 * The set of services can change though over the lifespan of the implementation (e.g. protocol changes imposed by HAP like
54 * the addition of secure-video for cameras).
55 * Such changes can be made using {@link initWithServices}. See below for more infos.
56 *
57 * The constructor of a Controller should only initialize controller specific configuration and states
58 * and MUST NOT create any services or characteristics.
59 * Additionally, it must implement all necessary methods as noted below. Those methods will get called
60 * when the accessory gets added to an Accessory or a Accessory is restored from disk.
61 * @group Controller API
62 */
63export interface Controller<M extends ControllerServiceMap = ControllerServiceMap> {
64 /**
65 * Every instance of a Controller must define appropriate identifying material.
66 * The returned identifier MUST NOT change over the lifetime of the Controller object.
67 *
68 * Note: The controller can choose to return the same identifier for all controllers of the same type.
69 * This will result in the user only being able to add ONE instance of an Controller to an accessory.
70 *
71 * Some predefined identifiers can be found in {@link ControllerIdentifier}.
72 */
73 controllerId(): ControllerIdentifier;
74 /**
75 * This method is called by the accessory the controller is added to. This method is only called if a new controller
76 * is constructed (aka the controller is not restored from disk {@link initWithServices}).
77 * It MUST create all needed services and characteristics.
78 * It MAY create links between services or mark them as hidden or primary.
79 * It MUST NOT configure any event handlers.
80 * The controller SHOULD save created services in internal properties for later access.
81 *
82 * The method must return all created services in a ServiceMap.
83 * A {@link ControllerServiceMap} basically maps a name to every service on the controller.
84 * It is used to potentially recreate a controller for a given ServiceMap using {@link initWithServices}.
85 *
86 * The set of services represented by the Controller MUST remain static and can only change over new version of
87 * the Controller implementation (see {@link initWithServices})
88 *
89 * @returns a {@link ControllerServiceMap} representing all services of a controller indexed by a controller chosen name.
90 */
91 constructServices(): M;
92 /**
93 * This method is called to initialize the controller with already created services.
94 * The controller SHOULD save the passed services in internal properties for later access.
95 *
96 * The controller can return a ServiceMap to signal that the set of services changed.
97 * A Controller MUST modify the ServiceMap which is passed to the method and MUST NOT create a new one (to support inheritance).
98 * It MUST NOT return a ServiceMap if the service configuration did not change!
99 * It MUST be able to restore services using a ServiceMap from any point in time.
100 *
101 * @param serviceMap - A {@link ControllerServiceMap} that represents all services of a controller indexed by the controller chosen name.
102 * @returns optionally a {@link ControllerServiceMap}. This can be used to alter the services configuration of a controller.
103 */
104 initWithServices(serviceMap: M): M | void;
105 /**
106 * This method is called to configure the services and their characteristics of the controller.
107 * When this method is called, it is guaranteed that either {@link constructServices} or {@link initWithServices}
108 * were called before and all services are already created.
109 *
110 * This method SHOULD set up all necessary event handlers for services and characteristics.
111 */
112 configureServices(): void;
113 /**
114 * This method is called once the Controller is removed from the accessory.
115 * The controller MUST reset everything to its initial state (just as it would have been constructed freshly)
116 * form the constructor.
117 * Adding the Controller back to an accessory after it was removed MUST be supported!
118 * If the controller is a {@link SerializableController} it MUST NOT call the {@link StateChangeDelegate}
119 * as a result of a call to this method.
120 *
121 * All service contained in the {@link ControllerServiceMap} returned by {@link constructServices}
122 * will be automatically removed from the Accessory. The Controller MUST remove any references to those services.
123 */
124 handleControllerRemoved(): void;
125 /**
126 * This method is called to signal a factory reset of the controller and its services and characteristics.
127 * A controller MUST reset any configuration or states to default values.
128 *
129 * This method is called once the accessory gets unpaired or the Controller gets removed from the Accessory.
130 */
131 handleFactoryReset?(): void;
132}
133/**
134 * A SerializableController is a Controller which additionally carries states/data (beside services and characteristics)
135 * which needs to be persistently stored. For example current target configuration for an AppleTV remote.
136 * @group Controller API
137 */
138export interface SerializableController<M extends ControllerServiceMap = ControllerServiceMap, S = any> extends Controller<M> {
139 /**
140 * This method can be used to persistently save controller related configuration across reboots.
141 * It should return undefined, if the controller data was reset to default values and nothing needs to be stored anymore.
142 *
143 * @returns an arbitrary Controller defined object containing all necessary data
144 */
145 serialize(): S | undefined;
146 /**
147 * This method is called to restore the controller state from disk.
148 * This is only called once, when the data was loaded from disk and the Accessory is to be published.
149 * A controller MUST provide backwards compatibility for any configuration layout exposed at any time.
150 * A Controller MUST NOT depend on any specific calling order.
151 *
152 * @param serialized
153 */
154 deserialize(serialized: S): void;
155 /**
156 * This method is inherited from {@link Controller.handleFactoryReset} though is required with {@link SerializableController}.
157 */
158 handleFactoryReset(): void;
159 /**
160 * This method is called once upon setup. It supplies a function used by the Controller to signal state changes.
161 * The implementing controller SHOULD store the function and call it every time the internal controller state changes.
162 * It should be expected that the {@link serialize} method will be called next and that the state will be stored
163 * to disk.
164 * The delegate parameter can be undefined when the controller is removed and the state change delegate is reset.
165 *
166 * @param delegate - The {@link StateChangeDelegate} to call when controller state has changed
167 */
168 setupStateChangeDelegate(delegate?: StateChangeDelegate): void;
169}
170/**
171 * @param controller
172 * @group Controller API
173 */
174export declare function isSerializableController(controller: Controller): controller is SerializableController;
175//# sourceMappingURL=Controller.d.ts.map
\No newline at end of file