Home > Language Reference > Classes

Bluetooth Class

  + Object
    + Bluetooth

Description

The Bluetooth class encapsulates methods and properties you can use for general Bluetooth management, such as discovering devices in the neighborhood, or retrieving the local device name. This class is instanciable, but can neither be derived nor duplicated.

Using the Bluetooth class

Instantiating a Bluetooth object on a device that does not have a Bluetooth support causes a runtime error to occur. To prevent the default, unfriendly error message to be displayed, it is advised to instantiates this class from a function protected by an error handler. For example, you could write in a module:

Public gBT As Bluetooth

Public Function IsBluetoothSupported() As Boolean
  Try
    Set gBT = New Bluetooth
    IsBluetoothSupported=True
  Catch
    MsgBox "No Bluetooth support found!"
  End Catch
End Function

In your main application class, you can then write:

Private Sub Application_NormalLaunch()
  Dim f As New frmMain

  If Not IsBluetoothSupported() Then Exit Sub
  f.Show hbFormModeless+hbFormGoto
End Sub

The global variable gBT is then accessible from your whole project, and can be used wherever you need to call a method of the Bluetooth class. A noticeable exception is when you have to handle events raised by the object, which is impossible here, since the gBT variable is declared in a module. A simple workaround is to create a new local instance of the Bluetooth class. For example, you could write on a form:

Private bt As New Bluetooth ' This can't fail, as the IsBluetoothSupported function already succeeded

Private Sub bt_NameResult(ByVal sName As String, ByVal lParam As Long)
  MsgBox sName ' Process a Bluetooth event
End Sub

You can create as many instances of the Bluetooth class as necessary. However, most applications will never need to catch events, and will only require one single global instance, as shown above.

Device addresses

Each Bluetooth device is uniquely identified by its 48-bit address, much like Ethernet cards are. As HB++ does not offer a basic type to handle 48-bit integers, it encapsulates those addresses into a Double. Technically, the two most significant bytes (sign and exposant) are set to a value that represents 1.0, while the six less significant bytes (the mantissa) store the address. Thus, a valid Bluetooth address is represented by a Double value lying between 1.0 inclusive and 2.0 exclusive.

You will typically consider those values as opaque. Notably, you should not present such a value to the user, as it is meaningless. Instead, you will convert it into a standard Bluetooth address, ie 6 hexadecimal bytes colon separated, by using the AddressToString function. The StringToAddress function is also available to achieve the opposite conversion.

Basic operations

The DiscoverSingleDevice and DiscoverMultipleDevices functions scan the neighborhood to discover remote devices, resolve their friendly names, and present them into a dialog box allowing the user to pick one or more. The addresses of the selected devices are then returned as a Double or a Collection of Double values. Once you get a device address, you can establish a Bluetooth connection to this device using the StreamBluetooth object.

You can also determine the various characteristics of the local device through the CurrentAccessible, UnconnectedAccessible, LocalClassOfDevice, and LocalName properties. Note that only the system can change those characteristics, which is why these properties are read-only.

The BtChat sample is a simplistic chat application that shows how to implement those basic Bluetooth operations.

Piconets

By default, Palm OS^® only permits peer-to-peer connections through the StreamBluetooth class. To allow multiple slave devices to connect to a master device, you'll have to create a piconet. A piconet can contain up to 8 devices, ie 7 slaves and 1 master. Creating and destroying a piconet is achieved by respectively calling the CreatePiconet and DestroyPiconet methods.

Once a piconet is successfully created, the master can either scan devices in the neighborhood and establish outbounds connections, or either let remote devices establish inbounds connections. The master can also lock the piconet to disable inbounds connections, by calling the LockInbound method.

The BtWhiteboard sample shows how to use a piconet to implement a whiteboard application.

Members

System requirements