OBEX library — Readme

10th August 2006

This a beta release of the library. Although the library has been thoroughly tested both with a full set of unit-tests, and also all the appropriate tests specified by the IrDA for a client-side implementation, the library should be treated as beta code. The main purpose of this release is to gain feedback from third-party users, please post any feedback to the Brecham.Obex forum at 32feet.NET.

What’s new

In brief:

Features

The library provides very broad client-side OBEX support, providing not just the ‘Put’ operation that most libraries and applications support, but also the complete set of operations: Connect, Put, Get, SetPath, Delete, and Abort. This is accessed through a session based interface. All errors communicating to the peer OBEX server are exposed to the calling application.

The library also provides access to its lower-level PDU (packet) creation and parsing facilities, enabling third-party implementation of any required features, for instance server-side operation, and perhaps even reliable-session support.

As well as the ‘on-the-wire’ protocol support there is also broad support for the objects defined in the OBEX specification. For instance the Folder Listing XML documents as used by the Folder-Browsing service. A full parser, returning an array of folder and file objects, is included

The library, its class documentation in both compiled HTML Help, and in raw XML for Intellisense, and a Programmer’s Guide are included.

Assemblies for both the FXv2 desktop and Compact Frameworks are supplied.

Included sample code contains examples in both C# and VB.NET, showing how to use Put, Get, SetPath and Folder Listings operations. They include examples of asynchronous usage, along with progress bar updating. The calling application is responsible for forming the transport level connection to the OBEX server, likely on a Bluetooth or IrDA peer. Examples of connection code is also included in the sample sources.

Samples

As noted above various sample programs are included. For C#, two PUT clients are included, one Windows Forms and one command-line. The command-line application prints usage information when run with no command-line arguments. The UI client shows asynchronous usage, and progress bar updating as the transfer proceeds. It uses delegate’s BeginInvoke feature, and using a ‘decorator’ stream to measure the progress with a Timer component using its result to update a progress bar.

Screenshot of PutGUI sample Screenshot of PutCmdline sample

There’s also a console-based menu-driven GET client, which, although it is called ‘GetFolderListing’, supports all Get operations, and can connect to both the “Folder-Browsing’ and ‘Inbox’ services. It can display the current folder’s folder listing, displaying its content in a similar layout to the Windows’ DIR command; except of course since the parent-folder item does not define any attributes it cannot display the current folder’s last modified time.

It saves any downloads to the current folder with a name created from the current operation, for instance a raw folder-listing object (command "L") is saved to a filename of <folderName>.xml, with “Root.xml’ used for the default folder. Note that the download is also currently displayed on the screen as it is received, for binary files the text conversion will fail and the displaying will cease, and continue only to display dots as the download proceeds. Its source code is also now included.

Screenshot of GetFolderListing sample

VB.NET

For VB.NET four samples are now included. The VbPutSample is a simple command-line Put client, PutGuiVb is a simple GUI Put client, GetFirstListedFile is a command-line program that will walk through the peer’s folders and download the first file it finds listed, finally FolderExplorerVb is a GUI Windows Explorer style application that lists the folders and files on the peer allow the user to navigate through them.

Screenshot of FolderExplorerVb sample

Both PutGuiVb and FolderExplorerVb display a progress bar as they do the upload / download. They use a Background Worker component in which the content is manually copied from the source to the destination stream, in the former application, from the file to the ObexPutStream and in the former from the ObexGetStream to the list boxes. Each time round they update the progress status, and watch for user cancelling.

Note that the Length property on the ObexGetStream, isn’t provided and thus it’s not possible to calculate the percentage completed progress there. However an OBEX server can optionally include a Length header in the Get response, and if provided this could be used for this purpose. Thus, in the next release of the library the ObexGetStream class will provide access to any metadata that the server returns.

Building

The source code for all projects is included. To compile all the sample projects from the command-line one could use the following command (on one line). The debug configuration of some of the samples includes NUnit tests, so as configured that library is required for debug compilation.

C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\MSBuild "Brecham Obex\Samples\Samples.sln" /p:Configuration=Release

Otherwise, the solution can be loaded in Visual Studio and built there. As I've noted in the forum I’m currently using a copy of VC# Express, and through the magic of MSBuild even the VB.NET projects can be built there. However as I coded them by hand, I’m not sure whether their forms can be loaded into the Forms Designer.

Compact Framework

The library and samples compiled for CF v2.0 are provided in the NETCF folder. Necessary changes were made to the source to have it compile against the CF; the changes to the OBEX library itself were minor: loosening of the strict ASCII string to Byte Sequence conversion due to the non-existence of fallback exception modes in Encoding / Decoding, and removal of some assembly level attributes.

I have no devices however that run the Compact Framework, so the code here is essential untested (except that when run against the full framework all tests pass!) The Debug+Tests assemblies are also supplied, so the library can be unit tested with NUnit on the CF platform if such a thing exists, and the tests specified by the IrDA are implemented in TestSpec101.exe, which write a message to the console on success and throws on failure. Any feedback is welcomed. :-)

In the sample PutGUI application, the changes made to successful compile were of the simple Windows Forms’ AutoSize etc variety and were made through the Forms Designer. However one manual edit was still required: System.Windows.Forms.Timer doesn't have a constructor that takes a System.ComponentModel.IContainer on the CF. All such changes are bracketed in C# #if NETCF blocks. No significant changes were necessary to the command-line samples; does Windows CE (etc) even have a command-line?

Unfortunately the Visual Basic compiler exploded (silently) whenever I tried to compile the VB samples for the NETCF, possibility related to this bug, however its fix apparently only applies to VS and not to the command-line compiler. I’ll look at this again when I've upgraded to the full version of Visual Studio.

On the WebRequest Pattern

The library does not implement the WebRequest pattern. This pattern, as generally used in its HttpWebRequest form, is most suited to that protocol, which is of course session-less. FTP and OBEX are session based, so on the same transport connection they can for instance connect, with authentication, perhaps then change directory, list its contents, then upload one file, and download another. To fit the WebRequest Pattern there has to be lots of magic behind the scenes to make a second FtpWebRequest instance use the connection that a previous instance finished using some time before... This also makes a very odd programming experience for the consuming developer, so, at the moment there's no such implementation, as my view that the library's session-based API is very much easier to use.

The sample TransportConnection library includes a class UriObexSessionConnection which takes a URI of a similar format to that used by 32feet.NET’s ObexWebRequest class, and forms a connection to the specified device and OBEX service, this can be used if converting your code between the two libraries.

Support

Support is available through the 32feet.NET website, where the Brecham.Obex support forum is provided for that purpose. New releases will be also made available there.

Andy Hume