hap-controller/lib/transport/ip/http-client.d.ts

Library to implement a HAP (HomeKit) controller

/**
 * Controller class for interacting with a HAP device over HTTP.
 */
import { EventEmitter } from 'events';
import { PairingData } from '../../protocol/pairing-protocol';
import { TLV } from '../../model/tlv';
import * as Characteristic from '../../model/characteristic';
import { Accessories } from '../../model/accessory';
import BigNumber from 'bignumber.js';
export interface GetCharacteristicsOptions {
    /**
     * Boolean value that determines whether or not the response should include metadata.
     * If true the response must include the following properties if they exist for the
     * characteristic: ”format”, ”unit”, ”minValue”, ”maxValue”, ”minStep”, and ”maxLen”.
     * Default: false
     */
    meta?: boolean;
    /**
     * Boolean value that determines whether or not the response should include the permissions
     * of the characteristic.
     * Default: false
     */
    perms?: boolean;
    /**
     * Boolean value that determines whether the response should include the type of characteristic.
     * Default: false
     */
    type?: boolean;
    /**
     * Boolean value that determines whether the ”ev” property of the characteristic should be
     * included in the response
     * Default: false
     */
    ev?: boolean;
}
export interface SetCharacteristicsObject {
    /**
     * The instance ID of the accessory that contains the characteristic to be written.
     */
    aid?: number | BigNumber;
    /**
     * The instance ID of the characteristic to be written.
     */
    iid?: number | BigNumber;
    /**
     * Property that contains the value to be written to the characteristic. Required
     */
    value: unknown;
    /**
     * Optional property that contains a base 64 encoded string of the authorization data
     * associated with the characteristic.
     */
    authData?: string;
    /**
     * Optional property that indicates if remote access was used to send the request.
     * A value of true indicates remote access was used.
     */
    remote?: boolean;
    /**
     * Optional property that indicates whether a value is expected in the response to the
     * write operation.
     */
    r?: boolean;
}
interface HttpClientOptions {
    /**
     * Set to true to use persistent connections for normal device interactions
     * Without persistent connections a new pairing verification is required
     * before each call which delays the execution.
     */
    usePersistentConnections?: boolean;
    /**
     * Set this to true to use the same persistent connection for subscriptions
     * as also for normal device interactions. This basically means that only
     * one connection to the device ist used
     */
    subscriptionsUseSameConnection?: boolean;
}
export default class HttpClient extends EventEmitter {
    deviceId: string;
    private address;
    private port;
    private pairingProtocol;
    private _pairingConnection?;
    private _defaultConnection?;
    private usePersistentConnections;
    private subscriptionsUseSameConnection;
    private subscriptionConnection?;
    private subscribedCharacteristics;
    private pairingQueue;
    /**
     * Initialize the HttpClient object.
     *
     * @param {string} deviceId - ID of the device
     * @param {string} address - IP address of the device
     * @param {number} port - HTTP port
     * @param {PairingData?} pairingData - existing pairing data
     * @param {HttpClientOptions} options - additional options
     */
    constructor(deviceId: string, address: string, port: number, pairingData?: PairingData, options?: HttpClientOptions);
    /**
     * Initialize or return an existing connection
     *
     * @private
     * @returns {Promise<HttpConnection>} The connection to use
     */
    private getDefaultVerifiedConnection;
    /**
     * Checks if a maybe persistent connection should be closed
     *
     * @param {HttpConnection} connection Connection which was returned by getDefaultVerifiedConnection()
     * @param {boolean} forceClose - Force close the connection
     * @private
     */
    private closeMaybePersistentConnection;
    /**
     * Queue an operation for the pairing.
     *
     * @param {function} op - Function to add to the queue
     * @returns {Promise} Promise which resolves when the function is called.
     */
    private _queuePairingOperation;
    /**
     * Get the data (keys) that needs to be stored long-term.
     *
     * @returns {PairingData} Object containing the keys that should be stored.
     */
    getLongTermData(): PairingData | null;
    /**
     * Run the identify routine on a device.
     *
     * This can only be done before pairing.
     * If the device is already paired the method returns an error (Identify failed with status 400)
     *
     * @returns {Promise} Promise which resolves if identify succeeded.
     */
    identify(): Promise<void>;
    /**
     * Verify the provided PIN
     *
     * @param pin {string} PIN
     */
    verifyPin(pin: string): void;
    /**
     * Begins the pairing process. For devices with random pins, this
     * will cause it to show the pin on the screen.
     *
     * @param {PairMethods} [pairMethod] - Method to use for pairing, default is PairSetupWithAuth
     * @param {PairingTypeFlags} [pairFlags] - Flags to use for Pairing for PairSetup
     *                                         * No provided flags is equivalent to providing
     *                                           kPairingFlag_Transient and kPairingFlag_Split and in this case a new
     *                                           code is generated randomly by the device (if supported) or the
     *                                           pre-defined code is used
     *                                         * If only the flag kPairingFlag_Split is provided the code which
     *                                           was created on the device from last transient+split call is reused
     *                                           and needs to be provided in finishPairing by user of this library
     *                                         * If only the flag kPairingFlag_Transient is provided the session
     *                                           security is enabled but no final pairing is done
     * @returns {Promise} Promise which resolves to opaque pairing data when complete.
     */
    startPairing(pairMethod?: number, pairFlags?: number): Promise<TLV>;
    /**
     * Finishes a pairing process that began with startPairing()
     *
     * @param {TLV} pairingData - The pairing data returned from startPairing()
     * @param {string} pin - The pairing PIN, needs to be formatted as XXX-XX-XXX
     * @returns {Promise} Promise which resolve when pairing is complete.
     */
    finishPairing(pairingData: TLV, pin: string): Promise<void>;
    /**
     * Attempt to pair with a device.
     *
     * @param {string} pin - The pairing PIN, needs to be formatted as XXX-XX-XXX
     * @param {PairMethods} [pairMethod] - Method to use for pairing, default is PairSetupWithAuth
     * @param {PairingTypeFlags} [pairFlags] - Flags to use for Pairing for PairSetup
     * @returns {Promise} Promise which resolves when pairing is complete.
     */
    pairSetup(pin: string, pairMethod?: number, pairFlags?: number): Promise<void>;
    /**
     * Method used internally to generate session keys for a connection.
     *
     * @private
     * @param {Object} connection - Existing HttpConnection object
     * @returns {Promise} Promise which resolves to the generated session keys.
     */
    private _pairVerify;
    /**
     * Unpair the controller from a device.
     *
     * @param {string | Buffer} identifier - Identifier of the controller to remove
     * @returns {Promise} Promise which resolves when the process completes.
     */
    removePairing(identifier: string | Buffer): Promise<void>;
    /**
     * Add a pairing to a device.
     *
     * @param {string} identifier - Identifier of new controller
     * @param {Buffer} ltpk - Long-term public key of the new controller
     * @param {boolean} isAdmin - Whether or not the new controller is an admin
     * @returns {Promise} Promise which resolves when the process is complete.
     */
    addPairing(identifier: string, ltpk: Buffer, isAdmin: boolean): Promise<void>;
    /**
     * List the pairings on a device.
     *
     * @returns {Promise} Promise which resolves to the final TLV when the process
     *                    is complete.
     */
    listPairings(): Promise<TLV>;
    /**
     * Get the accessory attribute database from a device.
     *
     * @returns {Promise} Promise which resolves to the JSON document.
     */
    getAccessories(): Promise<Accessories>;
    /**
     * Read a set of characteristics.
     *
     * @param {string[]} characteristics - List of characteristics ID to get in form ["aid.iid", ...]
     * @param {GetCharacteristicsOptions?} options - Options dictating what metadata to fetch
     * @returns {Promise} Promise which resolves to the JSON document.
     */
    getCharacteristics(characteristics: string[], options?: GetCharacteristicsOptions): Promise<{
        characteristics: Characteristic.CharacteristicObject[];
    }>;
    /**
     * Modify a set of characteristics.
     *
     * @param {Object} characteristics - Characteristic IDs to set in form
     *                                   * id -> val or
     *                                   * id -> SetCharacteristicsObject
     * @returns {Promise} Promise which resolves to the JSON document.
     */
    setCharacteristics(characteristics: Record<string, unknown>): Promise<Record<string, unknown | SetCharacteristicsObject>>;
    /**
     * Subscribe to events for a set of characteristics.
     *
     * @fires HttpClient#event
     * @fires HttpClient#event-disconnect
     * @param {String[]} characteristics - List of characteristic IDs to subscribe to,
     *                                       in form ["aid.iid", ...]
     * @returns {Promise} Promise
     */
    subscribeCharacteristics(characteristics: string[]): Promise<Record<string, unknown> | null>;
    /**
     * Unsubscribe from events for a set of characteristics.
     *
     * @param {String[]} characteristics - List of characteristic IDs to
     *                   unsubscribe from in form ["aid.iid", ...],
     *                   if ommited all currently subscribed characteristics will be unsubscribed
     * @returns {Promise} Promise which resolves when the procedure is done.
     */
    unsubscribeCharacteristics(characteristics?: string[]): Promise<Record<any, unknown> | null>;
    /**
     * Get the list of subscribed characteristics
     *
     * @returns {string[]} Array with subscribed entries in form ["aid.iid", ...]
     */
    getSubscribedCharacteristics(): string[];
    /**
     * Get an JPEG image with a snapshot from the devices camera
     *
     * @param {number} width width of the returned image
     * @param {number} height height of the returned image
     * @param {number | BigNumber} [aid] accessory ID (optional)
     *
     * @returns {Promise<Buffer>} Promise which resolves to a Buffer with the JPEG image content
     */
    getImage(width: number, height: number, aid?: number | BigNumber): Promise<Buffer>;
    /**
     * Closes the current persistent connection, if connected
     */
    closePersistentConnection(): void;
    /**
     * Close all potential open connections to the device
     *
     * @returns {Promise<void>} Promise when done
     */
    close(): Promise<void>;
}
export {};
//# sourceMappingURL=http-client.d.ts.map