diff --git a/definitions/Definitions.vcxproj b/definitions/Definitions.vcxproj index 3270aeb2..1031173d 100644 --- a/definitions/Definitions.vcxproj +++ b/definitions/Definitions.vcxproj @@ -19,8 +19,6 @@ - - @@ -188,12 +186,6 @@ - - Document - - - Document - Document diff --git a/interfaces/IBluetooth.h b/interfaces/IBluetooth.h index 2ea1d0dc..7b96544f 100644 --- a/interfaces/IBluetooth.h +++ b/interfaces/IBluetooth.h @@ -20,6 +20,7 @@ #pragma once #include "Module.h" +// @insert namespace Thunder { @@ -38,7 +39,7 @@ namespace Exchange { struct EXTERNAL ISecurityCallback : virtual public Core::IUnknown { enum { ID = ID_BLUETOOTH_DEVICE_CLASSIC_SECURITYCALLBACK }; - virtual void PINCodeRequest() = 0; + virtual void PINCodeRequest() = 0; }; virtual void PINCode(const string& pinCode) = 0; @@ -75,9 +76,9 @@ namespace Exchange { }; enum type : uint8_t { - ADDRESS_BREDR /*@text:Classic */, - ADDRESS_LE_PUBLIC /*@text:LowEnergy */, - ADDRESS_LE_RANDOM /*@text:LowEnergyRandom */ + ADDRESS_BREDR, + ADDRESS_LE_PUBLIC, + ADDRESS_LE_RANDOM }; enum pairingcapabilities : uint8_t { @@ -186,6 +187,315 @@ namespace Exchange { virtual uint32_t ForgetDevice(const string& address, const IDevice::type type) = 0; }; + + namespace JSONRPC { + + // @json 1.0.0 @text:legacy_lowercase + struct EXTERNAL IBluetoothControl { + + virtual ~IBluetoothControl() = default; + + enum class adaptertype : uint8_t { + CLASSIC, + LOW_ENERGY, + DUAL + }; + + enum class devicetype : uint8_t { + CLASSIC = IBluetooth::IDevice::type::ADDRESS_BREDR, + LOW_ENERGY = IBluetooth::IDevice::type::ADDRESS_LE_PUBLIC, + LOW_ENERGY_RANDOM = IBluetooth::IDevice::type::ADDRESS_LE_RANDOM + }; + + enum class scantype : uint8_t { + CLASSIC, + LOW_ENERGY + }; + + enum class scanmode : uint8_t { + GENERAL, + LIMITED + }; + + enum class devicestate : uint8_t { + PAIRING, + PAIRED, + UNPAIRED, + CONNECTED, + DISCONNECTED + }; + + enum class disconnectreason : uint8_t { + CONNECTION_TIMEOUT, + AUTHENTICATION_FAILURE, + REMOTE_LOW_ON_RESOURCES, + REMOTE_POWERED_OFF, + TERMINATED_BY_REMOTE, + TERMINATED_BY_HOST + }; + + + using pairingcapabilities = IBluetooth::IDevice::pairingcapabilities; + + struct device { + string address /* @brief Bluetooth address */; + devicetype type /* @brief Bluetooth device type */; + }; + + struct adapterinfo { + uint8_t id /* @brief Adapter ID number */; + string interface /* @brief Interface name (e.g. "hci0") */; + string address /* @brief Bluetooth address */; + adaptertype type /* @brief Adapter type */; + uint8_t version /* @brief Version */; + Core::OptionalType manufacturer /* @brief Company Identification Code (CIC) (e.g. 305) */; + Core::OptionalType cod /* @text:class */ /* @brief Class of Device (CoD) value (e.g. 2360324) */ /* @restrict:0xFFFFFF */; + Core::OptionalType name /* @brief Name */; + Core::OptionalType shortName /* @brief Shortened name */; + }; + + using IUUIDIterator = RPC::IIteratorType; + using IDeviceIterator = RPC::IIteratorType; + using IAdapterIterator = RPC::IIteratorType; + using IAddressIterator = RPC::IIteratorType; + + // @event + struct EXTERNAL INotification { + + virtual ~INotification() = default; + + // @statuslistener + // @brief Reports entering the discoverable state + // @param mode Advertising or inquiry scanning mode + // @param connectable Specifies if LE advertising reports that the device is connectable (LE-only) + virtual void DiscoverableStarted(const scantype type, const scanmode mode, + const Core::OptionalType& connectable) = 0; + + // @brief Reports leaving the discoverable state + virtual void DiscoverableComplete(const scantype type) = 0; + + // @statuslistener + // @brief Reports start of scanning + // @param mode Discovery or inquiry mode + virtual void ScanStarted(const scantype type, const scanmode mode) = 0; + + // @brief Reports end of scanning + virtual void ScanComplete(const scantype type) = 0; + + // @statuslistener + // @brief Reports device state changes + // @brief disconnectReason If disconnected specifies the cause of disconnection + virtual void DeviceStateChanged(const string& address, const devicetype type, + const devicestate state, const Core::OptionalType& disconnectReason) = 0; + }; + + // @event + struct EXTERNAL ISecurityNotification { + + virtual ~ISecurityNotification() = default; + + // @brief Notifies of a PIN code request during authenticated BR/EDR legacy pairing process + // @details Upon receiving this event the client is required to respond with "providePinCode" call + // in order to complete the pairing procedure. The PIN code value is typically collected by + // prompting the end-user on the local device. If the client fails to respond before the pairing + // timeout elapses the pairing procedure will be aborted. + virtual void PINCodeRequest(const string& address, const devicetype type) = 0; + + // @brief Notifies of a user confirmation request during authenticated BR/EDR SSP pairing process + // @details Upon receiving this event the client is required to respond with "confirmPasskey" call + // in order to complete the pairing procedure. The passkey confirmation is typically collected + // by prompting the end-user on the local device. If the client fails to respond before the pairing + // timeout elapses the pairing procedure will be aborted. + // @param secret A six-digit decimal number sent by the remote device to be presented to the end-user + // for confirmation on the local device (e.g 123456). The passkey may be omitted for simple yes/no paring. + virtual void PasskeyConfirmRequest(const string& address, const devicetype type, + const Core::OptionalType& secret /* @restrict:999999 */) = 0; + + // @brief Notifies of a passkey supply request during authenticated LE pairing process + // @details Upon receiving this event the client is required to respond with "providePasskey" call + // in order to complete the pairing procedure. The passkey value is typically collected by + // prompting the end-user on the local device. If the client fails to respond before the pairing + // timeout elapses the pairing procedure will be aborted. + virtual void PasskeyRequest(const string& address, const devicetype type) = 0; + + // @brief Notifies of a passkey presentation request during authenticated LE pairing process + // @details Upon receiving this event the client is required to display the passkey on the local + // device. The end-user on the remote device will need to enter this passkey to complete the + // pairing procedure. If end-user fails to respond before the pairing timeout elapses the pairing + // procedure will be aborted. + // @param secret A six-digit decimal number to be displayed on the local device (e.g 123456) + virtual void PasskeyDisplayRequest(const string& address, const devicetype type, const uint32_t secret /* @restrict:999999 */) = 0; + }; + + + // @brief Starts LE advertising or BR/EDR inquiry scanning, making the local interface visible for + // nearby Bluetooth devices + // @param mode Advertising or inquiry scanning mode + // @param connectable Specifies if LE advertising should report the device is connectable (LE-only) + // @param duration Time span of the discoverable state in seconds + // @retval ERROR_UNAVAILABLE The adapter does not support selected discovery type + // @retval ERROR_INPROGRESS Discoverable state of selected type is already in progress + virtual Core::hresult SetDiscoverable(const scantype type, + const Core::OptionalType& mode /* @default:GENERAL */, + const Core::OptionalType& connectable /* @default:true */, + const Core::OptionalType& duration /* @default:30 */) = 0; + + // @brief Stops LE advertising or BR/EDR inquiry scanning operation + // @retval ERROR_UNAVAILABLE The adapter does not support selected discovery type + // @retval ERROR_ILLEGAL_STATE The adapter is in not discoverable state of selected type + virtual Core::hresult StopDiscoverable(const scantype type) = 0; + + // @brief Starts LE active discovery or BR/EDR inquiry of nearby Bluetooth devices + // @param mode Discovery or inquiry mode (scan picks up only devices discoverable in paricular mode) + // @param duration Time span of the discovery in seconds + // @retval ERROR_UNAVAILABLE The adapter does not support selected scan type + // @retval ERROR_INPROGRESS Scan of selected type is already in progress + virtual Core::hresult Scan(const scantype type, + const Core::OptionalType& mode /* @default:GENERAL */, + const Core::OptionalType& duration /* @default:12 */) = 0; + + // @brief Stops LE discovery or BR/EDR inquiry operation + // @retval ERROR_UNAVAILABLE The adapter does not support selected scan type + // @retval ERROR_ILLEGAL_STATE Scan of selected type is not in progress + virtual Core::hresult StopScanning(const scantype type) = 0; + + // @brief Connects to a Bluetooth device + // @details This call also enables automatic reconnection of the device. If the device is currently + // not available it will be automatically connected as soon it becomes available. This call is asynchronous. + // @retval ERROR_UNKNOWN_KEY The device is not known + // @retval ERROR_INPROGRESS The host adapter is currently busy + // @retval ERROR_ILLEGAL_STATE The device is not paired + // @retval ERROR_ALREADY_CONNECTED The device is already connected + // @retval ERROR_REQUEST_SUBMITTED The device has not been connected, but will be automatically + // connected when it becomes available + virtual Core::hresult Connect(const string& address, const devicetype type) = 0; + + // @brief Disconnects from a connected Bluetooth device + // @details This call also disables automatic reconnection. If the device is currently not connected it + // will not be reconnected when it again becomes available. + // @retval ERROR_UNKNOWN_KEY The device is not known + // @retval ERROR_INPROGRESS The host adapter is currently busy + // @retval ERROR_ALREADY_RELEASED The device is not connected + // @retval ERROR_REQUEST_SUBMITTED The device is currently not connected, but it's automatic reconnection + // mode has been disabled + virtual Core::hresult Disconnect(const string& address, const devicetype type) = 0; + + // @brief Pairs a Bluetooth device + // @details PIN-code or passkey requests may appear during the pairing process. The process can be + // cancelled any time by calling *abortPairing*. This call is asynchronous. + // @param capabilities Host device pairing capabilities + // @param timeout Time allowed for the pairing process to complete + // @retval ERROR_UNKNOWN_KEY The device is not known + // @retval ERROR_INPROGRESS The host adapter is currently busy + // @retval ERROR_ALREADY_CONNECTED The device is already paired + // @retval ERROR_GENERAL Failed to pair + virtual Core::hresult Pair(const string& address, const devicetype type, + const Core::OptionalType& capabilities /* @default:NO_INPUT_NO_OUTPUT */, + const Core::OptionalType& timeout /* @default:10 */) = 0; + + // @brief Unpairs a paired Bluetooth device + // @retval ERROR_UNKNOWN_KEY The device is not known + // @retval ERROR_INPROGRESS The host adapter is currently busy + // @retval ERROR_ALREADY_RELEASED The device is not paired + virtual Core::hresult Unpair(const string& address, const devicetype type) = 0; + + // @brief Aborts pairing operation + // @details This call is asynchronous. + // @retval ERROR_UNKNOWN_KEY The device is not known + // @retval ERROR_ILLEGAL_STATE The device not currently pairing + virtual Core::hresult AbortPairing(const string& address, const devicetype type) = 0; + + // @brief Provides a PIN-code for authentication during a legacy pairing process + // @details This method should be called upon receiving a "pinCodeRequest" event during a legacy pairing + // process. If the specified PIN-code is incorrect the pairing process will be aborted. + // @param secret A PIN code, typically 4 ASCII digits (e.g. "1234") + // @retval ERROR_UNKNOWN_KEY The device is not known + // @retval ERROR_ILLEGAL_STATE The device not currently pairing or a PIN code has not been requested + virtual Core::hresult ProvidePINCode(const string& address, const devicetype type, const string& secret /* @restrict:16 */) = 0; + + // @brief Confirms a passkey for authentication during a BR/EDR SSP pairing processs + // @details This method should be called upon receiving a passkeyConfirmationRequest event during a pairing + // process. If the confirmation is negative the pairing process will be aborted. + // @param accept Confirm pairing (normally if the presented passkey is correct) + // @retval ERROR_UNKNOWN_KEY Unknown device + // @retval ERROR_ILLEGAL_STATE The device is currently not pairing or passkey confirmation has not been requested + virtual Core::hresult ConfirmPasskey(const string& address, const devicetype type, const bool accept) = 0; + + // @brief Provides a passkey for authentication during a pairing process + // @details This method should be called upon receiving a "passkeyRequest" event during pairing process. + // If the specified passkey is incorrect or empty the pairing process will be aborted. + // @param secret A decimal six-digit passkey value (e.g. 123456) + // @retval ERROR_UNKNOWN_KEY Unknown device + // @retval ERROR_ILLEGAL_STATE The device not currently pairing or a passkey has not been requested + virtual Core::hresult ProvidePasskey(const string& address, const devicetype type, const uint32_t secret /* @restrict:999999 */) = 0; + + // @brief Forgets a previously seen Bluetooth device + // @details The device will no longer be listed and its status tracked. If paired the device must be unpaired first. + // @retval ERROR_UNKNOWN_KEY The device is not known + // @retval ERROR_ILLEGAL_STATE The device is paired + virtual Core::hresult Forget(const string& address, const devicetype type) = 0; + + // @brief Retrieves a list of known remote Bluetooth devices + virtual Core::hresult GetDeviceList(IDeviceIterator*& devices /* @out */) const = 0; + + // @brief Retrieves detailed information about a known Bluetooth device + // @param name Device local name + // @param version Device version + // @param manufacturer Company Identification Code (CIC) (e.g. 305) + // @param cod Class of Device (CoD) value (e.g. 2360324) + // @param appearance Appearance value (LE-only) (e.g. 2113) + // @param services A list of supported service UUIDs + // @param paired Specifies if the device is currently paired + // @param connected Specifies if the device is currently connected + // @retval ERROR_UNKNOWN_KEY The device is not known + virtual Core::hresult GetDeviceInfo(string& address /* @inout */, devicetype& type /* @inout */, + Core::OptionalType& name /* @out */, + Core::OptionalType& version /* @out */, + Core::OptionalType& manufacturer /* @out */, + Core::OptionalType& cod /* @out @text:class @restrict:0xFFFFFF */, + Core::OptionalType& appearance /* @out */, + Core::OptionalType& services /* @out */, + bool& paired /* @out */, + bool& connected /* @out */) const = 0; + + // @property + // @brief List of local Bluetooth adapters + virtual Core::hresult Adapters(IAdapterIterator*& adapters /* @out */) const = 0; + + // @property + // @brief Local Bluetooth adapter information + // @param adapter Adapter index + // @retval ERROR_UNKNOWN_KEY The adapter ID is invalid + virtual Core::hresult Adapter(const uint8_t adapter /* @index */, adapterinfo& info /* @out */) const = 0; + + + // The legacy API below works with LowEnergy devices only and thus is deprecated + + struct deviceinfo { + string address /* @brief Bluetooth address */; + IBluetoothControl::devicetype type /* @brief Device type */; + Core::OptionalType name /* @brief Device name */; + Core::OptionalType cod /* @text:class */ /* @brief Class of Device (CoD) value (e.g. 2360324) */ /* @restrict:0xFFFFFF */; + Core::OptionalType appearance /* @brief Appearance value (LE only) (e.g. 2113) */; + Core::OptionalType services /* @opaque */ /* @brief Array of supported service UUIDs */; + bool paired /* @brief Specifies if the device is currently paired */; + bool connected /* @brief Specifies if the device is currently connected */; + }; + + // @property + // @deprecated + // @brief List of known remote Bluetooth LE devices + virtual Core::hresult Devices(IAddressIterator*& devices /* @out */) const = 0; + + // @property + // @deprecated + // @brief Remote Bluetooth LE device information + // @retval ERROR_UNKNOWN_KEY The device is not known + virtual Core::hresult Device(const string& deviceAddress /* @index */, deviceinfo& info /* @out */) const = 0; + }; + + } // namespace JSONRPC + } // namespace Exchange } diff --git a/jsonrpc/BluetoothControl.json b/jsonrpc/BluetoothControl.json deleted file mode 100644 index e383dfa2..00000000 --- a/jsonrpc/BluetoothControl.json +++ /dev/null @@ -1,1039 +0,0 @@ -{ - "$schema": "interface.schema.json", - "jsonrpc": "2.0", - "mode": "auto", - "info": { - "version": "1.0.0", - "title": "Bluetooth Control API", - "class": "BluetoothControl", - "description": "Bluetooth Control JSON-RPC interface" - }, - "common": { - "$ref": "common.json" - }, - "imports": { - "ibluetooth": { - "$ref": "{cppinterfacedir}/IBluetooth.h" - } - }, - "definitions": { - "enums": { - "devicetype": { - "description": "Device type", - "$ref": "#/imports/ibluetooth/Exchange::IBluetooth::IDevice::type", - "default": "LowEnergy" - }, - "pairingcapabilities": { - "description": "Pairing capabilities", - "$ref": "#/imports/ibluetooth/Exchange::IBluetooth::IDevice::pairingcapabilities", - "default": "NoInputNoOutput" - }, - "devicestate": { - "description": "Device state", - "hint": "devicestate", - "type": "string", - "enum": [ - "Pairing", - "Paired", - "Unpaired", - "Connected", - "Disconnected" - ], - "example": "Disconnected" - }, - "adaptertype": { - "description": "Adapter type", - "hint": "adaptertype", - "type": "string", - "case": "snake", - "enum": [ - "Classic", - "LowEnergy", - "Dual" - ], - "default": "Dual" - }, - "scantype": { - "description": "Scan type", - "hint": "scantype", - "type": "string", - "case": "snake", - "enum": [ - "Classic", - "LowEnergy" - ], - "default": "LowEnergy" - }, - "discoverabletype": { - "description": "Discoverable type", - "$ref": "#definitions/enums/scantype" - }, - "scanmode": { - "description": "Scan mode", - "hint": "scanmode", - "type": "string", - "enum": [ - "General", - "Limited" - ], - "default": "General" - }, - "discoverablemode": { - "description": "Discoverable mode", - "$ref": "#definitions/enums/scanmode" - }, - "disconnectreason": { - "description": "Disconnection reason in case of *Disconnected* event", - "hint": "disconnectreason", - "type": "string", - "case": "snake", - "enum": [ - "ConnectionTimeout", - "AuthenticationFailure", - "RemoteLowOnResources", - "RemotePoweredOff", - "TerminatedByRemote", - "TerminatedByHost" - ] - } - }, - "deviceaddress": { - "description": "Bluetooth address", - "type": "string", - "example": "81:6F:B0:91:9B:FE" - }, - "deviceinfo": { - "type": "object", - "hint": "DeviceData", - "properties": { - "address": { - "$ref": "#/definitions/deviceaddress" - }, - "type": { - "$ref": "#/definitions/enums/devicetype", - "example": "Classic" - }, - "name": { - "type": "string", - "example": "Thunder Bluetooth Speaker", - "description": "Name of the device" - }, - "class": { - "description": "Class of device", - "type": "integer", - "example": 2360324 - }, - "appearance": { - "description": "Appearance value", - "type": "integer", - "example": 2113 - }, - "services": { - "description": "List of supported services", - "type": "array", - "items": { - "description": "Service UUID", - "type": "string", - "example": "110a" - } - }, - "connected": { - "description": "Indicates if the device is currently connected", - "type": "boolean", - "example": true - }, - "paired": { - "description": "Indicates if the device is currently paired", - "type": "boolean", - "example": true - } - }, - "required": [ - "address", - "type", - "connected", - "paired" - ] - }, - "adapterinfo": { - "type": "object", - "hint": "AdapterData", - "properties": { - "id": { - "description": "Interface ID number", - "type": "integer", - "size": 16, - "example": 0 - }, - "interface": { - "description": "Interface name", - "type": "string", - "example": "hci0" - }, - "address": { - "$ref": "#/definitions/deviceaddress" - }, - "type": { - "$ref": "#/definitions/enums/adaptertype" - }, - "version": { - "description": "Version", - "type": "integer", - "size": 8, - "example": 8 - }, - "manufacturer": { - "description": "Manufacturer company identifer", - "type": "integer", - "size": 16, - "example": 15 - }, - "class": { - "description": "Class of device", - "type": "integer", - "size": 32, - "example": 1060 - }, - "name": { - "description": "Name", - "type": "string", - "example": "Thunder Bluetooth Controller" - }, - "shortname": { - "description": "Short name", - "type": "string", - "example": "Thunder" - } - }, - "required": [ - "id", - "interface", - "address", - "type", - "version" - ] - } - }, - "methods": { - "setdiscoverable": { - "summary": "Starts advertising (or inquiry scanning), making the local interface visible by nearby Bluetooth devices", - "description": "Please note that discoverable state in *Limited* mode for Bluetooth Classic is bounded to 30 seconds only.", - "hint": "SetDiscoverable", - "events": [ - "discoverablestarted", - "discoverablecomplete" - ], - "params": { - "type": "object", - "properties": { - "type": { - "$ref": "#/definitions/enums/discoverabletype" - }, - "mode": { - "$ref": "#/definitions/enums/discoverablemode" - }, - "connectable": { - "description": "Selects connectable advertising (true, *LowEnergy* only)", - "type": "boolean", - "default": false - }, - "duration": { - "description": "Duration of the discoverable operation (in seconds)", - "type": "integer", - "size": 16, - "default": 30 - } - }, - "required": [ - "type" - ] - }, - "result": { - "$ref": "#/common/results/void" - }, - "errors": [ - { - "description": "Failed set discoverable state", - "$ref": "#/common/errors/general" - }, - { - "description": "Discoverable state of selected type is already in progress", - "$ref": "#/common/errors/inprogress" - } - ] - }, - "stopdiscoverable": { - "summary": "Stops advertising (or inquiry scanning) operation", - "hint": "StopDiscoverable", - "events": [ - "discoverablecomplete" - ], - "params": { - "type": "object", - "properties": { - "type": { - "$ref": "#/definitions/enums/discoverabletype" - } - }, - "required": [ - "type" - ] - }, - "result": { - "$ref": "#/common/results/void" - }, - "errors": [ - { - "description": "Failed to top scanning", - "$ref": "#/common/errors/general" - }, - { - "description": "Adapter is in not discoverable state of selected type", - "$ref": "#/common/errors/illegalstate" - } - ] - }, - "scan": { - "summary": "Starts active discovery (or inquiry) of nearby Bluetooth devices", - "events": [ - "scanstarted", - "scancomplete" - ], - "params": { - "type": "object", - "properties": { - "type": { - "$ref": "#/definitions/enums/scantype" - }, - "mode": { - "$ref": "#/definitions/enums/scanmode" - }, - "timeout": { - "description": "Duration of the scan (in seconds)", - "deprecated": true, - "type": "integer", - "size": 16, - "example": 60, - "default": 10 - }, - "duration": { - "description": "Duration of the scan (in seconds)", - "type": "integer", - "size": 16, - "example": 60, - "default": 10 - } - }, - "required": [ - "type" - ] - }, - "result": { - "$ref": "#/common/results/void" - }, - "errors": [ - { - "description": "Failed to scan", - "$ref": "#/common/errors/general" - }, - { - "description": "Scan of selected type is already in progress", - "$ref": "#/common/errors/inprogress" - } - ] - }, - "stopscanning": { - "summary": "Stops discovery (or inquiry) operation", - "hint": "StopScanning", - "events": [ - "scancomplete" - ], - "params": { - "type": "object", - "properties": { - "type": { - "$ref": "#/definitions/enums/scantype" - } - }, - "required": [] - }, - "result": { - "$ref": "#/common/results/void" - }, - "errors": [ - { - "description": "Failed to top scanning", - "$ref": "#/common/errors/general" - }, - { - "description": "Scan of selected type is not in progress", - "$ref": "#/common/errors/illegalstate" - } - ] - }, - "connect": { - "summary": "Connects to a Bluetooth device", - "description": "This call also enables automatic reconnection of the device. If the device is currently not available it will be automatically connected as soon it becomes available.", - "events": [ - "devicestatechange" - ], - "params": { - "type": "object", - "properties": { - "address": { - "$ref": "#/definitions/deviceaddress" - }, - "type": { - "$ref": "#/definitions/enums/devicetype" - } - }, - "required": [ - "address" - ] - }, - "result": { - "$ref": "#/common/results/void" - }, - "errors": [ - { - "description": "Unknown device", - "$ref": "#/common/errors/unknownkey" - }, - { - "description": "Device not paired", - "$ref": "#/common/errors/illegalstate" - }, - { - "description": "Device already connected", - "$ref": "#/common/errors/alreadyconnected" - }, - { - "description": "Failed to connect the device", - "$ref": "#/common/errors/general" - }, - { - "description": "Device has not been connected but will be automatically connected when available", - "$ref": "#/common/errors/requestsubmitted" - } - ] - }, - "disconnect": { - "summary": "Disconnects from a connected Bluetooth device", - "description": "This call also disables automatic reconnection. If the device is currently not connected it will not be reconnected when it becomes available.", - "events": [ - "devicestatechange" - ], - "params": { - "type": "object", - "properties": { - "address": { - "$ref": "#/definitions/deviceaddress" - }, - "type": { - "$ref": "#/definitions/enums/devicetype" - } - }, - "required": [ - "address" - ] - }, - "result": { - "$ref": "#/common/results/void" - }, - "errors": [ - { - "description": "Unknown device", - "$ref": "#/common/errors/unknownkey" - }, - { - "description": "Device not connected", - "$ref": "#/common/errors/alreadyreleased" - }, - { - "description": "Device is currently not connected but it's autoconnection mode has been disabled", - "$ref": "#/common/errors/requestsubmitted" - } - ] - }, - "pair": { - "summary": "Pairs a Bluetooth device", - "description": "PIN-code or passkey requests may appear during the pairing process. The process can be cancelled any time by calling the *abortpairing* method.", - "events": [ - "devicestatechange", - "pincoderequest", - "passkeyrequest", - "passkeyconfirmrequest" - ], - "params": { - "type": "object", - "properties": { - "address": { - "$ref": "#/definitions/deviceaddress" - }, - "type": { - "$ref": "#/definitions/enums/devicetype" - }, - "capabilities": { - "$ref": "#/definitions/enums/pairingcapabilities" - }, - "timeout": { - "description": "Maximum time allowed for the pairing process to complete (in seconds)", - "type": "integer", - "size": 16, - "example": "60", - "default": 20 - } - }, - "required": [ - "address" - ] - }, - "result": { - "$ref": "#/common/results/void" - }, - "errors": [ - { - "description": "Unknown device", - "$ref": "#/common/errors/unknownkey" - }, - { - "description": "Device already paired", - "$ref": "#/common/errors/alreadyconnected" - }, - { - "description": "Failed to pair the device", - "$ref": "#/common/errors/general" - } - ] - }, - "unpair": { - "summary": "Unpairs a paired Bluetooth device", - "events": [ - "devicestatechange" - ], - "params": { - "type": "object", - "properties": { - "address": { - "$ref": "#/definitions/deviceaddress" - }, - "type": { - "$ref": "#/definitions/enums/devicetype" - } - }, - "required": [ - "address" - ] - }, - "result": { - "$ref": "#/common/results/void" - }, - "errors": [ - { - "description": "Unknown device", - "$ref": "#/common/errors/unknownkey" - }, - { - "description": "Device not paired", - "$ref": "#/common/errors/alreadyreleased" - } - ] - }, - "abortpairing": { - "summary": "Aborts pairing operation", - "hint": "AbortPairing", - "events": [ - "devicestatechange" - ], - "params": { - "type": "object", - "properties": { - "address": { - "$ref": "#/definitions/deviceaddress" - }, - "type": { - "$ref": "#/definitions/enums/devicetype" - } - }, - "required": [ - "address" - ] - }, - "result": { - "$ref": "#/common/results/void" - }, - "errors": [ - { - "description": "Unknown device", - "$ref": "#/common/errors/unknownkey" - }, - { - "description": "Device not currently pairing", - "$ref": "#/common/errors/illegalstate" - } - ] - }, - "providepincode": { - "summary": "Provides a PIN-code for authentication during a legacy pairing process", - "description": "This method should be called upon receiving a *pincoderequest* event during a legacy pairing process. If the specified PIN-code is incorrect the pairing process will be aborted.", - "hint": "ProvidePINCode", - "events": [ - "devicestatechange", - "pincoderequest" - ], - "params": { - "type": "object", - "properties": { - "address": { - "$ref": "#/definitions/deviceaddress" - }, - "type": { - "$ref": "#/definitions/enums/devicetype", - "default": "Classic", - "example": "Classic" - }, - "secret": { - "description": "A PIN-code string typically consisting of (but not limited to) four decimal digits", - "type": "string", - "example": "0000" - } - }, - "required": [ - "address", - "type", - "secret" - ] - }, - "result": { - "$ref": "#/common/results/void" - }, - "errors": [ - { - "description": "Unknown device", - "$ref": "#/common/errors/unknownkey" - }, - { - "description": "Device not currently pairing or PIN code has not been requested", - "$ref": "#/common/errors/illegalstate" - } - ] - }, - "providepasskey": { - "summary": "Provides a passkey for authentication during a pairing process", - "description": "This method should be called upon receiving a *passkeyrequest* event during pairing process. If the specified passkey is incorrect or empty the pairing process will be aborted.", - "hint": "ProvidePasskey", - "events": [ - "devicestatechange", - "passkeyrequest" - ], - "params": { - "type": "object", - "properties": { - "address": { - "$ref": "#/definitions/deviceaddress" - }, - "type": { - "$ref": "#/definitions/enums/devicetype", - "default": "Classic", - "example": "Classic" - }, - "secret": { - "description": "A six-digit decimal number passkey", - "type": "integer", - "size": 32, - "example": 123456 - } - }, - "required": [ - "address", - "type", - "secret" - ] - }, - "result": { - "$ref": "#/common/results/void" - }, - "errors": [ - { - "description": "Unknown device", - "$ref": "#/common/errors/unknownkey" - }, - { - "description": "Device not currently pairing or a passkey has not been requested", - "$ref": "#/common/errors/illegalstate" - } - ] - }, - "confirmpasskey": { - "summary": "Confirms a passkey for authentication during a pairing process", - "description": "This method should be called upon receiving a *passkeyconfirmationrequest* event during a pairing process. If the confirmation is negative the pairing process will be aborted.", - "hint": "ConfirmPasskey", - "events": [ - "devicestatechange", - "passkeyconfirmrequest" - ], - "params": { - "type": "object", - "properties": { - "address": { - "$ref": "#/definitions/deviceaddress" - }, - "type": { - "$ref": "#/definitions/enums/devicetype", - "default": "Classic", - "example": "Classic" - }, - "iscorrect": { - "description": "Specifies if the passkey sent in *passkeyconfirmrequest* event is correct (true) or incorrect (false)", - "type": "boolean", - "example": true - } - }, - "required": [ - "address", - "type", - "iscorrect" - ] - }, - "result": { - "$ref": "#/common/results/void" - }, - "errors": [ - { - "description": "Unknown device", - "$ref": "#/common/errors/unknownkey" - }, - { - "description": "Device is currently not pairing or passkey confirmation has not been requested", - "$ref": "#/common/errors/illegalstate" - } - ] - }, - "forget": { - "summary": "Forgets a known Bluetooth device", - "description": "The device will no longer be listed and its status tracked. If the device is connected and/or paired it will be disconnected and unpaired.", - "events": [ - "devicestatechange" - ], - "params": { - "type": "object", - "properties": { - "address": { - "$ref": "#/definitions/deviceaddress" - }, - "type": { - "$ref": "#/definitions/enums/devicetype" - } - }, - "required": [ - "address", - "type" - ] - }, - "result": { - "$ref": "#/common/results/void" - }, - "errors": [ - { - "description": "Unknown device", - "$ref": "#/common/errors/unknownkey" - } - ] - }, - "getdevicelist": { - "summary": "Retrieves a list of known remote Bluetooth devices", - "hint": "GetDeviceList", - "result": { - "description": "List of devices", - "type": "array", - "items": { - "description": "(device entry)", - "type": "object", - "properties": { - "address": { - "$ref": "#/definitions/deviceaddress" - }, - "type": { - "$ref": "#/definitions/enums/devicetype" - } - }, - "required": [ - "address", - "type" - ] - } - } - }, - "getdeviceinfo": { - "summary": "Retrieves detailed information about a known Bluetooth device", - "hint": "GetDeviceInfo", - "params": { - "type": "object", - "properties": { - "address": { - "$ref": "#/definitions/deviceaddress" - }, - "type": { - "$ref": "#/definitions/enums/devicetype" - } - }, - "required": [ - "address", - "type" - ] - }, - "result": { - "$ref": "#/definitions/deviceinfo" - }, - "errors": [ - { - "description": "Unknown device", - "$ref": "#/common/errors/unknownkey" - } - ] - } - }, - "properties": { - "adapters": { - "readonly": true, - "summary": "List of local Bluetooth adapters", - "params": { - "type": "array", - "items": { - "description": "Adapter ID", - "type": "integer", - "size": 16, - "example": 0 - } - } - }, - "adapter": { - "readonly": true, - "summary": "Local Bluetooth adapter information", - "index": { - "name": "Adapter ID", - "example": "0" - }, - "params": { - "$ref": "#/definitions/adapterinfo" - }, - "errors": [ - { - "description": "Unknown adapter device", - "$ref": "#/common/errors/unknownkey" - } - ] - }, - "devices": { - "readonly": true, - "deprecated": true, - "summary": "List of known remote Bluetooth devices", - "params": { - "type": "array", - "items": { - "$ref": "#/definitions/deviceaddress" - } - } - }, - "device": { - "deprecated": true, - "readonly": true, - "summary": "Remote Bluetooth device information", - "index": { - "name": "Device address", - "example": "81:6F:B0:91:9B:FE" - }, - "params": { - "$ref": "#/definitions/deviceinfo" - }, - "errors": [ - { - "description": "Unknown device", - "$ref": "#/common/errors/unknownkey" - } - ] - } - }, - "events": { - "discoverablestarted": { - "summary": "Notifies of entering the discoverable state", - "description": "Register to this event to be notified about entering the discoverable state", - "hint": "DiscoverableStarted", - "statuslistener": true, - "params": { - "type": "object", - "properties": { - "type": { - "$ref": "#/definitions/enums/discoverabletype" - }, - "mode": { - "$ref": "#/definitions/enums/discoverablemode" - }, - "connectable": { - "description": "Indicates connectable advertising (true, *LowEnergy* only)", - "type": "boolean", - "default": false - } - }, - "required": [ - "type", - "mode" - ] - } - }, - "discoverablecomplete": { - "summary": "Notifies of leaving the discoverable state", - "description": "Register to this event to be notified about leaving the discoverable state", - "hint": "DiscoverableComplete", - "params": { - "type": "object", - "properties": { - "type": { - "$ref": "#/definitions/enums/discoverabletype" - } - }, - "required": [ - "type" - ] - } - }, - "scanstarted": { - "summary": "Notifies of scan start", - "description": "Register to this event to be notified about device scan start", - "hint": "ScanStarted", - "statuslistener": true, - "params": { - "type": "object", - "properties": { - "type": { - "$ref": "#/definitions/enums/scantype" - }, - "mode": { - "$ref": "#/definitions/enums/scanmode" - } - }, - "required": [ - "type" - ] - } - }, - "scancomplete": { - "summary": "Notifies of scan completion", - "description": "Register to this event to be notified about device scan completion", - "hint": "ScanComplete", - "params": { - "type": "object", - "properties": { - "type": { - "$ref": "#/definitions/enums/scantype" - } - }, - "required": [ - "type" - ] - } - }, - "devicestatechange": { - "summary": "Notifies of device state changes", - "description": "Register to this event to be notified about device state changes", - "hint": "DeviceStateChanged", - "statuslistener": true, - "id": { - "name": "device type", - "example": "LowEnergy" - }, - "params": { - "type": "object", - "properties": { - "address": { - "$ref": "#/definitions/deviceaddress" - }, - "type": { - "$ref": "#/definitions/enums/devicetype" - }, - "state": { - "$ref": "#/definitions/enums/devicestate" - }, - "disconnectreason": { - "$ref": "#/definitions/enums/disconnectreason" - } - }, - "required": [ - "address", - "type", - "state" - ] - } - }, - "pincoderequest": { - "summary": "Notifies of a PIN code request", - "description": "Register to this event to be notified about PIN code requests during a legacy pairing process. Upon receiving this event the client is required to respond with a *providepincode* call in order to complete the pairing procedure. The PIN code value would typically be collected by prompting the end-user. If the client fails to respond before the pairing timeout elapses the pairing procedure will be aborted.

Note that this event will never be send for a Bluetooth LowEnergy device", - "hint": "PINCodeRequest", - "params": { - "type": "object", - "properties": { - "address": { - "$ref": "#/definitions/deviceaddress" - }, - "type": { - "$ref": "#/definitions/enums/devicetype", - "example": "Classic" - } - }, - "required": [ - "address", - "type" - ] - } - }, - "passkeyrequest": { - "summary": "Notifies of a passkey request", - "description": "Register to this event to be notified about passkey requests that may be required during a pairing process. Upon receiving this event the client is required to respond with a *providepasskey* call in order to complete the pairing procedure. The passkey value would typically be collected by prompting the end-user. If the client fails to respond before the pairing timeout elapses the pairing procedure will be aborted", - "hint": "PasskeyRequest", - "params": { - "type": "object", - "properties": { - "address": { - "$ref": "#/definitions/deviceaddress" - }, - "type": { - "$ref": "#/definitions/enums/devicetype", - "example": "Classic" - } - }, - "required": [ - "address", - "type" - ] - } - }, - "passkeyconfirmrequest": { - "summary": "Notifies of a passkey confirmation request", - "description": "Register to this event to be notified about passkey confirmation requests that may required during a pairing process. Upon receiving this event the client is required to respond with a *passkeyconfirm* call in order to complete the pairing procedure. The passkey confirmation would typically be collected by prompting the end-user. If the client fails to respond before the pairing timeout elapses the pairing procedure will be aborted", - "hint": "PasskeyConfirmRequest", - "params": { - "type": "object", - "properties": { - "address": { - "$ref": "#/definitions/deviceaddress" - }, - "type": { - "$ref": "#/definitions/enums/devicetype", - "default": "Classic", - "example": "Classic" - }, - "secret": { - "description": "A six-digit decimal number passkey sent by the remote device for confirmation; may be 0 for a simple accept/forbid paring request", - "type": "integer", - "example": 123456 - } - }, - "required": [ - "address", - "type", - "secret" - ] - } - } - } -}