IntroductionTop, Main, Index
The Object Exchange (OBEX) standard defines a protocol and application framework for transferring objects and related meta-information between two devices. It is similar to HTTP in functionality except that it is geared towards smaller devices with more constrained resources. Originally designed for use over IrDA, it is now used over other transport protocols as well, in particular Bluetooth and TCP/IP.
The obex package is an implementation of this protocol.
Download and installTop, Main, Index
The package is distributed as a single file Tcl module and may be downloaded from https://sourceforge.net/projects/magicsplat/files/obex/. To install the package, run the following command from the command line:
tclsh obex-VERSION.tm install
where VERSION is the package version you downloaded.
Alternatively, just copy the downloaded file into a directory listed in the list returned by the Tcl tcl::tm::path list command.
After installation, the package can be loaded as
package require obex
Only OBEX client functionality is implemented in this release.
The package is broken up into the following namespaces based on OBEX profiles:
| ::obex | Implements the Generic Object Exchange Profile on which the other profiles are based. |
| ::obex::opp | Implements the Object Push Profile. |
| [::obex::pbap] | Implements the Phone Book Access Profile. (Well, at some point in the future.) |
| [::obex::map] | Implements the Message Access Profile. (Coming up, right after PBAP!) |
| ::obex::core | Implements core low-level protocol commands. |
It is intended that details of the OBEX protocol is not required to use the obex package but some basic knowledge is useful. The sections below provide an overview.
The OBEX protocolTop, Main, Index
The OBEX session protocol is a client-server protocol where the client sends a request to a server which then sends a response back to the client. The protocol only permits one request to be outstanding at a time. Of course, independent requests may be in progress on separate transport connections.
OBEX requestsTop, Main, Index
Each request is composed of multiple request packets based on the maximum packet size supported by the two ends of the OBEX conversation.
A request packet begins with a operation code, or opcode, which specifies the requested operation, followed by a length field containing the length of the packet. These fixed fields are followed by optional headers which contain the attributes and data describing the desired operation. All request packets making up a single request start with the same operation code. The last packet in the request is marked by a special final bit which indicates the request is complete.
The request opcodes have corresponding methods defined in the package. These are described in OBEX operations.
The actual content itself, along with any metadata, is transferred in OBEX as a sequence of headers, possible across multiple packets.
OBEX responsesTop, Main, Index
Like requests, responses may be broken up into multiple response packets. A response packet has a similar structure to request packets except that the leading byte is a response code as opposed to a request opcode. These response codes are analogous to HTTP status codes and map to request completion status values as described in Request completion status.
Just like for requests, the data and related information in responses is transferred in the form of headers.
OBEX profilesTop, Main, Index
A profile defines
- An application usage scenario in terms of the functionality exposed to the user.
- The requirements expected of the underlying protocol stacks to ensure interoperability.
- The message formats and operations used to exchange objects between application instances.
Two independently developed applications adhering to the same profile are assured of interoperability.
As an example, consider the Bluetooth Phone Book Access Profile (PBAP). The usage scenario for the profile is retrieval of phone book entries stored on a server device from a client device. The protocol requirements include OBEX over RFCOMM over L2CAP as the transport with SDP for service advertising. The operations include GET/PUT for retrieval of the phone book as well as individual entries. Message formats include use of specific OBEX headers and formats specific to the content (e.g. v-card).
In the obex package, profiles are implemented within namespace that reflect the profile name. For example, the client and server classes for the Object Push Profile (OPP) are contained in the ::obex::opp namespace.
ReferencesTop, Main, Index
For a tutorial and examples see these blog posts.
An older version of the OBEX specification is available as a PDF. Newer versions require membership in IrDA.
OBEX profile specifications for Bluetooth are at the Bluetooth site