File cl_api.h

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

Classes

Type	Name
struct	cl_eth_config_t Ethernet config. Contains an auto negotiation setting (IEEE aneg enabled or disabled), one or more speed settings (ORed) and one or more link roles (ORed)
struct	cl_eth_interface_status_t Ethernet interface status. Has a link state (UP/DOWN), and if it is up, it'll also contain a speed and role that is determined by what was negotiated (or set, if not using aneg) for the link.
struct	cl_firmware_update_callbacks_t Struct containing function pointers to callbacks, to be called throughout the update process. Used with cl_device_update_firmware_from_blob andcl_device_update_firmware_from_path .
struct	cl_interface_status_t Interface status contains the status for an interface. It consists of struct_size, struct_version, interface_type and eth_interface_status.

Public Types

Type	Name
enum	cl_aneg_mode_t Ethernet auto negotiation.
typedef enum cl_aneg_mode_t	cl_aneg_mode_t Ethernet auto negotiation.
typedef struct cl_client_t	cl_client_t cl_client_t is the opaque pointer type used as a handle for all client operations
typedef struct cl_device_iterator_t	cl_device_iterator_t cl_device_iterator is the opaque pointer type used as a device list iterator
typedef struct cl_device_list_t *	cl_device_list_ptr_t cl_device_list__ptr_t is used as in parameter to functions that "return" a cl_device_list_t*
typedef struct cl_device_list_t	cl_device_list_t cl_device_list_t is the opaque pointer type used as a handle a collection of devices
typedef struct cl_device_t	cl_device_t cl_device_t is the opaque pointer type used as a handle for all device operations
typedef struct cl_eth_config_t	cl_eth_config_t Ethernet config. Contains an auto negotiation setting (IEEE aneg enabled or disabled), one or more speed settings (ORed) and one or more link roles (ORed)
typedef struct cl_eth_interface_status_t	cl_eth_interface_status_t Ethernet interface status. Has a link state (UP/DOWN), and if it is up, it'll also contain a speed and role that is determined by what was negotiated (or set, if not using aneg) for the link.
typedef struct cl_firmware_update_callbacks_t	cl_firmware_update_callbacks_t Struct containing function pointers to callbacks, to be called throughout the update process. Used with cl_device_update_firmware_from_blob andcl_device_update_firmware_from_path .
enum	cl_firmware_update_result_t
typedef enum cl_firmware_update_result_t	cl_firmware_update_result_t
typedef struct cl_interface_iterator_t	cl_interface_iterator_t cl_interface_iterator_t is the opaque pointer type used as a interface list iterator
typedef struct cl_interface_list_t *	cl_interface_list_ptr_t cl_interface_list_ptr_t is used as in parameter to functions that "return" a cl_interface_list_t*
typedef struct cl_interface_list_t	cl_interface_list_t cl_interface_list_t is the opaque pointer type used as a handle a collection of interfaces
typedef struct cl_interface_status_t	cl_interface_status_t Interface status contains the status for an interface. It consists of struct_size, struct_version, interface_type and eth_interface_status.
typedef struct cl_interface_t	cl_interface_t cl_interface_t is the opaque pointer type used as a handle for all interface operations
enum	cl_interface_type_t Interface type.
typedef enum cl_interface_type_t	cl_interface_type_t Interface type.
enum	cl_link_role_t Ethernet role.
typedef uint32_t	cl_link_role_t
enum	cl_link_speed_t Ethernet link speed.
typedef uint32_t	cl_link_speed_t
enum	cl_link_state_t Ethernet link state.
typedef enum cl_link_state_t	cl_link_state_t Ethernet link state.
enum	cl_status_t
typedef enum cl_status_t	cl_status_t
enum	cl_tc10_command_t
typedef enum cl_tc10_command_t	cl_tc10_command_t
enum	cl_tc10_state_t
typedef enum cl_tc10_state_t	cl_tc10_state_t

Public Functions

Type	Name
struct cl_client_t *	cl_client_create (void) Creates a client handle, to be used for all general library functions, must be freed with cl_client_destroy to free memery.
void	cl_client_destroy (struct cl_client_t * client) Frees the given client handle.
enum cl_status_t	cl_client_scan_for_devices (struct cl_client_t * client, cl_device_list_ptr_t * device_list) Uses DNS-SD to scan for cl devices on the local network (ethernet over USB)
enum cl_status_t	cl_client_scan_for_devices_with_timeout (struct cl_client_t * client, cl_device_list_ptr_t * device_list, uint32_t timeout_ms) Uses DNS-SD to scan for cl devices on the local network (ethernet over USB). This version of the function has an adjustable timeout to allow shorter or longer scan time. Default scan time is 1000ms.
enum cl_status_t	cl_device_get_bootloader_version (struct cl_device_t * device, char * buffer, size_t buffer_size) Gets the bootloader version as a semver string.
enum cl_status_t	cl_device_get_ean (struct cl_device_t * device, uint64_t * ean) Gets the 64bit EAN.
enum cl_status_t	cl_device_get_feature_ean (struct cl_device_t * device, uint64_t * ean) Gets the 64bit feature EAN.
enum cl_status_t	cl_device_get_firmware_ean (struct cl_device_t * device, uint64_t * ean) Gets the 64bit firmware EAN.
enum cl_status_t	cl_device_get_firmware_version (struct cl_device_t * device, char * buffer, size_t buffer_size) Gets the firmware version as a semver string.
enum cl_status_t	cl_device_get_interfaces (struct cl_device_t * device, cl_interface_list_ptr_t * interface_list) Gets the interfaces for the given device.
enum cl_status_t	cl_device_get_manufacturing_date (struct cl_device_t * device, uint64_t * timestamp) Gets the device manufacturing date as string.
enum cl_status_t	cl_device_get_name (struct cl_device_t * device, char * buffer, size_t buffer_size) Gets the device name. The returned string will be null terminated.
enum cl_status_t	cl_device_get_nickname (struct cl_device_t * device, char * buffer, size_t buffer_size) Gets the device nickname. The returned string will be null terminated.
enum cl_status_t	cl_device_get_pcb_revision (struct cl_device_t * device, char * buffer, size_t buffer_size) Gets the PCB revision as a string.
enum cl_status_t	cl_device_get_serial_number (struct cl_device_t * device, uint64_t * serial_number) Gets the 64bit serial_number.
enum cl_status_t	cl_device_identify (struct cl_device_t * device) Trigger identify device sequence (flash device LEDs)
struct cl_device_iterator_t *	cl_device_iterator_create (cl_device_list_ptr_t device_list) Creates a device iterator. To be used with cl_device_iterator_next. cl_device_iterator_destroy must be called to free memory when done with the iterator.
void	cl_device_iterator_destroy (struct cl_device_iterator_t * iterator) Frees the given device iterotor.
struct cl_device_t *	cl_device_iterator_next (struct cl_device_iterator_t * iterator) Gets the next device.
void	cl_device_list_destroy (cl_device_list_ptr_t device_list) Frees the given device_list.
struct cl_device_t *	cl_device_list_find_by_index (size_t index, cl_device_list_ptr_t device_list) Finds a device from the given index.
struct cl_device_t *	cl_device_list_find_by_info (const uint64_t * ean, uint64_t serial_number, cl_device_list_ptr_t device_list) Finds a device from the given ean and serial number.
enum cl_status_t	cl_device_set_nickname (struct cl_device_t * device, const char * name) Sets the given null terminated device_nickname.
enum cl_status_t	cl_device_update_firmware_from_blob (struct cl_device_t * device, const char * firmware_blob, size_t size, const struct cl_firmware_update_callbacks_t * callbacks) Sends a new firmware blob to the device.
enum cl_status_t	cl_device_update_firmware_from_path (struct cl_device_t * device, const char * firmware_path, const struct cl_firmware_update_callbacks_t * callbacks) Sends a new firmware from file at the given path to the device.
enum cl_status_t	cl_format_ean (uint64_t ean, char * buffer, size_t buffer_size) This is a helper to format an EAN number using the format XX-XXXXX-XXXXX-X.
enum cl_status_t	cl_format_serial_number (uint64_t serial_number, char * buffer, size_t buffer_size) This is a helper to format a serial number using the format 0000000 (essentially just a "%07lu" format string)
void	cl_get_api_version (uint32_t * major, uint32_t * minor, uint32_t * patch) Returns the API version.
enum cl_status_t	cl_interface_eth_get_config (struct cl_interface_t * interface, struct cl_eth_config_t * config) Gets the interface link configuration for an ethernet interface.
enum cl_status_t	cl_interface_eth_get_supported_configs (struct cl_interface_t * interface, struct cl_eth_config_t * config) Gets the supported configuration options for the given interface.
enum cl_status_t	cl_interface_eth_set_config (struct cl_interface_t * interface, struct cl_eth_config_t config) Sets the interface link mode for an ethernet interface.
enum cl_status_t	cl_interface_get_nickname (struct cl_interface_t * interface, char * buffer, size_t buffer_size) Gets the interface nickname.
enum cl_status_t	cl_interface_get_status (struct cl_interface_t * interface, struct cl_interface_status_t * status) Gets the interface status.
enum cl_status_t	cl_interface_get_tc10_state (struct cl_interface_t * interface, enum cl_tc10_state_t * state) Reads the current tc10 state for the given interface.
enum cl_status_t	cl_interface_identify (struct cl_interface_t * interface) Triggers identify interface sequence (flash interface LEDs) to help identify the given interface.
struct cl_interface_iterator_t *	cl_interface_iterator_create (struct cl_interface_list_t * interface_list) Creates an iterator to be used to access the interfaces from an cl_interface_list_t .
void	cl_interface_iterator_destroy (struct cl_interface_iterator_t * iterator) Frees the given interface iterotor.
struct cl_interface_t *	cl_interface_iterator_next (struct cl_interface_iterator_t * iterator) Gets the next interface.
void	cl_interface_list_destroy (cl_interface_list_ptr_t interface_list) Frees the given interface_list.
enum cl_status_t	cl_interface_send_tc10_command (struct cl_interface_t * interface, enum cl_tc10_command_t command) Sends the given tc10 command to the given interface.
enum cl_status_t	cl_interface_set_nickname (struct cl_interface_t * interface, const char * name) Sets the given null terminated interface nickname.

Macros

Type	Name
define	CL_API CL_API will be expanded to __declspec(dllimport) on windows, on Linux it expands to nothing.
define	CL_CC CL_CC will be expanded to __stdcall when compiling for 32bit windows applications, on Linux and 64bit windows it expands to nothing (use default calling convention for the platform).
define	CL_INTERFACE_STATUS_T_VERSION `1`

Public Types Documentation

enum cl_aneg_mode_t

Ethernet auto negotiation.

enum cl_aneg_mode_t {
    CL_ETH_ANEG_MODE_DISABLED = 0,
    CL_ETH_ANEG_MODE_IEEE_ANEG_ENABLED = 1
};

typedef cl_aneg_mode_t

Ethernet auto negotiation.

typedef enum cl_aneg_mode_t cl_aneg_mode_t;

typedef cl_client_t

cl_client_t is the opaque pointer type used as a handle for all client operations

typedef struct cl_client_t cl_client_t;

typedef cl_device_iterator_t

cl_device_iterator is the opaque pointer type used as a device list iterator

typedef struct cl_device_iterator_t cl_device_iterator_t;

typedef cl_device_list_ptr_t

cl_device_list__ptr_t is used as in parameter to functions that "return" a cl_device_list_t*

typedef struct cl_device_list_t* cl_device_list_ptr_t;

typedef cl_device_list_t

cl_device_list_t is the opaque pointer type used as a handle a collection of devices

typedef struct cl_device_list_t cl_device_list_t;

typedef cl_device_t

cl_device_t is the opaque pointer type used as a handle for all device operations

typedef struct cl_device_t cl_device_t;

typedef cl_eth_config_t

Ethernet config. Contains an auto negotiation setting (IEEE aneg enabled or disabled), one or more speed settings (ORed) and one or more link roles (ORed)

typedef struct cl_eth_config_t cl_eth_config_t;

typedef cl_eth_interface_status_t

Ethernet interface status. Has a link state (UP/DOWN), and if it is up, it'll also contain a speed and role that is determined by what was negotiated (or set, if not using aneg) for the link.

typedef struct cl_eth_interface_status_t cl_eth_interface_status_t;

typedef cl_firmware_update_callbacks_t

Struct containing function pointers to callbacks, to be called throughout the update process. Used with cl_device_update_firmware_from_blob andcl_device_update_firmware_from_path .

typedef struct cl_firmware_update_callbacks_t cl_firmware_update_callbacks_t;

enum cl_firmware_update_result_t

enum cl_firmware_update_result_t {
    CL_UF_STATUS_SUCCESS = 0,
    CL_UF_STATUS_TRANSFER_ERROR = 1,
    CL_UF_STATUS_FIRMWARE_FAILED_SIGNATURE_CHECK = 2,
    CL_UF_STATUS_FIRMWARE_CORRUPT = 3,
    CL_UF_STATUS_FIRMWARE_FOR_OTHER_DEVICE = 4,
    CL_UF_STATUS_UNKNOWN_ERROR = 5
};

Enum containing possible update results

typedef cl_firmware_update_result_t

typedef enum cl_firmware_update_result_t cl_firmware_update_result_t;

Enum containing possible update results

typedef cl_interface_iterator_t

cl_interface_iterator_t is the opaque pointer type used as a interface list iterator

typedef struct cl_interface_iterator_t cl_interface_iterator_t;

typedef cl_interface_list_ptr_t

cl_interface_list_ptr_t is used as in parameter to functions that "return" a cl_interface_list_t*

typedef struct cl_interface_list_t* cl_interface_list_ptr_t;

typedef cl_interface_list_t

cl_interface_list_t is the opaque pointer type used as a handle a collection of interfaces

typedef struct cl_interface_list_t cl_interface_list_t;

typedef cl_interface_status_t

Interface status contains the status for an interface. It consists of struct_size, struct_version, interface_type and eth_interface_status.

typedef struct cl_interface_status_t cl_interface_status_t;

The struct_size and struct_version are there to allow for this struct to grow in future versions of this API without breaking the ABI. To use it you'll want to initialize it before use as follows:

cl_interface_status_t interface_status = {
    .struct_size = sizeof(interface_status),
    .struct_version = CL_INTERFACE_STATUS_T_VERSION,
};
cl_status_t status = cl_interface_get_status(interface, &interface_status);

typedef cl_interface_t

cl_interface_t is the opaque pointer type used as a handle for all interface operations

typedef struct cl_interface_t cl_interface_t;

enum cl_interface_type_t

Interface type.

enum cl_interface_type_t {
    CL_INTERFACE_TYPE_T1 = 0,
    _RESERVED = 1,
    CL_INTERFACE_TYPE_T = 2
};

typedef cl_interface_type_t

Interface type.

typedef enum cl_interface_type_t cl_interface_type_t;

enum cl_link_role_t

Ethernet role.

enum cl_link_role_t {
    CL_ETH_LINK_ROLE_INVALID = 0,
    CL_ETH_LINK_ROLE_LEADER = 1,
    CL_ETH_LINK_ROLE_LEADER_PREFERRED = 2,
    CL_ETH_LINK_ROLE_FOLLOWER = 4,
    CL_ETH_LINK_ROLE_FOLLOWER_PREFERRED = 8
};

typedef cl_link_role_t

typedef uint32_t cl_link_role_t;

enum cl_link_speed_t

Ethernet link speed.

enum cl_link_speed_t {
    CL_ETH_LINK_SPEED_INVALID = 0,
    CL_ETH_LINK_SPEED_10MBIT_HALF_DUPLEX = 1,
    CL_ETH_LINK_SPEED_10MBIT_FULL_DUPLEX = 2,
    CL_ETH_LINK_SPEED_100MBIT_HALF_DUPLEX = 4,
    CL_ETH_LINK_SPEED_100MBIT_FULL_DUPLEX = 8,
    CL_ETH_LINK_SPEED_1000MBIT_HALF_DUPLEX = 16,
    CL_ETH_LINK_SPEED_1000MBIT_FULL_DUPLEX = 32
};

typedef cl_link_speed_t

typedef uint32_t cl_link_speed_t;

enum cl_link_state_t

Ethernet link state.

enum cl_link_state_t {
    CL_ETH_LINK_STATE_DOWN,
    CL_ETH_LINK_STATE_UP
};

typedef cl_link_state_t

Ethernet link state.

typedef enum cl_link_state_t cl_link_state_t;

enum cl_status_t

enum cl_status_t {
    CL_STATUS_SUCCESS = 0,
    CL_STATUS_OPERATION_NOT_PERMITTED = 10,
    CL_STATUS_OPERATION_FAILED = 11,
    CL_STATUS_OPERATION_NOT_SUPPORTED_BY_DEVICE = 12,
    CL_STATUS_OPERATION_NOT_SUPPORTED_BY_INTERFACE = 13,
    CL_STATUS_OPERATION_NOT_SUPPORTED_BY_DEVICE_FIRMWARE = 14,
    CL_STATUS_UNKNOWN_NETWORK_ERROR = 102,
    CL_STATUS_UNABLE_TO_CONNECT = 103,
    CL_STATUS_SOCKET_WRITE_ERROR = 105,
    CL_STATUS_SOCKET_READ_ERROR = 106,
    CL_STATUS_FILE_OPEN_ERROR = 150,
    CL_STATUS_FILE_READ_ERROR = 151,
    CL_STATUS_THREADING_ERROR = 160,
    CL_STATUS_NOT_IMPLEMENTED = 200,
    CL_STATUS_BUFFER_TOO_SMALL = 201,
    CL_STATUS_DEVICE_NOT_SUPPORTED_BY_CLIENT = 205,
    CL_STATUS_INVALID_USAGE = 207,
    CL_STATUS_INVALID_UTF8 = 208,
    CL_STATUS_UNSPECIFIED_ERROR = 1000
};

typedef cl_status_t

typedef enum cl_status_t cl_status_t;

enum cl_tc10_command_t

enum cl_tc10_command_t {
    CL_TC10_CMD_SLEEP = 0,
    CL_TC10_CMD_WAKE_UP = 1
};

The available TC10 commands

typedef cl_tc10_command_t

typedef enum cl_tc10_command_t cl_tc10_command_t;

The available TC10 commands

enum cl_tc10_state_t

enum cl_tc10_state_t {
    CL_TC10_STATE_NORMAL = 0,
    CL_TC10_STATE_SLEEP = 1,
    CL_TC10_STATE_SLEEP_FAILED = 2,
    CL_TC10_STATE_SLEEP_ABORTED = 3,
    CL_TC10_STATE_UNKNOWN = 4
};

The different possible TC10 states

typedef cl_tc10_state_t

typedef enum cl_tc10_state_t cl_tc10_state_t;

The different possible TC10 states

Public Functions Documentation

function cl_client_create

Creates a client handle, to be used for all general library functions, must be freed with cl_client_destroy to free memery.

struct cl_client_t * cl_client_create (
    void
)

Returns:

a new client handle

function cl_client_destroy

Frees the given client handle.

void cl_client_destroy (
    struct cl_client_t * client
)

Parameters:

client the client handle to free

function cl_client_scan_for_devices

Uses DNS-SD to scan for cl devices on the local network (ethernet over USB)

enum cl_status_t cl_client_scan_for_devices (
    struct cl_client_t * client,
    cl_device_list_ptr_t * device_list
)

Parameters:

client The client handle to use for the scan
device_list in parameter to store the scan result in

Returns:

status code, see cl_status_t for possible codes

function cl_client_scan_for_devices_with_timeout

Uses DNS-SD to scan for cl devices on the local network (ethernet over USB). This version of the function has an adjustable timeout to allow shorter or longer scan time. Default scan time is 1000ms.

enum cl_status_t cl_client_scan_for_devices_with_timeout (
    struct cl_client_t * client,
    cl_device_list_ptr_t * device_list,
    uint32_t timeout_ms
)

Parameters:

client The client handle to use for the scan
device_list in parameter to store the scan result in
timeout_ms the timeout to use

Returns:

status code, see cl_status_t for possible codes

function cl_device_get_bootloader_version

Gets the bootloader version as a semver string.

enum cl_status_t cl_device_get_bootloader_version (
    struct cl_device_t * device,
    char * buffer,
    size_t buffer_size
)

Parameters:

device The target device
buffer Buffer to store the version string in
buffer_size Size of the buffer

Returns:

status code, see cl_status_t for possible codes

function cl_device_get_ean

Gets the 64bit EAN.

enum cl_status_t cl_device_get_ean (
    struct cl_device_t * device,
    uint64_t * ean
)

Parameters:

device The target device
ean Out parameter

Returns:

status code, see cl_status_t for possible codes

function cl_device_get_feature_ean

Gets the 64bit feature EAN.

enum cl_status_t cl_device_get_feature_ean (
    struct cl_device_t * device,
    uint64_t * ean
)

Parameters:

device The target device
ean Out parameter

Returns:

status code, see cl_status_t for possible codes

function cl_device_get_firmware_ean

Gets the 64bit firmware EAN.

enum cl_status_t cl_device_get_firmware_ean (
    struct cl_device_t * device,
    uint64_t * ean
)

Parameters:

device The target device
ean Out parameter

Returns:

status code, see cl_status_t for possible codes

function cl_device_get_firmware_version

Gets the firmware version as a semver string.

enum cl_status_t cl_device_get_firmware_version (
    struct cl_device_t * device,
    char * buffer,
    size_t buffer_size
)

Parameters:

device The target device
buffer Buffer to store the string in
buffer_size Size of the buffer

Returns:

status code, see cl_status_t for possible codes

function cl_device_get_interfaces

Gets the interfaces for the given device.

enum cl_status_t cl_device_get_interfaces (
    struct cl_device_t * device,
    cl_interface_list_ptr_t * interface_list
)

Parameters:

device The target device
interface_list A pointer to the cl_interface_list_ptr_t (pointer to pointer)

Returns:

status code, see cl_status_t for possible codes

function cl_device_get_manufacturing_date

Gets the device manufacturing date as string.

enum cl_status_t cl_device_get_manufacturing_date (
    struct cl_device_t * device,
    uint64_t * timestamp
)

Parameters:

device The target device
timestamp Unix timestamp when device was manufactured

Returns:

status code, see cl_status_t for possible codes

function cl_device_get_name

Gets the device name. The returned string will be null terminated.

enum cl_status_t cl_device_get_name (
    struct cl_device_t * device,
    char * buffer,
    size_t buffer_size
)

Parameters:

device The target device
buffer A buffer to place the device name in
buffer_size The size of the buffer

Returns:

status code, see cl_status_t for possible codes

function cl_device_get_nickname

Gets the device nickname. The returned string will be null terminated.

enum cl_status_t cl_device_get_nickname (
    struct cl_device_t * device,
    char * buffer,
    size_t buffer_size
)

Parameters:

device The target device
buffer A buffer to place the device nickname in
buffer_size The size of the buffer

Returns:

status code, see cl_status_t for possible codes

function cl_device_get_pcb_revision

Gets the PCB revision as a string.

enum cl_status_t cl_device_get_pcb_revision (
    struct cl_device_t * device,
    char * buffer,
    size_t buffer_size
)

Parameters:

device The target device
buffer Buffer to store the PCB revision string in
buffer_size Size of the buffer

Returns:

status code, see cl_status_t for possible codes

function cl_device_get_serial_number

Gets the 64bit serial_number.

enum cl_status_t cl_device_get_serial_number (
    struct cl_device_t * device,
    uint64_t * serial_number
)

Parameters:

device The target device
serial_number Out parameter

Returns:

status code, see cl_status_t for possible codes

function cl_device_identify

Trigger identify device sequence (flash device LEDs)

enum cl_status_t cl_device_identify (
    struct cl_device_t * device
)

Parameters:

device The target device

Returns:

status code, see cl_status_t for possible codes

function cl_device_iterator_create

Creates a device iterator. To be used with cl_device_iterator_next. cl_device_iterator_destroy must be called to free memory when done with the iterator.

struct cl_device_iterator_t * cl_device_iterator_create (
    cl_device_list_ptr_t device_list
)

Parameters:

device_list The device list to iterate over

Returns:

the device iterator object

function cl_device_iterator_destroy

Frees the given device iterotor.

void cl_device_iterator_destroy (
    struct cl_device_iterator_t * iterator
)

Parameters:

iterator The iterator to free

function cl_device_iterator_next

Gets the next device.

struct cl_device_t * cl_device_iterator_next (
    struct cl_device_iterator_t * iterator
)

Parameters:

iterator A cl_device_iterator_t created with cl_device_iterator_create

Returns:

NULL if there is no next device.

function cl_device_list_destroy

Frees the given device_list.

void cl_device_list_destroy (
    cl_device_list_ptr_t device_list
)

Parameters:

device_list device list to free

function cl_device_list_find_by_index

Finds a device from the given index.

struct cl_device_t * cl_device_list_find_by_index (
    size_t index,
    cl_device_list_ptr_t device_list
)

Parameters:

index the index to find
device_list device list to search in

Returns:

the device, or NULL if out of bounds

function cl_device_list_find_by_info

Finds a device from the given ean and serial number.

struct cl_device_t * cl_device_list_find_by_info (
    const uint64_t * ean,
    uint64_t serial_number,
    cl_device_list_ptr_t device_list
)

Parameters:

ean a pointer to a serial number (will be ignored if NULL)
serial_number The device's serial number
device_list device list to search in

Returns:

the device, or NULL if no match or multiple matches

function cl_device_set_nickname

Sets the given null terminated device_nickname.

enum cl_status_t cl_device_set_nickname (
    struct cl_device_t * device,
    const char * name
)

Parameters:

device The target device
name A null terminated string

Returns:

status code, see cl_status_t for possible codes

function cl_device_update_firmware_from_blob

Sends a new firmware blob to the device.

enum cl_status_t cl_device_update_firmware_from_blob (
    struct cl_device_t * device,
    const char * firmware_blob,
    size_t size,
    const struct cl_firmware_update_callbacks_t * callbacks
)

Parameters:

device The target device
firmware_blob Raw firmware blob
size Size of blob in bytes
callbacks A cl_firmware_update_callbacks_t structure containing function pointers to call during the firmware update. It is safe for the struct pointer to be NULL, as well as any of the function pointers (if they're not of interest).

Returns:

status code, see cl_status_t for possible codes

function cl_device_update_firmware_from_path

Sends a new firmware from file at the given path to the device.

enum cl_status_t cl_device_update_firmware_from_path (
    struct cl_device_t * device,
    const char * firmware_path,
    const struct cl_firmware_update_callbacks_t * callbacks
)

Parameters:

device The target device
firmware_path File path to firmware file
callbacks A cl_firmware_update_callbacks_t structure containing function pointers to call during the firmware update. It is safe for the struct pointer to be NULL, as well as any of the function pointers (if they're not of interest).

Returns:

status code, see cl_status_t for possible codes

function cl_format_ean

This is a helper to format an EAN number using the format XX-XXXXX-XXXXX-X.

enum cl_status_t cl_format_ean (
    uint64_t ean,
    char * buffer,
    size_t buffer_size
)

Parameters:

ean The EAN to format
buffer Te buffer to place the resulting string in
buffer_size The size of the buffer

Returns:

status code, see cl_status_t for possible codes

function cl_format_serial_number

This is a helper to format a serial number using the format 0000000 (essentially just a "%07lu" format string)

enum cl_status_t cl_format_serial_number (
    uint64_t serial_number,
    char * buffer,
    size_t buffer_size
)

Parameters:

ean The serial number to format
buffer Te buffer to place the resulting string in
buffer_size The size of the buffer

Returns:

status code, see cl_status_t for possible codes

function cl_get_api_version

Returns the API version.

void cl_get_api_version (
    uint32_t * major,
    uint32_t * minor,
    uint32_t * patch
)

Parameters:

major the major version
minor the minor version
patch the patch version

function cl_interface_eth_get_config

Gets the interface link configuration for an ethernet interface.

enum cl_status_t cl_interface_eth_get_config (
    struct cl_interface_t * interface,
    struct cl_eth_config_t * config
)

Parameters:

interface The target interface
mode The config to get. See cl_eth_config_t,

Returns:

status code, see cl_status_t for possible codes

function cl_interface_eth_get_supported_configs

Gets the supported configuration options for the given interface.

enum cl_status_t cl_interface_eth_get_supported_configs (
    struct cl_interface_t * interface,
    struct cl_eth_config_t * config
)

Parameters:

interface The target interface
config The new config

Note:

Some interfaces will respond with CL_STATUS_OPERATION_NOT_SUPPORTED_BY_INTERFACE if it can not be directly controlled. For instance the T interface in Arcus 100/1000BASE-T1 H-MTD follows the negotiated link on the T1 side (since they're directly linked without an ethernet switch between them).

Returns:

status code, see cl_status_t for possible codes

function cl_interface_eth_set_config

Sets the interface link mode for an ethernet interface.

enum cl_status_t cl_interface_eth_set_config (
    struct cl_interface_t * interface,
    struct cl_eth_config_t config
)

Parameters:

interface The target interface
config The config to set. See cl_eth_config_t,

Note:

Only configs returned by cl_interface_eth_get_supported_configs are possible

Returns:

status code, see cl_status_t for possible codes

function cl_interface_get_nickname

Gets the interface nickname.

enum cl_status_t cl_interface_get_nickname (
    struct cl_interface_t * interface,
    char * buffer,
    size_t buffer_size
)

Parameters:

interface The target interface
buffer A buffer to place the interface nickname in
buffer_size The size of the buffer

Returns:

status code, see cl_status_t for possible codes

function cl_interface_get_status

Gets the interface status.

enum cl_status_t cl_interface_get_status (
    struct cl_interface_t * interface,
    struct cl_interface_status_t * status
)

Parameters:

interface The target interface
status The returned interface status, see cl_interface_status_t for more info.

Note:

When link is down, this function will return the active configuration, and if it's up it'll return the negotiated configuration.

Returns:

status code, see cl_status_t for possible codes

function cl_interface_get_tc10_state

Reads the current tc10 state for the given interface.

enum cl_status_t cl_interface_get_tc10_state (
    struct cl_interface_t * interface,
    enum cl_tc10_state_t * state
)

Parameters:

interface The target interface
state Pointer to cl_tc10_state_t to store result in

Note:

Only T1 interfaces support this function, others will return CL_STATUS_OPERATION_NOT_SUPPORTED_BY_INTERFACE

Returns:

status code, see cl_status_t for possible codes

function cl_interface_identify

Triggers identify interface sequence (flash interface LEDs) to help identify the given interface.

enum cl_status_t cl_interface_identify (
    struct cl_interface_t * interface
)

Parameters:

interface The target interface

Returns:

status code, see cl_status_t for possible codes

function cl_interface_iterator_create

Creates an iterator to be used to access the interfaces from an cl_interface_list_t .

struct cl_interface_iterator_t * cl_interface_iterator_create (
    struct cl_interface_list_t * interface_list
)

Parameters:

interface_list An interface list

Note:

This iterator must be freed with cl_interface_iterator_destroy to free memory.

Returns:

A cl_interface_iterator_t

function cl_interface_iterator_destroy

Frees the given interface iterotor.

void cl_interface_iterator_destroy (
    struct cl_interface_iterator_t * iterator
)

Parameters:

iterator The iterator to free

function cl_interface_iterator_next

Gets the next interface.

struct cl_interface_t * cl_interface_iterator_next (
    struct cl_interface_iterator_t * iterator
)

Parameters:

iterator A cl_interface_iterator_t created with cl_interface_iterator_create

Returns:

NULL if there is no next interface.

function cl_interface_list_destroy

Frees the given interface_list.

void cl_interface_list_destroy (
    cl_interface_list_ptr_t interface_list
)

Parameters:

interface_list interface list to free

function cl_interface_send_tc10_command

Sends the given tc10 command to the given interface.

enum cl_status_t cl_interface_send_tc10_command (
    struct cl_interface_t * interface,
    enum cl_tc10_command_t command
)

Parameters:

interface The target interface
command The tc10 command to send, see cl_tc10_command_t for possible values

Note:

Only T1 interfaces support this function, others will return CL_STATUS_OPERATION_NOT_SUPPORTED_BY_INTERFACE

Returns:

status code, see cl_status_t for possible codes

function cl_interface_set_nickname

Sets the given null terminated interface nickname.

enum cl_status_t cl_interface_set_nickname (
    struct cl_interface_t * interface,
    const char * name
)

Parameters:

interface The target interface
name A null terminated string

Returns:

status code, see cl_status_t for possible codes

Macro Definition Documentation

define CL_API

CL_API will be expanded to __declspec(dllimport) on windows, on Linux it expands to nothing.

#define CL_API

define CL_CC

CL_CC will be expanded to __stdcall when compiling for 32bit windows applications, on Linux and 64bit windows it expands to nothing (use default calling convention for the platform).

#define CL_CC

define CL_INTERFACE_STATUS_T_VERSION

#define CL_INTERFACE_STATUS_T_VERSION `1`

The current version of cl_interface_status_t, it will get bumped when fields are added to cl_interface_status_t and is used to track what data can be populated into this struct as the shared library grows, without the need to modify or rebuild the user's application (consumer of this API).

The documentation for this class was generated from the following file cl/cl_api.h