1 | import { 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 | */
|
8 | export 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 | */
|
19 | export type ControllerType = string | DefaultControllerType;
|
20 | /**
|
21 | * @group Controller API
|
22 | */
|
23 | export 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 | */
|
34 | export type ControllerIdentifier = string | ControllerType;
|
35 | /**
|
36 | * @group Controller API
|
37 | */
|
38 | export type StateChangeDelegate = () => void;
|
39 | /**
|
40 | * @group Controller API
|
41 | */
|
42 | export 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 | */
|
63 | export 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 | */
|
138 | export 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 | */
|
174 | export declare function isSerializableController(controller: Controller): controller is SerializableController;
|
175 | //# sourceMappingURL=Controller.d.ts.map |
\ | No newline at end of file |