Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

81    Bluetooth Library: General Functions

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

The Bluetooth library is a shared library that provides a direct interface to the Bluetooth communication capability of the Palm OS. This chapter presents reference material for the security and utility functions of the Bluetooth library API:

Security Functions
Describes security functions that allow the application to manage a database of trusted devices. Trusted devices don't need to undergo authentication when they reconnect with the local device.
Utility Functions
Describes utility functions and macros that are useful when working with the Bluetooth library. They perform such tasks as converting between host and network byte ordering, and converting between device addresses and strings.

The header file BtLib.h declares the Bluetooth library functions and macros. The header file BtLibTypes.h declares the data structures that you use with those functions and macros. For more information about using the Bluetooth library, see the Palm OS Programmer's Companion Supplement: Bluetooth.

Security Functions ^TOP^

The Bluetooth security functions allow the application to manage a database of devices that have been bonded or paired. To understand this database, it is important to understand the difference between pairing and bonding.

Typically, devices must authenticate with each other every time they connect to each other. This process is called pairing. However, the devices can bond instead. Bonding is similar to pairing except that both devices remember the link key for the connection. If the two devices ever want to connect to each other again, they don't need to repeat the pairing process.

Information about paired and bonded devices is stored in a device database on the local device. If a remote device has bonded with the local device, its record remains in the database until it is explicitly deleted. If the remote device has paired with the local device but not bonded with it, the record is removed when the connection to the remote device terminates.

Remote devices that have bonded with the local device are also called trusted devices.

BtLibSecurityFindTrustedDeviceRecord Function ^TOP^

Purpose

Search the device database for the device with the specified Bluetooth address. Return the index of the corresponding device record in the database.

Declared In

BtLib.h

Prototype

Err BtLibSecurityFindTrustedDeviceRecord (
   UInt16btLibRefNum,
   BtLibDeviceAddressTypePtraddrP,
   UInt16*index
)

Parameters

btLibRefNum
Reference number for the Bluetooth library.
addrP
Bluetooth address of remote device.
index
Index of the record.

Returns

Returns btLibErrNoError if successful. Returns btLibErrNotFound if a record with the specified remote device address could not be found.

See Also

BtLibSecurityRemoveTrustedDevice Record(), BtLibSecurityGetTrustedDeviceRecordInfo()

BtLibSecurityGetTrustedDeviceRecordInfo Function ^TOP^

Purpose

Get information from a device record in the device database.

Declared In

BtLib.h

Prototype

Err BtLibSecurityGetTrustedDeviceRecordInfo(
   UInt16btLibRefNum,
   UInt16index,
   BtLibDeviceAddressTypePtraddrP,
   Char*nameBuffer,
   UInt8*nameBufferSize,
   BtLibClassOfDeviceType*cod,
   Boolean*persistent
)

Parameters

btLibRefNum
Reference number for the Bluetooth library.
index
Index of the record.
addrP
Bluetooth address of remote device.
nameBuffer
Pointer to buffer to store user-friendly name of remote device. You must allocate this buffer. Provide a NULL pointer if the user-friendly name is not needed.
nameBufferSize
Size of the nameBuffer buffer on entry. On exit, the size of the name.
cod
Pointer to a BtLibClassOfDeviceType representing the class of the device. You must allocate this structure. Provide a NULL pointer if the device class is not needed.
lastConnected
The date since the device last connected. This date is measured in seconds since midnight January 1, 1904. Provide a NULL pointer if the date of last connection is not needed.
persistent
If true, the device is bonded and can connect to the local device without authentication. If false, the device is paired but not bonded—it will need to reauthenticate if it connects again. Provide a NULL pointer if this information is not needed.

Returns

Returns btLibErrNoError if successful. Returns dmErrIndexOutOfRange if a record with the specified index could not be found.

See Also

BtLibSecurityFindTrustedDeviceRecord()

BtLibSecurityNumTrustedDeviceRecords Function ^TOP^

Purpose

Return the number of bonded devices in the device database or return the total number of devices in the device database.

Declared In

BtLib.h

Prototype

UInt16 BtLibSecurityNumTrustedDeviceRecords (
   UInt16btLibRefNum,
   BooleanpersistentOnly
) 

Parameters

btLibRefNum
Reference number for the Bluetooth library.
persistentOnly
true to obtain the total number of bonded devices in the database. These are the same devices that appear in the trusted devices list. false to obtain the total number of devices in the device database. This includes the devices that are bonded and the devices that are paired but not bonded.

Returns

Returns the requested number of device records.

See Also

BtLibSecurityFindTrustedDeviceRecord(), BtLibSecurityGetTrustedDeviceRecordInfo()

BtLibSecurityRemoveTrustedDevice Record Function ^TOP^

Purpose

Remove a device record from the device database.

Declared In

BtLib.h

Prototype

Err BtLibSecurityRemoveTrustedDeviceRecord (
   UInt16btLibRefNum,
   UInt16index
)

Parameters

btLibRefNum
Reference number for the Bluetooth library.
index
Index of the record to remove.

Returns

Returns btLibErrNoError if successful. Returns dmErrIndexOutOfRange if a record with the specified index could not be found.

See Also

BtLibSecurityFindTrustedDeviceRecord()

Utility Functions ^TOP^

This section describes functions and macros that are useful when working with the Bluetooth library.

BtLibAddrAToBtd Function ^TOP^

Purpose

Convert an ASCII string a Bluetooth device address in colon-separated form to a 48-bit BtLibDeviceAddressType.

Declared In

BtLib.h

Prototype

Err BtLibAddrAToBtd (
   UInt16btLibRefNum,
   constChar*addressString,
   BtLibDeviceAddressType*btDevP
)

Parameters

btLibRefNum
Reference number for the Bluetooth library.
addressString
String containing ASCII colon-separated Bluetooth device address.
btDevP
Pointer to a BtLibDeviceAddressType to store the converted device address.

Returns

Returns btLibErrNoError to indicate that the conversion was successful.

See Also

BtLibAddrBtdToA()

BtLibAddrBtdToA Function ^TOP^

Purpose

Convert 48-bit BtLibDeviceAddressType to an ASCII string in colon-separated form.

Declared In

BtLib.h

Prototype

Err BtLibAddrBtdToA (
   UInt16btLibRefNum,
   BtLibDeviceAddressType*btDevP,
   Char*spaceP,
   UInt16spaceSize
)

Parameters

btLibRefNum
Reference number for the Bluetooth library.
btDevP
Address of a Bluetooth device. This parameter must not be NULL.
spaceP
Pointer to a buffer to store the ASCII formatted Bluetooth devices address upon return. This parameter must not be NULL.
spaceSize
Size of the spaceP buffer, in bytes. Must be at least 18.

Returns

Returns btLibErrNoError if successful. Returns btLibErrParamErr if

  • btDevP is NULL
  • spaceP is NULL
  • spaceSize is less than 18, the number of bytes required to store the ASCII formatted address

See Also

BtLibAddrAToBtd()

BtLibL2CapHToNL Macro ^TOP^

Purpose

Converts a 32-bit value from host to L2CAP byte order. L2CAP byte order is little endian.

Declared In

BtLib.h

Prototype

#define BtLibL2CapHToNL (
   value
)

Parameters

value
32-bit value to convert.

Returns

Returns value in L2CAP byte order.

See Also

BtLibL2CapHToNS(), BtLibL2CapNToHL(), BtLibL2CapNToHS()

BtLibL2CapHToNS Macro ^TOP^

Purpose

Converts a 16-bit value from host to L2CAP byte order. L2CAP byte order is little endian.

Declared In

BtLib.h

Prototype

#define BtLibL2CapHToNS (
   value
)

Parameters

value
16-bit value to convert.

Returns

Returns value in L2CAP byte order.

See Also

BtLibL2CapHToNL(), BtLibL2CapNToHS(), BtLibSdpNToHL()

BtLibL2CapNToHL Macro ^TOP^

Purpose

Converts a 32-bit value from L2CAP to host byte order. L2CAP byte order is little endian.

Declared In

BtLib.h

Prototype

#define BtLibL2CapNToHL (
   value
)

Parameters

value
32-bit value to convert.

Returns

Returns value in host byte order.

See Also

BtLibL2CapNToHS(), BtLibL2CapHToNL(), BtLibL2CapHToNS()

BtLibL2CapNToHS Macro ^TOP^

Purpose

Converts a 16-bit value from L2CAP to host byte order. L2CAP byte order is little endian.

Declared In

BtLib.h

Prototype

#define BtLibL2CapNToHS (
   value
)

Parameters

value
16-bit value to convert.

Returns

Returns value in host byte order.

See Also

BtLibL2CapNToHL(), BtLibL2CapHToNS(), BtLibL2CapHToNL()

BtLibRfCommHToNL Macro ^TOP^

Purpose

Converts a 32-bit value from host to RFCOMM byte order. RFCOMM byte order is big endian.

Declared In

BtLib.h

Prototype

#define BtLibRfCommHToNL (
   value
)

Parameters

value
32-bit value to convertx

Returns

Returns value in RFCOMM byte order.

See Also

BtLibRfCommHToNS(), BtLibRfCommNToHL(), BtLibRfCommNToHS()

BtLibRfCommHToNS Macro ^TOP^

Purpose

Converts a 16-bit value from host to RFCOMM byte order. RFCOMM byte order is big endian.

Declared In

BtLib.h

Prototype

#define BtLibRfCommHToNS (
   value
)

Parameters

value
16-bit value to convertx

Returns

Returns value in RFCOMM byte order.

See Also

BtLibRfCommHToNL(), BtLibRfCommHToNS(), BtLibRfCommNToHL()

BtLibRfCommNToHL Macro ^TOP^

Purpose

Converts a 32-bit value from RFCOMM to host byte order. RFCOMM byte order is big endian.

Declared In

BtLib.h

Prototype

#define BtLibRfCommNToHL (
   value
)

Parameters

value
32-bit value to convertx

Returns

Returns value in host byte order.

See Also

BtLibRfCommNToHS(), BtLibRfCommHToNL(), BtLibRfCommHToNS()

BtLibRfCommNToHS Macro ^TOP^

Purpose

Converts a 16-bit value from RFCOMM to host byte order. RFCOMM byte order is big endian.

Declared In

BtLib.h

Prototype

#define BtLibRfCommNToHS (
   value
)

Parameters

value
16-bit value to convertx

Returns

Returns value in host byte order.

See Also

BtLibRfCommNToHL(), BtLibRfCommHToNS(), BtLibRfCommHToNL()

BtLibSdpHToNL Macro ^TOP^

Purpose

Converts a 32-bit value from host to Service Discovery Protocol (SDP) byte order. SDP byte order is big endian.

Declared In

BtLib.h

Prototype

#define BtLibSdpHToNL (
   value
)

Parameters

value
32-bit value to convertx

Returns

Returns value in SDP byte order.

See Also

BtLibSdpHToNS(), BtLibSdpNToHL(), BtLibSdpNToHS()

BtLibSdpHToNS Macro ^TOP^

Purpose

Converts a 16-bit value from host to Service Discovery Protocol (SDP) byte order. SDP byte order is big endian.

Declared In

BtLib.h

Prototype

#define BtLibSdpHToNS (
   value
)

Parameters

value
16-bit value to convertx

Returns

Returns value in SDP byte order.

See Also

BtLibSdpHToNL(), BtLibSdpNToHS(), BtLibSdpNToHL()

BtLibSdpNToHL Macro ^TOP^

Purpose

Converts a 32-bit value from Service Discovery Protocol (SDP) to host byte order. SDP byte order is big endian.

Declared In

BtLib.h

Prototype

#define BtLibSdpNToHL (
   value
)

Parameters

value
32-bit value to convertx

Returns

Returns value in host byte order.

See Also

BtLibSdpNToHS(), BtLibSdpHToNL(), BtLibSdpHToNS()

BtLibSdpNToHS Macro ^TOP^

Purpose

Converts a 16-bit value from Service Discovery Protocol (SDP) to host byte order. SDP byte order is big endian.

Declared In

BtLib.h

Prototype

#define BtLibSdpNToHS (
   value
)

Parameters

value
16-bit value to convertx

Returns

Returns value in host byte order.

See Also

BtLibSdpNToHL(), BtLibSdpHToNS(), BtLibSdpHToNL()