OBEX Session Protocol
As mentioned above, the OBEX session protocol defines a structured dialog where a client sends request packets to a server, after which the server sends response packets to the client. This exchange proceeds in strict rotation, request-response, request-response until the required
2 Strictly speaking, even Body headers are not fragmented between OBEX packets; rather, the payload of an object is fragmented into multiple individual Body headers.
transfer or transfers are complete. The following sections summarize the packet exchanges involved for each OBEX command.
Connect
The Connect command is used by OBEX client application to establish a session with an OBEX server. The Connect command must therefore be used before any other OBEX commands for a given session.3
A Connect command will comprise either a single request-response exchange, or two request-response exchanges, depending on whether the client, or server, or both client and server, are requesting authentication. Whether authentication is required or not is an application-specific decision. The various authentication scenarios are described below.
Connect (no authentication) The sequence of events is as follows:
1. The OBEX client sends a Connect request packet to OBEX server.
2. The OBEX server receives the Connect request packet. It then prepares and sends a Connect response packet to the OBEX client.
3. The OBEX client receives the Connect response packet.
Connect (client authenticates server) The sequence of events is as follows:
1. The OBEX client sends a Connect request packet to the OBEX server containing an authenticate challenge header.
2. The OBEX server receives the Connect request packet, and extracts the authenticate challenge header. It then prepares and sends a Connect response packet to the OBEX client. The Connect response packet contains an authenticate response header (preparation of the authentication response header often involves accepting user input of a password).
3. The OBEX client receives the Connect response packet, extracts the authenticate response header and verifies the authenticity of the OBEX server. If the authentication is successful, the OBEX client will proceed with further OBEX commands. If the authentication is not successful, the OBEX client may proceed with a Disconnect command or simply disconnect the transport.
Connect (server authenticates client)
1. The OBEX client sends a Connect request packet to the OBEX server.
3 This is not strictly true; there are variations of OBEX that are not connection oriented (e.g., OBEX over IrDA Ultra), but the vast majority of applications of OBEX use the connection-oriented version.
2. The OBEX server receives the Connect request packet. Itthen prepares and sends a Connect response packet to the OBEX client with the response code value 'Unauthorized' and an authenticate challenge header originating from the OBEX Server.
3. The OBEX client receives the Connect response packet, and extracts the authenticate challenge header. It then prepares and sends a second Connect request packet similar to its first, but this time including an authenticate response header.
4. The OBEX server receives the Connect request packet, and extracts the authenticate response header and verifies the authenticity of the OBEX client. If the authentication is successful, the OBEX server responds to the OBEX client with a Connect response packet with a response code value 'Success'. If the authentication is unsuccessful, the OBEX server may respond with a Connect response packet containing a response code indicating the failure of the connection.
5. (Assuming successful authentication) the OBEX client receives the Connect response packet, and the OBEX session has been connected.
Connect (both client and server authenticate each other)
1. The OBEX client sends a Connect request packet to the OBEX server containing an authenticate challenge header.
2. The OBEX server receives the Connect request packet. Itthen prepares and sends a Connect response packet to the OBEX client with the response code value 'Unauthorized' and another authenticate challenge header, this one originating from the OBEX server.
3. The OBEX client receives the Connect response packet, and extracts the authenticate challenge header. It then prepares and sends a second Connect request packet similar to the first (including a copy of the original authentication challenge header), but this time includes an authenticate response header to satisfy the OBEX server's requirements.
4. The OBEX server receives the Connect request packet, and extracts the authenticate response header and verifies the authenticity of the OBEX client. If the authentication is successful, the OBEX server responds to the OBEX client with a Connect response packet with a response code value 'Success', and an authenticate response header of its own to satisfy the OBEX client's requirements. If the authentication is unsuccessful, the OBEX server may respond with a Connect response packet containing a response code indicating the failure of the connection.
5. (Assuming successful authentication of the OBEX client by the OBEX server), the OBEX client receives the Connect response packet, and extracts the authenticate response from the OBEX server. It then attempts to verify the authenticity of the OBEX server. If this succeeds, the OBEX session has been connected.
Connection failure cases Aside from authentication failures, there are other reasons why a Connect command may fail. For example, some client applications or server applications will only work if connected to a 'strict peer' - that means the Target header specified by the OBEX client in a Connect command matches the Who header associated with the OBEX server that processes the Connect command. When such a failure case is encountered, the OBEX client can abandon a Connect command by disconnecting the OBEX transport. The OBEX server can refuse a Connect command in two ways:
• send a response packet with a non-success response code.
• disconnect the OBEX transport.
Disconnect
The Disconnect command is used by the OBEX client application to close down an existing session with an OBEX server. A Disconnect command will always comprise a single request-response exchange. When the OBEX client application performs a Disconnect command, the OBEX client sends a Disconnect request packet. Upon receiving this, the OBEX server can send back a Disconnect response packet (which must always indicate successful disconnection), or can simply disconnect the OBEX transport to complete the command.
The Put command is used by the OBEX client application to transfer an object from the OBEX client to the connected OBEX server. The OBEX client application specifies the object to be sent, and the OBEX client performs the necessary processing to convert this into a sequence of request-response exchanges. A Put command can be completed in a single request-response exchange, but this depends upon the size of the object being transferred and the maximum OBEX packet size that the OBEX client is capable of sending and the OBEX server is capable of receiving.
Most Put commands will require more than one request-response exchange. The OBEX client uses the final bit in the request opcode to indicate the final request packet of a given Put command so that the OBEX server can complete the object transfer (e.g., commit the received data to file) and prepare itself to accept the first request packet of the next command from the OBEX client (see Figure 10.1).
The Get command is used by the OBEX client application to request that the connected OBEX server transfers a specified object to the OBEX client. The Get command is a little more complex than the Put command, as it has two distinct phases.
In the first phase, the OBEX client sends a 'specification object' to the server. In the second phase, the OBEX server sends an object, whose content is dependent on the specification object, back to the OBEX client. The phases of a Get command should not be confused with the request-response exchange of packets; both phases of the Get may consist of several request-response exchanges of packets as illustrated in Figure 10.3.
- Figure 10.3 (Symbian OS-based) simplified view of OBEX Get command
In the first phase, the data flows predominantly from the OBEX client to the OBEX server in the request packets, which, as always, are acknowledged by the OBEX server returning response packets. In the last request packet to contain specification object data, the OBEX client sets the final bit to indicate that the first phase is over.
Upon receiving the request packet with the final bit set, the OBEX server completes the specification object transfer, and decides on the object to be sent back to the client-this decision is entirely dependent on the service being used by the client and offered by the server. The second phase commences, and the data now flows predominantly from the OBEX server to the OBEX client in the response packets. Effectively, during this phase, the OBEX client acknowledges the response packets by sending further Get request packets, until the OBEX server sends a final response packet with the Success response code, and prepares itself for the first request packet of the next command from the OBEX client. Upon receiving the response packet, the OBEX client can complete the object transfer, for example, commit the received data to file.
SetPath
The SetPath command is used by the OBEX client application to navigate the directory structure on the OBEX server. This directory structure will often map directly onto a real file system, but can also be used for virtual directory structures that describe different areas of a given service, for example, IrMC or the Bluetooth Phonebook Access Profile.
A SetPath command will always consist of a single request-response exchange. The OBEX client application determines the folder to move into, and encodes this into the request packet, along with flags which indicate whether to 'back up' a level first, and whether to create a named folder if it doesn't currently exist. Upon receiving the request packet, the OBEX server will attempt to move to (and, if requested, create) the specified folder, before sending back a response packet with a response code indicating the success or failure of the SetPath command.
Note: the OBEX specification also indicates a defined XML format for folder listing objects that can be used on request to pass information on the folder structure of an OBEX service to the OBEX client. This format has been used in the OBEX FTP server example code.
Abort
The Abort command is used by the OBEX client application to abandon an ongoing command without taking the drastic step of disconnecting the OBEX transport. It is treated as a special case in the OBEX protocol, as an Abort request packet can be sent by the OBEX client instead of a request packet that continues an ongoing OBEX command. Upon receipt of an Abort request packet, the OBEX server will abandon any ongoing activities associated with the current command. It will then send back an Abort response packet, and prepare itself for the first request packet of the next command from the OBEX client.
Post a comment