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 (
   UInt16 btLibRefNum,
   BtLibDeviceAddressTypePtr addrP,
   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(
   UInt16 btLibRefNum,
   UInt16 index,
   BtLibDeviceAddressTypePtr addrP,
   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 (
   UInt16 btLibRefNum,
   Boolean persistentOnly
)

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 (
   UInt16 btLibRefNum,
   UInt16 index
)

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 (
   UInt16 btLibRefNum,
   const Char *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 (
   UInt16 btLibRefNum,
   BtLibDeviceAddressType *btDevP,
   Char *spaceP,
   UInt16 spaceSize
)

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()

 
   

Copyright © 1996-2004, PalmSource, Inc. and its affiliates. All rights reserved.
Write Us | Training | Knowledge Base | Legal


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