OBEX library — Changes

3^rd December 2007 — release 1.5 (1.5.1203).

What’s new

In the core library, in brief:

• Support for NETCFv1.
• All NETCF code has been tested on real devices including running the full test-suite there (~700 unit tests, plus IrDA-specified tests and the sample programs).
• Support for Mono (http://www.mono-project.com/Main_Page), tested on Windows and on Linux, on versions 1.2.4, 1.2.5 and 1.2.6.  For the library in 1.2.4 some differences in behaviour remain, for instance on certain invalid Folder-Listings a NullReferenceException occurs (Mono bug 80231) instead an XML exception, and in certain cases of calling Abort with an ObexPutStream/ObexGetStream a MissingMemberException occurs rather that an ObjectDisposedException.  The sample work fully in 1.2.6 and some of them work in earlier versions, however the BackgroundWorker component in Mono prior to 1.2.6 is not thread-safe so bad behaviour can occur in samples that use it.
• Added a HasSize property and a corresponding ResetSize method to ObexFileOrFolderItem class, and thus to ObexFolderItem, and ObexFileItem classes.  This allows one to know whether a size was included in the folder-listing, or whether the folder-listing item simply did not have a size value. See the FolderExplorer sample Details view for an example of using these properties. 
• The ProtocolViolationException message when parsing an incorrectly formatted received PDU now reports information about the location of the fault, for example “Overrun PDU in parsing at index: 3, location: 'pre-header-bytes', pduLength: 3.”
• A fix to workaround the bug in various servers where a connect response packet signalling an error is in a bad format (it doesn't contain the necessary connect bytes).  We detect the short response when it has an error code and suppress the ProtocolViolationException in that case so that the ‘bad response code error’ can occur.
• A fix to workaround the bug in the Widcomm servers, where a connect response packet signalling an error has zero in the maximum-packet-size field.
• A fix to workaround the Widcomm Abort fault where it returns an illegal Final PDU.  We now ignore any such invalid responses in that case.
• Adding null Byte-Array headers disallowed.

In the samples, in brief:

• 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).
• Added TraceStream to the TransportConnections library, providing simple diagnostic of stream operations for NETCF.  Use network tracing on the full framework, see the “Samples/Enable Network Logging, rename to app.exe.config” file.
• UriObexSessionConnection did not support the scheme "obex:" and new constructors taking a BluetoothAddress or IrDAAddress and a scheme. Some checking of command format in GetFolderListings.
• A fix to workaround a fault in the NETCFv1 where TcpClient fails to connect to a peer where the target is an IPAddress string.
• Form titles all made to match the application’s name.
• FolderExplorer opens the GET operation in the sub form which also provides must better error handling and reporting.
• FolderExplorer on NETCF, fix the Close button state after cancel/fail fix.
• FolderExplorerSp (SmartPhone) renaming of Soft Key menu 2.
• Mark manual new threads as ‘IsBackground=true’ to ensure that they don't keep the program around after the form is closed.
• Handle IOException on conn.Connect()

Beta 3 changes

In the core library, in brief:

• Access to the response metadata headers in a GET request is provided via the ResponseHeaders property on ObexGetStream.  This can be used to find the length of the object being downloaded.  See the FolderExplorer2 sample which uses this feature to update the progress bar.
• GET (GetTo/Get) did not work on the NETCF; failing with an InvalidCastException.  This has been fixed.
• Code to run the NUnit-based unit-tests on the NETCF has been created to ensure the code quality of the complete library on that platform.
• The Folder Listing parser failed on the NETCF when reading listings from most peer devices.  This is due to a lack of support for DTDs in the NETCF XmlTextReader class, if used on a document that contains a DOCTYPE element it throws a NotSupportedException. This is bad, as the Folder Listing document is defined in the OBEX specification by a DTD and all the documents I've see do contain the document type declaration.  This has been worked-around by creating code to strip any DOCTYPE element from received documents.
• It also has been reported that some devices produce Folder Listing XML documents containing null bytes.  When first writing the parser I had been aware that some devices included null bytes at the end of the document, and thus the parser is careful to read no further that the document end tag.  However due to reports of some documents having null bytes in the middle of the document has meant creating another bit of ‘stripping’ code.  This is disabled by default as I’ve seen no such documents showing this. This applies to both platforms.
• The SetPath, SetPathUp, and SetPathReset methods have been changed to set the flag that indicates not to create a folder when it doesn't already exist by default.  This was done particularly to suit some device types which prompt the user to allow an 'up' change even though the parent folder does exist. This could be a breaking change for code which uses the SetPath(String) method in particular. The method which used to take boolean arguments for the flags has also been changed to use enum values instead.
• There has been one breaking change in the Pdus namespace, the values of the ObexPduType enum have changed. So, don't redirect an application compiled against Beta 2 to this version, instead recompile. I aim for this to be the last such change.
• Class documentation has been completed on all the main library classes, in particular on the ObexPduFactory class.
• The class methods meant only for ‘advanced’ usages have been marked as such; firstly with the text “[Advanced usage]” in their parameter documentation, and secondly with System.ComponentModel.EditorBrowsableState.Advanced to control their appearance in Intellisense.

In the samples, in brief:

• The NETCF Windows Forms samples in the previous version were pretty much useless.  Whilst the library (and the command-line program) did work, the UI samples (and the IrDA-specified tests) did not — due to threading issues.  The samples have now been recreated in a full version of VS, tested, and they all seem to work fine in the emulator. However a beta tester reports that they do not work for him on a real device. As the complete source for the samples is included, can any Compact Framework experts give me any recommendations for changes so that they do work.
• Both the GuiObexSessionConnection class and the ConsoleMenuObexSessionConnection in the TransportConnection library now support TCP/IP connections.  They connect to the specified default port of 650, with the GuiObexSessionConnection class displaying a prompt dialog box for the IP Address or hostname, and the ConsoleMenuObexSessionConnection class prompts on the console. With Alan's help support for both IPv4 and IPv6 has been verified.
• A new Forms Control ProtocolComboBox is included in the TransportConnection library, it represents a drop-down list from which the user can select Bluetooth, IrDA, or TCP/IP.  It returns the selected protocol as a System.Net.Sockets.ProtocolFamily value.  All the UI samples have been updated to use this control.
• FxCop has been run on the library and all major recommendations followed.

Beta 2 changes

• Folder-Listing XML parser. See classes Brecham.Obex.Objects.FolderListing and Brecham.Obex.Objects.FolderListingParser, and method GetFolderListing on class Brecham.Obex.ObexClientSession.
• ObexClientSession. Addition of 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 Abort.
• GetFolderListing sample updated to use the folder-listing parser, printing folder contents in the same style as Windows’ DIR command, also now supports download of any file types.
• There are also a number of new sample projects all for VB.NET, as the feedback clearly showed that they were important. They are VbPutSample, PutGuiVb, GetFirstListedFile, and FolderExplorerVb. See below. Also the source for the GetFolderListing is now included.
• The samples now includes a library to handle creating connection to OBEX servers over both Bluetooth or IrDA, and also handle disconnect and clean-up. It includes three classes, one to handle connections in a GUI application, one for console menu-driven applications like GetFolderListings, and one that accepts a URI of a similar format to that used by 32feet.NET’s ObexWebRequest class.
• In Beta 1 the command-line programs built for the NETCF were incorrectly being compiled as type WinExe so produced no console output, this has been fixed in this release. Unfortunately the VB samples could not be compiled for the NETCF, the VB compiler exploding when asked to do so…
• Exceptions now serializable. Also, ObexCreateTooLongException was moved to the Pdus namespace.

Andy Hume