btDiscoverDevicesStart()

Starts the discovery of nearby Bluetooth devices.

Synopsis

int btDiscoverDevicesStart(string|function_ptr callback [, mapping options]);

Parameters


Parameter	Meaning
callback	Callback function, which is started when a state changes.
options	The options mapping can contain the following key (value type) pairs:
	"adapter" (string)	Defines which Bluetooth adapter to use in the system, defined by the Bluetooth address. The format of this address can be either given as XX:XX:XX:XX:XX:XX or XXXXXXXXXXXX, where X is a hexadecimal digit. This is not case sensitive. If no adapter is given, the default adapter will be used.
	"btleTimeout" (int)	Sets the maximum search time for Bluetooth Low Energy device search to the time out in milliseconds. If the time-out is set to 0, the discovery runs until btDiscoverDevicesStop() is called. This reflects the fact that the discovery process for Bluetooth Low Energy devices is mostly open ended. The platform continues to look for more devices until the search is manually stopped. The time-out ensures that the search is aborted after it has run though. It is still possible to manually abort the discovery by calling btDiscoverDevicesStop() during this time out.
	"discoveryMethods" (string)	A combination of "ClassicMethod" and/or "LowEnergyMethod" (separated by \|) to limit the scope of the device search. For example, if the target service or device is a Bluetooth Low Energy device, this option can be used to limit the search to Bluetooth Low Energy devices and thereby reduces the discovery time significantly. The default is LowEnergyMethod except the adapter can only discover classic Bluetooth. In that case it's ClassicMethod

Return Value

Returns 0 when the discovery was started or -1 if an error occurs.

Errors

Another discovery is currently running or invalid arguments were given.

Description

Every time a device is discovered, an error occurs or some other state changes, the given callback will be triggered.

The callback must have one argument of type mapping (e.g.: callback(mapping map) { ... } )

The mapping passed to the callback will have the following keys:


callback mapping
"reason" (string)	This key is always present. It specifies why the callback has been started. It can be one of the following:
	"finished"	The discovery has finished
	"canceled"	The discovery has been canceled via the CTRL function btDiscoverDevicesStop()
	"device"	A device has been discovered. In this case the mapping holds another key, "device".
	"error"	An Error occurred, in which case the mapping will now also hold the keys "errorString and "error"
In case a device has been discovered the callback mapping holds the additional key:
"device" (mapping)	mapping, included as value for the "device" Key, it contains the following key (value type) pairs:
	"address" (string)	The Bluetooth address as a string of the form XX:XX:XX:XX:XX:XX
	"name" (string)	The name assigned to the device.
	"majorDeviceClass" (uint)	The MajorDeviceClass enum, see Qt-Documentation.
	"minorDeviceClass" (uint)	The MinorDeviceClass enum, see Qt-Documentation.
	"rssi" (int)	The signal strength.
	"coreConfigurations" (uint)	The coreConfiguration enum, see Qt-Documentation. Basically: 1 = BT-LowEnergy; 2 = classic Bluetooth, 3 = 1 + 2
	"serviceClasses" (uint)	The serviceClass enum, see Qt-Documentation.
The following additional keys will be present only in the case of "reason" is "error":
"errorString" (string)	a human-readable description of the last error.
"error" (string)	The error expressed in one of the following error codes:
	"PoweredOff"	The Bluetooth adapter is powered off, power it on before doing discovery.
	"InputOutput"	Writing or reading from the device resulted in an error.
	"InvalidBluetoothAdapter"	The passed local adapter address does not match the physical adapter address of any local Bluetooth device.
	"UnsupportedPlatform"	Device discovery is not possible or implemented on the current platform
	"Unknown"	An unknown error has occurred.

VORSICHT:

You can not start the discovery again until the first discovery is finished or stopped.

Assignment

Mobile UI control functions