I/O layer refactoring finished

[Jef Driesen]

Hi,

I just pushed the latest changes for the I/O layer refactoring to the 
master branch. Unfortunately these changes break backwards compatibility 
for anyone using libdivecomputer.

In a nutshell, the main changes are:

  * The dc_device_open() function has been modified. Instead of a string 
with the name of the serial port, it now takes a pointer to a 
dc_iostream_t. That means that the application becomes responsible for 
opening the underlying I/O stream.

  * The dc_descriptor_get_transport() function has been replaced with a 
new dc_descriptor_get_transports() function (notice the extra "s" in the 
name). This new function returns a bitmask with all the transports 
supported by the device.

  * The dc_context_get_transports() function has been added to query the 
available built-in transports.

These changes enables the use of Bluetooth Classic (rfcomm) with the 
built-in implementation (Windows and Linux), and Bluetooth Low Energy 
(ble) with a custom implementation. More details about these new 
features are in the remainder of this email.


With the above changes, the typical sequence to download dives will now 
look similar to this:

    1. Enumerate all supported dive computers and choose one
    2. Choose the transport type
    3. Ignore unsupported transport types
    4. Enumerate the I/O devices
    5. Open the I/O stream
    6. Connect to the dive computer
    7. Download dives

Let's have a closer look at each step:

1. Enumerate all supported dive computers and choose one

This is exactly the same as before.

2. Choose the transport type

This is where the first important change will be. Previously, each 
device descriptor supported exactly one transport type (serial, usb, 
usbhid or irda). But with bluetooth we have devices that support more 
than just one transport. Therefore, the transport type has been changed 
into a bitmask:

typedef enum dc_transport_t {
     DC_TRANSPORT_NONE      = 0,
     DC_TRANSPORT_SERIAL    = (1 << 0),
     DC_TRANSPORT_USB       = (1 << 1),
     DC_TRANSPORT_USBHID    = (1 << 2),
     DC_TRANSPORT_IRDA      = (1 << 3),
     DC_TRANSPORT_BLUETOOTH = (1 << 4),
     DC_TRANSPORT_BLE       = (1 << 5)
} dc_transport_t;

Now, each descriptor can support more than one transport, and you can 
query them using the new function:

unsigned int
dc_descriptor_get_transports (dc_descriptor_t *descriptor);

For example, the Heinrichs Weikamp OSTC 2 will report 
DC_TRANSPORT_SERIAL | DC_TRANSPORT_BLUETOOTH | DC_TRANSPORT_BLE.

3. Ignore unsupported transport types

With support for custom I/O, libdivecomputer no longer knows which 
devices are actually supported. Hence the #ifdef's will be removed from 
the descriptor table, and thus libdivecomputer will always report all 
the devices it knows about. That means it's up to the application to 
filter out entries for which there is no suitable transport available 
(either built-in or custom).

Therefore libdivecomputer provides a new function to query the built-in 
transports:

unsigned int
dc_context_get_transports (dc_context_t *context);

This will again return a bitmask with the available built-in transports. 
With a simple bitwise AND operation, you can easily filter out 
transports for which no built-in implementation is available:

unsigned int supported = dc_descriptor_get_transports(descriptor);
unsigned int available = dc_context_get_transports(context);
unsigned int usable = supported & available;

When using custom I/O, the application should of course also keep the 
transports for which it has a custom I/O implementation.

4. Enumerate the I/O devices

Once you have selected the underlying transport type, you want to scan 
the system for possible matches. Previously, libdivecomputer did this 
internally for irda and usbhid, and automatically picked the first 
available device. For serial communication, applications were supposed 
to enumerate the serial ports themselves and pass the name of the device 
node. Since every transport types has different parameters (e.g a 
vid/pid for usbhid, and address and port for irda and bluetooth classic, 
etc), this can't easily be extended to arbitrary transport types.

Therefore, each of the built-in iostream implementations will provide 
its own enumeration api, based on the existing iterator api:

dc_iterator_t *iterator = NULL;
dc_xxx_iterator_new (&iterator, context, descriptor);

dc_xxx_device_t *device = NULL;
while (dc_iterator_next (iterator, &device) == DC_STATUS_SUCCESS) {
     dc_xxx_device_get_yyy(device);
     dc_xxx_device_free (device);
}
dc_iterator_free (iterator);

Where xxx can be replaced with serial, irda, usbhid, etc.

For serial, you'll be able to get the device node, for irda/bluetooth 
the address and device name, for usbhid the vid/pid, and so on.


Of course we also don't want to push too much knowledge to the 
application. Ideally the application shouldn't need to know which 
VID/PID's match certain dive computers, or things like that. That's why 
the dc_xxx_iterator_new() function accepts an (optional) descriptor as 
argument. It will acts as a filter and return only those devices that 
match the selected dive computer. For example if you scan for usb hid 
devices with the Eon Steel descriptor, you'll only get devices matching 
the Eon Steel VID/PID. Same for bluetooth and irda, where we can filter 
on the device name.


Note that for custom I/O, this whole discovery step is obviously always 
the responsibility of the application.

5. Open the I/O stream

The next step is opening the I/O stream.

To use one of the built-in implementations, you simply call one of these 
functions:

dc_serial_open (&iostream, context, name);
dc_irda_open (&iostream, context, address, 1);
dc_usbhid_open (&iostream, context, device);
dc_bluetooth_open (&iostream, context, address, 0);

The values for the extra parameters (name, address, device, etc) are 
available from the device discovery in the previous step.

To use a custom implementation, you need to implement a set of callback 
functions, and create an iostream for them as follows:

dc_custom_cbs_t callbacks = {
    app_custom_set_timeout, /* set_timeout */
    app_custom_set_latency, /* set_latency */
    app_custom_set_break, /* set_break */
    app_custom_set_dtr, /* set_dtr */
    app_custom_set_rts, /* set_rts */
    app_custom_get_available, /* get_received */
    app_custom_get_lines, /* get_lines */
    app_custom_configure, /* configure */
    app_custom_read, /* read */
    app_custom_write, /* write */
    app_custom_flush, /* flush */
    app_custom_purge, /* purge */
    app_custom_sleep, /* sleep */
    app_custom_close, /* close */
};

dc_custom_open (&iostream, context, transport, &callbacks, userdata);

6. Connect to the dive computer

Instead of accepting a string with the device node (which only makes 
sense for serial communication), you now pass the iostream handle to the 
dc_device_open() function:

dc_status_t
dc_device_open (dc_device_t **device, dc_context_t *context, 
dc_descriptor_t *descriptor, dc_iostream_t *iostream);


7. Download dives

This remains exactly the same as before.

Jef