---

The Bluetooth Classes

Whether you choose C or Objective-C to develop your application, it’s important to become comfortable with an object-oriented perspective of Bluetooth connections. The Bluetooth framework defines object-oriented abstractions that encapsulate all the components in a Bluetooth connection. Channels, connections, and remote devices are all represented by objects. Even if you choose to develop a Bluetooth application in C, it helps to view the various entities in the connection as objects with specific, well-defined capabilities and responsibilities. This helps you visualize a Bluetooth connection and keep track of each object’s scope of operation.

This section examines the Objective-C Bluetooth classes, describing their inheritance relationships and some of their functionality and displaying how they fit into the protocol stack. The next section, “Objects in Bluetooth Connections,” examines the objects instantiated from these classes and describes their dynamic relationships in a particular Bluetooth connection.

The Bluetooth framework contains several classes, a few of which will never be handled directly by any application. Some of the classes are base classes that provide you with useful subclasses. Others are accessible only through instances that are created by intermediate objects. Nevertheless, an understanding of the class hierarchy will give you insight into the architecture of a Bluetooth connection in Mac OS X.

Figure 2-3 shows the inheritance relationships of the Bluetooth framework classes.

As you can see in Figure 2-3, the inheritance relationships among these classes are uncomplicated. All classes in the Bluetooth framework inherit directly or indirectly from NSObject, which is the root class of most Objective-C class hierarchies. NSObject provides its subclasses with the ability to behave as objects and with a basic interface to the run-time system for the Objective-C language.

In this section:

IOBluetoothObject Class
OBEXSession Class
OBEXFileTransferServices Class
IOBluetoothUserNotification Class
Remaining Classes
Bluetooth Classes in the Mac OS X Bluetooth Protocol Stack

IOBluetoothObject Class

The classes IOBluetoothDevice, IOBluetoothL2CAPChannel, and IOBluetoothRFCOMMChannel inherit from the IOBluetoothObject class. The IOBluetoothObject class imparts the ability to respond to Bluetooth-specific events. The IOBluetoothDevice class provides instance methods to open and close baseband connections to a remote device and to get information about that connection.

Mac OS X version 10.2.5 includes fully asynchronous versions of the IOBluetoothDevice methods to open and close L2CAP and RFCOMM channels. In Objective-C, these methods rely on the instantiation of a delegate object to receive notifications of incoming data and other callbacks. A delegate object is simply an object that performs a task on behalf of another object. For example, if an Objective-C application wants to receive notifications of the state of an L2CAP channel (such as open completed or closed) it can register its object as a delegate of the associated IOBluetoothL2CAPChannel object. The application then chooses to implement the delegate methods that relay information about the state of the channel. When the state of the L2CAP channel changes, the appropriate delegate method is called, notifying the application.

Because a C or C++ application does not have access to Objective-C delegates, it registers callback functions to receive notifications of the events it’s interested in. The Bluetooth framework follows a naming convention that emphasizes the functional similarity of the delegate methods and events. For example, the Objective-C delegate method l2capChannelOpenComplete:status: is equivalent to the C event type kIOBluetoothL2CAPChannelEventTypeOpenComplete.

The IOBluetoothL2CAPChannel class and IOBluetoothRFCOMMChannel class provide methods to write data to the channels and to register for various open and close notifications. These two classes can also use a delegate as a target for data and events. Be aware that to take advantage of the benefits delegates provide, you must:

• Be running on Mac OS X version 10.2.5 or later

• Create a delegate object and register it as a client of the channel

• Implement at least the incoming data–callback method in your delegate

For more information on how to use the new asynchronous methods, see “Using Delegates to Receive Asynchronous Messages.”

OBEXSession Class

The OBEXSession class (which descends directly from NSObject) provides the methods required to manipulate an OBEX session. The OBEXSession class doesn’t inherit from IOBluetoothObject, because the particular transport on which the connection is established is immaterial to the implementation of the OBEX protocol. With some work, you could use the OBEXSession class’s methods to implement an OBEX session over a non-Bluetooth transport, such as Ethernet. The OBEXSession class is strictly concerned with the details of communicating using the OBEX protocol, regardless of the underlying transport.

The Bluetooth framework hierarchy includes one subclass of the OBEXSession class, the IOBluetoothOBEXSession class. This class provides methods to manipulate an OBEX session with a Bluetooth RFCOMM channel as the transport.

OBEXFileTransferServices Class

In Mac OS X version 10.4, Apple introduced the OBEXFileTransferServices class. Inheriting from NSObject, the new OBEXFileTransferServices class supports file-transfer operations beyond the PUT and GET primitives in the OBEX API. Using a valid IOBluetoothOBEXSession object, you create an OBEXFileTransferServices object which you can use to perform FTP or object push operations.

The OBEXFileTransferServices API includes delegate methods that correspond to the class’s connection, disconnection, and folder manipulation instance methods.

IOBluetoothUserNotification Class

The IOBluetoothUserNotification class encapsulates a user notification registered on a Mac OS X system. When your application registers for certain notifications (such as incoming channel notifications), it receives an IOBluetoothUserNotification object. The single method the IOBluetoothUserNotification class provides allows you to unregister from these notifications.

Remaining Classes

In Mac OS X version 10.4, Apple introduced the IOBluetoothDeviceInquiry class. A subclass of NSObject, the IOBluetoothDeviceInquiry class is intended for the small subset of applications that cannot use the GUI-based device-discovery API provided in the Bluetooth UI framework. Although the Bluetooth specification describes an inquiry process, there are good reasons not to implement it without restrictions (for more information on this, see “Inquiring and Paging”). The IOBluetoothDeviceInquiry class provides methods that allow applications to perform Bluetooth inquiries while enforcing limitations that ensure the best possible user experience.

The remaining classes shown in Figure 2-3 are concerned with the implementation of the service discovery protocol. Recall that information about the services a Bluetooth device offers is contained in that device’s SDP database. The SDP database comprises a set of records, each of which uses service attributes to describe the service. The IOBluetoothSDPServiceRecord class provides instance methods to get information about individual SDP service records. As its name suggests, the IOBluetoothSDPServiceAttribute class provides methods to create, initialize, and get information about the attributes of SDP service records.

The information contained in each service attribute is a value of a particular type (such as Boolean value or text string) with a particular size. A device must be prepared for the type and size of the information it receives in a service attribute, so the attributes are sent inside SDP data elements. An SDP data element is part type descriptor and part size descriptor. The IOBluetoothSDPDataElement class maps the data types described in the Bluetooth specification onto various Foundation classes. These classes include NSNumber, NSString, and NSArray, as well as the NSData subclass, IOBluetoothSDPUUID, which provides methods to represent and manipulate UUIDs. In addition, the IOBluetoothSDPDataElement class provides methods to create, initialize, and get information about the data element of each service attribute. (NSNumber, NSArray, and NSData are subclasses of NSObject; for more information on these and other Foundation classes, see the Foundation API reference at Cocoa Documentation.)

Bluetooth Classes in the Mac OS X Bluetooth Protocol Stack

The inheritance relationships pictured in Figure 2-3 display the hierarchical structure of the Bluetooth framework classes. This helps describe their spheres of influence. Figure 2-4 shows the classes that applications can use (in addition to the IOBluetoothHCIController class you can subclass to support Bluetooth over an alternate transport) and how they fit into the protocol stack.

The next section describes the objects that are instantiated from these classes (with the exception of the IOBluetoothHCIController class) and how they work together to represent a connection to a remote Bluetooth device.

---