libjaylink
0.2.0
Library to access J-Link devices
|
Device enumeration and handling. More...
#include <stdlib.h>
#include <stdint.h>
#include <stdbool.h>
#include <string.h>
#include <sys/socket.h>
#include <arpa/inet.h>
#include "libjaylink.h"
#include "libjaylink-internal.h"
Functions | |
int | jaylink_get_devices (struct jaylink_context *ctx, struct jaylink_device ***devs, size_t *count) |
Get available devices. More... | |
void | jaylink_free_devices (struct jaylink_device **devs, bool unref) |
Free devices. More... | |
int | jaylink_device_get_host_interface (const struct jaylink_device *dev, enum jaylink_host_interface *iface) |
Get the host interface of a device. More... | |
int | jaylink_device_get_serial_number (const struct jaylink_device *dev, uint32_t *serial_number) |
Get the serial number of a device. More... | |
int | jaylink_device_get_usb_address (const struct jaylink_device *dev, enum jaylink_usb_address *address) |
Get the USB address of a device. More... | |
int | jaylink_device_get_usb_bus_ports (const struct jaylink_device *dev, uint8_t *bus, uint8_t **ports, size_t *length) |
Get the USB bus and port numbers of a device. More... | |
int | jaylink_device_get_ipv4_address (const struct jaylink_device *dev, char *address) |
Get the IPv4 address string of a device. More... | |
int | jaylink_device_get_mac_address (const struct jaylink_device *dev, uint8_t *address) |
Get the MAC address of a device. More... | |
int | jaylink_device_get_hardware_version (const struct jaylink_device *dev, struct jaylink_hardware_version *version) |
Get the hardware version of a device. More... | |
int | jaylink_device_get_product_name (const struct jaylink_device *dev, char *name) |
Get the product name of a device. More... | |
int | jaylink_device_get_nickname (const struct jaylink_device *dev, char *nickname) |
Get the nickname of a device. More... | |
struct jaylink_device * | jaylink_ref_device (struct jaylink_device *dev) |
Increment the reference count of a device. More... | |
void | jaylink_unref_device (struct jaylink_device *dev) |
Decrement the reference count of a device. More... | |
int | jaylink_open (struct jaylink_device *dev, struct jaylink_device_handle **devh) |
Open a device. More... | |
int | jaylink_close (struct jaylink_device_handle *devh) |
Close a device. More... | |
struct jaylink_device * | jaylink_get_device (struct jaylink_device_handle *devh) |
Get the device instance from a device handle. More... | |
int | jaylink_get_firmware_version (struct jaylink_device_handle *devh, char **version, size_t *length) |
Retrieve the firmware version of a device. More... | |
int | jaylink_get_hardware_info (struct jaylink_device_handle *devh, uint32_t mask, uint32_t *info) |
Retrieve the hardware information of a device. More... | |
int | jaylink_get_counters (struct jaylink_device_handle *devh, uint32_t mask, uint32_t *values) |
Retrieve the counter values of a device. More... | |
int | jaylink_get_hardware_version (struct jaylink_device_handle *devh, struct jaylink_hardware_version *version) |
Retrieve the hardware version of a device. More... | |
int | jaylink_get_hardware_status (struct jaylink_device_handle *devh, struct jaylink_hardware_status *status) |
Retrieve the hardware status of a device. More... | |
int | jaylink_get_caps (struct jaylink_device_handle *devh, uint8_t *caps) |
Retrieve the capabilities of a device. More... | |
int | jaylink_get_extended_caps (struct jaylink_device_handle *devh, uint8_t *caps) |
Retrieve the extended capabilities of a device. More... | |
int | jaylink_get_free_memory (struct jaylink_device_handle *devh, uint32_t *size) |
Retrieve the size of free memory of a device. More... | |
int | jaylink_read_raw_config (struct jaylink_device_handle *devh, uint8_t *config) |
Read the raw configuration data of a device. More... | |
int | jaylink_write_raw_config (struct jaylink_device_handle *devh, const uint8_t *config) |
Write the raw configuration data of a device. More... | |
int | jaylink_register (struct jaylink_device_handle *devh, struct jaylink_connection *connection, struct jaylink_connection *connections, size_t *count) |
Register a connection on a device. More... | |
int | jaylink_unregister (struct jaylink_device_handle *devh, const struct jaylink_connection *connection, struct jaylink_connection *connections, size_t *count) |
Unregister a connection from a device. More... | |
Device enumeration and handling.
int jaylink_close | ( | struct jaylink_device_handle * | devh | ) |
Close a device.
[in,out] | devh | Device instance. |
JAYLINK_OK | Success. |
JAYLINK_ERR_ARG | Invalid arguments. |
JAYLINK_ERR | Other error conditions. |
int jaylink_device_get_hardware_version | ( | const struct jaylink_device * | dev, |
struct jaylink_hardware_version * | version | ||
) |
Get the hardware version of a device.
[in] | dev | Device instance. |
[out] | version | Hardware version of the device on success and undefined on failure. |
JAYLINK_OK | Success. |
JAYLINK_ERR_ARG | Invalid arguments. |
JAYLINK_ERR_NOT_SUPPORTED | Supported for devices with host interface JAYLINK_HIF_TCP only. |
JAYLINK_ERR_NOT_AVAILABLE | Hardware version is not available. |
int jaylink_device_get_host_interface | ( | const struct jaylink_device * | dev, |
enum jaylink_host_interface * | iface | ||
) |
Get the host interface of a device.
[in] | dev | Device instance. |
[out] | iface | Host interface of the device on success, and undefined on failure. |
JAYLINK_OK | Success. |
JAYLINK_ERR_ARG | Invalid arguments. |
int jaylink_device_get_ipv4_address | ( | const struct jaylink_device * | dev, |
char * | address | ||
) |
Get the IPv4 address string of a device.
[in] | dev | Device instance. |
[out] | address | IPv4 address string in quad-dotted decimal format of the device on success and undefined on failure. |
JAYLINK_OK | Success. |
JAYLINK_ERR_ARG | Invalid arguments. |
JAYLINK_ERR_NOT_SUPPORTED | Supported for devices with host interface JAYLINK_HIF_TCP only. |
int jaylink_device_get_mac_address | ( | const struct jaylink_device * | dev, |
uint8_t * | address | ||
) |
Get the MAC address of a device.
[in] | dev | Device instance. |
[out] | address | MAC address of the device on success and undefined on failure. The length of the MAC address is JAYLINK_MAC_ADDRESS_LENGTH bytes. |
JAYLINK_OK | Success. |
JAYLINK_ERR_ARG | Invalid arguments. |
JAYLINK_ERR_NOT_SUPPORTED | Supported for devices with host interface JAYLINK_HIF_TCP only. |
JAYLINK_ERR_NOT_AVAILABLE | MAC address is not available. |
int jaylink_device_get_nickname | ( | const struct jaylink_device * | dev, |
char * | nickname | ||
) |
Get the nickname of a device.
[in] | dev | Device instance. |
[out] | nickname | Nickname of the device on success and undefined on failure. The maximum length of the nickname is JAYLINK_NICKNAME_MAX_LENGTH bytes. |
JAYLINK_OK | Success. |
JAYLINK_ERR_ARG | Invalid arguments. |
JAYLINK_ERR_NOT_SUPPORTED | Supported for devices with host interface JAYLINK_HIF_TCP only. |
JAYLINK_ERR_NOT_AVAILABLE | Nickname is not available. |
int jaylink_device_get_product_name | ( | const struct jaylink_device * | dev, |
char * | name | ||
) |
Get the product name of a device.
[in] | dev | Device instance. |
[out] | name | Product name of the device on success and undefined on failure. The maximum length of the product name is JAYLINK_PRODUCT_NAME_MAX_LENGTH bytes. |
JAYLINK_OK | Success. |
JAYLINK_ERR_ARG | Invalid arguments. |
JAYLINK_ERR_NOT_SUPPORTED | Supported for devices with host interface JAYLINK_HIF_TCP only. |
JAYLINK_ERR_NOT_AVAILABLE | Product name is not available. |
int jaylink_device_get_serial_number | ( | const struct jaylink_device * | dev, |
uint32_t * | serial_number | ||
) |
Get the serial number of a device.
[in] | dev | Device instance. |
[out] | serial_number | Serial number of the device on success, and undefined on failure. |
JAYLINK_OK | Success. |
JAYLINK_ERR_ARG | Invalid arguments. |
JAYLINK_ERR_NOT_AVAILABLE | Serial number is not available. |
int jaylink_device_get_usb_address | ( | const struct jaylink_device * | dev, |
enum jaylink_usb_address * | address | ||
) |
Get the USB address of a device.
[in] | dev | Device instance. |
[out] | address | USB address of the device on success, and undefined on failure. |
JAYLINK_OK | Success. |
JAYLINK_ERR_ARG | Invalid arguments. |
JAYLINK_ERR_NOT_SUPPORTED | Supported for devices with host interface JAYLINK_HIF_USB only. |
int jaylink_device_get_usb_bus_ports | ( | const struct jaylink_device * | dev, |
uint8_t * | bus, | ||
uint8_t ** | ports, | ||
size_t * | length | ||
) |
Get the USB bus and port numbers of a device.
[in] | dev | Device instance. |
[out] | bus | The bus number of the device on success and undefined on failure. |
[out] | ports | Newly allocated array which contains the port numbers on success and is undefined on failure. The array must be free'd by the caller. |
[out] | length | Length of the port array on success and undefined on failure. |
JAYLINK_OK | Success. |
JAYLINK_ERR_ARG | Invalid arguments. |
JAYLINK_ERR_MALLOC | Memory allocation error. |
JAYLINK_ERR_NOT_SUPPORTED | Supported for devices with host interface JAYLINK_HIF_USB only. |
void jaylink_free_devices | ( | struct jaylink_device ** | devs, |
bool | unref | ||
) |
Free devices.
[in,out] | devs | Array of device instances. Must be NULL-terminated. |
[in] | unref | Determines whether the device instances should be unreferenced. |
int jaylink_get_caps | ( | struct jaylink_device_handle * | devh, |
uint8_t * | caps | ||
) |
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.
[in,out] | devh | Device handle. |
[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. |
JAYLINK_OK | Success. |
JAYLINK_ERR_ARG | Invalid arguments. |
JAYLINK_ERR_TIMEOUT | A timeout occurred. |
JAYLINK_ERR_IO | Input/output error. |
JAYLINK_ERR | Other error conditions. |
int jaylink_get_counters | ( | struct jaylink_device_handle * | devh, |
uint32_t | mask, | ||
uint32_t * | values | ||
) |
Retrieve the counter values of a device.
[in,out] | devh | Device handle. |
[in] | mask | A bit field where each set bit represents a counter value to request. See jaylink_counter for a description of the counters and their bit positions. |
[out] | values | Array to store the counter values 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 mask . |
JAYLINK_OK | Success. |
JAYLINK_ERR_ARG | Invalid arguments. |
JAYLINK_ERR_TIMEOUT | A timeout occurred. |
JAYLINK_ERR_IO | Input/output error. |
JAYLINK_ERR | Other error conditions. |
struct jaylink_device* jaylink_get_device | ( | struct jaylink_device_handle * | devh | ) |
Get the device instance from a device handle.
[in] | devh | Device handle. |
int jaylink_get_devices | ( | struct jaylink_context * | ctx, |
struct jaylink_device *** | devs, | ||
size_t * | count | ||
) |
Get available devices.
[in,out] | ctx | libjaylink context. |
[out] | devs | 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(). |
[out] | count | Number of available devices on success, and undefined on failure. Can be NULL. |
JAYLINK_OK | Success. |
JAYLINK_ERR_ARG | Invalid arguments. |
JAYLINK_ERR_MALLOC | Memory allocation error. |
JAYLINK_ERR | Other error conditions. |
int jaylink_get_extended_caps | ( | struct jaylink_device_handle * | devh, |
uint8_t * | caps | ||
) |
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.
[in,out] | devh | Device handle. |
[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. |
JAYLINK_OK | Success. |
JAYLINK_ERR_ARG | Invalid arguments. |
JAYLINK_ERR_TIMEOUT | A timeout occurred. |
JAYLINK_ERR_IO | Input/output error. |
JAYLINK_ERR | Other error conditions. |
int jaylink_get_firmware_version | ( | struct jaylink_device_handle * | devh, |
char ** | version, | ||
size_t * | length | ||
) |
Retrieve the firmware version of a device.
[in,out] | devh | Device handle. |
[out] | version | Newly allocated string which contains the firmware version on success, and undefined if length is zero or on failure. The string is null-terminated and must be free'd by the caller. |
[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. |
JAYLINK_OK | Success. |
JAYLINK_ERR_ARG | Invalid arguments. |
JAYLINK_ERR_TIMEOUT | A timeout occurred. |
JAYLINK_ERR_MALLOC | Memory allocation error. |
JAYLINK_ERR_IO | Input/output error. |
JAYLINK_ERR | Other error conditions. |
int jaylink_get_free_memory | ( | struct jaylink_device_handle * | devh, |
uint32_t * | size | ||
) |
Retrieve the size of free memory of a device.
[in,out] | devh | Device handle. |
[out] | size | Size of free memory in bytes on success, and undefined on failure. |
JAYLINK_OK | Success. |
JAYLINK_ERR_ARG | Invalid arguments. |
JAYLINK_ERR_TIMEOUT | A timeout occurred. |
JAYLINK_ERR_IO | Input/output error. |
JAYLINK_ERR | Other error conditions. |
int jaylink_get_hardware_info | ( | struct jaylink_device_handle * | devh, |
uint32_t | mask, | ||
uint32_t * | info | ||
) |
Retrieve the hardware information of a device.
[in,out] | devh | Device handle. |
[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. |
[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 mask. |
JAYLINK_OK | Success. |
JAYLINK_ERR_ARG | Invalid arguments. |
JAYLINK_ERR_TIMEOUT | A timeout occurred. |
JAYLINK_ERR_IO | Input/output error. |
JAYLINK_ERR | Other error conditions. |
int jaylink_get_hardware_status | ( | struct jaylink_device_handle * | devh, |
struct jaylink_hardware_status * | status | ||
) |
Retrieve the hardware status of a device.
[in,out] | devh | Device handle. |
[out] | status | Hardware status on success, and undefined on failure. |
JAYLINK_OK | Success. |
JAYLINK_ERR_ARG | Invalid arguments. |
JAYLINK_ERR_TIMEOUT | A timeout occurred. |
JAYLINK_ERR_IO | Input/output error. |
JAYLINK_ERR | Other error conditions. |
int jaylink_get_hardware_version | ( | struct jaylink_device_handle * | devh, |
struct jaylink_hardware_version * | version | ||
) |
Retrieve the hardware version of a device.
version
where jaylink_hardware_version::type is not covered by jaylink_hardware_type.[in,out] | devh | Device handle. |
[out] | version | Hardware version on success, and undefined on failure. |
JAYLINK_OK | Success. |
JAYLINK_ERR_ARG | Invalid arguments. |
JAYLINK_ERR_TIMEOUT | A timeout occurred. |
JAYLINK_ERR_IO | Input/output error. |
JAYLINK_ERR | Other error conditions. |
int jaylink_open | ( | struct jaylink_device * | dev, |
struct jaylink_device_handle ** | devh | ||
) |
Open a device.
[in,out] | dev | Device instance. |
[out] | devh | Newly allocated handle for the opened device on success, and undefined on failure. |
JAYLINK_OK | Success. |
JAYLINK_ERR_ARG | Invalid arguments. |
JAYLINK_ERR_TIMEOUT | A timeout occurred. |
JAYLINK_ERR_MALLOC | Memory allocation error. |
JAYLINK_ERR_IO | Input/output error. |
JAYLINK_ERR | Other error conditions. |
int jaylink_read_raw_config | ( | struct jaylink_device_handle * | devh, |
uint8_t * | config | ||
) |
Read the raw configuration data of a device.
[in,out] | devh | Device handle. |
[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. |
JAYLINK_OK | Success. |
JAYLINK_ERR_ARG | Invalid arguments. |
JAYLINK_ERR_TIMEOUT | A timeout occurred. |
JAYLINK_ERR_IO | Input/output error. |
JAYLINK_ERR | Other error conditions. |
struct jaylink_device* jaylink_ref_device | ( | struct jaylink_device * | dev | ) |
Increment the reference count of a device.
[in,out] | dev | Device instance. |
int jaylink_register | ( | struct jaylink_device_handle * | devh, |
struct jaylink_connection * | connection, | ||
struct jaylink_connection * | connections, | ||
size_t * | count | ||
) |
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.
Example code:
[in,out] | devh | Device handle. |
[in,out] | connection | Connection to register on the device. |
[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. |
[out] | count | Number of device connections on success, and undefined on failure. |
JAYLINK_OK | Success. |
JAYLINK_ERR_ARG | Invalid arguments. |
JAYLINK_ERR_TIMEOUT | A timeout occurred. |
JAYLINK_ERR_PROTO | Protocol violation. |
JAYLINK_ERR_IO | Input/output error. |
JAYLINK_ERR | Other error conditions. |
void jaylink_unref_device | ( | struct jaylink_device * | dev | ) |
Decrement the reference count of a device.
[in,out] | dev | Device instance. |
int jaylink_unregister | ( | struct jaylink_device_handle * | devh, |
const struct jaylink_connection * | connection, | ||
struct jaylink_connection * | connections, | ||
size_t * | count | ||
) |
Unregister a connection from a device.
[in,out] | devh | Device handle. |
[in,out] | connection | Connection to unregister from the device. |
[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. |
[out] | count | Number of device connections on success, and undefined on failure. |
JAYLINK_OK | Success. |
JAYLINK_ERR_ARG | Invalid arguments. |
JAYLINK_ERR_TIMEOUT | A timeout occurred. |
JAYLINK_ERR_PROTO | Protocol violation. |
JAYLINK_ERR_IO | Input/output error. |
JAYLINK_ERR | Other error conditions. |
int jaylink_write_raw_config | ( | struct jaylink_device_handle * | devh, |
const uint8_t * | config | ||
) |
Write the raw configuration data of a device.
[in,out] | devh | Device handle. |
[in] | config | Buffer to write configuration data from. The size of the configuration data is expected to be JAYLINK_DEV_CONFIG_SIZE bytes. |
JAYLINK_OK | Success. |
JAYLINK_ERR_ARG | Invalid arguments. |
JAYLINK_ERR_TIMEOUT | A timeout occurred. |
JAYLINK_ERR_IO | Input/output error. |
JAYLINK_ERR | Other error conditions. |