semi/signal

I’ve released the BTObex library (I’m playing around with using bitbucket for hosting the code) I wrote a few months ago which is a Win32 bluetooth library that allows for file transfers with devices that support the Bluetooth File Transfer Profile. This library uses the MS Bluetooth stack (included w/ Win XP SP2 and later).

For those wondering what OBEX is and what Bluetooth has to do with it: Bluetooth devices support a set of profiles, one of which is the File Transfer Profile. However, the FTP itself doesn’t really take care of anything much, once the connection is established, actual file transfers are handled by the OBEX protocol.

OBEX was originally designed for transfers across infrared devices and is not handled by the Bluetooth SIG, its specs are controlled by the IrDA. Now, aside from being a useless bit of trivia, this is important because while the Bluetooth SIG publishes a ton of documentation, the IrDA does not. The documentation on the specs for OBEX requires signing up for IrDA membership and paying some hefty membership fees. That said I was able to get my hands on a copy of the OBEX documentation here. How long that remains up and the legality of me reading it is up in the air. Charging for documentation is a shitty practice by the IrDA and I can only hope that the Bluetooth SIG ditches OBEX for something better in the future.

There’s little-to-no documentation for the library, so I’m going to use this blog post to provide some examples.

Link with necessary libraries

#pragma comment(lib, "ws2_32.lib")
#pragma comment(lib, "irprops.lib")


Include header file

#include "BTOBEX.h"

The entire library simply consists of a bunch of header files. BTOBEX.h will include everything else.

Query all Bluetooth devices

std::vector<BTSock::Device*> btDevices;
BTSock::Session* btSession = new BTSock::Session();
btSession->DeviceQueryObject()->PerformQuery(btDevices);
delete btSession;


The vector btDevices will contain an entry for each device paired with the system. Look at BTSockDevice.h to see the structure of the BTSock::Device class.

Make a connection

BTOBEX::Session* btObexSession = new BTOBEX::Session();
bool connOk = btObexSession->Connect(devAddress, port, 8192);


devAddress is the deviceAddress member of a BTSock::Device object.
port is the port number for a given profile, for the file transfer profile it’s 5. If you can’t connect on the port, it likely means that the profile is not support by the device.

Set the current directory on the device

bool setPathOk = btObexSession->SetPathForward(L"my_picture");

OBEX only allows you to move forward into a subdirectory (SetPathForward) or jump back to a parent directory (SetPathForward).

Get a directory listing

OBEX::NakedVector<OBEX::byte> xmlBytes;
btObexSession->GetFolderListing(xmlBytes);


The bytes are UTF-8 bytes that form a XML document (an XML parser is not part of the library). The XML doc will have folder and/or file elements, each with a required name attribute. Directory listings are one of the dumbest aspects of the OBEX protocol; whereas everything else is binary and well-defined, directory listings are verbose and text-based (remember, this is a low bandwidth connection) and have no required attribute aside from name. Other attributes (e.g. size) may be present, but they’re optional, meaning, in general, you’ll likely avoid them in order to develop for the lowest common denominator.

Get a file from the device

bool getOk = btObexSession->GetFile(L"remote.jpg", L"local.jpg", new BTOBEX::Progress());


The last parameter is optional, you can pass a BTOBEX::Progress object if you wish to poll the progress of the transfer from another thread.

Put a file on the device

bool putOk = btObexSession->PutFile(L"remote.jpg", L"local.jpg", new BTOBEX::Progress());

The last parameter is optional, you can pass a BTOBEX::Progress object if you wish to poll the progress of the transfer from another thread.

Disconnect and clean up

btObexSession->Disconnect();
delete btObexSession;


Have fun! The code is released under the BSD license. Any comments or bug reports are greatly appreciated.

Edit (11/22/2020): Update link to point to GitHub repo.