configure.ac: Add 'check-news' Automake option

[libjaylink.git] / libjaylink / device.c

/*
 * This file is part of the libjaylink project.
 *
 * Copyright (C) 2014-2016 Marc Schink <jaylink-dev@marcschink.de>
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

#include <stdlib.h>
#include <stdint.h>
#include <stdbool.h>
#include <string.h>
#ifdef _WIN32
#include <winsock2.h>
#else
#include <sys/socket.h>
#include <arpa/inet.h>
#endif
#include <libusb.h>

#include "libjaylink.h"
#include "libjaylink-internal.h"

/**
 * @file
 *
 * Device enumeration and handling.
 */

/** @cond PRIVATE */
#define CMD_GET_VERSION         0x01
#define CMD_GET_HW_STATUS       0x07
#define CMD_REGISTER            0x09
#define CMD_GET_HW_INFO         0xc1
#define CMD_GET_FREE_MEMORY     0xd4
#define CMD_GET_CAPS            0xe8
#define CMD_GET_EXT_CAPS        0xed
#define CMD_GET_HW_VERSION      0xf0
#define CMD_READ_CONFIG         0xf2
#define CMD_WRITE_CONFIG        0xf3

#define REG_CMD_REGISTER        0x64
#define REG_CMD_UNREGISTER      0x65

/** Size of the registration header in bytes. */
#define REG_HEADER_SIZE         8
/** Minimum registration information size in bytes. */
#define REG_MIN_SIZE            0x4c
/** Maximum registration information size in bytes. */
#define REG_MAX_SIZE            0x200
/** Size of a connection entry in bytes. */
#define REG_CONN_INFO_SIZE      16
/** @endcond */

/** @private */
JAYLINK_PRIV struct jaylink_device *device_allocate(
                struct jaylink_context *ctx)
{
        struct jaylink_device *dev;
        struct list *list;

        dev = malloc(sizeof(struct jaylink_device));

        if (!dev)
                return NULL;

        list = list_prepend(ctx->devs, dev);

        if (!list) {
                free(dev);
                return NULL;
        }

        ctx->devs = list;

        dev->ctx = ctx;
        dev->ref_count = 1;
        dev->usb_dev = NULL;

        return dev;
}

static struct jaylink_device **allocate_device_list(size_t length)
{
        struct jaylink_device **list;

        list = malloc(sizeof(struct jaylink_device *) * (length + 1));

        if (!list)
                return NULL;

        list[length] = NULL;

        return list;
}

/**
 * Get available devices.
 *
 * @param[in,out] ctx libjaylink context.
 * @param[out] devices Newly allocated array which contains instances of
 *                     available devices on success, and undefined on failure.
 *                     The array is NULL-terminated and must be free'd by the
 *                     caller with jaylink_free_devices().
 * @param[out] count Number of available devices on success, and undefined on
 *                   failure. Can be NULL.
 *
 * @retval JAYLINK_OK Success.
 * @retval JAYLINK_ERR_ARG Invalid arguments.
 * @retval JAYLINK_ERR_MALLOC Memory allocation error.
 * @retval JAYLINK_ERR Other error conditions.
 *
 * @see jaylink_discovery_scan()
 *
 * @since 0.1.0
 */
JAYLINK_API int jaylink_get_devices(struct jaylink_context *ctx,
                struct jaylink_device ***devices, size_t *count)
{
        size_t num;
        struct list *item;
        struct jaylink_device **devs;
        struct jaylink_device *dev;
        size_t i;

        if (!ctx || !devices)
                return JAYLINK_ERR_ARG;

        num = list_length(ctx->discovered_devs);
        devs = allocate_device_list(num);

        if (!devs) {
                log_err(ctx, "Failed to allocate device list.");
                return JAYLINK_ERR_MALLOC;
        }

        item = ctx->discovered_devs;

        for (i = 0; i < num; i++) {
                dev = (struct jaylink_device *)item->data;
                devs[i] = jaylink_ref_device(dev);
                item = item->next;
        }

        if (count)
                *count = num;

        *devices = devs;

        return JAYLINK_OK;
}

/**
 * Free devices.
 *
 * @param[in,out] devices Array of device instances. Must be NULL-terminated.
 * @param[in] unref Determines whether the device instances should be
 *                  unreferenced.
 *
 * @see jaylink_get_devices()
 *
 * @since 0.1.0
 */
JAYLINK_API void jaylink_free_devices(struct jaylink_device **devices,
                bool unref)
{
        size_t i;

        if (!devices)
                return;

        if (unref) {
                for (i = 0; devices[i]; i++)
                        jaylink_unref_device(devices[i]);
        }

        free(devices);
}

/**
 * Get the host interface of a device.
 *
 * @param[in] dev Device instance.
 * @param[out] iface Host interface of the device on success, and undefined on
 *                   failure.
 *
 * @retval JAYLINK_OK Success.
 * @retval JAYLINK_ERR_ARG Invalid arguments.
 *
 * @since 0.1.0
 */
JAYLINK_API int jaylink_device_get_host_interface(
                const struct jaylink_device *dev,
                enum jaylink_host_interface *iface)
{
        if (!dev || !iface)
                return JAYLINK_ERR_ARG;

        *iface = dev->interface;

        return JAYLINK_OK;
}

/**
 * Get the serial number of a device.
 *
 * @note This serial number is for enumeration purpose only and might differ
 *       from the real serial number of the device.
 *
 * @param[in] dev Device instance.
 * @param[out] serial_number Serial number of the device on success, and
 *                           undefined on failure.
 *
 * @retval JAYLINK_OK Success.
 * @retval JAYLINK_ERR_ARG Invalid arguments.
 * @retval JAYLINK_ERR_NOT_AVAILABLE Serial number is not available.
 *
 * @since 0.1.0
 */
JAYLINK_API int jaylink_device_get_serial_number(
                const struct jaylink_device *dev, uint32_t *serial_number)
{
        if (!dev || !serial_number)
                return JAYLINK_ERR_ARG;

        if (!dev->valid_serial_number)
                return JAYLINK_ERR_NOT_AVAILABLE;

        *serial_number = dev->serial_number;

        return JAYLINK_OK;
}

/**
 * Get the USB address of a device.
 *
 * @note Identification of a device with the USB address is deprecated and the
 *       serial number should be used instead.
 *
 * @param[in] dev Device instance.
 * @param[out] address USB address of the device on success, and undefined on
 *                     failure.
 *
 * @retval JAYLINK_OK Success.
 * @retval JAYLINK_ERR_ARG Invalid arguments.
 * @retval JAYLINK_ERR_NOT_SUPPORTED Operation not supported.
 *
 * @see jaylink_device_get_serial_number()
 *
 * @since 0.1.0
 */
JAYLINK_API int jaylink_device_get_usb_address(
                const struct jaylink_device *dev,
                enum jaylink_usb_address *address)
{
        if (!dev || !address)
                return JAYLINK_ERR_ARG;

        if (dev->interface != JAYLINK_HIF_USB)
                return JAYLINK_ERR_NOT_SUPPORTED;

        *address = dev->usb_address;

        return JAYLINK_OK;
}

/**
 * Increment the reference count of a device.
 *
 * @param[in,out] dev Device instance.
 *
 * @return The given device instance on success, or NULL on invalid argument.
 *
 * @since 0.1.0
 */
JAYLINK_API struct jaylink_device *jaylink_ref_device(
                struct jaylink_device *dev)
{
        if (!dev)
                return NULL;

        dev->ref_count++;

        return dev;
}

/**
 * Decrement the reference count of a device.
 *
 * @param[in,out] dev Device instance.
 *
 * @since 0.1.0
 */
JAYLINK_API void jaylink_unref_device(struct jaylink_device *dev)
{
        struct jaylink_context *ctx;

        if (!dev)
                return;

        dev->ref_count--;

        if (!dev->ref_count) {
                ctx = dev->ctx;

                log_dbg(ctx, "Device destroyed (bus:address = %03u:%03u).",
                        libusb_get_bus_number(dev->usb_dev),
                        libusb_get_device_address(dev->usb_dev));

                ctx->devs = list_remove(dev->ctx->devs, dev);

                if (dev->usb_dev)
                        libusb_unref_device(dev->usb_dev);

                free(dev);
        }
}

static struct jaylink_device_handle *allocate_device_handle(
                struct jaylink_device *dev)
{
        struct jaylink_device_handle *devh;

        devh = malloc(sizeof(struct jaylink_device_handle));

        if (!devh)
                return NULL;

        devh->dev = jaylink_ref_device(dev);

        return devh;
}

static void free_device_handle(struct jaylink_device_handle *devh)
{
        jaylink_unref_device(devh->dev);
        free(devh);
}

/**
 * Open a device.
 *
 * @param[in,out] dev Device instance.
 * @param[out] devh Newly allocated handle for the opened device on success,
 *                  and undefined on failure.
 *
 * @retval JAYLINK_OK Success.
 * @retval JAYLINK_ERR_ARG Invalid arguments.
 * @retval JAYLINK_ERR_TIMEOUT A timeout occurred.
 * @retval JAYLINK_ERR_MALLOC Memory allocation error.
 * @retval JAYLINK_ERR_IO Input/output error.
 * @retval JAYLINK_ERR Other error conditions.
 *
 * @since 0.1.0
 */
JAYLINK_API int jaylink_open(struct jaylink_device *dev,
                struct jaylink_device_handle **devh)
{
        int ret;
        struct jaylink_device_handle *handle;

        if (!dev || !devh)
                return JAYLINK_ERR_ARG;

        handle = allocate_device_handle(dev);

        if (!handle) {
                log_err(dev->ctx, "Device handle malloc failed.");
                return JAYLINK_ERR_MALLOC;
        }

        ret = transport_open(handle);

        if (ret != JAYLINK_OK) {
                free_device_handle(handle);
                return ret;
        }

        *devh = handle;

        return JAYLINK_OK;
}

/**
 * Close a device.
 *
 * @param[in,out] devh Device instance.
 *
 * @retval JAYLINK_OK Success.
 * @retval JAYLINK_ERR_ARG Invalid arguments.
 * @retval JAYLINK_ERR Other error conditions.
 *
 * @since 0.1.0
 */
JAYLINK_API int jaylink_close(struct jaylink_device_handle *devh)
{
        int ret;

        if (!devh)
                return JAYLINK_ERR_ARG;

        ret = transport_close(devh);
        free_device_handle(devh);

        return ret;
}

/**
 * Get the device instance from a device handle.
 *
 * @note The reference count of the device instance is not increased.
 *
 * @param[in] devh Device handle.
 *
 * @return The device instance on success, or NULL on invalid argument.
 *
 * @since 0.1.0
 */
JAYLINK_API struct jaylink_device *jaylink_get_device(
                struct jaylink_device_handle *devh)
{
        if (!devh)
                return NULL;

        return devh->dev;
}

/**
 * Retrieve the firmware version of a device.
 *
 * @param[in,out] devh Device handle.
 * @param[out] version Newly allocated string which contains the firmware
 *                     version  on success, and undefined if @p length is zero
 *                     or on failure. The string is null-terminated and must be
 *                     free'd by the caller.
 * @param[out] length Length of the firmware version string including trailing
 *                    null-terminator on success, and undefined on failure.
 *                    Zero if no firmware version string is available.
 *
 * @retval JAYLINK_OK Success.
 * @retval JAYLINK_ERR_ARG Invalid arguments.
 * @retval JAYLINK_ERR_TIMEOUT A timeout occurred.
 * @retval JAYLINK_ERR_MALLOC Memory allocation error.
 * @retval JAYLINK_ERR_IO Input/output error.
 * @retval JAYLINK_ERR Other error conditions.
 *
 * @since 0.1.0
 */
JAYLINK_API int jaylink_get_firmware_version(
                struct jaylink_device_handle *devh, char **version,
                size_t *length)
{
        int ret;
        struct jaylink_context *ctx;
        uint8_t buf[2];
        uint16_t dummy;
        char *tmp;

        if (!devh || !version || !length)
                return JAYLINK_ERR_ARG;

        ctx = devh->dev->ctx;
        ret = transport_start_write_read(devh, 1, 2, true);

        if (ret != JAYLINK_OK) {
                log_err(ctx, "transport_start_write_read() failed: %s.",
                        jaylink_strerror(ret));
                return ret;
        }

        buf[0] = CMD_GET_VERSION;

        ret = transport_write(devh, buf, 1);

        if (ret != JAYLINK_OK) {
                log_err(ctx, "transport_write() failed: %s.",
                        jaylink_strerror(ret));
                return ret;
        }

        ret = transport_read(devh, buf, 2);

        if (ret != JAYLINK_OK) {
                log_err(ctx, "transport_read() failed: %s.",
                        jaylink_strerror(ret));
                return ret;
        }

        dummy = buffer_get_u16(buf, 0);
        *length = dummy;

        if (!dummy)
                return JAYLINK_OK;

        ret = transport_start_read(devh, dummy);

        if (ret != JAYLINK_OK) {
                log_err(ctx, "transport_start_read() failed: %s.",
                        jaylink_strerror(ret));
                return ret;
        }

        tmp = malloc(dummy);

        if (!tmp) {
                log_err(ctx, "Firmware version string malloc failed.");
                return JAYLINK_ERR_MALLOC;
        }

        ret = transport_read(devh, (uint8_t *)tmp, dummy);

        if (ret != JAYLINK_OK) {
                log_err(ctx, "transport_read() failed: %s.",
                        jaylink_strerror(ret));
                free(tmp);
                return ret;
        }

        /* Last byte is reserved for null-terminator. */
        tmp[dummy - 1] = 0;
        *version = tmp;

        return JAYLINK_OK;
}

/**
 * Retrieve the hardware information of a device.
 *
 * @note This function must only be used if the device has the
 *       #JAYLINK_DEV_CAP_GET_HW_INFO capability.
 *
 * @param[in,out] devh Device handle.
 * @param[in] mask A bit field where each set bit represents hardware
 *                 information to request. See #jaylink_hardware_info for a
 *                 description of the hardware information and their bit
 *                 positions.
 * @param[out] info Array to store the hardware information on success. Its
 *                  content is undefined on failure. The array must be large
 *                  enough to contain at least as many elements as bits set in
 *                  @a mask.
 *
 * @retval JAYLINK_OK Success.
 * @retval JAYLINK_ERR_ARG Invalid arguments.
 * @retval JAYLINK_ERR_TIMEOUT A timeout occurred.
 * @retval JAYLINK_ERR_IO Input/output error.
 * @retval JAYLINK_ERR Other error conditions.
 *
 * @since 0.1.0
 */
JAYLINK_API int jaylink_get_hardware_info(struct jaylink_device_handle *devh,
                uint32_t mask, uint32_t *info)
{
        int ret;
        struct jaylink_context *ctx;
        uint8_t buf[5];
        unsigned int i;
        unsigned int num;
        unsigned int length;

        if (!devh || !mask || !info)
                return JAYLINK_ERR_ARG;

        ctx = devh->dev->ctx;
        num = 0;

        for (i = 0; i < 32; i++) {
                if (mask & (1 << i))
                        num++;
        }

        length = num * sizeof(uint32_t);

        ret = transport_start_write_read(devh, 5, length, true);

        if (ret != JAYLINK_OK) {
                log_err(ctx, "transport_start_write_read() failed: %s.",
                        jaylink_strerror(ret));
                return ret;
        }

        buf[0] = CMD_GET_HW_INFO;
        buffer_set_u32(buf, mask, 1);

        ret = transport_write(devh, buf, 5);

        if (ret != JAYLINK_OK) {
                log_err(ctx, "transport_write() failed: %s.",
                        jaylink_strerror(ret));
                return ret;
        }

        ret = transport_read(devh, (uint8_t *)info, length);

        if (ret != JAYLINK_OK) {
                log_err(ctx, "transport_read() failed: %s.",
                        jaylink_strerror(ret));
                return ret;
        }

        for (i = 0; i < num; i++)
                info[i] = buffer_get_u32((uint8_t *)info,
                        i * sizeof(uint32_t));

        return JAYLINK_OK;
}

/**
 * Retrieve the hardware version of a device.
 *
 * @note This function must only be used if the device has the
 *       #JAYLINK_DEV_CAP_GET_HW_VERSION capability.
 *
 * @warning This function may return a value for @p version where
 *          #jaylink_hardware_version::type is not covered by
 *          #jaylink_hardware_type.
 *
 * @param[in,out] devh Device handle.
 * @param[out] version Hardware version on success, and undefined on failure.
 *
 * @retval JAYLINK_OK Success.
 * @retval JAYLINK_ERR_ARG Invalid arguments.
 * @retval JAYLINK_ERR_TIMEOUT A timeout occurred.
 * @retval JAYLINK_ERR_IO Input/output error.
 * @retval JAYLINK_ERR Other error conditions.
 *
 * @since 0.1.0
 */
JAYLINK_API int jaylink_get_hardware_version(
                struct jaylink_device_handle *devh,
                struct jaylink_hardware_version *version)
{
        int ret;
        struct jaylink_context *ctx;
        uint8_t buf[4];
        uint32_t tmp;

        if (!devh || !version)
                return JAYLINK_ERR_ARG;

        ctx = devh->dev->ctx;
        ret = transport_start_write_read(devh, 1, 4, true);

        if (ret != JAYLINK_OK) {
                log_err(ctx, "transport_start_write_read() failed: %s.",
                        jaylink_strerror(ret));
                return ret;
        }

        buf[0] = CMD_GET_HW_VERSION;

        ret = transport_write(devh, buf, 1);

        if (ret != JAYLINK_OK) {
                log_err(ctx, "transport_write() failed: %s.",
                        jaylink_strerror(ret));
                return ret;
        }

        ret = transport_read(devh, buf, 4);

        if (ret != JAYLINK_OK) {
                log_err(ctx, "transport_read() failed: %s.",
                        jaylink_strerror(ret));
                return ret;
        }

        tmp = buffer_get_u32(buf, 0);

        version->type = (tmp / 1000000) % 100;
        version->major = (tmp / 10000) % 100;
        version->minor = (tmp / 100) % 100;
        version->revision = tmp % 100;

        return JAYLINK_OK;
}

/**
 * Retrieve the hardware status of a device.
 *
 * @param[in,out] devh Device handle.
 * @param[out] status Hardware status on success, and undefined on failure.
 *
 * @retval JAYLINK_OK Success.
 * @retval JAYLINK_ERR_ARG Invalid arguments.
 * @retval JAYLINK_ERR_TIMEOUT A timeout occurred.
 * @retval JAYLINK_ERR_IO Input/output error.
 * @retval JAYLINK_ERR Other error conditions.
 *
 * @since 0.1.0
 */
JAYLINK_API int jaylink_get_hardware_status(struct jaylink_device_handle *devh,
                struct jaylink_hardware_status *status)
{
        int ret;
        struct jaylink_context *ctx;
        uint8_t buf[8];

        if (!devh || !status)
                return JAYLINK_ERR_ARG;

        ctx = devh->dev->ctx;
        ret = transport_start_write_read(devh, 1, 8, true);

        if (ret != JAYLINK_OK) {
                log_err(ctx, "transport_start_write_read() failed: %s.",
                        jaylink_strerror(ret));
                return ret;
        }

        buf[0] = CMD_GET_HW_STATUS;

        ret = transport_write(devh, buf, 1);

        if (ret != JAYLINK_OK) {
                log_err(ctx, "transport_write() failed: %s.",
                        jaylink_strerror(ret));
                return ret;
        }

        ret = transport_read(devh, buf, 8);

        if (ret != JAYLINK_OK) {
                log_err(ctx, "transport_read() failed: %s.",
                        jaylink_strerror(ret));
                return ret;
        }

        status->target_voltage = buffer_get_u16(buf, 0);
        status->tck = buf[2];
        status->tdi = buf[3];
        status->tdo = buf[4];
        status->tms = buf[5];
        status->tres = buf[6];
        status->trst = buf[7];

        return JAYLINK_OK;
}

/**
 * Retrieve the capabilities of a device.
 *
 * The capabilities are stored in a 32-bit bit array consisting of
 * #JAYLINK_DEV_CAPS_SIZE bytes where each individual bit represents a
 * capability. The first bit of this array is the least significant bit of the
 * first byte and the following bits are sequentially numbered in order of
 * increasing bit significance and byte index. A set bit indicates a supported
 * capability. See #jaylink_device_capability for a description of the
 * capabilities and their bit positions.
 *
 * @param[in,out] devh Device handle.
 * @param[out] caps Buffer to store capabilities on success. Its content is
 *                  undefined on failure. The buffer must be large enough to
 *                  contain at least #JAYLINK_DEV_CAPS_SIZE bytes.
 *
 * @retval JAYLINK_OK Success.
 * @retval JAYLINK_ERR_ARG Invalid arguments.
 * @retval JAYLINK_ERR_TIMEOUT A timeout occurred.
 * @retval JAYLINK_ERR_IO Input/output error.
 * @retval JAYLINK_ERR Other error conditions.
 *
 * @see jaylink_get_extended_caps()
 * @see jaylink_has_cap()
 *
 * @since 0.1.0
 */
JAYLINK_API int jaylink_get_caps(struct jaylink_device_handle *devh,
                uint8_t *caps)
{
        int ret;
        struct jaylink_context *ctx;
        uint8_t buf[1];

        if (!devh || !caps)
                return JAYLINK_ERR_ARG;

        ctx = devh->dev->ctx;
        ret = transport_start_write_read(devh, 1, JAYLINK_DEV_CAPS_SIZE, true);

        if (ret != JAYLINK_OK) {
                log_err(ctx, "transport_start_write_read() failed: %s.",
                        jaylink_strerror(ret));
                return ret;
        }

        buf[0] = CMD_GET_CAPS;

        ret = transport_write(devh, buf, 1);

        if (ret != JAYLINK_OK) {
                log_err(ctx, "transport_write() failed: %s.",
                        jaylink_strerror(ret));
                return ret;
        }

        ret = transport_read(devh, caps, JAYLINK_DEV_CAPS_SIZE);

        if (ret != JAYLINK_OK) {
                log_err(ctx, "transport_read() failed: %s.",
                        jaylink_strerror(ret));
                return ret;
        }

        return JAYLINK_OK;
}

/**
 * Retrieve the extended capabilities of a device.
 *
 * The extended capabilities are stored in a 256-bit bit array consisting of
 * #JAYLINK_DEV_EXT_CAPS_SIZE bytes. See jaylink_get_caps() for a further
 * description of how the capabilities are represented in this bit array. For a
 * description of the capabilities and their bit positions, see
 * #jaylink_device_capability.
 *
 * @note This function must only be used if the device has the
 *       #JAYLINK_DEV_CAP_GET_EXT_CAPS capability.
 *
 * @param[in,out] devh Device handle.
 * @param[out] caps Buffer to store capabilities on success. Its content is
 *                  undefined on failure. The buffer must be large enough to
 *                  contain at least #JAYLINK_DEV_EXT_CAPS_SIZE bytes.
 *
 * @retval JAYLINK_OK Success.
 * @retval JAYLINK_ERR_ARG Invalid arguments.
 * @retval JAYLINK_ERR_TIMEOUT A timeout occurred.
 * @retval JAYLINK_ERR_IO Input/output error.
 * @retval JAYLINK_ERR Other error conditions.
 *
 * @see jaylink_get_caps()
 *
 * @since 0.1.0
 */
JAYLINK_API int jaylink_get_extended_caps(struct jaylink_device_handle *devh,
                uint8_t *caps)
{
        int ret;
        struct jaylink_context *ctx;
        uint8_t buf[1];

        if (!devh || !caps)
                return JAYLINK_ERR_ARG;

        ctx = devh->dev->ctx;
        ret = transport_start_write_read(devh, 1, JAYLINK_DEV_EXT_CAPS_SIZE,
                true);

        if (ret != JAYLINK_OK) {
                log_err(ctx, "transport_start_write_read() failed: %s.",
                        jaylink_strerror(ret));
                return ret;
        }

        buf[0] = CMD_GET_EXT_CAPS;

        ret = transport_write(devh, buf, 1);

        if (ret != JAYLINK_OK) {
                log_err(ctx, "transport_write() failed: %s.",
                        jaylink_strerror(ret));
                return ret;
        }

        ret = transport_read(devh, caps, JAYLINK_DEV_EXT_CAPS_SIZE);

        if (ret != JAYLINK_OK) {
                log_err(ctx, "transport_read() failed: %s.",
                        jaylink_strerror(ret));
                return ret;
        }

        return JAYLINK_OK;
}

/**
 * Retrieve the size of free memory of a device.
 *
 * @note This function must only be used if the device has the
 *       #JAYLINK_DEV_CAP_GET_FREE_MEMORY capability.
 *
 * @param[in,out] devh Device handle.
 * @param[out] size Size of free memory in bytes on success, and undefined on
 *                  failure.
 *
 * @retval JAYLINK_OK Success.
 * @retval JAYLINK_ERR_ARG Invalid arguments.
 * @retval JAYLINK_ERR_TIMEOUT A timeout occurred.
 * @retval JAYLINK_ERR_IO Input/output error.
 * @retval JAYLINK_ERR Other error conditions.
 *
 * @since 0.1.0
 */
JAYLINK_API int jaylink_get_free_memory(struct jaylink_device_handle *devh,
                uint32_t *size)
{
        int ret;
        struct jaylink_context *ctx;
        uint8_t buf[4];

        if (!devh || !size)
                return JAYLINK_ERR_ARG;

        ctx = devh->dev->ctx;
        ret = transport_start_write_read(devh, 1, 4, true);

        if (ret != JAYLINK_OK) {
                log_err(ctx, "transport_start_write_read() failed: %s.",
                        jaylink_strerror(ret));
                return ret;
        }

        buf[0] = CMD_GET_FREE_MEMORY;

        ret = transport_write(devh, buf, 1);

        if (ret != JAYLINK_OK) {
                log_err(ctx, "transport_write() failed: %s.",
                        jaylink_strerror(ret));
                return ret;
        }

        ret = transport_read(devh, buf, 4);

        if (ret != JAYLINK_OK) {
                log_err(ctx, "transport_read() failed: %s.",
                        jaylink_strerror(ret));
                return ret;
        }

        *size = buffer_get_u32(buf, 0);

        return JAYLINK_OK;
}

/**
 * Read the raw configuration data of a device.
 *
 * @note This function must only be used if the device has the
 *       #JAYLINK_DEV_CAP_READ_CONFIG capability.
 *
 * @param[in,out] devh Device handle.
 * @param[out] config Buffer to store configuration data on success. Its
 *                    content is undefined on failure. The buffer must be large
 *                    enough to contain at least
 *                    #JAYLINK_DEV_CONFIG_SIZE bytes.
 *
 * @retval JAYLINK_OK Success.
 * @retval JAYLINK_ERR_ARG Invalid arguments.
 * @retval JAYLINK_ERR_TIMEOUT A timeout occurred.
 * @retval JAYLINK_ERR_IO Input/output error.
 * @retval JAYLINK_ERR Other error conditions.
 *
 * @since 0.1.0
 */
JAYLINK_API int jaylink_read_raw_config(struct jaylink_device_handle *devh,
                uint8_t *config)
{
        int ret;
        struct jaylink_context *ctx;
        uint8_t buf[1];

        if (!devh || !config)
                return JAYLINK_ERR_ARG;

        ctx = devh->dev->ctx;
        ret = transport_start_write_read(devh, 1, JAYLINK_DEV_CONFIG_SIZE,
                true);

        if (ret != JAYLINK_OK) {
                log_err(ctx, "transport_start_write_read() failed: %s.",
                        jaylink_strerror(ret));
                return ret;
        }

        buf[0] = CMD_READ_CONFIG;

        ret = transport_write(devh, buf, 1);

        if (ret != JAYLINK_OK) {
                log_err(ctx, "transport_write() failed: %s.",
                        jaylink_strerror(ret));
                return ret;
        }

        ret = transport_read(devh, config, JAYLINK_DEV_CONFIG_SIZE);

        if (ret != JAYLINK_OK) {
                log_err(ctx, "transport_read() failed: %s.",
                        jaylink_strerror(ret));
                return ret;
        }

        return JAYLINK_OK;
}

/**
 * Write the raw configuration data of a device.
 *
 * @note This function must only be used if the device has the
 *       #JAYLINK_DEV_CAP_WRITE_CONFIG capability.
 *
 * @param[in,out] devh Device handle.
 * @param[in] config Buffer to write configuration data from. The size of the
 *                   configuration data is expected to be
 *                   #JAYLINK_DEV_CONFIG_SIZE bytes.
 *
 * @retval JAYLINK_OK Success.
 * @retval JAYLINK_ERR_ARG Invalid arguments.
 * @retval JAYLINK_ERR_TIMEOUT A timeout occurred.
 * @retval JAYLINK_ERR_IO Input/output error.
 * @retval JAYLINK_ERR Other error conditions.
 *
 * @since 0.1.0
 */
JAYLINK_API int jaylink_write_raw_config(struct jaylink_device_handle *devh,
                const uint8_t *config)
{
        int ret;
        struct jaylink_context *ctx;
        uint8_t buf[1];

        if (!devh || !config)
                return JAYLINK_ERR_ARG;

        ctx = devh->dev->ctx;
        ret = transport_start_write(devh, 1 + JAYLINK_DEV_CONFIG_SIZE, true);

        if (ret != JAYLINK_OK) {
                log_err(ctx, "transport_start_write() failed: %s.",
                        jaylink_strerror(ret));
                return ret;
        }

        buf[0] = CMD_WRITE_CONFIG;

        ret = transport_write(devh, buf, 1);

        if (ret != JAYLINK_OK) {
                log_err(ctx, "transport_write() failed: %s.",
                        jaylink_strerror(ret));
                return ret;
        }

        ret = transport_write(devh, config, JAYLINK_DEV_CONFIG_SIZE);

        if (ret != JAYLINK_OK) {
                log_err(ctx, "transport_write() failed: %s.",
                        jaylink_strerror(ret));
                return ret;
        }

        return JAYLINK_OK;
}

static void parse_conntable(struct jaylink_connection *conns,
                const uint8_t *buffer, uint16_t num, uint16_t entry_size)
{
        unsigned int i;
        size_t offset;
        struct in_addr in;

        offset = 0;

        for (i = 0; i < num; i++) {
                conns[i].pid = buffer_get_u32(buffer, offset);

                in.s_addr = buffer_get_u32(buffer, offset + 4);
                /*
                 * Use inet_ntoa() instead of inet_ntop() because the latter
                 * requires at least Windows Vista.
                 */
                strcpy(conns[i].hid, inet_ntoa(in));

                conns[i].iid = buffer[offset + 8];
                conns[i].cid = buffer[offset + 9];
                conns[i].handle = buffer_get_u16(buffer, offset + 10);
                conns[i].timestamp = buffer_get_u32(buffer, offset + 12);
                offset = offset + entry_size;
        }
}

static bool _inet_pton(const char *str, struct in_addr *in)
{
#ifdef _WIN32
        int ret;
        struct sockaddr_in sock_in;
        int length;

        length = sizeof(sock_in);

        /*
         * Use WSAStringToAddress() instead of inet_pton() because the latter
         * requires at least Windows Vista.
         */
        ret = WSAStringToAddress((LPTSTR)str, AF_INET, NULL,
                (LPSOCKADDR)&sock_in, &length);

        if (ret != 0)
                return false;

        *in = sock_in.sin_addr;
#else
        if (inet_pton(AF_INET, str, in) != 1)
                return false;
#endif

        return true;
}

/**
 * Register a connection on a device.
 *
 * A connection can be registered by using 0 as handle. Additional information
 * about the connection can be attached whereby the timestamp is a read-only
 * value and therefore ignored for registration. On success, a new handle
 * greater than 0 is obtained from the device.
 *
 * However, if an obtained handle does not appear in the list of device
 * connections, the connection was not registered because the maximum number of
 * connections on the device is reached.
 *
 * @note This function must only be used if the device has the
 *       #JAYLINK_DEV_CAP_REGISTER capability.
 *
 * Example code:
 * @code{.c}
 * static bool register_connection(struct jaylink_device_handle *devh,
 *                 struct jaylink_connection *conn)
 * {
 *         int ret;
 *         struct jaylink_connection conns[JAYLINK_MAX_CONNECTIONS];
 *         bool found_handle;
 *         size_t count;
 *         size_t i;
 *
 *         conn->handle = 0;
 *         conn->pid = 0;
 *         strcpy(conn->hid, "0.0.0.0");
 *         conn->iid = 0;
 *         conn->cid = 0;
 *
 *         ret = jaylink_register(devh, conn, conns, &count);
 *
 *         if (ret != JAYLINK_OK) {
 *                 printf("jaylink_register() failed: %s.\n",
 *                         jaylink_strerror(ret));
 *                 return false;
 *         }
 *
 *         found_handle = false;
 *
 *         for (i = 0; i < count; i++) {
 *                 if (conns[i].handle == conn->handle) {
 *                         found_handle = true;
 *                         break;
 *                 }
 *         }
 *
 *         if (!found_handle) {
 *                 printf("Maximum number of connections reached.\n");
 *                 return false;
 *         }
 *
 *         printf("Connection successfully registered.\n");
 *
 *         return true;
 * }
 * @endcode
 *
 * @param[in,out] devh Device handle.
 * @param[in,out] connection Connection to register on the device.
 * @param[out] connections Array to store device connections on success.
 *                         Its content is undefined on failure. The array must
 *                         be large enough to contain at least
 *                         #JAYLINK_MAX_CONNECTIONS elements.
 * @param[out] count Number of device connections on success, and undefined on
 *                   failure.
 *
 * @retval JAYLINK_OK Success.
 * @retval JAYLINK_ERR_ARG Invalid arguments.
 * @retval JAYLINK_ERR_TIMEOUT A timeout occurred.
 * @retval JAYLINK_ERR_PROTO Protocol violation.
 * @retval JAYLINK_ERR_IO Input/output error.
 * @retval JAYLINK_ERR Other error conditions.
 *
 * @see jaylink_unregister()
 *
 * @since 0.1.0
 */
JAYLINK_API int jaylink_register(struct jaylink_device_handle *devh,
                struct jaylink_connection *connection,
                struct jaylink_connection *connections, size_t *count)
{
        int ret;
        struct jaylink_context *ctx;
        uint8_t buf[REG_MAX_SIZE];
        uint16_t handle;
        uint16_t num;
        uint16_t entry_size;
        uint32_t size;
        uint32_t table_size;
        uint16_t addinfo_size;
        struct in_addr in;

        if (!devh || !connection || !connections || !count)
                return JAYLINK_ERR_ARG;

        ctx = devh->dev->ctx;

        buf[0] = CMD_REGISTER;
        buf[1] = REG_CMD_REGISTER;
        buffer_set_u32(buf, connection->pid, 2);

        if (!_inet_pton(connection->hid, &in))
                return JAYLINK_ERR_ARG;

        buffer_set_u32(buf, in.s_addr, 6);

        buf[10] = connection->iid;
        buf[11] = connection->cid;
        buffer_set_u16(buf, connection->handle, 12);

        ret = transport_start_write_read(devh, 14, REG_MIN_SIZE, true);

        if (ret != JAYLINK_OK) {
                log_err(ctx, "transport_start_write_read() failed: %s.",
                        jaylink_strerror(ret));
                return ret;
        }

        ret = transport_write(devh, buf, 14);

        if (ret != JAYLINK_OK) {
                log_err(ctx, "transport_write() failed: %s.",
                        jaylink_strerror(ret));
                return ret;
        }

        ret = transport_read(devh, buf, REG_MIN_SIZE);

        if (ret != JAYLINK_OK) {
                log_err(ctx, "transport_read() failed: %s.",
                        jaylink_strerror(ret));
                return ret;
        }

        handle = buffer_get_u16(buf, 0);
        num = buffer_get_u16(buf, 2);
        entry_size = buffer_get_u16(buf, 4);
        addinfo_size = buffer_get_u16(buf, 6);

        if (num > JAYLINK_MAX_CONNECTIONS) {
                log_err(ctx, "Maximum number of device connections exceeded: "
                        "%u.", num);
                return JAYLINK_ERR_PROTO;
        }

        if (entry_size != REG_CONN_INFO_SIZE) {
                log_err(ctx, "Invalid connection entry size: %u bytes.",
                        entry_size);
                return JAYLINK_ERR_PROTO;
        }

        table_size = num * entry_size;
        size = REG_HEADER_SIZE + table_size + addinfo_size;

        if (size > REG_MAX_SIZE) {
                log_err(ctx, "Maximum registration information size exceeded: "
                        "%u bytes.", size);
                return JAYLINK_ERR_PROTO;
        }

        if (size > REG_MIN_SIZE) {
                ret = transport_start_read(devh, size - REG_MIN_SIZE);

                if (ret != JAYLINK_OK) {
                        log_err(ctx, "transport_start_read() failed: %s.",
                                jaylink_strerror(ret));
                        return JAYLINK_ERR;
                }

                ret = transport_read(devh, buf + REG_MIN_SIZE,
                        size - REG_MIN_SIZE);

                if (ret != JAYLINK_OK) {
                        log_err(ctx, "transport_read() failed: %s.",
                                jaylink_strerror(ret));
                        return JAYLINK_ERR;
                }
        }

        if (!handle) {
                log_err(ctx, "Obtained invalid connection handle.");
                return JAYLINK_ERR_PROTO;
        }

        connection->handle = handle;
        parse_conntable(connections, buf + REG_HEADER_SIZE, num, entry_size);

        *count = num;

        return JAYLINK_OK;
}

/**
 * Unregister a connection from a device.
 *
 * @note This function must only be used if the device has the
 *       #JAYLINK_DEV_CAP_REGISTER capability.
 *
 * @param[in,out] devh Device handle.
 * @param[in,out] connection Connection to unregister from the device.
 * @param[out] connections Array to store device connections on success.
 *                         Its content is undefined on failure. The array must
 *                         be large enough to contain at least
 *                         #JAYLINK_MAX_CONNECTIONS elements.
 * @param[out] count Number of device connections on success, and undefined on
 *                   failure.
 *
 * @retval JAYLINK_OK Success.
 * @retval JAYLINK_ERR_ARG Invalid arguments.
 * @retval JAYLINK_ERR_TIMEOUT A timeout occurred.
 * @retval JAYLINK_ERR_PROTO Protocol violation.
 * @retval JAYLINK_ERR_IO Input/output error.
 * @retval JAYLINK_ERR Other error conditions.
 *
 * @see jaylink_register()
 *
 * @since 0.1.0
 */
JAYLINK_API int jaylink_unregister(struct jaylink_device_handle *devh,
                const struct jaylink_connection *connection,
                struct jaylink_connection *connections, size_t *count)
{
        int ret;
        struct jaylink_context *ctx;
        uint8_t buf[REG_MAX_SIZE];
        uint16_t num;
        uint16_t entry_size;
        uint32_t size;
        uint32_t table_size;
        uint16_t addinfo_size;
        struct in_addr in;

        if (!devh || !connection || !connections || !count)
                return JAYLINK_ERR_ARG;

        ctx = devh->dev->ctx;

        buf[0] = CMD_REGISTER;
        buf[1] = REG_CMD_UNREGISTER;
        buffer_set_u32(buf, connection->pid, 2);

        if (!_inet_pton(connection->hid, &in))
                return JAYLINK_ERR_ARG;

        buffer_set_u32(buf, in.s_addr, 6);

        buf[10] = connection->iid;
        buf[11] = connection->cid;
        buffer_set_u16(buf, connection->handle, 12);

        ret = transport_start_write_read(devh, 14, REG_MIN_SIZE, true);

        if (ret != JAYLINK_OK) {
                log_err(ctx, "transport_start_write_read() failed: %s.",
                        jaylink_strerror(ret));
                return ret;
        }

        ret = transport_write(devh, buf, 14);

        if (ret != JAYLINK_OK) {
                log_err(ctx, "transport_write() failed: %s.",
                        jaylink_strerror(ret));
                return ret;
        }

        ret = transport_read(devh, buf, REG_MIN_SIZE);

        if (ret != JAYLINK_OK) {
                log_err(ctx, "transport_read() failed: %s.",
                        jaylink_strerror(ret));
                return ret;
        }

        num = buffer_get_u16(buf, 2);
        entry_size = buffer_get_u16(buf, 4);
        addinfo_size = buffer_get_u16(buf, 6);

        if (num > JAYLINK_MAX_CONNECTIONS) {
                log_err(ctx, "Maximum number of device connections exceeded: "
                        "%u.", num);
                return JAYLINK_ERR_PROTO;
        }

        if (entry_size != REG_CONN_INFO_SIZE) {
                log_err(ctx, "Invalid connection entry size: %u bytes.",
                        entry_size);
                return JAYLINK_ERR_PROTO;
        }

        table_size = num * entry_size;
        size = REG_HEADER_SIZE + table_size + addinfo_size;

        if (size > REG_MAX_SIZE) {
                log_err(ctx, "Maximum registration information size exceeded: "
                        "%u bytes.", size);
                return JAYLINK_ERR_PROTO;
        }

        if (size > REG_MIN_SIZE) {
                ret = transport_start_read(devh, size - REG_MIN_SIZE);

                if (ret != JAYLINK_OK) {
                        log_err(ctx, "transport_start_read() failed: %s.",
                                jaylink_strerror(ret));
                        return JAYLINK_ERR;
                }

                ret = transport_read(devh, buf + REG_MIN_SIZE,
                        size - REG_MIN_SIZE);

                if (ret != JAYLINK_OK) {
                        log_err(ctx, "transport_read() failed: %s.",
                                jaylink_strerror(ret));
                        return JAYLINK_ERR;
                }
        }

        parse_conntable(connections, buf + REG_HEADER_SIZE, num, entry_size);

        *count = num;

        return JAYLINK_OK;
}