32feetNET.doc

32feet.NET Users GuideVersion 3.0 Beta, September 201032feet.NET Users Guide. 1Supported hardware and software. 1Broadcom/Widcomm. 2Multi-stack support. 2Referencing the library. 3VisualBasic samples. 3OBEX object transfer. 3Behaviour from servers. 4Server side. 4Brecham.Obex. 5General Bluetooth data connections. 5Discovery. 5DeviceName and discovery. 6Server side. 6Errors. 6Stream.Read and the number of bytes returned. 7The Connected property and connection loss. 7Connecting to Bluetooth services. 7General IrDA connections. 8Bluetooth settings, device information etc. 8Peer Device information. 8Local Radio information. 8Bluetooth Serial Ports. 9Getting virtual COM port names for remote Bluetooth devices. 9Bluetooth Security. 10Bluetooth SDP Service Discovery Protocol. 11Creating Records. 11Connect by Service Name. 12Manual record creation. 12IntroductionThere are generally four ways an application might want to use Bluetooth:1. Make a direct data connectionWhere the program connects directly to a Bluetooth RFCOMM service, and sends and receives the raw data for that connection. The server side function can also be provided. See section “General Bluetooth data connections” below.2. Do an OBEX transferWhere the program is an OBEX client and connects to a server, and sends (PUTs) or GETs a file/object. The server side function can also be provided. See section “OBEX” below.3. Have the Bluetooth stack and/or the OS connect to and use a remote serviceCommon services for this case are where the service is Headset/Handsfree/A2DP, or networking for instance. Here we do not want the program to connect directly to those services, as we wouldnt know what to do with the raw bytes, but instead want the OS to send audio to the headset, or form a network connection with an access-point or similar. See section “Connecting to Bluetooth services” below.4. Make a direct data connection using the L2CAP protocolWhere the program connects directly to a Bluetooth L2CAP service, and sends and receives the raw data for that connection. This is not supported currently.See http:/www.alanjmcf.me.uk/comms/bluetooth/Bluetooth Profiles and 32feet.NET.html for information on what services use which method.For device discovery see the section under “General Bluetooth data connections” below.Supported hardware and softwareThe library is supported both in a version for desktop Windows, and a version for NETCF v2.0. On both platforms various companies have provided software protocol stack software to use Bluetooth hardware. For instance, on desktop Windows there are well known stacks from Microsoft, Widcomm (now Broadcom), BlueSoleil and Toshiba. On CE platforms there are also stacks from Microsoft and Widcomm/Broadcom. To visually identify which stack is installed see /VisuallyIdentifyYourBluetoothStack.aspx. On both platforms we have long standing support for the Microsoft stack, and we have new support for the Broadcom/Widcomm stack again on both platforms. Wed like to support the BlueSoleil stack but are looking for funding to do so, contact Alan if you need support for this stack.On a device where there is no Bluetooth hardware connected or a non-Microsoft stack is present the library will obviously not function. Opening a socket will fail with an exception and getting the list of local radios (BluetoothRadio.AllRadios) will return a zero length array, and getting the primary radio (BluetoothRadio.PrimaryRadio) will return null/Nothing, thus code like the following will fail with a NullReferenceException.BluetoothRadio.PrimaryRadio.Mode = RadioMode.DiscoverableOn desktop Windows it is generally possible to disable the third-party stack and install the Microsoft stack. The document Belkin F8T012 and Microsoft Stack downloadable from http:/32/files/folders/1118/download.aspx describes how to install the Microsoft stack, and also includes the steps necessary to install a Bluetooth device that Windows wasnt originally aware of.On machines with the Toshiba software, from Add/Remove programs remove Bluetooth Stack for Windows by Toshiba, then run the C:TOSHIBAMS_BluetoothBtMon2Inst.exe installer to install the BT monitor, and finally reboot the machine, whereupon the system will detect the radio and install the necessary Microsoft-supplied drivers as above.Finally note that each of these stacks support only one attached radio. For instance on the Microsoft XP stack when I have two dongles attached I see an event log warning from BTHUSB with message “Only one active Bluetooth radio is supported at a time.”Broadcom/WidcommThis was new support in version 2.4. In 3.0 we have done a lot of work to ensure that all functionality works from asynchronous callbacks, new features include setting BluetoothRadio.Mode on CE/WM (theres no Widcomm API on Win32), correctly reporting the Mode when the radio is disabled, support for InquiryLength in DiscoverDevices, and closing all connections when the radio is switched off. In 2.5, there were improvements to diagnostics on setting-up dependencies and BluetoothListener was rewritten amongst other changes.To enable the Widcomm support, in brief the 32feetWidcomm.dll native DLL need to be present at runtime in the same folder as the main library assembly (InTheHand.Net.Personal.dll) and the application itself. As a native DLL it cannot be referenced at compile-time like a normal managed .NET assembly.Also, Win32 needs a particular version of the Visual C+ Runtime libraries, since 2.5.1 this is version 9.0.21022.8, and can be found at “Microsoft Visual C+ 2008 Redistributable Package (x86)” /downloads/en/details.aspx?FamilyID=9b2da534-3e03-4391-8a4d-074b9f2bc1bf. (Version 2.5 required version 8.0.50727.4053. If not already installed, this can be found at “Microsoft Visual C+ 2005 Service Pack 1 Redistributable Package ATL Security Update” /downloads/details.aspx?familyid=766a6af7-ec73-40ff-b072-9112bab119c2&displaylang=en)In more detail, Since the Widcomm API is C+ and thus cant be P/Invoked directly we unfortunately require a native DLL as well as the normal library assembly. Versions of the native DLL are supplied primarily for Win32 x86 and WM2005, we also include PPC2003 and Win32 x64 but we dont/cant test them. At runtime the 32feetWidcomm.dll DLL needs to be present alongside the library assembly (or somewhere else in the path presumably), there is no need to reference it at compile-time (as a native DLL is cant be referenced like a .NET assembly).For Widcomm, various users have reported that there are problems on desktop Windows with newer versions of the Widcomm stack, with for instance BluetoothClient.Connect failing with a SocketException with it message including the code “PortLookup_NoneRfcomm”. We now supply two versions of 32feetWidcomm.dll for Win32 for this reason. Unfortunately when to use them is complex I wish Widcomm had been a bit cleverer about how they provided their Vista support. :-( (Note that Bluecove on Java also has to supply two versions of the DLL presumably for similar reasons1). Normal 32feetWidcomm.dll versionWorks even when the Microsoft Bluetooth stack is also active, and so allows multi-stack support. But might not work on newer version installations of the Widcomm stack. “SDK6” versionMay be required on newer version installations of the Widcomm stack, but will not work when the Microsoft Bluetooth stack is active.We also now include copies of the 32feetWidcomm.dll for x64, let me know if it works for you, it is untested by us.There are no further dependencies on Windows Mobile but there is on desktop Windows. Thats the C Runtime (CRT) libraries as described above. If the correct version is not installed, then the Widcomm support in the library will report that it cant load the 32feetWidcomm.dll even if its present in the same folder as the application/library. To check this, run the test app Test32FeetWidcommWin32.exe which will report something like: “This application has failed to start because the application configuration is incorrect. Reinstalling the application may fix this problem.” Installing the CRT will fix this. See the Widcomm document for more information.Multi-stack supportFrom version 2.5 (actually version 2.4.1) we support using the Microsoft and Widcomm stacks at the same time. This allows one program to support more than seven connections, or similar situations. To use the multi-stack support on Windows XP, install both Microsoft and Widcomm stacks and attach their radio dongles. Then create an app.config file with your application and set the flag “oneStackOnly” to “false” there is a sample app.config file in the assemblies folder, copy it, rename it to match you app e.g. “thisismyapp.exe.config”, and change the settings as required. It is likely that we will change the default for “oneStackOnly” to be “false” in the next version.If the two stacks both load successfully, then BluetoothRadio.AllRadios should contain two items. Using new BluetoothClient() etc will always create an instance from the first radio/stack. To specifically create an instance from a particular radio/stack use the StackFactory property on BluetoothRadio. For instance:Dim radioB As BluetoothRadio = BluetoothRadio.AllRadios(1)Dim cli As BluetoothClient = radioB.StackFactory.CreateBluetoothClient()Dim lsnr As BluetoothListener = _ radioB.StackFactory.CreateBluetoothListener(BluetoothService.Wap)If at least one of the stacks loads, but one or more fails to load then the program will continue. More diagnostics can be enabled to allow troubleshooting. Set app.config flag “reportAllErrors” to “true”. This outputs any errors on the Console and on System.Diagnostics.Trace output; since we use Trace.Fail currently, an assert dialog box will pop-up and need to be closed manually if necessary see MSDN on “AssertUiEnabled=false” for disabling the dialog.Referencing the libraryThe library is provided as an assembly with name InTheHand.Net.Personal.dll. The installer arranges that it can be selected directly from Visual Studios Add Reference dialog.Two versions of the library are provided, one for use with: desktop (Win32) CLR and one for NETCF v2.0 applications. They are installed in directories called XP2 and CE2 respectively. The correct one for the project type is listed in the Add Reference dialog as above.VisualBasic samplesThe samples here are provided in VisualBasic.NET. C# users are generally always able to read VB except in the most advanced cases. Apart from obvious like needing semicolons added, method calls and member access for example are very similar, and explicit SubEndSub, While End While can simply be replaced by braces . For the samples here the only thing that might need to be explained is that “Dim” creates a variable definition, so the first two lines in the first OBEX sample below in C# are:String addr = 112233445566;Uri uri = new Uri(obex:/ + addr + /HelloWorld.txt);So apart from the change to the variable definition syntax we needed to add a semicolon to end of each line, change the case of keyword “New” to be “new”, and change VBs string append operator (&) to C#s + equivalent.OBEX object transferIf you want to transfer a file or other object using the standard service as used by Windows Wireless Link / Bluetooth File Transfer Wizard, Palms Beam, Nokias Send via Infrared, then use the OBEX protocol. On the client-side one can use code like the following to send a file. The host part of the URI is the device address, e.g. IrDAAddress.ToString(), and the file part is the OBEX object name.Dim addr As String = 112233445566Dim uri As New Uri(obex:/ & addr & /HelloWorld.txt)Dim req As New ObexWebRequest(uri)req.ReadFile(Hello World.txt)Dim rsp As ObexWebResponse = CType(req.GetResponse(),ObexWebResponse)Console.WriteLine(Response Code: 0 (0x0:X), rsp.StatusCode)Or, to send locally generated content use something like the following. The host part of the URI is the device address, e.g. IrDAAddress.ToString(), and the file part is the OBEX object name.Dim addr As String = 112233445566Dim uri As New Uri(obex:/ & addr & /HelloWorld2.txt)Dim req As New ObexWebRequest(uri)Using content As Stream = req.GetRequestStream() Using a StreamWriter to write text to the stream. Using wtr As New StreamWriter(content) wtr.WriteLine(Hello World GetRequestStream) wtr.WriteLine(Hello World GetRequestStream 2) wtr.Flush() Set the Length header value req.ContentLength = content.Length End Using In this case closing the StreamWriter also closed the Stream, but .End UsingDim rsp As ObexWebResponse = CType(req.GetResponse(),ObexWebResponse) Console.WriteLine(Response Code: 0 (0x0:X), rsp.StatusCode)See also the ObexPushApplication and ObexPushVB sample programs.The PUT operation is supported, and there is new support for GET, but there is no support for changing folders or getting a folder listing. In previous version there were some issue with handling file names that include non-English characters, and making connections to some device types failed. Both are fixed in the current version.This class can only send one file, closing the connection after it does so. The Brecham.Obex library that we distribute can send more than one file without reconnecting. That depends on the peer server being allowing that too. See below for more information in this library.Like the frameworks HttpWebResponse class etc, the ObexWebRequest signals an error by throwing a WebException and it includes the original error as the InnerException property. Status code BadRequest indicates an error at connect time, in the network connection, the OBEX connection or even in the format or content of the URI. Status code InternalServerError indicates an error during the transfer.The OBEX protocol is used to provide access to various types of service; in Bluetooth we have for instance Push (OPP), FTP, and PBAP “Phone Book Access” etc. Push normally allows PUT only and doesnt require authentication whereas FTP allows general GET support and folder browsing but normally requires authentication. What service to connect to can be specified in the “scheme” of the URL passed to the ObexWebRequest constructor, see the class documentation.Finally, note that the ObexWebRequest class its