.PNG "Screenshot of FolderExplorerVb sample")
3rd December 2007 — release 1.5 (1.5.1203).
For the full list of changes in the current and previous versions see the Changes document. In brief the changes in the core library in this version include:
HasSize property to ObexFileOrFolderItem class,
and thus to ObexFolderItem, and ObexFileItem classes.
This allows one to know whether a size value was included in the folder-listing.
These are also many fixes and improvements to the sample programs. They have also been updated to use version 2.2 of the InTheHand 32feet.NET library. Note that the NullReferenceException that would occur when attempting a Bluetooth connection on a CE/PPC device without the Microsoft Bluetooth stack was an issue in that library and has been fixed (their workitem 11744).
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.
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 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.
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 Framework versions 1 and 2 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. Most use the TransportConnection library to form the connection to the OBEX server. Some however manually create the connection.
In summary, the following samples are included
| Name | Lang. | Format | Features | Background threading method |
| PutGuiVb2 | VB.NET | WinForms | PUT | BackgroundWorker |
| VbPutSample | VB.NET | Command-line | PUT | None |
| FolderExplorer2 | VB.NET | WinForms | Explorer style; FolderListings, GET | BackgroundWorker |
| GetFirstListedFile | VB.NET | Command-line | FolderListings, GET | None |
| PutGUI | C# | WinForms | PUT | delegate.BeginInvoke and progress decorator Stream |
| PutCmdline | C# | Command-line | PUT | None |
| GetFolderListings | C# | Console | FolderListings, GET, PUT. | None |
For VB.NET four samples are included. The VbPutSample is a simple command-line Put client, PutGuiVb2 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 FolderExplorer2 is a GUI Windows Explorer style application that lists the folders and files on the peer allow the user to navigate through them. In a previous release the Visual Basic samples were created and built by hand, now the samples have been created with Visual Studio with the forms created in the Forms Designer etc.
Both PutGuiVb2 and FolderExplorer2 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 stream to the ObexPutStream, and in the latter from the
ObexGetStream to the list boxes. Each time round they update the
progress status, and check for user cancelling.
The Length of the object in the GET operation is accessed through the headers in
the ObexGetStream’s new ResponseHeaders
property, and is used to calculate the percentage-completed progress there. However
the inclusion of such a header is optional and thus if the server has not provided
a Length header then a pseudo-progress bar is displayed.
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 the rather complex method of using delegate’s
BeginInvoke feature, along with a ‘decorator’ stream to
measure the progress of the download, with a Timer component using its result to update
a progress bar.
.png "Screenshot of PutGUI sample")
.png "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 can also do a Put operation.
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.
.PNG "Screenshot of GetFolderListing sample")
The source code for all the sample projects is included. To compile them from the command-line one could use the following command (on one line).
C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\MSBuild "Brecham
Obex\Samples\Samples.sln" /p:Configuration=Release
Otherwise, the solutions can be loaded in Visual Studio and built there.
The debug configuration of some of the samples includes NUnit tests, so as
configured that library is required for debug compilation. To get the
build to work, one way would thus be to install the NUnit tool from
http://www.nunit.org/, otherwise, the tests
are all defined within #if NUNIT ... #endif blocks; and currently
only two of the projects contains unit-tests: TransportConnection and GetFolderListings.
So you could go to the properties pages of those samples and remove "NUNIT" from
the Conditional compilation symbols field in the debug build configurations.
The library and samples compiled for CF v2.0 are provided in the NETCF folder, and
for CF v1.0 in the NETCFv1 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
System.Text.Encoding, removal of some assembly level attributes, and latterly,
removal of some logging code, and the implementation of the DOCTYPE stripping
as discussed above. The library is also supplied compiled for CF
v1.0 and one sample for it is also included.
.PNG)
Early version of the library did not fully work on the NETCF unfortunately, and
I was no longer happy with releasing the core library for a platform on which it hadn't
been fully tested. Running the ~600 unit-tests from the NETCF assembly on the desktop
CLR obviously not being up to the job, as of course it used the desktop
Framework Class Library, so I set about
finding a solution to that. I thus created an application to run all of my NUnit
unit-tests on a PocketPC device. Now, I haven't yet got any code
coverage solution there, but all of the applicable
tests run and pass, so I'm much
happier now. The main thing highlighted by running the tests was the DOCTYPE issue in the Folder
Listing parser. The samples have also all
been tested on real Windows Mobile devices.
Four samples are included (thought only one for NETCFv1). There are conversions of the PutGUI C#, PutGuiVb2, and FolderExplorer programs from the desktop, there is also a version of FolderExplorer for Smartphone. In all cases the projects were created from scratch within Visual Studio with the Forms laid out there and the communications code copied from their desktop equivalents. In all cases of course the background threading functionality had to be created from scratch, manual implementations of the BackgroundWorker component and the delegate.BeginInvoke being provided respectively. There is also a new simple GET sample, GetUi, which allow downloading of files, with their name and optionally media type supplied manually; this sample was of most use before the DOCTYPE stripping work was done for the folder-listing parser.
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 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