This high-level form of defining a Bluetooth device identifies where in the Service Class field the OBEX-based Profile resides (see Table 11-6) which, in turn, determines the category of service. Here, the category of service falls within Object Transfer.

This high-level form of defining a Bluetooth device identifies where in the Major Device Class the category of device supporting the OBEX-based Profile resides (see Table 11-7). Here, the various categories of devices that may support the OBEX-based Profile are shown.

The Minor Device Class in this profile is used to convey further context for the setting within the major class grouping (see Table 11-8). Here, the bit may be set appropriately for Notebook, Handheld PDA or Palm-sized PDA to denote the type of device supporting the OBEX-based Profile. Further categorisation can also be provided for a Phone.

The OBEX specification provides a formal representation to achieve data object exchange between devices, using what is called an Object Model. This formal representation includes the provision of a Session Protocol, which is used to structure the nature of any communication and is based upon a format that includes a request-response client-server concept. Communication is transported through connection-orientated channels available through RFCOMM and L2CAP; the connectionless-specific transfer would impose interoperability issues between devices.

In our first detailed examination of the OBEX protocol, we look at the structure of the object model, which is used to represent data objects in OBEX. In Figure 11-7, we can see the object encompassing a Header ID followed by a number of Header Values. The HeaderID is made up of one byte and is further broken down into a two-bit and a six-bit segment. The purpose of such a structure is to provide a descriptive meaning to the objects being transferred and to carry the object itself. The two-bit segment is used to identify the type of encoding, whereas the six-bit segment is used to identify the header meaning.

Figure 11-7. The structure of the object model.

In Table 11-9, we show the six-bit segment format that is used in conjunction with Table 11-11; the table describes the header types that are available. The values presented in Table 11-11 provide a known set of header values that can be used for most applications. However, the header value range 0x30 to 0x3F are reserved for user or implementation-specific use. The range should accommodate the upper six bits of the HeaderID value; any user-defined header value must also accommodate the lower two-bit encoding method as shown in Table 11-10.

In establishing the object model, we turn our attention to the session protocol, which forms the request-response nature of exchanging OBEX objects between two devices. In simple terms, the client requests and the server responds; this essentially forms what is called the conversational format between two devices. In Figure 11-8, we can identify an OpCode, which is used to denote the type of request being sent to the server; this is followed by the two-byte Packet Length. You should further note in Figure 11-8 that the header information may also be included (see Figure 11-7); this, of course, depends upon the type of operation that is being requested.

Figure 11-8. The structure of the request packet contains the header parameters of our original object model.

When managing multi-packets during a request operation, it is the high-order bit in the OpCode that is used to denote the final packet and is referred to as the final bit.

One such example is with the PUT operation, where the object may need to be carried over several packets; however, the GET operation is a function that may require multiple responses. Here, the server will indicate to the client that it needs to continue; this is gleaned from the response packet and we will cover this in more detail shortly. In the meantime, Table 11-12 provides a summary of the operations that are available as function primitives.

We now turn our attention to the format of a response. In Figure 11-9, we can identify a Response Code, which is used to denote the type of response being returned to the client, followed by the two-byte Packet Length.

Figure 11-9. The structure of the request packet contains the header parameters of our original object model.

When managing multi-packets during a response operation, it is the high-order bit in the ResponseCode that is used to denote the final packet and is also referred to as the final bit. If you recall from our earlier example, the GET operation may require a number of packets to be retrieved from the server to fulfil the original request. The server indicates to the client, by setting the final bit in the ResponseCode, that several GET operations need to be performed before receiving the final packet. The final bit is also used to inform the client that the server is now ready to receive a new request, but how do we distinguish between more packets and a new operation? It is the ResponseCode type that is used to determine what the client should do. In our GET operation example, the final bit would be set and the value of the Response Code would be 0x10, indicating Continue (remember the final bit will be set so that the translated value will be 0x90). A further Response Code of 0x20 (remember that the final bit will be set so our translated value here will be 0xA0), indicates Success. The final bit being set would then appropriately inform the client that it can now continue with a new operation. See IrDA OBEX for a full definition of the response codes.

We have introduced the Object Model and the Session Protocol; in the following sections we consider the implementation of a basic set of APIs that are capable of fulfilling genuine functions for our applications. More specifically, we look at how these operations are constructed to enable their intended function. In later sections, we will discuss how OBEX supports the RFCOMM and TCP/IP transport models (see Section 11.3.1.2.8, OBEX over RFCOMM and Section 11.3.1.2.9, OBEX over TCP/IP).

Having established our functional primitives, we can now turn our attention to the APIs, as shown in Table 11-13. Here, we have a basic set of functions that are capable of being exposed at the upper-edge of our OBEX component; these functions are ready for integration with a chosen OBEX application.

In the following sections, we examine some of the typical functions that we may come across when implementing our OBEX-specific APIs. As such, the OBEX_Connect, OBEX_Disconnect, OBEX_Put, OBEX_Get and OBEX_SetPath will be discussed.

In our first examination, the OBEX_ Connect function, we look at how the Connect operation is encapsulated within the request packet (see Figure 11-10).

Figure 11-10. The structure of a Connect request packet.

The Connect request packet is constructed and then used to establish a new OBEX session. Conversely, its response is shown in Figure 11-11; this will be parsed ^[6] to ascertain appropriate instructions by the client device. Let us take a closer look at the parameters that make up these two packets. Our OpCode, shown as 0x80 in Figure 11-10, always has the final bit set, since it is always communicated in one packet transaction. In our response, we indicate 0xA0 as our response code, since we are assuming a successful operation and again the final bit is set, indicating to the client that the server is ready to receive a new request. The PacketLength will accurately reflect the packet size in its entirety, whereas the OBEXVersion reflects the current IrDA OBEX specification (that is, Version 1.2). The FLAGS parameter has the default value of zero and is always ignored by the server. Finally, the OBEX PacketLength reflects the maximum packet size capable of being transferred, which is currently 64 KB (less one).

Figure 11-11. The structure of a Connect response packet.

We have established an OBEX session and naturally we would wish to disconnect it at some point. As such, the OBEX_ Disconnect function will enable us to disconnect our established session. In Figure 11-12, we provide the structure of a Disconnect operation and how it is encapsulated within the request packet.

Figure 11-12. The structure of a Disconnect request packet.

Conversely, its response is shown in Figure 11-13; this will be parsed to ascertain appropriate instructions by the client device. Let us take a closer look at the parameters that make up these two packets. Our OpCode, shown as 0x81 in Figure 11-12, always has the final bit set. It is always communicated in one packet transaction, which informs the server that it is ready to receive its response.

Figure 11-13. The structure of a Disconnect response packet.

In our response, we indicate 0xA0 as our ResponseCode; note that we are assuming a successful operation and that the final bit is set, indicating to the client that the server is ready to receive a new request. The PacketLength will accurately reflect the packet size in its entirety.

The physical data transfer of objects is achieved through the use of OBEX_Put and OBEX_Get. In this section, we will consider the transfer of data from the client to the server. In Figure 11-14 and Figure 11-15 we provide the structure of a Put operation and how it is encapsulated within the request packet.

Figure 11-14. The structure of a Put request packet indicating that there is more data to be transferred.

Figure 11-15. The structure of a Put request packet, which indicates that the final packet has been sent and that the client is now ready to receive a response.

Conversely, its potential responses are shown in Figure 11-16 and Figure 11-17; subsequently, it will be parsed to ascertain an appropriate action by the client device. Let us take a closer look at the parameters that make up these two packets. Our OpCode, shown as 0x02 in Figure 11-14, does not have the final bit set. The client has a large amount of data to transfer and, as such, several packets will be required to transfer its payload. However, in Figure 11-15, the OpCode is shown as 0x82, which indicates to the server that it has now sent the final packet. It sets the final bit of the OpCode and is now ready to send a new request.

Figure 11-16. The structure of a Put response packet, indicating to the client that it may continue to transfer the data.

Figure 11-17. The structure of a Put response packet, indicating to the client that its Put operation has been completed successfully.

There are two possible responses during the course of this request. In the first, we may receive a ResponseCode of 0x90, which indicates a Continue as a result of the client indicating an OpCode of 0x02. If our OpCode does not have the final bit set and we are indicting to the server we have more data to transfer, then its response is Continue (see Figure 11-16). In our second indication, see Figure 11-17, we receive 0xA0 in our ResponseCode. This informs us that the data transfer was Successful on the basis that we sent the last packet and indicated as such with the OpCode of 0x82. Once we have received a successful indication, the client can then begin to send a new request. The PacketLength will accurately reflect the packet size in its entirety.

We will now consider the transfer of data from the server to the client. In Figure 11-18 and Figure 11-19, we provide the structure of a Get operation and how it is encapsulated within the request packet.

Figure 11-18. The structure of a Get request packet, indicating that there is more data to be retrieved as implied by the ResponseCode 0x90 (Continue).

Figure 11-19. The structure of a Get request packet, indicating that the final packet has been collected as implied by the ResponseCode 0xA0 (Successful).

Conversely, its potential responses are shown in Figure 11-20 and Figure 11-21; it will be subsequently parsed to ascertain an appropriate action by the client device. Let us take a closer look at the parameters that make up these two packets. Our OpCode, shown as 0x03 in Figure 11-18, does not have the final bit set. The client has a large amount of data to collect and, as such, several packets will be retrieved to complete its payload. This is implied in the ResponseCode of 0x90, which indicates Continue. However, in Figure 11-19 the OpCode is shown as 0x83, which now indicates to the server that it has retrieved the final packet and sets the final bit of the OpCode; it is now ready to send a new request. This is implied in the ResponseCode of 0xA0, which indicates that the request has been Successful.

Figure 11-20. The structure of a Put response packet, indicating to the client that it may continue to transfer the data.

Figure 11-21. The structure of a Put response packet, indicating to the client that its Put operation has been completed successfully.

We have two possible responses during the course of this request. In the first, we may receive a ResponseCode of 0x90, which indicates a Continue as a result of the client indicating an OpCode of 0x03. If our OpCode does not have the final bit set and we are indicating to the server that we have more data to collect, then its response is Continue (see Figure 11-20). In our second indication, see Figure 11-21, we receive 0xA0 in our ResponseCode; this informs us that the data transfer was Successful on the basis that we sent the last packet and indicated as such with the OpCode of 0x83. Once we have received a successful indication, the client can then begin to send a new request. The PacketLength will accurately reflect the packet size in its entirety.

During the transfer of data to and from the client, a specific location may be required to place the data in the directory ^[7] of the device. The OBEX_SetPath function is capable of performing such an operation and we can look specifically at how the SetPath operation is encapsulated within the request packet, as shown in Figure 11-20.

The SetPath request packet is constructed and then used to locate an area within the server’s file structure. Conversely, its response is shown in Figure 11-23; subsequently, it will be parsed to ascertain an appropriate action by the client device. Let us take a closer look at the parameters that make up these two packets. Our OpCode, shown as 0x85 in Figure 11-22, always has the final bit set since it is always communicated in one packet transaction.

Figure 11-22. The structure of a SetPath request packet.

Figure 11-23. The structure of a SetPath response packet.

In our response, we indicate 0xA0 as our response code, since we are assuming a successful operation and, again, the final bit is set, indicating to the client that the server is ready to receive a new request. The PacketLength will accurately reflect the packet size in its entirety, whereas the FLAGS parameter always has the default value of zero and is always ignored by the server. The CONSTANTS parameter is not used and is reserved for future use.

RFCOMM has been discussed extensively in the Serial Port Profile, Chapter 6. You may remember that RFCOMM provides serial port emulation and is capable of supporting multiple connections. The OBEX protocol has been designed to support RFCOMM, where a server must be capable of supporting several simultaneous connections. These connections must be registered in the Service Discovery Database, which we discussed in some detail in the Service Discovery Application Profile, Chapter 3. We will learn more of the dependencies of the GOEP as we move forward into the relevant sections later on in this chapter.

There are several assumptions that are made when a client issues a Connect request to the server. In the first assumption, we assume that the client is capable of connecting to the server on the basis that it has learned of the RFCOMM channel number from the Service Discovery Database. The second assumption is that the client then initiates the connection to the server, where it is awaiting a connection from the client.

The nature of RFCOMM dictates that it receives data as a byte stream and, as such, the data is collected and sent a byte at a time, using the Get and Put operations. The OBEX-parsing module of the OBEX component will await and identify an OpCode or ResponseCode, depending on the type of data it is expecting to receive. How will the parser know the end of the payload? You may remember that request and response packets have a PacketLength parameter, which informs us of the size of the payload in its entirety. As such, once the OpCode or ResponseCode is received, we know that the following two bytes represent the PacketLength. To disconnect from the server, the client issues the Disconnect-request packet, where the RFCOMM channel is subsequently closed.

We have come across TCP/IP in earlier chapters, but why does this protocol exist within the OBEX transport mechanism? One fundamental reason for using TCP/IP is the inherent reliability that is achieved by using this protocol; it should not be confused with any networking-related association.

The implementation to use TCP/IP as a mode of transport becomes further complicated. In Table 11-12, we illustrated a series of APIs that can be exposed to our OBEX-specific application. Within our OBEX component, we have to further manage the removal of several layers of encapsulation to retrieve the request or response packet enclosed within the TCP/IP structure (see RFC791 and RFC793). Again, the OBEX protocol has been designed to support TCP/IP, where a server must be capable of supporting several simultaneous connections. These connections must be registered in the Service Discovery Database, which we discussed in some detail in the Service Discovery Application Profile, Chapter 3.

There are several assumptions that are made when a client issues a Connect request to the server. First, we assume that the client is capable of connecting to the server. Since it has learned of the TCP port ^[8] number, the client subsequently initialises a socket. ^[9] Secondly, we assume that the client then initiates the connection to the server, where it is awaiting a connection from the client.

Data is sent and retrieved using the Put and Get request operations. The OBEX-parsing component of your application will await and identify an OpCode or ResponseCode, depending on the type of data it is expecting to receive. To disconnect from the server, the client issues the Disconnect-request packet, where the TCP port is subsequently closed.

Prior to establishing an OBEX session, authentication must occur. An OBEX password may be required and can match the Bluetooth Passkey ^[10] for convenience; this itself reduces user complexity. Further convenience can be provided for the user as both the client and server may store the passkey for future ad-hoc connections.

As a minimum, GOEP must be able to support OBEX without authentication, but if it is requested, then support for the authentication challenge should be provided; we discuss this in Section 11.3.1.3.2, OBEX Connection with Authentication. In Figure 11-24, we provide a series of events that lead up to the establishment of an OBEX session with a server. In Table 11-14, we provide a list of mandatory fields that make up our request packets and provide further information with regard to their usage within the structure.

Figure 11-24. The sequence of events that are used to create a successful connection with the server.

As you know, the Connect request is used to establish the OBEX session and the Target header is used to identify the targeted service; in some OBEX-specific profiles, this header is mandatory. The Target header is used to identify the intended service; for instance, IrMC-SYNC may be indicated to identify the synchronisation service. The Connect response message is shown in Table 11-15; it is the expected response, where the ResponseCode will indicate 0xA0 if the transfer was successful. The ConnectionID and Who headers must be used if the Target header was used in the original Connect request.

In our previous section, we provided the scenario and features that are required to establish an OBEX session without authentication. This section now discusses the features expected from the OBEX protocol when authentication is required. This new authentication procedure is an additional requirement above the Bluetooth specific authentication process, that is, a Bluetooth Passkey is used to instigate the pairing process. The OBEX authentication is used to establish a trusted relationship at the client and server level, where it is the server that will initiate the challenge. The server is unable to commit to an OBEX session, until the authentication features are fully adhered to; in Figure 11-25, we illustrate the sequence of events that are used to establish this relationship. In the first instance of sending a Connect request, the client is unaware that authentication is required and, as such, it sends a request in the usual manner. The fields have been illustrated in Table 11-14.

Figure 11-25. The sequence of events that are used to create a successful authenticated connection with the server.

The client learns of the news when it receives the response from the server. When we look more closely at the fields used in our Connect response (as shown in Table 11-16), we notice that the AuthenticationChallenge header is used. Furthermore, when the client parses the ResponseCode, it will learn of the value 0x41 Unauthorised; this notifies the client that it must send a new Connect request with the AuthenticationChallenge and AuthenticationResponse headers (as shown in Table 11-17); these headers carry the digest-challenge string and digest-response strings, respectively.

The fields and headers used in the second response are shown in Table 11-18. If the ResponseCode contains the value 0xA0 from the server, then authentication has been successful and the OBEX session can now be established.

At some point, a disconnection of the established OBEX session will be terminated, which may be due to a user request or a loss of connection. The session is terminated using the Disconnect operation, where the OpCode has the value 0x81. In Table 11-19, we show the remaining fields that are used during this operation.

The Disconnect response message is shown in Table 11-20. The ResponseCode will indicate 0xA0 if the disconnection was successful; this operation is not refused by the server.

Data is transferred to the server using the Put request, where the OpCode may indicate 0x02, for multiple packets and 0x82 to indicate that it has sent the last packet. The features used for this transaction are identified in Table 11-21, where the ConnectionID is mandatory if the Target header was used in the original Connect request.

The Name header is used to identify the object being transferred and the Body/ End of Body headers are used to identify the start and end of the object being transferred. In Table 11-22, we identify the features that are required in the Put response, where the ResponseCode may indicate 0x90 for continue in response to the Put OpCode 0x02 or 0xA0 for successful in response to the Put OpCode for successful completion of the transfer.

Data is transferred from the server using the Get request, where the OpCode may indicate 0x03, for multiple packets and 0x83 to indicate that it has retrieved the last packet. The features used for this transaction are identified in Table 11-21, where the ConnectionID is mandatory if the Target header was used in the original Connect request.

The Name header is used to identify the object being transferred and the Type header is used to identify the type of object being pulled. In Table 11-22, we identify the features that are required in the Get response, where the ResponseCode may indicate 0x90 for continue in response to the Get OpCode 0x03 or 0xA0 for successful in response to the Get OpCode for successful completion of the transfer. The Name header is used to identify the object being transferred and the Body/End of Body headers are used to identify the start and end of the object being pulled.

A physical location on the server can be sought using the SetPath request, where the OpCode will indicate 0x85 and the Name header is used to contain the path name. The initial reference used by the server is the root directory. On the basis of this location, the server will reference down into the hierarchy to obtain the new location. For example, if the client requests My Documents in the Name header, it will effectively locate C:My Documents, on a typical Microsoft Windows based operating system or similar.

The FLAGS parameter is used to denote the type of action to be applied in locating the new directory; for example, where bit 0 is set to indicate that the directory needs to be moved up one level before applying the Name header. This is equivalent to .. on a Microsoft Windows environment or ../ on a Unix environment. Setting bit 1 recommends to the system that it should not create a directory if it already exists; otherwise an error must be reported to the user. The Constant parameter is not used and is reserved for future use.

In the request-response packets for the SetPath operation, the final bit is always set since this transaction is made in one packet. In Table 11-24, we identify the features that are required in the SetPath response, where the ResponseCode may indicate 0xA0 for a successful operation. A ResponseCode of 0xC4 informs the client that the folder does not exist and a 0xC1 informs the client that folder browsing is not allowed.

In Table 11-27, we have identified that Connection-Orientated Channels are mandatory, whereas Connectionless Channels are excluded; this type of channel is aimed at broadcasting, where all devices may be targeted. L2CAP uses Protocol Data Units (PDUs) to transport connection, signalling and configuration options, which will be discussed in a moment. The higher-layers of the Bluetooth protocol stack will instigate a connection with L2CAP using the L2CA_ConnectReq request packet, where the corresponding result is contained within the L2CA_ConnectRsp response packet. An L2CA_ConnectRspNeg negative response packet is used to denote a response, where the connection with the remote device was unsuccessful. Since our profile resides above L2CAP and employs its services, we are only concerned with the upper protocol layer of L2CAP. This higher functionality is offered to us through a series of L2CAP events and is denoted through the prefix L2CA_ (see Table 11-28).

When creating an L2CAP connection between two devices, a Protocol/Service Multiplexor (PSM) value is used to denote the higher-layer protocol that is using the connection. Table 11-29 identifies these values and the corresponding protocol they represent. The value of 0x0003 (RFCOMM) is used for this profile.

When establishing communication with a remote device, a signalling channel is created and reserved for use during connection, disconnection and configuration of subsequent L2CAP connections. A channel is used to describe the communication and data flow that exists between L2CAP entities and Table 11-30 illustrates the range of CIDs that are used to identify the channel type. As we can see in Table 11-27, Connection Establishment and Termination is mandatory in the local device, although the remote device may be capable of initiating and terminating a connection to the local device. The L2CA_DisconnectReq request packet is used to terminate the connection with the remote device and an L2CA_DisconnectRsp response packet is used to ascertain the result of the termination. All disconnection requests must be completed successfully. The support of Configuration is shown as mandatory and we will discuss these specific options in more detail in the following section. Finally, Echo and Command Rejection are both mandatory for a compliant GOEP.

In establishing a connection with the remote device, the channel is subject to configuration and the higher-layer prototype L2CA_ ConfigReq request packet is used to carry configuration requests. Its associated response is contained within the L2CA_ConfigRsp packet; an L2CA_ConfigRspNeg packet is used to denote a negative response during configuration where, for example, the suggested Maximum Transmission Unit (MTU) is too large. In Table 11-27, we show that the MTU and Flush Timeout parameters are mandatory, whereas the QoS is optional.

The default MTU setting for the signalling channel is 48-bytes, whereas other channels may be capable of transferring larger payloads; essentially, the MTU determines the size of payloads that are capable of being exchanged between two devices. During configuration, the local device will inform the remote device that it is potentially capable of accepting larger payloads. If the remote device is unwilling to accept a larger MTU, then the local device is informed with the response contained within the L2CA_ConfigRspNeg packet.

When L2CA_ request and response packets are being exchanged, the Flush Timeout parameter is used to determine how long the local device is prepared to continue to transmit an L2CAP fragment before it gives up; the packet is subsequently flushed or, in other words, discarded. The suggested Flush Timeout value is sent during the L2CA_ ConfigReq request packet. However, if no value is set, then the default value is used. The GOEP uses the default value of 0xFFFF.

As we have already mentioned, the QoS configuration is optional. However, if it is used during an L2CA_ConfigReq request, then the best effort service is established as a default; the available services that are supported for an L2CAP channel are shown in Table 11-31. However, if the QoS service is set at Guaranteed, then parameters such Token Rate, Token Bucket, Peak Bandwidth, Latency and Delay Variation are used to determine an acceptable guaranteed service, where the L2CA_ConnectRspNeg will indicate that these values are unacceptable. These parameters are then subject to further negotiation.

Table 11-32 summarises the broad capabilities that are expected from the LC. In the table, you will notice features are marked with M (Mandatory), O (Optional), X (Excluded), C (Conditional) and N/A (Not Applicable); these will determine what is expected from the features at the LC.