libjaylink 0.3.1
Library to access J-Link devices
Loading...
Searching...
No Matches
Functions
device.c File Reference

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.
 
void jaylink_free_devices (struct jaylink_device **devs, bool unref)
 Free devices.
 
int jaylink_device_get_host_interface (const struct jaylink_device *dev, enum jaylink_host_interface *iface)
 Get the host interface of a device.
 
int jaylink_device_get_serial_number (const struct jaylink_device *dev, uint32_t *serial_number)
 Get the serial number of a device.
 
int jaylink_device_get_usb_address (const struct jaylink_device *dev, enum jaylink_usb_address *address)
 Get the USB address of a device.
 
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.
 
int jaylink_device_get_ipv4_address (const struct jaylink_device *dev, char *address)
 Get the IPv4 address string of a device.
 
int jaylink_device_get_mac_address (const struct jaylink_device *dev, uint8_t *address)
 Get the MAC address of a device.
 
int jaylink_device_get_hardware_version (const struct jaylink_device *dev, struct jaylink_hardware_version *version)
 Get the hardware version of a device.
 
int jaylink_device_get_product_name (const struct jaylink_device *dev, char *name)
 Get the product name of a device.
 
int jaylink_device_get_nickname (const struct jaylink_device *dev, char *nickname)
 Get the nickname of a device.
 
struct jaylink_devicejaylink_ref_device (struct jaylink_device *dev)
 Increment the reference count of a device.
 
void jaylink_unref_device (struct jaylink_device *dev)
 Decrement the reference count of a device.
 
int jaylink_open (struct jaylink_device *dev, struct jaylink_device_handle **devh)
 Open a device.
 
int jaylink_close (struct jaylink_device_handle *devh)
 Close a device.
 
struct jaylink_devicejaylink_get_device (struct jaylink_device_handle *devh)
 Get the device instance from a device handle.
 
int jaylink_get_firmware_version (struct jaylink_device_handle *devh, char **version, size_t *length)
 Retrieve the firmware version of a device.
 
int jaylink_get_hardware_info (struct jaylink_device_handle *devh, uint32_t mask, uint32_t *info)
 Retrieve the hardware information of a device.
 
int jaylink_get_counters (struct jaylink_device_handle *devh, uint32_t mask, uint32_t *values)
 Retrieve the counter values of a device.
 
int jaylink_get_hardware_version (struct jaylink_device_handle *devh, struct jaylink_hardware_version *version)
 Retrieve the hardware version of a device.
 
int jaylink_get_hardware_status (struct jaylink_device_handle *devh, struct jaylink_hardware_status *status)
 Retrieve the hardware status of a device.
 
int jaylink_get_caps (struct jaylink_device_handle *devh, uint8_t *caps)
 Retrieve the capabilities of a device.
 
int jaylink_get_extended_caps (struct jaylink_device_handle *devh, uint8_t *caps)
 Retrieve the extended capabilities of a device.
 
int jaylink_get_free_memory (struct jaylink_device_handle *devh, uint32_t *size)
 Retrieve the size of free memory of a device.
 
int jaylink_read_raw_config (struct jaylink_device_handle *devh, uint8_t *config)
 Read the raw configuration data of a device.
 
int jaylink_write_raw_config (struct jaylink_device_handle *devh, const uint8_t *config)
 Write the raw configuration data of a device.
 
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.
 
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.
 

Detailed Description

Device enumeration and handling.

Function Documentation

◆ jaylink_close()

int jaylink_close ( struct jaylink_device_handle * devh)

Close a device.

Parameters
[in,out]devhDevice instance.
Return values
JAYLINK_OKSuccess.
JAYLINK_ERR_ARGInvalid arguments.
JAYLINK_ERROther error conditions.
Since
0.1.0

◆ jaylink_device_get_hardware_version()

int jaylink_device_get_hardware_version ( const struct jaylink_device * dev,
struct jaylink_hardware_version * version )

Get the hardware version of a device.

Note
The hardware type can not be obtained by this function, use jaylink_get_hardware_version() instead.
Parameters
[in]devDevice instance.
[out]versionHardware version of the device on success and undefined on failure.
Return values
JAYLINK_OKSuccess.
JAYLINK_ERR_ARGInvalid arguments.
JAYLINK_ERR_NOT_SUPPORTEDSupported for devices with host interface JAYLINK_HIF_TCP only.
JAYLINK_ERR_NOT_AVAILABLEHardware version is not available.
Since
0.2.0

◆ jaylink_device_get_host_interface()

int jaylink_device_get_host_interface ( const struct jaylink_device * dev,
enum jaylink_host_interface * iface )

Get the host interface of a device.

Parameters
[in]devDevice instance.
[out]ifaceHost interface of the device on success, and undefined on failure.
Return values
JAYLINK_OKSuccess.
JAYLINK_ERR_ARGInvalid arguments.
Since
0.1.0

◆ jaylink_device_get_ipv4_address()

int jaylink_device_get_ipv4_address ( const struct jaylink_device * dev,
char * address )

Get the IPv4 address string of a device.

Parameters
[in]devDevice instance.
[out]addressIPv4 address string in quad-dotted decimal format of the device on success and undefined on failure.
Return values
JAYLINK_OKSuccess.
JAYLINK_ERR_ARGInvalid arguments.
JAYLINK_ERR_NOT_SUPPORTEDSupported for devices with host interface JAYLINK_HIF_TCP only.
Since
0.2.0

◆ jaylink_device_get_mac_address()

int jaylink_device_get_mac_address ( const struct jaylink_device * dev,
uint8_t * address )

Get the MAC address of a device.

Parameters
[in]devDevice instance.
[out]addressMAC address of the device on success and undefined on failure. The length of the MAC address is JAYLINK_MAC_ADDRESS_LENGTH bytes.
Return values
JAYLINK_OKSuccess.
JAYLINK_ERR_ARGInvalid arguments.
JAYLINK_ERR_NOT_SUPPORTEDSupported for devices with host interface JAYLINK_HIF_TCP only.
JAYLINK_ERR_NOT_AVAILABLEMAC address is not available.
Since
0.2.0

◆ jaylink_device_get_nickname()

int jaylink_device_get_nickname ( const struct jaylink_device * dev,
char * nickname )

Get the nickname of a device.

Parameters
[in]devDevice instance.
[out]nicknameNickname of the device on success and undefined on failure. The maximum length of the nickname is JAYLINK_NICKNAME_MAX_LENGTH bytes.
Return values
JAYLINK_OKSuccess.
JAYLINK_ERR_ARGInvalid arguments.
JAYLINK_ERR_NOT_SUPPORTEDSupported for devices with host interface JAYLINK_HIF_TCP only.
JAYLINK_ERR_NOT_AVAILABLENickname is not available.
Since
0.2.0

◆ jaylink_device_get_product_name()

int jaylink_device_get_product_name ( const struct jaylink_device * dev,
char * name )

Get the product name of a device.

Parameters
[in]devDevice instance.
[out]nameProduct name of the device on success and undefined on failure. The maximum length of the product name is JAYLINK_PRODUCT_NAME_MAX_LENGTH bytes.
Return values
JAYLINK_OKSuccess.
JAYLINK_ERR_ARGInvalid arguments.
JAYLINK_ERR_NOT_SUPPORTEDSupported for devices with host interface JAYLINK_HIF_TCP only.
JAYLINK_ERR_NOT_AVAILABLEProduct name is not available.
Since
0.2.0

◆ jaylink_device_get_serial_number()

int jaylink_device_get_serial_number ( const struct jaylink_device * dev,
uint32_t * serial_number )

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.
Parameters
[in]devDevice instance.
[out]serial_numberSerial number of the device on success, and undefined on failure.
Return values
JAYLINK_OKSuccess.
JAYLINK_ERR_ARGInvalid arguments.
JAYLINK_ERR_NOT_AVAILABLESerial number is not available.
Since
0.1.0

◆ jaylink_device_get_usb_address()

int jaylink_device_get_usb_address ( const struct jaylink_device * dev,
enum jaylink_usb_address * address )

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.
Parameters
[in]devDevice instance.
[out]addressUSB address of the device on success, and undefined on failure.
Return values
JAYLINK_OKSuccess.
JAYLINK_ERR_ARGInvalid arguments.
JAYLINK_ERR_NOT_SUPPORTEDSupported for devices with host interface JAYLINK_HIF_USB only.
See also
jaylink_device_get_serial_number()
Since
0.1.0

◆ jaylink_device_get_usb_bus_ports()

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.

Parameters
[in]devDevice instance.
[out]busThe bus number of the device on success and undefined on failure.
[out]portsNewly allocated array which contains the port numbers on success and is undefined on failure. The array must be free'd by the caller.
[out]lengthLength of the port array on success and undefined on failure.
Return values
JAYLINK_OKSuccess.
JAYLINK_ERR_ARGInvalid arguments.
JAYLINK_ERR_MALLOCMemory allocation error.
JAYLINK_ERR_NOT_SUPPORTEDSupported for devices with host interface JAYLINK_HIF_USB only.
Since
0.2.0

◆ jaylink_free_devices()

void jaylink_free_devices ( struct jaylink_device ** devs,
bool unref )

Free devices.

Parameters
[in,out]devsArray of device instances. Must be NULL-terminated.
[in]unrefDetermines whether the device instances should be unreferenced.
See also
jaylink_get_devices()
Since
0.1.0

◆ jaylink_get_caps()

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.

Parameters
[in,out]devhDevice handle.
[out]capsBuffer 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.
Return values
JAYLINK_OKSuccess.
JAYLINK_ERR_ARGInvalid arguments.
JAYLINK_ERR_TIMEOUTA timeout occurred.
JAYLINK_ERR_IOInput/output error.
JAYLINK_ERROther error conditions.
See also
jaylink_get_extended_caps()
jaylink_has_cap()
Since
0.1.0

◆ jaylink_get_counters()

int jaylink_get_counters ( struct jaylink_device_handle * devh,
uint32_t mask,
uint32_t * values )

Retrieve the counter values of a device.

Note
This function must only be used if the device has the JAYLINK_DEV_CAP_GET_COUNTERS capability.
Parameters
[in,out]devhDevice handle.
[in]maskA 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]valuesArray 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.
Return values
JAYLINK_OKSuccess.
JAYLINK_ERR_ARGInvalid arguments.
JAYLINK_ERR_TIMEOUTA timeout occurred.
JAYLINK_ERR_IOInput/output error.
JAYLINK_ERROther error conditions.
Since
0.2.0

◆ jaylink_get_device()

struct jaylink_device * jaylink_get_device ( struct jaylink_device_handle * devh)

Get the device instance from a device handle.

Note
The reference count of the device instance is not increased.
Parameters
[in]devhDevice handle.
Returns
The device instance on success, or NULL on invalid argument.
Since
0.1.0

◆ jaylink_get_devices()

int jaylink_get_devices ( struct jaylink_context * ctx,
struct jaylink_device *** devs,
size_t * count )

Get available devices.

Parameters
[in,out]ctxlibjaylink context.
[out]devsNewly 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]countNumber of available devices on success, and undefined on failure. Can be NULL.
Return values
JAYLINK_OKSuccess.
JAYLINK_ERR_ARGInvalid arguments.
JAYLINK_ERR_MALLOCMemory allocation error.
JAYLINK_ERROther error conditions.
See also
jaylink_discovery_scan()
Since
0.1.0

◆ jaylink_get_extended_caps()

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.

Note
This function must only be used if the device has the JAYLINK_DEV_CAP_GET_EXT_CAPS capability.
Parameters
[in,out]devhDevice handle.
[out]capsBuffer 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.
Return values
JAYLINK_OKSuccess.
JAYLINK_ERR_ARGInvalid arguments.
JAYLINK_ERR_TIMEOUTA timeout occurred.
JAYLINK_ERR_IOInput/output error.
JAYLINK_ERROther error conditions.
See also
jaylink_get_caps()
Since
0.1.0

◆ jaylink_get_firmware_version()

int jaylink_get_firmware_version ( struct jaylink_device_handle * devh,
char ** version,
size_t * length )

Retrieve the firmware version of a device.

Parameters
[in,out]devhDevice handle.
[out]versionNewly 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]lengthLength of the firmware version string including trailing null-terminator on success, and undefined on failure. Zero if no firmware version string is available.
Return values
JAYLINK_OKSuccess.
JAYLINK_ERR_ARGInvalid arguments.
JAYLINK_ERR_TIMEOUTA timeout occurred.
JAYLINK_ERR_MALLOCMemory allocation error.
JAYLINK_ERR_IOInput/output error.
JAYLINK_ERROther error conditions.
Since
0.1.0

◆ jaylink_get_free_memory()

int jaylink_get_free_memory ( struct jaylink_device_handle * devh,
uint32_t * size )

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.
Parameters
[in,out]devhDevice handle.
[out]sizeSize of free memory in bytes on success, and undefined on failure.
Return values
JAYLINK_OKSuccess.
JAYLINK_ERR_ARGInvalid arguments.
JAYLINK_ERR_TIMEOUTA timeout occurred.
JAYLINK_ERR_IOInput/output error.
JAYLINK_ERROther error conditions.
Since
0.1.0

◆ jaylink_get_hardware_info()

int jaylink_get_hardware_info ( struct jaylink_device_handle * devh,
uint32_t mask,
uint32_t * info )

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.
Parameters
[in,out]devhDevice handle.
[in]maskA 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]infoArray 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.
Return values
JAYLINK_OKSuccess.
JAYLINK_ERR_ARGInvalid arguments.
JAYLINK_ERR_TIMEOUTA timeout occurred.
JAYLINK_ERR_IOInput/output error.
JAYLINK_ERROther error conditions.
Since
0.1.0

◆ jaylink_get_hardware_status()

int jaylink_get_hardware_status ( struct jaylink_device_handle * devh,
struct jaylink_hardware_status * status )

Retrieve the hardware status of a device.

Parameters
[in,out]devhDevice handle.
[out]statusHardware status on success, and undefined on failure.
Return values
JAYLINK_OKSuccess.
JAYLINK_ERR_ARGInvalid arguments.
JAYLINK_ERR_TIMEOUTA timeout occurred.
JAYLINK_ERR_IOInput/output error.
JAYLINK_ERROther error conditions.
Since
0.1.0

◆ jaylink_get_hardware_version()

int jaylink_get_hardware_version ( struct jaylink_device_handle * devh,
struct jaylink_hardware_version * version )

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 version where jaylink_hardware_version::type is not covered by jaylink_hardware_type.
Parameters
[in,out]devhDevice handle.
[out]versionHardware version on success, and undefined on failure.
Return values
JAYLINK_OKSuccess.
JAYLINK_ERR_ARGInvalid arguments.
JAYLINK_ERR_TIMEOUTA timeout occurred.
JAYLINK_ERR_IOInput/output error.
JAYLINK_ERROther error conditions.
Since
0.1.0

◆ jaylink_open()

int jaylink_open ( struct jaylink_device * dev,
struct jaylink_device_handle ** devh )

Open a device.

Parameters
[in,out]devDevice instance.
[out]devhNewly allocated handle for the opened device on success, and undefined on failure.
Return values
JAYLINK_OKSuccess.
JAYLINK_ERR_ARGInvalid arguments.
JAYLINK_ERR_TIMEOUTA timeout occurred.
JAYLINK_ERR_MALLOCMemory allocation error.
JAYLINK_ERR_IOInput/output error.
JAYLINK_ERROther error conditions.
Since
0.1.0

◆ jaylink_read_raw_config()

int jaylink_read_raw_config ( struct jaylink_device_handle * devh,
uint8_t * config )

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.
Parameters
[in,out]devhDevice handle.
[out]configBuffer 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.
Return values
JAYLINK_OKSuccess.
JAYLINK_ERR_ARGInvalid arguments.
JAYLINK_ERR_TIMEOUTA timeout occurred.
JAYLINK_ERR_IOInput/output error.
JAYLINK_ERROther error conditions.
Since
0.1.0

◆ jaylink_ref_device()

struct jaylink_device * jaylink_ref_device ( struct jaylink_device * dev)

Increment the reference count of a device.

Parameters
[in,out]devDevice instance.
Returns
The given device instance on success, or NULL on invalid argument.
Since
0.1.0

◆ jaylink_register()

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.

Note
This function must only be used if the device has the JAYLINK_DEV_CAP_REGISTER capability.

Example code:

static bool register_connection(struct jaylink_device_handle *devh,
struct jaylink_connection *conn)
{
int ret;
bool found_handle;
size_t count;
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",
return false;
}
found_handle = false;
for (size_t 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;
}
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.
Definition device.c:1515
const char * jaylink_strerror(int error_code)
Return a human-readable description of a libjaylink error code.
Definition error.c:40
Parameters
[in,out]devhDevice handle.
[in,out]connectionConnection to register on the device.
[out]connectionsArray 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]countNumber of device connections on success, and undefined on failure.
Return values
JAYLINK_OKSuccess.
JAYLINK_ERR_ARGInvalid arguments.
JAYLINK_ERR_TIMEOUTA timeout occurred.
JAYLINK_ERR_PROTOProtocol violation.
JAYLINK_ERR_IOInput/output error.
JAYLINK_ERROther error conditions.
See also
jaylink_unregister()
Since
0.1.0

◆ jaylink_unref_device()

void jaylink_unref_device ( struct jaylink_device * dev)

Decrement the reference count of a device.

Parameters
[in,out]devDevice instance.
Since
0.1.0

◆ jaylink_unregister()

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.

Note
This function must only be used if the device has the JAYLINK_DEV_CAP_REGISTER capability.
Parameters
[in,out]devhDevice handle.
[in,out]connectionConnection to unregister from the device.
[out]connectionsArray 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]countNumber of device connections on success, and undefined on failure.
Return values
JAYLINK_OKSuccess.
JAYLINK_ERR_ARGInvalid arguments.
JAYLINK_ERR_TIMEOUTA timeout occurred.
JAYLINK_ERR_PROTOProtocol violation.
JAYLINK_ERR_IOInput/output error.
JAYLINK_ERROther error conditions.
See also
jaylink_register()
Since
0.1.0

◆ jaylink_write_raw_config()

int jaylink_write_raw_config ( struct jaylink_device_handle * devh,
const uint8_t * config )

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.
Parameters
[in,out]devhDevice handle.
[in]configBuffer to write configuration data from. The size of the configuration data is expected to be JAYLINK_DEV_CONFIG_SIZE bytes.
Return values
JAYLINK_OKSuccess.
JAYLINK_ERR_ARGInvalid arguments.
JAYLINK_ERR_TIMEOUTA timeout occurred.
JAYLINK_ERR_IOInput/output error.
JAYLINK_ERROther error conditions.
Since
0.1.0