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.
In brief:
Brecham.Obex.Objects.FolderListing
and
Brecham.Obex.Objects.FolderListingParser
, and
method GetFolderListing
on class
Brecham.Obex.ObexClientSession
.
GetFolderListing method
.
It is also now
implements IDisposable
, calling its Dispose
method will close the underlying stream.
Also one fix, Connect and Delete can be called after after Abort.
ObexCreateTooLongException
was moved to the Pdus
namespace.
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.
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.
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.
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.
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.
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.
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.
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