/** * \brief BONDI bluetooth API. * * This API provides access to the bluetooth functionality. This set of interfaces provides a framework for * short range device and service discovery of other bluetooth devices. * * Once a service has been discovered it is then possible to connect to this service and exchange data. * * \def-api-feature http://bondi.omtp.org/api/bluetooth.discovery * \brief Call to LocalDevice.findDevices,LocalDevice.findService * \device-cap localdevice.discovery * * \author Jim O'Leary <jim.oleary@rococosoft.com> * \version 1.5 */ module bluetooth { /** * \brief Interface for the local bluetooth radio */ interface LocalDevice { /** * \brief The local device friendly name * * \code * alert("friendly name : " + bondi.bluetooth.name); * \endcode */ readonly attribute DOMString name; /** * \brief The local device bluetooth address * * The Bluetooth address will never be null. The Bluetooth address * will be 12 characters long. Valid characters are 0-9 and A-F. * * \code * alert(bondi.bluetooth.LocalDevice.address); * \endcode */ readonly attribute DOMString address; /** * \brief The local device class * * The Device Class consists of :\n * * service classes : e.g. poistioning, networking etc\n * * major device classes : e.g. computer , phone etc\n * * minor device classes : the meaning of these bits depends on the major device class\n * * * \code * var serviceClass = bondi.bluetooth.deviceClass & 0xFFE000; * var services = ""; * if (serviceClass & bondi.bluetooth.DeviceClass.SERVICE_POSITIONING !== 0) { * services += "Posiitioning"; * } * if (serviceClass & bondi.bluetooth.DeviceClass.SERVICE_NETWORKING !== 0) { * services += "Networking"; * } // and the rest * alert("Local Device Supports the following services " + services); * \endcode */ attribute unsigned long deviceClass setraises(SecurityError, DeviceAPIError); /** * \brief set the Local Devices discovery mode * * The dicoverable mode of the device can be one of :\n * * DiscoveryAgent.NOT_DISCOVERABLE : the device cannot be found by other devices * (i.e. it won't reposnd to inquiry scans)\n * * DiscoveryListener.GIAC : the device responds to General/Unlimited * Inquiry Access Code inquiries, i.e. the device is discoverable for an indefinite * amount of time\n * * DiscoveryListener.LIAC : the device responds to Limited Inquiry * Access Code inquiries, i.e the device is discoverable for a limited amount * of time (180 seconds).\n * * value in the range 0x9E8B00 to 0x9E8B3F\n * TODO : \api-feature http://bondi.omtp.org/api/bluetooth.discovery * * \code * bondi.bluetooth.discoveryMode = bondi.bluetooth.DiscoveryListener.LIAC; * \endcode */ attribute unsigned long discoveryMode setraises(SecurityError, DeviceAPIError); /** * \brief The cached devices. * * A list of devices that were found in previous inquiries. */ readonly attribute RemoteDeviceArray cachedDevices; /** * \brief The pre-known devices. * * A list of pre-known devices. */ readonly attribute RemoteDeviceArray preknownDevices; /** * \brief The trusted devices. * * A list of trusted devices. */ readonly attribute RemoteDeviceArray trustedDevices; /** * \brief the maiximum supported MTU * * \code * alert(bondi.bluetooth.l2cap_max_receiveMTU); * \endcode */ readonly attribute int l2cap_max_receiveMTU; /** * \brief true if this device support role switch * * \code * alert(bondi.bluetooth.master_switch); * \endcode */ readonly attribute boolean master_switch; /** * \brief The maximum number of connected device. * * This value can be greater than 7 if parking is supported. * * \code * alert(bondi.bluetooth.max_connected_devices); * \endcode */ readonly attribute int max_connected_devices; /** * \brief The maximum number of simultaneous service searches. * * \code * alert(bondi.bluetooth.sd_max); * \endcode */ readonly attribute int sd_max; /** * \brief true if device discovery supported while connceted to another * device. * * \code * alert(bondi.bluetooth.connected_inquiry); * \endcode */ readonly attribute boolean connected_inquiry; /** * \brief true if this device will respond to a device discovery * while connceted to another device. * * \code * alert(bondi.bluetooth.connected_inquiry_scan); * \endcode */ readonly attribute boolean connected_inquiry_scan; /** * \brief true if this device can do a page scan * while connceted to another device. * * page scanning is required to retrieve the friendly name of * another device. * * \code * alert(bondi.bluetooth.connected_page); * \endcode */ readonly attribute boolean connected_page; /** * \brief true if this device can respond a page scan * while connceted to another device. * * page scanning is required to retrieve the friendly name of * another device. #* * \code * alert(bondi.bluetooth.connected_page_scan); * \endcode */ readonly attribute boolean connected_page_scan; /** * \brief Search for devices in the area. * * Start an inquiry in the specified mode. Use the listener to handle device and * service discovery events. * * TODO: \api-feature http://bondi.omtp.org/api/bluetooth.discovery * * \code * var listener = { * discovered: {}, * deviceDiscovered: function (device) { * this.discovered[this.discovered.length] = device; * } * }; * function errorCB(err) { * alert("BONDI bluetooth API device discovery failed : " + err.message); * } * * function successCB() { * for (var i = 0; i < listener.devices.length; i++) { * alert(listener.devices[i].name); * } * } * bondi.bluetooth.findDevices(successCB, errorCB, listener); * // find devices in LIAC mode for 60 seconds * bondi.bluetooth.findDevices(successCB, errorCB, listener, {mode: bondi.bluetooth.DiscoveryAgent.LIAC}); * // find devices for 12 seconds only * bondi.bluetooth.findDevices(successCB, errorCB, listener, {timeout: 12000}); * // find devices until operation is cancelled * var operation = bondi.bluetooth.findDevices(successCB, errorCB, listener, {timeout: 0}); * \endcode * * \param successCallback the callback interface * \param errorCallback the callback interface * \param listener the discovery callback interface * \param connectOptions a hash of other options, including\n * \n * * * accessCode(unsigned long) : the inquiry type, either GIAC or LIAC or in the range 0x9E8B00 \n * to 0x9E8B3F.defaults GIAC.\n * * * timeout(unsigned long) : the max amount of time (in millis) to spend searching. defaults 60 seconds,0 => forever.\n * * \throw DeviceAPIError INVALID_ARGUMENT_ERROR if the params are invalid (for example invalid accesss code, listener is undefined). */ PendingOperation findDevices(in SuccessCallback successCallback, in ErrorCallback errorCallback, in DiscoveryListener listener, in Map connectOptions) raises(DeviceAPIError); /** * \brief Find a matching service on a remote device. * * search a device to determine if it hosts the service specified by the UUID. The uuid * must be in the ServiceClassIDList on the remote host. This method will also search for the * optional protocol UUID (defaults to rfcomm) and optional name. If multiple * services match then the first service is returned. * * \code * function errorCB(err) { * alert("BONDI bluetooth API device discovery failed : " + err.message); * } * * function successCB(uri) { * if (uri !== undefined) { * alert("bondi.bluetooth : discovered service : " + uri); * } else { * alert("bondi.bluetooth : no such service"); * } * } * // search for rfcomm service with 16 bit UUID "E205" * var operation = bondi.bluetooth.findService(successCB, errorCB, "112233445566", "E205"); * // 32 bit UUID, same search as above * var operation = bondi.bluetooth.findService(successCB, * errorCB, * "112233445566", * "000000E205"); * // 128 bit UUID but same search as above * var operation = bondi.bluetooth.findService(successCB, * errorCB, * "112233445566", * "0000E205-0000-1000-8000-00805F9B34FB"); * * // search for an rfcomm service named "bondi" * bondi.bluetooth.findService(successCB, errorCB, "112233445566", "E205", {name: "bondi"}); * * // search for an rfcomm connection, the generated uri specifies that the connection * // must be encrypted * bondi.bluetooth.findService(successCB, errorCB, "112233445566", "E205", {}, {encrypted: true}); * \endcode * * \param successCallback the success callback * \param errorCallback the error callback * \param uuid the uuid to search the ServiceClassIDList * \param address the bluetooth address of the host to search (default to nil). * \param searchOptions a map of search related options\n * \n * * * name : if a name is provided then the name must match then service * name in the remote service record. If name is undefined (default) then the * name is not checked.\n * * * protocol : the type of connection to search for. It must be one of :\n * * - btspp : Serial Port Profile (Rfcomm)the default\n * * - btgoep : Obbex Profile NOT SUPPORTED in this version\n * * - btl2cap : L2cap Profile NOT SUPPORTED in this version\n * \n * \param connectOptions a map of connection related options1\n * \n * * * authenticate : does the service need to authenticated, defaults * to false\n * * * encrypt : does the service need to encrypted, defaults to false\n * * * master : does the client need to be master. (defaults to undefined, * which means dont care )). If set to true then the client must be master and * will not accept a role switch (not recommended as it will limit the number of * connections the server can accept and it might cause the connection to fail if the server * wants to be the master). If set to false then the client doesn't care.\n * \return a pending operation, which can be used to cancel the service search */ PendingOperation findService(in ServiceSuccessCallback successCallback, in ErrorCallback errorCallback, in DOMString address, in DOMString uuid, in Map searchOptions, in Map connectOptions) raises(DeviceAPIError); /** * \brief Create a socket and connect to the remote service for this * bluetooth uri connector string. * * Create a new (connected) socket representing the a connection to the * remote service. * * TODO: \api-feature http://bondi.omtp.org/api/bluetooth.connect * * \code * var uri; // find the service first * var operation; * function successCB(socket) { * if (socket.operation === undefined) { * alert("bondi.bluetooth connection to " + socket.device.address); * } else { * alert("bondi.bluetooth connection from " + socket.device.address); * } * } * function errorCB(err) { * alert("BONDI bluetooth connection failed : " + err.message); * } * var dataHandler = { * received : function (socket) { * var len = socket.byteAvailable(); * alert("bondi.bluetooth : " + len + " bytes available"); * alert(socket.read().toString()); * }, * sent : function (socket, len) { * alert("bondi.bluetooth : " + len + " bytes sent"); * }, * error : function (socket, e) { * alert("bondi.bluetooth : error " + e.msg); * } * }; * try { * operation = bondi.bluetooth.connect(successCB, errorCB, uri); * } catch (e) { * alert(e.message); * } * \endcode * * \param successCallback the callback interface * \param errorCallback the callback interface * \param rwCallback the data callback that is used to handle events on the sockets * \param uri the bluetooth connector string * \param connectOptions a map of connection related options1\n * \n * * -timeout : the amount o f time in millis to wait, -1 => forever this is * the default */ PendingOperation connect(in SocketSuccessCallback successCallback, in ErrorCallback errorCallback, in ReadWriteCallback rwCallback, in DOMString uri, in Map connectOptions); /** * \brief Create a server socket for a service. * * Create a new server socket representing a service called name with the specified uuid * in the service class idl ist. * * TODO: \api-feature http://bondi.omtp.org/api/bluetooth.listen * * \code * var operation; * function errorCB(err) { * alert("BONDI bluetooth server connection failed : " + err.message); * } * * function successCB(socket) { * if (socket.operation === undefined) { * alert("bondi.bluetooth connection to " + socket.device.address); * } else { * alert("bondi.bluetooth connection from " + socket.device.address); * } * } * var dataHandler = { * received : function (socket) { * var len = socket.byteAvailable(); * alert("bondi.bluetooth : " + len + " bytes available"); * alert(socket.read().toString()); * }, * sent : function (socket, len) { * alert("bondi.bluetooth : " + len + " bytes sent"); * }, * error : function (socket, e) { * alert("bondi.bluetooth : error " + e.msg); * } * }; * try { * operation = bondi.bluetooth.listen(successCB, errorCB, dataHandler, "E205"); * } catch (e) { * alert(e.message); * } * // or a service with a name * try { * operation = bondi.bluetooth.listen(successCB, errorCB, dataHandler, "E205", {name: "bondi"}); * } catch (e) { * alert(e.message); * } * // or a service that must be encrypted * try { * operation = bondi.bluetooth.listen(successCB, errorCB, dataHandler, "E205", {}, {encrypted: true}); * } catch (e) { * alert(e.message); * } * \endcode * * \param successCallback the success callback * \param errorCallback the error callback * \param rwCallback the data callback that is used to handle events on the sockets * created by this listener * \param uuid the uuid to register in the ServiceClassIDList * \param serviceOptions a map of service options, including\n * * - name : if a name is provided then it will be added to the service * record and can be used to further narrow the client search criteria (defaults * to nothing).\n * * - protocol : the type of connection to search for. It must be one of : * * * btspp : Serial Port Profile (Rfcomm)the default\n * * *btgoep : Obbex Profile NOT SUPPORTED in this version\n * * *btl2cap : L2cap Profile NOT SUPPORTED in this version\n * \n * * \param connectOptions a map of connection related options, including\n * \n * * - authenticate : does the service need to authenticated, defaults to * false\n * * - encrypt : does the service need to encrypted, defaults to * false\n * * - master : does the client need to be master. master defaults to false. * If set to true then the client must be master and will not accept a role switch * (not recommended as it will limit the number of connections the server can accept and * it might cause the connection to fail if the server wants/needs to be the master). * If set to false then the client doesn't care.\n * \return a pending operation, which can be used to cancel the listen. */ PendingOperation listen(in SocketSuccessCallback successCallback, in ErrorCallback errorCallback, in ReadWriteCallback rwCallback, in DOMString uuid, in Map serviceOptions, in Map connectOptions); }; /** * \brief Discovery event listener class. * * This listener defines methods to handle device discovery notifications. Note that * it is possible that no device is found so this callback may never be called. * * \code * var listener = { * discovered: [], * deviceDiscovered: function (device) { * this.discovered[this.discovered.length] = device; * alert("Discovered device " + device.address); * } * }; * function errorCB(err) { * alert("BONDI bluetooth API device discovery failed : " + err.message); * } * * function successCB(devices) { * alert("discovery complete"); * } * bondi.bluetooth.findDevices(successCB, errorCB, listener); * \endcode */ interface DiscoveryListener { /** * \brief Takes the device out of discoverable mode. */ const unsigned long NOT_DISCOVERABLE = 0; /** * \brief General/Unlimited Inquiry Access Code * * This is used to specify the type of inquiry to complete or * respond to. */ const unsigned long GIAC = 0x9E8B33; /** * \brief Limited Dedicated Inquiry Access Code * * This is used to specify the type of inquiry to complete or * respond to. */ const unsigned long LIAC = 0x9E8B00; /** * \brief Access code range starting value. */ const unsigned long AC_START_RANGE = 0x9E8B00; /** * \brief Access code range end value. */ const unsigned long AC_END_RANGE = 0x9E8B3F; /** * \brief Method invoked when a new device is discovered. * * A new device is in range. * * \param device the device. */ void deviceDiscovered(in RemoteDevice device); }; /** * \brief Success callback for service discovery. * * If the service couldn't be found then the service uri may be undefined. */ [Callback=FunctionOnly, NoInterfaceObject] interface ServiceSuccessCallback { /** * \brief Method invoked at the end of a successfull service search. * * \code * var uuid = "E205"; * var address = "112233445566"; * function errorCB(err) { * alert("BONDI bluetooth API device discovery failed : " + err.message); * } * * function successCB(uri) { * if (uri !== undefined) { * alert("bondi.bluetooth : discovered service " + uri); * } else { * alert("bondi.bluetooth : no such service " + uuid + " on " + address); * } * } * bondi.bluetooth.findService(successCB, errorCB, uuid, address); * * \endcode * * \param uri the remote service connector string, will be undefined if * no service found. */ void onSuccess(in DOMString uri); }; /** * \brief Callback interface used to indicate when data is read or written * * \code * var dataHandler = { * name : function (socket) { * return (socket.device.name === undefined ? socket.device.address : socket.device.name); * }, * received : function (socket) { * var len, str; * len = socket.byteAvailable(); * str = "
" + socket.read().toString() + "
"; * alert("bondi.bluetooth : " + len + " bytes available from " + this.name(socket)); * document.getElementById("content").innerHTML += str; * }, * sent : function (socket, len) { * alert("bondi.bluetooth : " + len + " bytes sent to " + this.name(socket)); * document.getElementById("sendBtn").className = "enabled"; * } * }; * document.getElementById("sendBtn").className = "disabled"; * try { * bondi.bluetooth.connect(successCB, * errorCB, * dataHandler, * uri); * } catch (e) { * alert("error connecting to remote device " + e); * } * document.getElementById("sendBtn").className = "enabled"; * * \endcode */ [Callback=FunctionOnly, NoInterfaceObject] interface ReadWriteCallback { /** * \brief This method is invoked when data is available to read. * * * \param socket the socket that has data available */ void recevied(in Socket socket); /** * \brief This method is invoked when data was sent * * \param socket the socket that sent the data * \param len the amount of data sent */ void sent(in Socket socket,in int len); /** * \brief This method is invoked when an error occurrs * * \param socket the socket that sent the data * \param e the error */ void error(in Socket socket,in Object e); }; /** * \brief Success callback for socket connections (both client and server). * */ [Callback=FunctionOnly, NoInterfaceObject] interface SocketSuccessCallback { /** * \brief Method invoked when a connection is created (either through * a call to create or a listen). * * \code * function errorCB(err) { * alert("BONDI bluetooth API device discovery failed : " + err.message); * } * * function successCB(socket) { * if (socket.operation === undefined) { * alert("bondi.bluetooth : connection to " + socket.device.address); * } else { * alert("bondi.bluetooth : connection from " + socket.device.address); * } * } * // service uri came from findSrvice call * bondi.bluetooth.connect(successCB, errorCB, uri); * * // listen for incoming rfcomm connections from clients * bondi.bluetooth.listen(successCB, errorCB, "E205"); * * \endcode * * \param uri the remote service connector string */ void onSuccess(in Socket uri); }; /** * \brief Array of remote devices. * * This array type is used to get cached, preknown and trusted devices. */ typedef sequence| " + d.name + " |
* The value of SERVICE_POSITIONING is 0x10000 (65536). */ const unsigned long SERVICE_POSITIONING = 0x10000; /** * Represents the Networking (LAN, Ad hoc, ...) Major Service Class. *
* The value of SERVICE_NETWORKING is 0x20000 (131072). */ const unsigned long SERVICE_NETWORKING = 0x20000; /** * Represents the Rendering (Printing, Speaker, ...) Major Service Class. *
* The value of SERVICE_RENDERING is 0x40000 (262144). */ const unsigned long SERVICE_RENDERING = 0x40000; /** * Represents the Capturing (Scanner, Microphone, ...) Major Service Class. *
* The value of SERVICE_CAPTURING is 0x80000 (524288). */ const unsigned long SERVICE_CAPTURING = 0x80000; /** * Represents the Object Transfer (v-Inbox, v-Folder, ...) Major Service * Class. *
* The value of SERVICE_OBJECT_TRANSFER is 0x100000 * (1048576). */ const unsigned long SERVICE_OBJECT_TRANSFER = 0x100000; /** * Represents the Audio (Speaker, Microphone, Headset service, ...) Major * Service Class. *
* The value of SERVICE_AUDIO is 0x200000 (2097152). */ const unsigned long SERVICE_AUDIO = 0x200000; /** * Represents the Telephony (Cordless telephony, Modem, Headset service, * ...) Major Service Class. *
* The value of SERVICE_TELEPHONY is 0x400000 (4194304). */ const unsigned long SERVICE_TELEPHONY = 0x400000; /** * Represents the Information (WEB-server, WAP-server, ...) Major Service * Class. *
* The value of the SERVICE_INFORMATION is 0x800000 (8388608). */ const unsigned long SERVICE_INFORMATION = 0x800000; /** * The mask to get the major device bits. */ const unsigned long MAJOR_DEVICE_MASK = 0x1F00; /** * Represents the Miscellaneous Major Device Class. */ const unsigned long MISCELLANEOUS_MAJOR_DEVICE = 0x000; /** * Represents the Computer Major Device Class (e.g. laptop, desktop , PDA etc.). */ const unsigned long COMPUTER_MAJOR_DEVICE = 0x100; /** * Represents the Phone Major Device Class (e.g. cell, cordless, smart phone etc.) */ const unsigned long PHONE_MAJOR_DEVICE = 0x200; /** * Represents the LAN/Networking Major Device Class */ const unsigned long NETWORKING_MAJOR_DEVICE = 0x300; /** * Represents the Audio/Visual Major Device Class (e.g headset, handsfree etc.) */ const unsigned long AUDIO_VISUAL_MAJOR_DEVICE = 0x400; /** * Represents the Peripheral Major Device Class (e.g keyboard, mouse etc.) */ const unsigned long PERIPHERAL_MAJOR_DEVICE = 0x500; /** * Represents the Imaging Major Device Class (e.g display, camera, scanner etc.) */ const unsigned long IMAGING_MAJOR_DEVICE = 0x600; /** * Represents the Wearable Major Device Class (e.g wrist watch, pager, jacket etc.) */ const unsigned long WEARABLE_MAJOR_DEVICE = 0x700; /** * Represents the Toy Major Device Class (e.g robot , vehicle, doll/action figure etc.) */ const unsigned long TOY_MAJOR_DEVICE = 0x800; /** * Represents the Uncategorized Major Device Class */ const unsigned long UNCATEGORIZED_MAJOR_DEVICE = 0x1F00; /** * The mask to get the minor device bits. The exact meaning of these bits depends on the major * device class. Please refer to http://www.bluetooth.org/assigned-numbers/ for more detail. */ const unsigned long MINOR_DEVICE_MASK = 0xFC; }; };