diff options
author | Marc Schink <jaylink-dev@marcschink.de> | 2014-09-28 12:24:27 -0400 |
---|---|---|
committer | Marc Schink <jaylink-dev@marcschink.de> | 2015-03-02 03:20:30 -0500 |
commit | 38e193fc8926771c995f14b445fec167da320228 (patch) | |
tree | 33607cb01d3c4c88b8c1ab60d65c668caaa44ed6 /libjaylink/device.c | |
parent | 89cdbe9de95d6cd4f4a22a2bad2064f84de2c8fb (diff) | |
download | libjaylink-38e193fc8926771c995f14b445fec167da320228.zip libjaylink-38e193fc8926771c995f14b445fec167da320228.tar.gz libjaylink-38e193fc8926771c995f14b445fec167da320228.tar.bz2 |
Improve doxygen documentation.
Diffstat (limited to 'libjaylink/device.c')
-rw-r--r-- | libjaylink/device.c | 113 |
1 files changed, 101 insertions, 12 deletions
diff --git a/libjaylink/device.c b/libjaylink/device.c index aaf1ef1..bcc8cb2 100644 --- a/libjaylink/device.c +++ b/libjaylink/device.c @@ -23,6 +23,13 @@ #include "libjaylink.h" #include "libjaylink-internal.h" +/** + * @file + * + * Device enumeration and handling. + */ + +/** @cond PRIVATE */ #define CMD_GET_VERSION 0x01 #define CMD_SET_SPEED 0x05 #define CMD_GET_HW_STATUS 0x07 @@ -32,7 +39,9 @@ #define CMD_GET_HW_VERSION 0xf0 #define CMD_READ_CONFIG 0xf2 #define CMD_WRITE_CONFIG 0xf3 +/** @endcond */ +/** @private */ struct jaylink_device *device_allocate(struct jaylink_context *ctx) { struct jaylink_device *dev; @@ -59,6 +68,7 @@ struct jaylink_device *device_allocate(struct jaylink_context *ctx) return dev; } +/** @private */ static struct jaylink_device_handle *allocate_device_handle( struct jaylink_device *dev) { @@ -74,40 +84,74 @@ static struct jaylink_device_handle *allocate_device_handle( return devh; } +/** @private */ static void free_device_handle(struct jaylink_device_handle *devh) { jaylink_unref_device(devh->dev); free(devh); } +/** + * Get a list of 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_device_list(). + * + * @return The length of the array excluding the trailing NULL-terminator, or a + * negative error code on failure. + */ ssize_t jaylink_get_device_list(struct jaylink_context *ctx, - struct jaylink_device ***list) + struct jaylink_device ***devices) { - if (!ctx || !list) + if (!ctx || !devices) return JAYLINK_ERR_ARG; - return discovery_get_device_list(ctx, list); + return discovery_get_device_list(ctx, devices); } -void jaylink_free_device_list(struct jaylink_device **list, int unref_devices) +/** + * Free a device list. + * + * @param[in,out] devices Array of device instances. Must be NULL-terminated. + * @param[in] unref_devices Determines whether the device instances should be + * unreferenced. + */ +void jaylink_free_device_list(struct jaylink_device **devices, + int unref_devices) { size_t i; - if (!list) + if (!devices) return; if (unref_devices) { i = 0; - while (list[i]) { - jaylink_unref_device(list[i]); + while (devices[i]) { + jaylink_unref_device(devices[i]); i++; } } - free(list); + free(devices); } +/** + * 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. + */ int jaylink_device_get_serial_number(const struct jaylink_device *dev, uint32_t *serial_number) { @@ -119,6 +163,20 @@ int jaylink_device_get_serial_number(const struct jaylink_device *dev, 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. + * + * @return The USB address of the device on success, or #JAYLINK_ERR_ARG for + * invalid device instance. See #jaylink_usb_address for valid USB + * addresses. + * + * @see jaylink_device_get_serial_number() to get the serial number of a device. + */ int jaylink_device_get_usb_address(const struct jaylink_device *dev) { if (!dev) @@ -127,6 +185,14 @@ int jaylink_device_get_usb_address(const struct jaylink_device *dev) return dev->usb_address; } +/** + * Increment the reference count of a device. + * + * @param[in,out] dev Device instance. + * + * @return The given device instance on success, or NULL for invalid device + * instance. + */ struct jaylink_device *jaylink_ref_device(struct jaylink_device *dev) { if (!dev) @@ -137,6 +203,11 @@ struct jaylink_device *jaylink_ref_device(struct jaylink_device *dev) return dev; } +/** + * Decrement the reference count of a device. + * + * @param[in,out] dev Device instance. + */ void jaylink_unref_device(struct jaylink_device *dev) { if (!dev) @@ -154,6 +225,19 @@ void jaylink_unref_device(struct jaylink_device *dev) } } +/** + * 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 Other error conditions. + */ int jaylink_open(struct jaylink_device *dev, struct jaylink_device_handle **devh) { @@ -182,6 +266,11 @@ int jaylink_open(struct jaylink_device *dev, return JAYLINK_OK; } +/** + * Close a device. + * + * @param[in,out] devh Device instance. + */ void jaylink_close(struct jaylink_device_handle *devh) { if (!devh) @@ -201,8 +290,8 @@ void jaylink_close(struct jaylink_device_handle *devh) * null-terminated and must be free'd by the caller. * * @return The length of the newly allocated firmware version string including - * trailing null-terminator or 0 if the device returns no firmware - * version or any #jaylink_error error code on failure. + * trailing null-terminator, 0 if the device returns no firmware + * version, or a negative error code on failure. */ int jaylink_get_firmware_version(struct jaylink_device_handle *devh, char **version) @@ -403,7 +492,7 @@ int jaylink_get_hardware_status(struct jaylink_device_handle *devh, * capabilities and their bit positions. * * @param[in,out] devh Device handle. - * @param[out] caps Buffer to store capabilities on success. Its value is + * @param[out] caps Buffer to store capabilities on success. Its content is * undefined on failure. The size of the buffer must be large * enough to contain at least #JAYLINK_DEV_CAPS_SIZE bytes. * @@ -463,7 +552,7 @@ int jaylink_get_caps(struct jaylink_device_handle *devh, uint8_t *caps) * #JAYLINK_DEV_CAP_GET_EXT_CAPS capability. * * @param[in,out] devh Device handle. - * @param[out] caps Buffer to store capabilities on success. Its value is + * @param[out] caps Buffer to store capabilities on success. Its content is * undefined on failure. The size of the buffer must be large * enough to contain at least #JAYLINK_DEV_EXT_CAPS_SIZE bytes. * |