Bondi logo

The Bondi bluetooth Module - Version 1.5

February 2010

Authors

© 2009-2010 OMTP Ltd. All rights reserved. OMTP and OMTP BONDI are registered trademarks of OMTP Ltd.

Abstract

BONDI bluetooth API.

Table of Contents

Summary of Methods

Interface Method
LocalDevice PendingOperation findDevices(SuccessCallback successCallback, ErrorCallback errorCallback, DiscoveryListener listener, Map connectOptions)
PendingOperation findService(ServiceSuccessCallback successCallback, ErrorCallback errorCallback, DOMString address, DOMString uuid, Map searchOptions, Map connectOptions)
PendingOperation connect(SocketSuccessCallback successCallback, ErrorCallback errorCallback, ReadWriteCallback rwCallback, DOMString uri, Map connectOptions)
PendingOperation listen(SocketSuccessCallback successCallback, ErrorCallback errorCallback, ReadWriteCallback rwCallback, DOMString uuid, Map serviceOptions, Map connectOptions)
DiscoveryListener void deviceDiscovered(RemoteDevice device)
ServiceSuccessCallback void onSuccess(DOMString uri)
ReadWriteCallback void recevied(Socket socket)
void sent(Socket socket, int len)
void error(Socket socket, Object e)
SocketSuccessCallback void onSuccess(Socket uri)
RemoteDevice
Socket void close()
Stream PendingOperation close(SuccessCallback successCallback, ErrorCallback errorCallback)
PendingOperation flush(SuccessCallback successCallback, ErrorCallback errorCallback)
ByteArray read(unsigned long byteCount)
PendingOperation write(SuccessCallback successCallback, ErrorCallback errorCallback, ByteArray byteData)
DeviceClass

1. Introduction

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.

1.2. Features

This is the list of URIs used to declare this API's features, for use in bondi.requestFeature. For each URL, the list of functions covered is provided.

http://bondi.omtp.org/api/bluetooth.discovery

Call to LocalDevice.findDevices,LocalDevice.findService

Device capabilities:

  • localdevice.discovery

2. Type Definitions

2.1. RemoteDeviceArray

Array of remote devices. 

        typedef sequence<RemoteDevice> RemoteDeviceArray;

This array type is used to get cached, preknown and trusted devices.

3. Interfaces

3.1. LocalDevice

Interface for the local bluetooth radio 

        interface LocalDevice {

                readonly attribute DOMString name;

                readonly attribute DOMString address;

                attribute unsigned long deviceClass setraises(SecurityError, DeviceAPIError);

                attribute unsigned long discoveryMode setraises(SecurityError, DeviceAPIError);

                readonly attribute RemoteDeviceArray cachedDevices;

                readonly attribute RemoteDeviceArray preknownDevices;

                readonly attribute RemoteDeviceArray trustedDevices;

                readonly attribute int l2cap_max_receiveMTU;

                readonly attribute boolean master_switch;

                readonly attribute int max_connected_devices;

                readonly attribute int sd_max;

                readonly attribute boolean connected_inquiry;

                readonly attribute boolean connected_inquiry_scan;

                readonly attribute boolean connected_page;

                readonly attribute boolean connected_page_scan;

                PendingOperation findDevices(in SuccessCallback successCallback,
                                             in ErrorCallback        errorCallback,
                                             in DiscoveryListener listener,
                                             in Map connectOptions)
                        raises(DeviceAPIError);

                PendingOperation findService(in ServiceSuccessCallback successCallback,
                                             in ErrorCallback        errorCallback,
                                             in DOMString address,
                                             in DOMString uuid,
                                             in Map searchOptions,
                                             in Map connectOptions) raises(DeviceAPIError);


                PendingOperation connect(in SocketSuccessCallback successCallback,
                                         in ErrorCallback   errorCallback,
                                         in ReadWriteCallback   rwCallback,
                                         in DOMString uri,
                                         in Map connectOptions);

                PendingOperation listen(in SocketSuccessCallback successCallback,
                                        in ErrorCallback   errorCallback,
                                        in ReadWriteCallback rwCallback,
                                        in DOMString uuid,
                                        in Map serviceOptions,
                                        in Map connectOptions);
       };

Attributes

readonly DOMString name

The local device friendly name

Code example
        alert("friendly name  : " + bondi.bluetooth.name);
readonly DOMString address

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 example
        alert(bondi.bluetooth.LocalDevice.address);
unsigned long deviceClass

The local device class

The Device Class consists of :
    service classes : e.g. poistioning, networking etc
    major device classes : e.g. computer , phone etc
    minor device classes : the meaning of these bits depends on the major device class

  • SecurityError:
  • DeviceAPIError:
    • Code example
            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);
    unsigned long discoveryMode

    set the Local Devices discovery mode

    The dicoverable mode of the device can be one of :
        DiscoveryAgent.NOT_DISCOVERABLE : the device cannot be found by other devices (i.e. it won't reposnd to inquiry scans)
        DiscoveryListener.GIAC : the device responds to General/Unlimited Inquiry Access Code inquiries, i.e. the device is discoverable for an indefinite amount of time
        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).
        value in the range 0x9E8B00 to 0x9E8B3F
    TODO :

  • SecurityError:
  • DeviceAPIError:
    • Code example
            bondi.bluetooth.discoveryMode = bondi.bluetooth.DiscoveryListener.LIAC;
    readonly RemoteDeviceArray cachedDevices

    The cached devices.

    A list of devices that were found in previous inquiries.

    readonly RemoteDeviceArray preknownDevices

    The pre-known devices.

    A list of pre-known devices.

    readonly RemoteDeviceArray trustedDevices

    The trusted devices.

    A list of trusted devices.

    readonly int l2cap_max_receiveMTU

    the maiximum supported MTU

    Code example
            alert(bondi.bluetooth.l2cap_max_receiveMTU);
    readonly boolean master_switch

    true if this device support role switch

    Code example
            alert(bondi.bluetooth.master_switch);
    readonly int max_connected_devices

    The maximum number of connected device.

    This value can be greater than 7 if parking is supported.

    Code example
            alert(bondi.bluetooth.max_connected_devices);
    readonly int sd_max

    The maximum number of simultaneous service searches.

    Code example
            alert(bondi.bluetooth.sd_max);
    readonly boolean connected_inquiry

    true if device discovery supported while connceted to another device.

    Code example
            alert(bondi.bluetooth.connected_inquiry);
    readonly boolean connected_inquiry_scan

    true if this device will respond to a device discovery while connceted to another device.

    Code example
            alert(bondi.bluetooth.connected_inquiry_scan);
    readonly boolean connected_page

    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 example
            alert(bondi.bluetooth.connected_page);
    readonly boolean connected_page_scan

    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 example
            alert(bondi.bluetooth.connected_page_scan);

    Methods

    findDevices

    Search for devices in the area.

    Signature
    PendingOperation findDevices(in SuccessCallback successCallback, in ErrorCallback errorCallback, in DiscoveryListener listener, in Map connectOptions);

    Start an inquiry in the specified mode. Use the listener to handle device and service discovery events.

    TODO:

    Parameters
    • successCallback: the callback interface
    • errorCallback: the callback interface
    • listener: the discovery callback interface
    • connectOptions: a hash of other options, including

            * accessCode(unsigned long) : the inquiry type, either GIAC or LIAC or in the range 0x9E8B00
      to 0x9E8B3F.defaults GIAC.
            * timeout(unsigned long) : the max amount of time (in millis) to spend searching. defaults 60 seconds,0 => forever.
    Exceptions
    • DeviceAPIError:

      INVALID_ARGUMENT_ERROR if the params are invalid (for example invalid accesss code, listener is undefined).

    API features
    http://bondi.omtp.org/api/bluetooth.discovery
    Code example
            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});
    findService

    Find a matching service on a remote device.

    Signature
    PendingOperation findService(in ServiceSuccessCallback successCallback, in ErrorCallback errorCallback, in DOMString address, in DOMString uuid, in Map searchOptions, in Map connectOptions);

    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.

    Parameters
    • successCallback: the success callback
    • errorCallback: the error callback
    • address: the bluetooth address of the host to search (default to nil).
    • uuid: the uuid to search the ServiceClassIDList
    • searchOptions: a map of search related options

            * 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.
            * protocol : the type of connection to search for. It must be one of :
                 - btspp : Serial Port Profile (Rfcomm)the default
                 - btgoep : Obbex Profile NOT SUPPORTED in this version
                 - btl2cap : L2cap Profile NOT SUPPORTED in this version

    • connectOptions: a map of connection related options1

            * authenticate : does the service need to authenticated, defaults to false
            * encrypt : does the service need to encrypted, defaults to false
            * 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.
    Return value
    a pending operation, which can be used to cancel the service search
    Exceptions
    • DeviceAPIError:
    Code example
            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});
    connect

    Create a socket and connect to the remote service for this bluetooth uri connector string.

    Signature
    PendingOperation connect(in SocketSuccessCallback successCallback, in ErrorCallback errorCallback, in ReadWriteCallback rwCallback, in DOMString uri, in Map connectOptions);

    Create a new (connected) socket representing the a connection to the remote service.

    TODO:

    Parameters
    • successCallback: the callback interface
    • errorCallback: the callback interface
    • rwCallback: the data callback that is used to handle events on the sockets
    • uri: the bluetooth connector string
    • connectOptions: a map of connection related options1

            -timeout : the amount o f time in millis to wait, -1 => forever this is the default
    API features
    http://bondi.omtp.org/api/bluetooth.connect
    Code example
            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);
        }
    listen

    Create a server socket for a service.

    Signature
    PendingOperation listen(in SocketSuccessCallback successCallback, in ErrorCallback errorCallback, in ReadWriteCallback rwCallback, in DOMString uuid, in Map serviceOptions, in Map connectOptions);

    Create a new server socket representing a service called name with the specified uuid in the service class idl ist.

    TODO:

    Parameters
    • successCallback: the success callback
    • errorCallback: the error callback
    • rwCallback: the data callback that is used to handle events on the sockets created by this listener
    • uuid: the uuid to register in the ServiceClassIDList
    • serviceOptions: a map of service options, including
            - 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).
            - protocol : the type of connection to search for. It must be one of :            * btspp : Serial Port Profile (Rfcomm)the default
                 *btgoep : Obbex Profile NOT SUPPORTED in this version
                 *btl2cap : L2cap Profile NOT SUPPORTED in this version

    • connectOptions: a map of connection related options, including

            - authenticate : does the service need to authenticated, defaults to false
            - encrypt : does the service need to encrypted, defaults to false
            - 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.
    Return value
    a pending operation, which can be used to cancel the listen.
    API features
    http://bondi.omtp.org/api/bluetooth.listen
    Code example
            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);
        }

    3.2. DiscoveryListener

    Discovery event listener class. 

            interface DiscoveryListener {
                const unsigned long NOT_DISCOVERABLE = 0;

                const unsigned long GIAC = 0x9E8B33;

                const unsigned long LIAC = 0x9E8B00;

                const unsigned long AC_START_RANGE = 0x9E8B00;

                const unsigned long AC_END_RANGE = 0x9E8B3F;


                void deviceDiscovered(in RemoteDevice device);
        };

    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 example
            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);

    Constants

    unsigned long NOT_DISCOVERABLE

    Takes the device out of discoverable mode.

    unsigned long GIAC

    General/Unlimited Inquiry Access Code

    This is used to specify the type of inquiry to complete or respond to.

    unsigned long LIAC

    Limited Dedicated Inquiry Access Code

    This is used to specify the type of inquiry to complete or respond to.

    unsigned long AC_START_RANGE

    Access code range starting value.

    unsigned long AC_END_RANGE

    Access code range end value.

    Methods

    deviceDiscovered

    Method invoked when a new device is discovered.

    Signature
    void deviceDiscovered(in RemoteDevice device);

    A new device is in range.

    Parameters
    • device: the device.

    3.3. ServiceSuccessCallback

    Success callback for service discovery. 

            [Callback=FunctionOnly, NoInterfaceObject] interface ServiceSuccessCallback {
                void onSuccess(in DOMString uri);
        };

    If the service couldn't be found then the service uri may be undefined.

    Methods

    onSuccess

    Method invoked at the end of a successfull service search.

    Signature
    void onSuccess(in DOMString uri);
    Parameters
    • uri: the remote service connector string, will be undefined if no service found.
    Code example
            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);

    3.4. ReadWriteCallback

    Callback interface used to indicate when data is read or written 

            [Callback=FunctionOnly, NoInterfaceObject] interface ReadWriteCallback {
                void recevied(in Socket socket);

                void sent(in Socket socket,in int len);

                void error(in Socket socket,in Object e);
        };
    Code example
            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 = "p class='read'>" + socket.read().toString() + "/p>";
                    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";

    Methods

    recevied

    This method is invoked when data is available to read.

    Signature
    void recevied(in Socket socket);
    Parameters
    • socket: the socket that has data available
    sent

    This method is invoked when data was sent

    Signature
    void sent(in Socket socket, in int len);
    Parameters
    • socket: the socket that sent the data
    • len: the amount of data sent
    error

    This method is invoked when an error occurrs

    Signature
    void error(in Socket socket, in Object e);
    Parameters
    • socket: the socket that sent the data
    • e: the error

    3.5. SocketSuccessCallback

    Success callback for socket connections (both client and server). 

            [Callback=FunctionOnly, NoInterfaceObject] interface SocketSuccessCallback {
                void onSuccess(in Socket uri);
        };

    Methods

    onSuccess

    Method invoked when a connection is created (either through a call to create or a listen).

    Signature
    void onSuccess(in Socket uri);
    Parameters
    • uri: the remote service connector string
    Code example
            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");

    3.6. RemoteDevice

    Interface representing a Remote Bluetooth device 

            interface RemoteDevice {

                readonly attribute boolean trusted;

                readonly attribute DOMString name;

                readonly attribute DOMString address;

                readonly attribute unsigned long deviceClass;

                readonly attribute boolean authenticated;

                readonly attribute boolean authorized;

                readonly attribute boolean encrypted;


        };

    Attributes

    readonly boolean trusted

    Is this bluetooth device trusted

    readonly DOMString name

    Get the remote device friendly name

    The remote device will only be contacted if the name isn't already known.

    readonly DOMString address

    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 example
            var devices = bondi.bluetooth.preknownDevices;
        var str = "div id='title'>Pre Known Devices(" + devices.length + ")/div>";

        str += "div id='preknown'>";
        str += "table>";
        var i;
        try {
            for (i = 0; i  devices.length; i++) {
                var d = devices[i];
                str += "tr>td>a href='javascript:displayDetails(" + d.address + ");'>" + d.name + "/a>/td>/tr>";
            }
        } catch (e) {
            alert(e.message);
        }
        str += "/table>";
    readonly unsigned long deviceClass

    Get the device class

    readonly boolean authenticated

    Is the connection to the remote device authenticated

    Authentication is a means of verifying the identity of a remote device.

    readonly boolean authorized

    Is this device authorized

    Some Bluetooth systems may allow the user to permanently authorize a remote device for all local services. When a device is authorized in this way, it is known as a "trusted device".

    readonly boolean encrypted

    Is data send or received from this device encrypted.

    Note : encrypting any connection to a remote device (through the connectOptions on connect or listen) implies all data transfered between thee 2 devices is encrtypted.

    3.7. Socket

    Socket interface . 

            interface Socket  {

                readonly attribute RemoteDevice device;

                readonly attribute PendingOperation server;

                readonly attribute Stream stream;

                void close() raises(DeviceAPIError);

        };

    This interface represents a connection between the Local device and a Remote device.

    Attributes

    readonly RemoteDevice device

    The device on the other end of the connection

    readonly PendingOperation server

    The pending operation for the listen.

    This value is undefined if the socket is as a result of calling connect.

    readonly Stream stream

    The stream.

    Methods

    close

    Close the socket.

    Signature
    void close();
    Exceptions
    • DeviceAPIError:

    3.8. Stream

    Bluetooth Stream API. 

            interface Stream {

                readonly attribute boolean eof;

                readonly attribute unsigned long available;

                PendingOperation close(in SuccessCallback successCallback,
                                       in ErrorCallback          errorCallback);

                PendingOperation flush(in SuccessCallback successCallback,
                                       in ErrorCallback          errorCallback);

                ByteArray read(in unsigned long byteCount)
                        raises(DeviceAPIError);

                PendingOperation write(in SuccessCallback successCallback,
                                       in ErrorCallback          errorCallback,
                                       in ByteArray byteData)
                        raises(DeviceAPIError);

        };

    A Stream represents a handle to a connected service for read and/or write operations.

    A series of read/write methods are available that permit both binary and text to be processed.

    Once a stream is closed, any operation attempted on this stream will result in a normal JavaScript error.

    Attributes

    readonly boolean eof

    Indicates whether or not the stream has been closed.

    true if the stream was closed.

    Code example
            var stream;
        if (stream.eof) {
                // stream has been read completely
        }
    readonly unsigned long available

    Returns the number of bytes that are available for reading from the stream.

    The number of bytes available for reading is the maximum amount of bytes that can be read in the next read operation.

    -1 if eof is true.

    Code example
            alert(stream.available); // displays the available bytes to be read

    Methods

    close

    Closes this Stream.

    Signature
    PendingOperation close(in SuccessCallback successCallback, in ErrorCallback errorCallback);

    Flushes any pending buffered writes and closes the Stream. Always succeeds. Note that pending writes will not succeed.

    Parameters
    • successCallback: the success callback
    • errorCallback: the error callback
    Return value
    a pending operation, which can be used to cancel the service search
    Code example
            function errorCB(err) {
            alert("bluetooth.bondi stream close failed " + err.message);
        }

        function successCB() {
            alert("bluetooth.bondi stream closed");
        }
        // closes this stream, subsequent access to stream
        // throws exception
        stream.close(successCB, errorCB);
    flush

    Flush the stream.

    Signature
    PendingOperation flush(in SuccessCallback successCallback, in ErrorCallback errorCallback);

    Flushes any pending writes.

    Parameters
    • successCallback: the success callback
    • errorCallback: the error callback
    Return value
    a pending operation, which can be used to cancel the service search
    Code example
            function errorCB(err) {
            alert("bluetooth.bondi stream flush failed " + err.message);
        }

        function successCB() {
            alert("bluetooth.bondi stream flushed");
        }
        stream.flush(successCB, errorCB);
    read

    Reads the specified number of bytes from this Stream.

    Signature
    ByteArray read(in unsigned long byteCount);

    If 0 is supplied it will read all available bytes in a single read operation.

    Parameters
    • byteCount: number of bytes being read. If 0(default value)it will read all the available data.
    Return value
    the result of read bytes as a byte (or number) array.
    Exceptions
    • DeviceAPIError:

      IO_ERROR if an error occurs during readBytes.

    Code example
            // reads up to 256 bytes from the stream
        var raw = stream.readBytes(256);
        for (var i = 0; i < raw.length; i++) {
           // raw[i] contains the i-th byte of the current data chunk
        }
    write

    Writes the specified bytes to this Stream.

    Signature
    PendingOperation write(in SuccessCallback successCallback, in ErrorCallback errorCallback, in ByteArray byteData);
    Parameters
    • successCallback:
    • errorCallback:
    • byteData: the byte data array being written.
    Exceptions
    • DeviceAPIError:

      IO_ERROR if an error occurs during writeBytes.

    Code example
            var stream; 
        var bytes = stream.readBytes(256);
        function errorCB(err) {
            alert("bluetooth.bondi write failed " + err.message);
        }

        function successCB() {
            alert("bluetooth.bondi write completed");
        }
        // writes the bytes read from in to out
        stream.writeBytes(successCB, errorCB, bytes);

    3.9. DeviceClass 

            interface DeviceClass {
                const unsigned long SERVICE_MASK = 0xFFE000;

                const unsigned long SERVICE_POSITIONING = 0x10000;

                const unsigned long SERVICE_NETWORKING = 0x20000;

                const unsigned long SERVICE_RENDERING = 0x40000;

                const unsigned long SERVICE_CAPTURING = 0x80000;

                const unsigned long SERVICE_OBJECT_TRANSFER = 0x100000;

                const unsigned long SERVICE_AUDIO = 0x200000;

                const unsigned long SERVICE_TELEPHONY = 0x400000;

                const unsigned long SERVICE_INFORMATION = 0x800000;

                const unsigned long MAJOR_DEVICE_MASK = 0x1F00;

                const unsigned long MISCELLANEOUS_MAJOR_DEVICE = 0x000;

                const unsigned long COMPUTER_MAJOR_DEVICE = 0x100;

                const unsigned long PHONE_MAJOR_DEVICE = 0x200;

                const unsigned long NETWORKING_MAJOR_DEVICE = 0x300;

                const unsigned long AUDIO_VISUAL_MAJOR_DEVICE = 0x400;

                const unsigned long PERIPHERAL_MAJOR_DEVICE = 0x500;

                const unsigned long IMAGING_MAJOR_DEVICE = 0x600;

                const unsigned long WEARABLE_MAJOR_DEVICE = 0x700;

                const unsigned long TOY_MAJOR_DEVICE = 0x800;

                const unsigned long UNCATEGORIZED_MAJOR_DEVICE = 0x1F00;

                const unsigned long MINOR_DEVICE_MASK = 0xFC;

        };

    DeviceClass comprises of 3 components : Service Classes - The major service classes define the services available on a device, e.g. positioning , networking etc. The device can have MANY service classes, i.e. it can provide any number of services. Major Device class - A device can only have one major device class e.g. computer , phone etc. Minor Device class - the meaning of this value depends on the major device class. For example if the major device class is imaging then the minor device class then specifies whether the device is a camera, scanner, or printer etc.

    Constants

    unsigned long SERVICE_MASK

    The mask to get the Service bits.

    unsigned long SERVICE_POSITIONING

    Represents the Positioning Major Service Class.

    The value of SERVICE_POSITIONING is 0x10000 (65536).

    unsigned long SERVICE_NETWORKING

    Represents the Networking (LAN, Ad hoc, ...) Major Service Class.

    The value of SERVICE_NETWORKING is 0x20000 (131072).

    unsigned long SERVICE_RENDERING

    Represents the Rendering (Printing, Speaker, ...) Major Service Class.

    The value of SERVICE_RENDERING is 0x40000 (262144).

    unsigned long SERVICE_CAPTURING

    Represents the Capturing (Scanner, Microphone, ...) Major Service Class.

    The value of SERVICE_CAPTURING is 0x80000 (524288).

    unsigned long SERVICE_OBJECT_TRANSFER

    Represents the Object Transfer (v-Inbox, v-Folder, ...) Major Service Class.

    The value of SERVICE_OBJECT_TRANSFER is 0x100000 (1048576).

    unsigned long SERVICE_AUDIO

    Represents the Audio (Speaker, Microphone, Headset service, ...) Major Service Class.

    The value of SERVICE_AUDIO is 0x200000 (2097152).

    unsigned long SERVICE_TELEPHONY

    Represents the Telephony (Cordless telephony, Modem, Headset service, ...) Major Service Class.

    The value of SERVICE_TELEPHONY is 0x400000 (4194304).

    unsigned long SERVICE_INFORMATION

    Represents the Information (WEB-server, WAP-server, ...) Major Service Class.

    The value of the SERVICE_INFORMATION is 0x800000 (8388608).

    unsigned long MAJOR_DEVICE_MASK

    The mask to get the major device bits.

    unsigned long MISCELLANEOUS_MAJOR_DEVICE

    Represents the Miscellaneous Major Device Class.

    unsigned long COMPUTER_MAJOR_DEVICE

    Represents the Computer Major Device Class (e.g. laptop, desktop , PDA etc.).

    unsigned long PHONE_MAJOR_DEVICE

    Represents the Phone Major Device Class (e.g. cell, cordless, smart phone etc.)

    unsigned long NETWORKING_MAJOR_DEVICE

    Represents the LAN/Networking Major Device Class

    unsigned long AUDIO_VISUAL_MAJOR_DEVICE

    Represents the Audio/Visual Major Device Class (e.g headset, handsfree etc.)

    unsigned long PERIPHERAL_MAJOR_DEVICE

    Represents the Peripheral Major Device Class (e.g keyboard, mouse etc.)

    unsigned long IMAGING_MAJOR_DEVICE

    Represents the Imaging Major Device Class (e.g display, camera, scanner etc.)

    unsigned long WEARABLE_MAJOR_DEVICE

    Represents the Wearable Major Device Class (e.g wrist watch, pager, jacket etc.)

    unsigned long TOY_MAJOR_DEVICE

    Represents the Toy Major Device Class (e.g robot , vehicle, doll/action figure etc.)

    unsigned long UNCATEGORIZED_MAJOR_DEVICE

    Represents the Uncategorized Major Device Class

    unsigned long MINOR_DEVICE_MASK

    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.