fluxengine/dep/libusbp/include/libusbp.h

// Copyright (C) Pololu Corporation.  See www.pololu.com for details.

/*! \file libusbp.h
 *
 * This header file provides the C API for libusbp.
 */

#pragma once

/*! The major component of libusbp's version number.  In accordance with
 * semantic versioning, this gets incremented every time there is a breaking
 * change. */
#define LIBUSBP_VERSION_MAJOR 1

#ifdef __cplusplus
extern "C"
{
#endif

#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>

#ifdef _WIN32
#include <wtypesbase.h>
#endif

#ifdef _WIN32
#define LIBUSBP_DLL_EXPORT __declspec(dllexport)
#define LIBUSBP_DLL_IMPORT __declspec(dllimport)
#else
#define LIBUSBP_DLL_IMPORT __attribute__((visibility("default")))
#define LIBUSBP_DLL_EXPORT __attribute__((visibility("default")))
#endif

#ifdef _MSC_VER
#define LIBUSBP_WARN_UNUSED _Check_return_
#else
#define LIBUSBP_WARN_UNUSED __attribute__((warn_unused_result))
#endif

#ifdef LIBUSBP_STATIC
#define LIBUSBP_API
#else
#ifdef LIBUSBP_EXPORTS
#define LIBUSBP_API LIBUSBP_DLL_EXPORT
#else
#define LIBUSBP_API LIBUSBP_DLL_IMPORT
#endif
#endif

    /*! Some functions in this library return strings to the caller via a char
     * ** argument.  If the function call was successful, it is the caller's
     * responsibility to free those strings by passing them to this function.
     * Passing the NULL pointer to this function is OK.  Do not pass any strings
     * to this function unless they were previously returned by a call to this
     * library.  Do not free the same non-NULL string twice. */
    LIBUSBP_API
    void libusbp_string_free(char*);

    /** libusbp_error
     * **************************************************************/

    /*! A libusbp_error object represents an error that occurred in the library.
     * Many functions return a libusbp_error pointer as a return value.  The
     * convention is that a NULL pointer indicates success.  If the pointer is
     * not NULL, the caller needs to free it at some point by calling
     * libusbp_error_free().
     *
     * NULL is a valid value for a libusbp_error pointer, and can be passed to
     * any function in this library that takes a libusbp_error pointer. */
    typedef struct libusbp_error libusbp_error;

    /*! Each ::libusbp_error can have 0 or more error codes that give additional
     * information about the error that might help the caller take the right
     * action when the error occurs.  This enum defines which error codes are
     * possible. */
    enum libusbp_error_code
    {
        /*! There were problems allocating memory.  A memory shortage might be
         * the root cause of the error, or there might be another error that is
         * masked by the memory problems. */
        LIBUSBP_ERROR_MEMORY = 1,

        /*! It is possible that the error was caused by a temporary condition,
         * such as the operating system taking some time to initialize drivers.
         * Any function that could return this error will say so explicitly in
         * its documentation so you do not have to worry about handling it in
         * too many places. */
        LIBUSBP_ERROR_NOT_READY = 2,

        /*! Access was denied.  A common cause of this error on Windows is that
         *  another application has a handle open to the same device. */
        LIBUSBP_ERROR_ACCESS_DENIED = 3,

        /*! The device does not have a serial number. */
        LIBUSBP_ERROR_NO_SERIAL_NUMBER = 4,

        /*! The device took too long to respond to a request or transfer data.
         */
        LIBUSBP_ERROR_TIMEOUT = 5,

        /*! The error might have been caused by the device being disconnected,
         * but it is possible it was caused by something else. */
        LIBUSBP_ERROR_DEVICE_DISCONNECTED = 6,

        /*! The error might have been caused by the host receiving a STALL
         * packet from the device, but it is possible it was caused by something
         * else. */
        LIBUSBP_ERROR_STALL = 7,

        /*! The error might have been caused by the transfer getting cancelled
         * from the host side.  Some data might have been transferred anyway. */
        LIBUSBP_ERROR_CANCELLED = 8,
    };

    /*! Attempts to copy an error.  If you copy a NULL ::libusbp_error
     * pointer, the result will also be NULL.  If you copy a non-NULL
     * ::libusbp_error pointer, the result will be non-NULL, but if there are
     * issues allocating memory, then the copied error might have different
     * properties than the original error, and it will have the
     * ::LIBUSBP_ERROR_MEMORY code.
     *
     * It is the caller's responsibility to free the copied error. */
    LIBUSBP_API LIBUSBP_WARN_UNUSED libusbp_error* libusbp_error_copy(
        const libusbp_error*);

    /*! Frees a returned error object.  Passing the NULL pointer to this
     * function is OK.  Do not free the same non-NULL error twice. */
    LIBUSBP_API
    void libusbp_error_free(libusbp_error*);

    /*! Returns true if the error has specified error code.  The error codes are
     *  listed in the ::libusbp_error_code enum. */
    LIBUSBP_API bool libusbp_error_has_code(
        const libusbp_error*, uint32_t code);

    /*! Returns an English-language ASCII-encoded string describing the error.
     * The message consists of one or more sentences.  If there are multiple
     * sentences, the earlier ones will typically explain the context that the
     * error happened in.
     *
     * The returned pointer will be valid until the error is freed, at which
     * point it might become invalid.  Do not pass the returned pointer to
     * libusbp_string_free(). */
    LIBUSBP_API const char* libusbp_error_get_message(const libusbp_error*);

    /** libusbp_async_in_pipe
     * ******************************************************/

    /*! A libusbp_async_in_pipe is an object that holds the memory and other
     * data structures for a set of asynchronous USB requests to read data from
     * a non-zero endpoint.  It can be used to read data from a bulk or IN
     * endpoint with high throughput. */
    typedef struct libusbp_async_in_pipe libusbp_async_in_pipe;

    /*! Closes the pipe immediately.  Note that if the pipe has any
     * pending transfers, then it is possible that they cannot be freed
     * by this function.  Freeing a pipe with pending transfers could
     * cause a memory leak, but is otherwise safe. */
    LIBUSBP_API
    void libusbp_async_in_pipe_close(libusbp_async_in_pipe*);

    /*! Allocates buffers and other data structures for performing multiple
     * concurrent transfers on the pipe.
     *
     * The @a transfer_count parameter specifies how many transfers to allocate.
     * You can also think of this as the maximum number of concurrent transfers
     * that can be active at the same time.
     *
     * The @a transfer_size parameter specifies how large each transfer's buffer
     * should be, and is also the number of bytes that will be requested from
     * the operating system when the transfer is submitted.
     *
     * It is best to set the transfer size to a multiple of the maximum packet
     * size of the endpoint.  Otherwise, you might get an error when the device
     * sends more data than can fit in the transfer's buffer.  This type of
     * error is called an overflow.
     *
     * If you want to be reading the pipe every millisecond without gaps, you
     * should set the transfer count high enough so that it would take about 100
     * ms to 250 ms to finish all the transfers.  As long as the operating
     * system runs your process that often, you should be able to keep the USB
     * host controller busy permanently.  (Though we have observed gaps in the
     * transfers when trying to do this inside a VirtualBox machine.)
     *
     * You should not set the transfer count too high, or else it might end up
     * taking a long time to cancel the transfers when you are closing the pipe.
     */
    LIBUSBP_API LIBUSBP_WARN_UNUSED libusbp_error*
    libusbp_async_in_pipe_allocate_transfers(
        libusbp_async_in_pipe*, size_t transfer_count, size_t transfer_size);

    /*! Starts reading data from the pipe. */
    LIBUSBP_API LIBUSBP_WARN_UNUSED libusbp_error*
    libusbp_async_in_pipe_start_endless_transfers(libusbp_async_in_pipe*);

    /*! Checks for new events, such as a transfer completing.  This
     * function and libusbp_async_in_pipe_handle_finished_transfer() should
     * be called regularly in order to get data from the pipe. */
    LIBUSBP_API LIBUSBP_WARN_UNUSED libusbp_error*
    libusbp_async_in_pipe_handle_events(libusbp_async_in_pipe*);

    /*! Retrieves a boolean saying whether there are any pending
     * transfers.  A pending transfer is a transfer that was submitted to
     * the operating system, and it may have been completed, but it has
     * not been passed to the caller yet via
     * libusbp_async_in_pipe_handle_finished_transfer(). */
    LIBUSBP_API LIBUSBP_WARN_UNUSED libusbp_error*
    libusbp_async_in_pipe_has_pending_transfers(
        libusbp_async_in_pipe*, bool* result);

    /*! Checks to see if there is a finished transfer that can be handled.
     * If there is one, then this function retrieves the data from the
     * transfer, the number of bytes transferred, and any error that might
     * have occurred related to the transfer.
     *
     * @param finished An optional output pointer used to return a pointer that
     * indicates whether a transfer was finished.  If the returned value is
     * false, then no transfer was finished, and there is no transfer_error or
     * data to handle.
     *
     * @param buffer An optional output pointer used to return the data
     * from the transfer.  The buffer must be at least as large as the
     * transfer size specifed when
     * libusbp_async_in_pipe_allocate_transfers was called.
     *
     * @param transferred An optional output pointer used to return the
     * number of bytes transferred.
     *
     * @param transfer_error An optional pointer used to return an error
     * related to the transfer, such as a timeout or a cancellation.  If
     * this pointer is provided, and a non-NULL error is returned via it,
     * then the error must later be freed with libusbp_error_free().  There
     * will never be a non-NULL transfer error if there is a regular error
     * returned as the return value of this function. */
    LIBUSBP_API LIBUSBP_WARN_UNUSED libusbp_error*
    libusbp_async_in_pipe_handle_finished_transfer(libusbp_async_in_pipe*,
        bool* finished,
        void* buffer,
        size_t* transferred,
        libusbp_error** transfer_error);

    /*! Cancels all the transfers for this pipe.  The cancellation is
     * asynchronous, so it won't have an immediate effect.  If you want
     * to actually make sure that all the transfers get cancelled, you
     * will need to call libusbp_async_in_pipe_handle_events() and
     * libusbp_async_in_pipe_handle_finished_transfer() repeatedly until
     * libusbp_async_in_pipe_has_pending_transfers() indicates there are
     * no pending transfers left. */
    LIBUSBP_API LIBUSBP_WARN_UNUSED libusbp_error*
    libusbp_async_in_pipe_cancel_transfers(libusbp_async_in_pipe*);

    /** libusbp_device
     * *************************************************************/

    /*! Represents a single USB device.  A composite device with multiple
     * functions is represented by a single libusbp_device object.
     *
     * A NULL libusbp_device pointer is valid and can be passed to any function
     * in this library that takes such pointers.  */
    typedef struct libusbp_device libusbp_device;

    /*! Finds all the USB devices connected to the computer and returns a list
     * of them.
     *
     * The optional @a device_count parameter is used to return the number of
     * devices in the list.  The list is actually one element larger because it
     * ends with a NULL pointer.
     *
     * If this function is successful (the returned error pointer is NULL), then
     * you must later free each device by calling libusbp_device_free() and free
     * the list by calling libusbp_list_free().  The order in which the
     * retrieved objects are freed does not matter. */
    LIBUSBP_API LIBUSBP_WARN_UNUSED libusbp_error*
    libusbp_list_connected_devices(
        libusbp_device*** device_list, size_t* device_count);

    /*! Frees a device list returned by libusbp_list_connected_device(). */
    LIBUSBP_API
    void libusbp_list_free(libusbp_device** list);

    /*! Finds a device with the specified vendor ID and product ID and returns a
     * pointer to it.  If no device can be found, returns a NULL pointer.  If
     * the retrieved device pointer is not NULL, you must free it later by
     * calling libusbp_device_free().  The retrieved device pointer will always
     * be NULL if an error is returned. */
    LIBUSBP_API LIBUSBP_WARN_UNUSED libusbp_error*
    libusbp_find_device_with_vid_pid(
        uint16_t vendor_id, uint16_t product_id, libusbp_device** device);

    /*! Makes a copy of a device object.  If this function is successful, you
     * will need to free the copy by calling libusbp_device_free() at some
     * point. */
    LIBUSBP_API LIBUSBP_WARN_UNUSED libusbp_error* libusbp_device_copy(
        const libusbp_device* source, libusbp_device** dest);

    /*! Frees a device object.  Passing a NULL pointer to this function is OK.
     * Do not free the same non-NULL device twice. */
    LIBUSBP_API void libusbp_device_free(libusbp_device*);

    /*! Gets the USB vendor ID of the device (idVendor). */
    LIBUSBP_API LIBUSBP_WARN_UNUSED libusbp_error* libusbp_device_get_vendor_id(
        const libusbp_device*, uint16_t* vendor_id);

    /*! Gets the USB product ID of the device (idProduct). */
    LIBUSBP_API LIBUSBP_WARN_UNUSED libusbp_error*
    libusbp_device_get_product_id(const libusbp_device*, uint16_t* product_id);

    /*! Gets the USB revision code of the device (bcdDevice). */
    LIBUSBP_API LIBUSBP_WARN_UNUSED libusbp_error* libusbp_device_get_revision(
        const libusbp_device*, uint16_t* revision);

    /*! Gets the serial number of the device as an ASCII-encoded string.
     *
     * On Windows, this just returns the segment of the Device Instance ID after
     * the last slash.  If the device does not have a serial number, it will
     * return some other type of identifier that contains andpersands (&).
     * Windows ignores serial numbers with invalid characters in them.  For more
     * information, see:
     *
     *   https://msdn.microsoft.com/en-us/library/windows/hardware/dn423379#usbsn
     *
     * On other systems, if the device does not have a serial number, then this
     * function returns an error with the code ::LIBUSBP_ERROR_NO_SERIAL_NUMBER.
     *
     * (Most applications should only call this function on specific USB devices
     * that are already known to have serial numbers, in which case the lack of
     * a serial number really does indicate a failure.)
     *
     * You should free the returned string by calling libusbp_string_free(). */
    LIBUSBP_API LIBUSBP_WARN_UNUSED libusbp_error*
    libusbp_device_get_serial_number(
        const libusbp_device*, char** serial_number);

    /*! Gets an operating system-specific string that identifies the device.
     *
     * Note that the level of specificity provided by the ID depends on the
     * system you are on, and whether your device has a USB serial number.  As
     * long as the device remains connected to the bus, this ID is not expected
     * to change and there should be no other devices that have the same ID.
     * However, if the device gets disconnected from the bus, it may be possible
     * for the ID to be reused by another device.
     *
     * @b Windows: This will be a device instance ID, and it will look something
     * like this:
     *
     * <pre>
     * USB\\VID_1FFB&PID_DA01\6&11A23516&18&0000
     * </pre>
     *
     * If your device has a serial number, the part after the slash will be the
     * serial number.  Otherwise, it will be a string with andpersands in it.
     *
     * @b Linux: This will be a sysfs path, and it will look like something like
     * this:
     *
     * <pre>
     * /sys/devices/pci0000:00/0000:00:06.0/usb1/1-2
     * </pre>
     *
     * <b>macOS:</b> This will be an integer from
     * IORegistryEntryGetRegistryEntryID, formatted as a lower-case hex number
     * with no leading zeros.  It will look something like this:
     *
     * <pre>
     * 10000021a
     * </pre>
     */
    LIBUSBP_API LIBUSBP_WARN_UNUSED libusbp_error* libusbp_device_get_os_id(
        const libusbp_device*, char** id);

    /** libusbp_generic_interface
     * **************************************************/

    /*! Represents a generic or vendor-defined interface of a USB device.  A
     * null libusbp_generic_interface pointer is valid and can be passed to any
     * function in this library that takes such pointers. */
    typedef struct libusbp_generic_interface libusbp_generic_interface;

    /*! Creates a generic interface object for a specified interface of the
     * specified USB device.  This function does as many checks as possible to
     * make sure that a handle to the interface could be opened, without
     * actually opening it yet.
     *
     * On all platforms, if a record of the interface cannot be found, then an
     * error is returned with the code LIBUSBP_ERROR_NOT_READY, because this
     * could just be a temporary condition that happens right after the device
     * is plugged in.
     *
     * On Windows, the generic interface must use the WinUSB driver, or this
     * function will fail.  If it is using no driver, that could be a temporary
     * condition, and the error returned will use the LIBUSBP_ERROR_NOT_READY
     * error code.
     *
     * On Linux, if the corresponding devnode file does not exist, an error with
     * code LIBUSBP_ERROR_NOT_READY is returned.  If the interface is assigned
     * to a driver that is not "usbfs", an error is returned.
     *
     * On macOS, we do not have any additional checks beyond just making sure
     * that an entry for the interface is found.  For non-composite devices,
     * that check is deferred until a handle is opened.
     *
     * @param interface_number The lowest @a bInterfaceNumber for the interfaces
     * in the USB function you want to use.
     *
     * @param composite Should be true if the device is composite, and false
     * otherwise.
     *
     * The returned object must be freed with libusbp_generic_interface_free().
     */
    LIBUSBP_API LIBUSBP_WARN_UNUSED libusbp_error*
    libusbp_generic_interface_create(const libusbp_device*,
        uint8_t interface_number,
        bool composite,
        libusbp_generic_interface**);

    /*! Frees the specified generic interface object.  Passing the NULL pointer
     * to this function is OK.  Do not free the same non-NULL pointer twice. */
    LIBUSBP_API void libusbp_generic_interface_free(libusbp_generic_interface*);

    /*! Makes a copy of the generic interface object.  The copy must be freed
     * with libusbp_generic_interface_free(). */
    LIBUSBP_API LIBUSBP_WARN_UNUSED libusbp_error*
    libusbp_generic_interface_copy(const libusbp_generic_interface* source,
        libusbp_generic_interface** dest);

    /*! Returns an operating system-specific string that can be used to uniquely
     * identify this generic interface.
     *
     * <b>Windows:</b> This will be a device instance ID specific to this
     * interface, and it will look something like this:
     *
     * <pre>
     * USB\\VID_1FFB&PID_DA01&MI_00\6&11A23516&18&0000
     * </pre>
     *
     * <b>Linux:</b> This will be a sysfs path specific to this interface, and
     * it will look like something like this:
     *
     * <pre>
     * /sys/devices/pci0000:00/0000:00:06.0/usb1/1-2/1-2:1.0
     * </pre>
     *
     * <b>macOS:</b> This will be an integer from
     * IORegistryEntryGetRegistryEntryID, formatted as a lower-case hex number
     * with no leading zeros.  It will look something like this:
     *
     * <pre>
     * 10000021a
     * </pre>
     */
    LIBUSBP_API LIBUSBP_WARN_UNUSED libusbp_error*
    libusbp_generic_interface_get_os_id(
        const libusbp_generic_interface*, char** id);

    /*! Returns an operating system-specific filename corresponding to this
     * interface.
     *
     * <b>Windows:</b> This will be the name of a file you can use with
     * CreateFile to access the device, and it will look something like this:
     *
     * <pre>
     * \\\\?\\usb#vid_1ffb&pid_da01&mi_00#6&11a23516&18&0000#{99c4bbb0-e925-4397-afee-981cd0702163}
     * </pre>
     *
     * <b>Linux:</b> this will return a device node file name that represents
     * the overall USB device.  It will look something like:
     *
     * <pre>
     * /dev/bus/usb/001/007
     * </pre>
     *
     * <b>macOS:</b> This will be an integer from
     * IORegistryEntryGetRegistryEntryID, formatted as a lower-case hex number
     * with no leading zeros.  It will look something like this:
     *
     * <pre>
     * 10000021a
     * </pre>
     */
    LIBUSBP_API LIBUSBP_WARN_UNUSED libusbp_error*
    libusbp_generic_interface_get_os_filename(
        const libusbp_generic_interface*, char** filename);

    /** libusbp_generic_handle
     * *****************************************************/

    /*! Represents a generic handle to a USB device.  This handle can be used to
     * perform operations such as control transfers and reading and writing data
     * from non-zero endpoints.
     *
     * NULL is a valid value for a libusbp_generic_handle pointer, and can be
     * passed in any functions of this library that take a
     * libusbp_generic_handle pointer. */
    typedef struct libusbp_generic_handle libusbp_generic_handle;

    /*! Opens a generic handle to the specified interface of a USB device which
     * can be used to perform USB I/O operations.
     *
     * The handle must later be closed with libusbp_generic_handle_close().
     *
     * On Windows, for devices using WinUSB, if another application has a handle
     * open already when this function is called, then this function will fail
     * and the returned error will have code ::LIBUSBP_ERROR_ACCESS_DENIED.
     *
     * On macOS, this function will set the device's configuration to 1 as a
     * side effect in case it is not already configured. */
    LIBUSBP_API LIBUSBP_WARN_UNUSED libusbp_error* libusbp_generic_handle_open(
        const libusbp_generic_interface*, libusbp_generic_handle**);

    /*! Closes and frees the specified generic handle.  It is OK to pass NULL to
     * this function.  Do not close the same non-NULL handle twice. All
     * ::libusbp_async_in_pipe objects created by the handle must be closed
     * before closing the handle. */
    LIBUSBP_API
    void libusbp_generic_handle_close(libusbp_generic_handle*);

    /*! Creates a new asynchronous pipe object for reading data in from the
     * device on one of its bulk or interrupt IN endpoints.
     *
     * The behavior of this library is unspecified if you use both an
     * asynchronous IN pipe and synchronous reads with libusbp_read_pipe() on
     * the same pipe of the same generic handle.  One reason for that is because
     * for WinUSB devices, this function enables RAW_IO for the pipe, and it
     * does not turn off RAW_IO again after the pipe is closed.  So the behavior
     * of libusbp_read_pipe() could change depending on whether an asynchronous
     * IN pipe has been used. */
    LIBUSBP_API
    libusbp_error* libusbp_generic_handle_open_async_in_pipe(
        libusbp_generic_handle*,
        uint8_t pipe_id,
        libusbp_async_in_pipe** async_in_pipe);

    /*! Sets a timeout for a particular pipe on the USB device.
     *
     * The @a pipe_id should either be 0 to specify control transfers on
     * endpoint 0, or should be a bEndpointAddress value from one of the
     * device's endpoint descriptors.  Specifying an invalid pipe might result
     * in an error.
     *
     * The timeout value is specified in milliseconds, and a value of 0 means no
     * timeout (wait forever).  If this function is not called, the default
     * behavior of the handle is to have no timeout.
     *
     * The behavior of this function is unspecified if there is any data being
     * transferred on the pipe while this function is running.
     *
     * It is unspecified whether this timeout has an effect on asynchronous
     * transfers. */
    LIBUSBP_API LIBUSBP_WARN_UNUSED libusbp_error*
    libusbp_generic_handle_set_timeout(
        libusbp_generic_handle*, uint8_t pipe_id, uint32_t timeout);

    /*! Performs a synchronous (blocking) control transfer on endpoint 0.
     *
     * Under Linux, this blocking transfer unfortunately cannot be interrupted
     * with Ctrl+C.
     *
     * The @a buffer parameter should point to a buffer that is at least @a
     * wLength bytes long.
     *
     * The @a transferred pointer is optional, and is used to return the number
     * of bytes that were actually transferred.
     *
     * The direction of the transfer is determined by the @a bmRequestType
     * parameter.
     */
    LIBUSBP_API LIBUSBP_WARN_UNUSED libusbp_error* libusbp_control_transfer(
        libusbp_generic_handle*,
        uint8_t bmRequestType,
        uint8_t bRequest,
        uint16_t wValue,
        uint16_t wIndex,
        void* buffer,
        uint16_t wLength,
        size_t* transferred);

    /*! Performs a synchronous (blocking) write of data to a bulk or interrupt
     * endpoint.
     *
     * Under Linux, this blocking transfer unfortunately cannot be interrupted
     * with Ctrl+C.
     *
     * The @a pipe_id parameter specifies which endpoint to use.  This argument
     * should be bEndpointAddress value from one of the device's IN endpoint
     * descriptors.  (Its most significant bit must be 0.)
     *
     * The @a transferred parameter is an optional pointer to a variable that
     * will receive the number of bytes transferred. */
    LIBUSBP_API LIBUSBP_WARN_UNUSED libusbp_error* libusbp_write_pipe(
        libusbp_generic_handle*,
        uint8_t pipe_id,
        const void* buffer,
        size_t size,
        size_t* transferred);

    /*! Performs a synchronous (blocking) read of data from a bulk or interrupt
     * endpoint.
     *
     * It is best to set the buffer size to a multiple of the maximum
     * packet size of the endpoint.  Otherwise, this function might return
     * an error when the device sends more data than can fit in the
     * buffer.  This type of error is called an overflow.
     *
     * Under Linux, this blocking transfer unfortunately cannot be interrupted
     * with Ctrl+C.
     *
     * The @a pipe_id parameter specifies which endpoint to use.  This argument
     * should be bEndpointAddress value from one of the device's IN endpoint
     * descriptors.  (Its most significant bit must be 1.)
     *
     * The @a transferred parameter is an optional pointer to a variable that
     * will receive the number of bytes transferred. */
    LIBUSBP_API LIBUSBP_WARN_UNUSED libusbp_error* libusbp_read_pipe(
        libusbp_generic_handle*,
        uint8_t pipe_id,
        void* buffer,
        size_t size,
        size_t* transferred);

#ifdef __linux__
    /*! Gets the underlying file descriptor of the generic handle.  This
     * function is only available on Linux, and is intended for advanced users.
     * The returned file descriptor will remain open and valid as long as the
     * handle is open and has not been closed. */
    LIBUSBP_API
    int libusbp_generic_handle_get_fd(libusbp_generic_handle*);
#endif

#ifdef _WIN32
    /*! Gets the underlying WinUSB handle for the generic handle.  This function
     * is only available on Windows, and is intended for advanced users.  The
     * returned WinUSB handle will remain open and valid as long as the generic
     * handle is open and has not been closed. */
    LIBUSBP_API
    HANDLE libusbp_generic_handle_get_winusb_handle(libusbp_generic_handle*);
#endif

#ifdef __APPLE__
    /*! Gets the underlying IOCFPlugInInterface object representing the
     * interface. You can cast the returned pointer to a `IOCFPlugInInterface
     * **` and then use `QueryInterface` to get the corresponding
     * `IOUSBInterfaceInterface **`. There is an example of this in
     * generic_handle_test.cpp. */
    LIBUSBP_API
    void** libusbp_generic_handle_get_cf_plug_in(libusbp_generic_handle*);
#endif

    /** libusbp_serial_port
     * ********************************************************/

    /*! Represents a serial port. A null libusbp_serial_port pointer is valid
     * and can be passed to any function in this library that takes such
     * pointers. */
    typedef struct libusbp_serial_port libusbp_serial_port;

    /*! Creates a serial port object for a specified interface of the
     * specified USB device.
     *
     * On all platforms, if a record of the interface cannot be found, then an
     * error is returned with the code LIBUSBP_ERROR_NOT_READY, because this
     * could just be a temporary condition that happens right after the device
     * is plugged in.
     *
     * On macOS, it is assumed that the interface with a @a bInterfaceNumber one
     * greater than @a interface_number is the interface that the
     * IOSerialBSDClient will attach to.  This should be true if the device
     * implements the USB CDC ACM class and has ordered its interfaces so that
     * the control interface is right before the data interface.
     *
     * @param interface_number The lowest @a bInterfaceNumber for the USB
     * interfaces that comprise the serial port.
     *
     * @param composite Should be true if the device is composite, and false
     * otherwise.
     *
     * The returned object must be freed with libusbp_generic_interface_free().
     */
    LIBUSBP_API LIBUSBP_WARN_UNUSED libusbp_error* libusbp_serial_port_create(
        const libusbp_device*,
        uint8_t interface_number,
        bool composite,
        libusbp_serial_port**);

    /*! Frees the specified serial port object.  Passing the NULL pointer to
     * this function is OK.  Do not free the same non-NULL pointer twice. */
    LIBUSBP_API void libusbp_serial_port_free(libusbp_serial_port*);

    /*! Makes a copy of the generic interface object.  The copy must be freed
     * with libusbp_generic_interface_free(). */
    LIBUSBP_API LIBUSBP_WARN_UNUSED libusbp_error* libusbp_serial_port_copy(
        const libusbp_serial_port* source, libusbp_serial_port** dest);

    /*! Gets the user-friendly name of the COM port
     * that could be used to open a handle.
     *
     * On Windows, this will be something like "COM12".
     *
     * On Linux, it will be something like "/dev/ttyACM0".
     *
     * On macOS, it will be something like "/dev/cu.usbmodem012345".
     * Specifically, it will be a call-out device, not a dial-in device.
     *
     * You should free the returned string by calling libusbp_string_free().
     */
    LIBUSBP_API LIBUSBP_WARN_UNUSED libusbp_error* libusbp_serial_port_get_name(
        const libusbp_serial_port*, char** name);

#ifdef __cplusplus
}
#endif