HID device UDP client
Nicolas Pouillon
11 Oct 2011
1 Overview
Foils-HID is a library for creating Freebox Network HID devices. It uses libela for event loop abstraction and librudp for low-level UDP transport. Libela makes it abstract from a particular event loop. In this way, it should be embeddable in any GUI toolkit.
Table of contents
2 User APIs
High-level API is prefered over other the low-level one.
High-level API
Description
High-level API takes an array of device descriptors and creates a client object. Libary code takes care of reconnecting, handling device grabs and resending device descriptors on connection.
Usage
Devices are described in a struct foils_hid_device_descriptor. This references the three standard HID descriptors: report descriptor, physical descriptor and string descriptor. Report descriptor is the only mandatory one. Physical descriptor is only mandatory for joystick/gamepad devices.
Client may be connected to one server at a time. Connection is initiated through either foils_hid_client_connect_hostname, foils_hid_client_connect_ipv4, or foils_hid_client_connect_ipv6,
User code may enable and disable devices selectively with foils_hid_device_enable and foils_hid_device_disable. On an enabled device, user may send input and feature reports with foils_hid_input_report_send and foils_hid_feature_report_send.
Reliability of transport is selected on a per-report basis. Reports containing only absolute/relative data (like keyboard, mouse, joystick) should be sent unreliably. Reports with data that are transcient should be sent reliably (like unicode).
Example
First thing to do is to create a set of device definitions.
This code declares a report descriptor and the associated report structure. This makes the HID device self-contained: all the data sent by the device are in a described fixed format.
static const uint8_t mouse_report_descriptor[] = {
0x05, 0x01, /* Usage Page (Desktop), */
0x09, 0x02, /* Usage (Mouse), */
0xA1, 0x01, /* Collection (Application), */
0x05, 0x09, /* Usage Page (Button), */
0x19, 0x01, /* Usage Minimum (01h), */
0x29, 0x03, /* Usage Maximum (03h), */
0x15, 0x00, /* Logical Minimum (0), */
0x25, 0x01, /* Logical Maximum (1), */
0x75, 0x01, /* Report Size (1), */
0x95, 0x03, /* Report Count (3), */
0x81, 0x02, /* Input (Variable), */
0x75, 0x05, /* Report Size (5), */
0x95, 0x01, /* Report Count (1), */
0x81, 0x01, /* Input (Constant), */
0x05, 0x01, /* Usage Page (Desktop), */
0x09, 0x30, /* Usage (X), */
0x09, 0x31, /* Usage (Y), */
0x09, 0x38, /* Usage (Wheel), */
0x15, 0x81, /* Logical Minimum (-127), */
0x26, 0x80, 0x00, /* Logical Maximum (128), */
0x75, 0x08, /* Report Size (8), */
0x95, 0x03, /* Report Count (3), */
0x81, 0x06, /* Input (Variable, Relative), */
0xC0, /* End Collection, */
};
struct mouse_report
{
uint8_t buttons;
int8_t x;
int8_t y;
int8_t wheel;
};
This code declares a mouse descriptor and an array of one device containing the said descriptor. Physical and string descriptors are not filled.
static const
struct foils_hid_device_descriptor descriptors[] =
{
{ "Mouse", 0x0100,
(void*)mouse_report_descriptor, sizeof(mouse_report_descriptor),
NULL, 0, NULL, 0
},
};
Then there is the main entry point. First you must create an event loop. See libela documentation for alternative ways to create an event loop.
struct ela_el *el = ela_create(NULL);
Then initialize the client using the device descriptors.
struct foils_hid client;
int err = foils_hid_init(&client, el, &handler, descriptors, 1);
if (err) {
fprintf(stderr, "Error creating client: %s\n", strerror(err));
return 1;
}
Finally, tell the client to connect a given host.
foils_hid_client_connect_hostname(&client, argv[1], 904, 0);
Here we enable the first device, this will make it available to the server as soon as it connects.
foils_hid_device_enable(&client, 0);
Then we can run the event loop.
ela_run(el);
Once the event loop quits, we can cleanup the leftovers.
foils_hid_deinit(&client);
ela_close(el);
Inside the event loop, some events (like GUI) can trigger emission of reports. Here is some code sending some circular mouse movements:
float angle;
struct mouse_report report = {
.x = cosf(angle) * 32.,
.y = sinf(angle) * 16.,
};
foils_hid_input_report_send(ms->client, 0, 0, 0, &report, sizeof(report));
Low-level API
Low-level API is just a protocol mapping above librudp. It does not handle a list of devices like the high-level one.
Low level API handles:
Protocol datatypes and serialization (payload serialization, endianness, etc.),
Protocol commands and semantics,
rudp interface,
HID device enumeration (send device presence notifications, handle grabs, etc.).
Low-level API user must handle its own device list, create the device descriptors and send device descriptors to the server each time the connection is established.
Main feature of the low-level API is to be able to create dynamic devices, i.e. register devices unknown at time of initialization.
Once you understand the protocol, you should understand the API quite well. .
See also foils/rudp_hid_client.h header.
3 HID notes
HID stands for "Human Interface Device". It defines a standard for interoperable interface devices (It used to be input-oriented, but standard commitee found there was also output, hence "interface"). HID is well thought for most parts. It handles both backwards compatibility and future evolutions. It was primarily developed for USB, but was taken verbatim for Bluetooth.
HID is defined on the USB Implementers' Forum pages on http://www.usb.org/developers/hidpage/. Two documents define the whole HID (Check the website for updates):
Device Class Definition for Human Interface Devices, v. 1.11.
This document defines the core protocol, report descriptor format, data format, general guidelines, etc.
HID Usage Tables, v. 1.12.
This document defines support for various kind of devices. At first, it defines support for legacy devices, like Keyboards and Mice. Then it defines usual Joysticks and Gamepads. Later on, it defines "Consumer control". Finally comes application-specific definitions.
HID notes
Some various notes for device designers:
All values are little-endian in reports (if multibyte);
A report ID is mandatory if more than one report may be emitted by a device. If any report has a report ID set, all reports must have one;
Report ID 0 may not exist explicitely (i.e. it is only valid when no report IDs are defined). In other words, if multiple reports are present, they may not use report ID 0;
HID-RD (http://sourceforge.net/projects/digimend/files/hidrd/) is a great tool for HID report descriptor parsing and creation.
Dos and Donts
For a Set-top box control API, "Consumer control" should be enough, but as new STBs also have a browser, they need an usual Keyboard/mouse API.
Remote control
A remote control should find all its needs in the "Consumer control" usage page (HID Usage Tables, section 15, p.75). There are commands for about anything an usual remote control has. Keypad, playback control, menu navigation, etc.
Basic remote control only needs to define one input report with one item containing remote control. Report descriptor can look like:
0x05, 0x0C, /* Usage Page (Consumer), */
0x09, 0x01, /* Usage (Consumer Control), */
0xA1, 0x01, /* Collection (Application), */
/* 1 "Consumer" input item */
0x95, 0x01, /* Report Count (1), */
0x75, 0x10, /* Report Size (16), */
0x19, 0x00, /* Usage Minimum (Consumer Control), */
0x2A, 0x9C, 0x02, /* Usage Maximum (AC Distribute Vertically),*/
0x15, 0x00, /* Logical Minimum (1), */
0x26, 0x8C, 0x02, /* Logical Maximum (652), */
0x80, /* Input, */
0xC0, /* End Collection, */This defines one 16-bit input item containing any value in the consumer page. Then any sent value corresponds to its usage. Expected report data is a 16 bit payload, containing a little-endian value. 0 is a special "noop" value.
Matching C structure is:
struct report
{
uint16_t consumer;
};Mouse
A mouse report is defined in the HID standard (HID 1.11, secion B.2, p. 61). Nevertheless, if we do not expect BIOS compatibility (which we dont), we can modify the report layout to suit our needs.
Report descriptor can look like:
0x05, 0x01, /* Usage Page (Desktop), */
0x09, 0x02, /* Usage (Mouse), */
0xA1, 0x01, /* Collection (Application), */
/* 3 "Button" input items */
0x05, 0x09, /* Usage Page (Button), */
0x19, 0x01, /* Usage Minimum (01h), */
0x29, 0x03, /* Usage Maximum (03h), */
0x15, 0x00, /* Logical Minimum (0), */
0x25, 0x01, /* Logical Maximum (1), */
0x75, 0x01, /* Report Size (1), */
0x95, 0x03, /* Report Count (3), */
0x81, 0x02, /* Input (Variable), */
/* 5 padding bits */
0x75, 0x05, /* Report Size (5), */
0x95, 0x01, /* Report Count (1), */
0x81, 0x01, /* Input (Constant), */
/* 3 "Desktop" (X, Y, Wheel) relative axis */
0x05, 0x01, /* Usage Page (Desktop), */
0x09, 0x30, /* Usage (X), */
0x09, 0x31, /* Usage (Y), */
0x09, 0x38, /* Usage (Wheel), */
0x15, 0x81, /* Logical Minimum (-127), */
0x26, 0x80, 0x00, /* Logical Maximum (128), */
0x75, 0x08, /* Report Size (8), */
0x95, 0x02, /* Report Count (3), */
0x81, 0x06, /* Input (Variable, Relative), */
0xC0, /* End Collection, */Matching structure is:
struct report
{
uint8_t buttons;
int8_t x;
int8_t y;
int8_t wheel;
};Keyboard and text
Keyboard sending scancodes is a legacy concept. It existed a time when keyboards where complex devices (for the time) and making them send scancodes was already a big thing. Today, scancodes still exist but are a pain to handle.
For instance, when an user presses "A" on a french keyboard, the keyboard actually sends the value 0x14 on the wire (meaning "Q" key on an US keyboard). Then host has to know the actual keymap to emit the "a" (or "A", depending on caps state) text to the application.
Here, we are designing a network-based protocol. That implies the client "Hardware" module has a complex OS running, and probably resolved the scancode-to-text problem. The text may even come from a touchscreen or speech recognition. Of course we dont want to translate this to scancodes.
HID has support for text input not based on scancodes: HID can handle unicode characters transport (HID Usage Tables, section 17, p. 108). In the context of Foils, sending actual text rather than scancodes is highly preferred.
Sending only unicode would be great if it could handle all keyboard input. Unfortunately, a keyboard also emits scancodes with no associated text, but an associated meaning. Basic examples are control keys (Arrows, Backspace, Enter, Tab, F1 to F12, etc.). Most of these keys are not present as semantic controls in the Consumer page either. For a complete keyboard emulation with control keys support, we can use an hybrid report containing both standard keyboard scancodes for control keys, and unicode for text. Modifiers (Shift, Alt, Ctrl) are of little interest in this context.
0x05, 0x01, /* Usage Page (Desktop), */
0x09, 0x06, /* Usage (Keyboard), */
0xA1, 0x01, /* Collection (Application), */
/* 1 item containing one unicode character */
0x05, 0x10, /* Usage Page (Unicode), */
0x08, /* Usage (00h), */
0x95, 0x01, /* Report Count (1), */
0x75, 0x20, /* Report Size (32), */
0x14, /* Logical Minimum (0), */
0x25, 0xFF, /* Logical Maximum (-1), */
0x81, 0x06, /* Input (Variable, Relative), */
/* 1 item containing one keyboard scancode */
0x95, 0x01, /* Report Count (1), */
0x75, 0x08, /* Report Size (8), */
0x15, 0x00, /* Logical Minimum (0), */
0x26, 0xFF, 0x00, /* Logical Maximum (255), */
0x05, 0x07, /* Usage Page (Keyboard), */
0x19, 0x00, /* Usage Minimum (None), */
0x2A, 0xFF, 0x00, /* Usage Maximum (FFh), */
0x81, 0x00, /* Input, */
0xC0 /* End Collection */Matching structure is:
struct report
{
uint32_t unicode;
uint8_t scancode;
};4 Protocol
Protocol is based on librudp. The Foils HID protocol is stacked above librudp. Foils HID commands are librudp "user" commands.
Standard HID descriptors are used as defined in the standard.
Datatypes
All the protocol uses big-endian data for custom fields and structures.
Header
Foils HID header is small, it only contains a device ID and a report ID. Device ID is always relevant. Report ID is not always used. It may be kept 0 in such cases.
| Offset (byte) | Size (byte) | Name | Description |
|---|---|---|---|
| 0 | 4 | Device ID | Numeric constant identifying the device the message is about. This has to be constant and unique inside the client. Server sends commands about the declared devices. Device IDs may be reused across diffrent devices in time, as long as DEVICE_DROPPED has be sent. |
| 4 | 4 | Report ID | Report the message is about. If no report is involved in the message, keep this to 0. |
Device new
| Offset (byte) | Size (byte) | Name | Description |
|---|---|---|---|
| 0 | 64 | Device Name | UTF-8 character string containing the device name. This must be NUL-terminated. The trailing NUL must be in the 64 bytes. |
| 64 | 32 | Device Serial | UTF-8 character string containing the device serial name. This must be NUL-terminated. The trailing NUL must be in the 32 bytes. |
| 96 | 2 | Zero | Reserved field. Must be 0 for now. |
| 98 | 2 | Version | Device version. This is purely informational. |
| 100 | 2 | Descriptor offset | Offset between start of structure and start of the report descriptor blob. |
| 102 | 2 | Descriptor size | Report descriptor size, in bytes. |
| 104 | 2 | Physical offset | Offset between start of structure and start of the physical descriptor blob. |
| 106 | 2 | Physical size | Physical descriptor size, in bytes. |
| 108 | 2 | Strings offset | Offset between start of structure and start of the strings descriptor blob. |
| 110 | 2 | Strings size | Strings descriptor size, in bytes. |
| 112+ | At least (Descriptor size + Physical size + Strings size) | Then follows the descriptor blobs, concatenated after the structure. Offsets to descriptors are taken between first byte of the structure (i.e. first character of "Device name") and first byte of the relevant blob. |
Commands
| Value | Name | Direction | Description |
|---|---|---|---|
| 0 | DEVICE_NEW | Client to server | Notifies the server there is a new device available in the client. This message contains a Device new argument. |
| 1 | DEVICE_DROPPED | Client to server | Notifies the server the device is not available any more. All the relevant fields are present in the header. |
| 2 | DEVICE_OPEN | Server to client | Notifies the client the server created a handle for the device. This makes the device usable by the server afterwards. |
| 3 | DEVICE_CLOSE | Server to client | Notifies the client that the server no longer has any reference to the device. |
| 4 | FEATURE | Both | A feature report payload follows the header. Report ID is in the header. |
| 5 | DATA | Both | An input (client to server) or output (server to client) report payload follows the header. Report ID is in the header. |
| 6 | GRAB | Server to client | Notifies the client that the server now listens for input reports sent by this device. Clients should not send input reports without a prior grab. Relevant Report ID is in the header. |
| 7 | RELEASE | Server to client | Notifies the client that the server does not listen for input reports any more. Clients should not send input reports afterwards. Relevant Report ID is in the header. |
| 8 | FEATURE_SOLLICIT | Server to client | Notifies the client that the server needs to receive a feature report ASAP. Report ID is in the header. |
5 Headers
Header list
| Name | Description |
|---|---|
| foils/hid.h | Human interface device high-level client |
| foils/hid_device.h | Device internal definition |
| foils/rudp_hid_client.h | Human interface device low-level client |
foils/hid.h header reference
[HID device client module]
Human interface device high-level client More
Header inclusion
Members
Types
- struct foils_hid
- struct foils_hid_handler
- enum foils_hid_state
Functions
- int foils_hid_client_connect_hostname(struct foils_hid *client, const char *hostname, const uint16_t port, uint32_t ip_flags)
- void foils_hid_client_connect_ipv4(struct foils_hid *client, const struct in_addr *address, const uint16_t port)
- void foils_hid_client_connect_ipv6(struct foils_hid *client, const struct in6_addr *address, const uint16_t port)
- void foils_hid_deinit(struct foils_hid *rlh)
- void foils_hid_device_disable(struct foils_hid *rlh, size_t index)
- void foils_hid_device_enable(struct foils_hid *rlh, size_t index)
- void foils_hid_feature_report_send(struct foils_hid *rlh, size_t device_index, uint8_t report_id, int reliable, const void *data, size_t datalen)
- int foils_hid_init(struct foils_hid *rlh, struct ela_el *el, const struct foils_hid_handler *handler, const struct foils_hid_device_descriptor *device, size_t device_count)
- void foils_hid_input_report_send(struct foils_hid *rlh, size_t device_index, uint8_t report_id, int reliable, const void *data, size_t datalen)
Description
Members detail
This macro is declared in foils/hid.h source file, line 12.
This struct is declared in foils/hid.h source file, line 99.
this struct is the foils HID device client state.
int foils_hid_client_connect_hostname(struct foils_hid *client, const char *hostname, const uint16_t port, uint32_t ip_flags)
This function is declared in foils/hid.h source file, line 210.
this function tries to connect to the given hostname and port
Parameters list:
- client: Client context
- hostname: Host name to connect to. This is resolved through standard libc resolution.
- port: Port to connect to
- ip_flags: Librudp connection flags. See librudp documentation
The return value is 0 if OK, or an error taken from errno(7)
void foils_hid_client_connect_ipv4(struct foils_hid *client, const struct in_addr *address, const uint16_t port)
This function is declared in foils/hid.h source file, line 222.
this function tries to connect to the given IPv4 address and port
Parameters list:
- client: Client context
- address: IPv4 address, in in_addr usual order
- port: Port to connect to
void foils_hid_client_connect_ipv6(struct foils_hid *client, const struct in6_addr *address, const uint16_t port)
This function is declared in foils/hid.h source file, line 234.
this function tries to connect to the given IPv6 address and port
Parameters list:
- client: Client context
- address: IPv6 address, in in6_addr usual order
- port: Port to connect to
void foils_hid_deinit(struct foils_hid *rlh)
This function is declared in foils/hid.h source file, line 192.
this function releases all context of the client.
This disconnects from the server and makes all devices unavailable.
Parameters list:
- rlh: Client context
void foils_hid_device_disable(struct foils_hid *rlh, size_t index)
This function is declared in foils/hid.h source file, line 145.
this function disables a device. Disabling a device makes it appear disconnected.
Parameters list:
- rlh: The client state
- index: Device index in the array
void foils_hid_device_enable(struct foils_hid *rlh, size_t index)
This function is declared in foils/hid.h source file, line 136.
this function enables a device. An enabled device becomes visible to the server.
Parameters list:
- rlh: The client state
- index: Device index in the array
void foils_hid_feature_report_send(struct foils_hid *rlh, size_t device_index, uint8_t report_id, int reliable, const void *data, size_t datalen)
This function is declared in foils/hid.h source file, line 183.
this function sends a feature report from a given device.
User must ensure the payload correspond to the device's report descriptor.
Parameters list:
- rlh: The client state
- device_index: Device index in the array
- report_id: Report index
- reliable: Whether this report may be lost in transport
- data: Report data
- datalen: Report data size
This struct is declared in foils/hid.h source file, line 44.
this struct is a set of callbacks from the client state to user code.
| Field | Description |
|---|---|
| void (*status)(struct foils_hid *client, enum foils_hid_state state) ; | this struct notifies the user code of current client state.
|
| void (*feature_report)(struct foils_hid *client, uint32_t device_id, uint8_t report_id, const void *data, size_t datalen) ; | this struct is called when a device receives a feature report
|
| void (*output_report)(struct foils_hid *client, uint32_t device_id, uint8_t report_id, const void *data, size_t datalen) ; | this struct is called when a device receives an output report
|
| void (*feature_report_sollicit)(struct foils_hid *client, uint32_t device_id, uint8_t report_id) ; | this struct is called when the server needs the device to send a feature report Parameters list:
|
int foils_hid_init(struct foils_hid *rlh, struct ela_el *el, const struct foils_hid_handler *handler, const struct foils_hid_device_descriptor *device, size_t device_count)
This function is declared in foils/hid.h source file, line 127.
this function initializes the foils HID state from a set of devices.
Parameters list:
- rlh: The client state
- el: A valid event loop abstraction handle
- handler: The user-provided handler function structure
- device: A device array
- device_count: Count of devices in the array, limited to 32.
The return value is 0 when done, or an error taken from errno(7)
void foils_hid_input_report_send(struct foils_hid *rlh, size_t device_index, uint8_t report_id, int reliable, const void *data, size_t datalen)
This function is declared in foils/hid.h source file, line 164.
this function sends an input report from a given device.
User must ensure the payload correspond to the device's report descriptor.
Parameters list:
- rlh: The client state
- device_index: Device index in the array
- report_id: Report index
- reliable: Whether this report may be lost in transport
- data: Report data
- datalen: Report data size
This enum is declared in foils/hid.h source file, line 32.
this enum is the client state. User code gets notified of state evolution through the foils_hid_handler::status.
| Identifier | Description |
|---|---|
| FOILS_HID_IDLE | |
| FOILS_HID_CONNECTING | |
| FOILS_HID_CONNECTED | |
| FOILS_HID_RESOLVE_FAILED | |
| FOILS_HID_DROPPED |
foils/hid_device.h header reference
[HID device descriptor module]
Device internal definition More
Members
Type
- struct foils_hid_device_descriptor
Description
Members detail
This macro is declared in foils/hid_device.h source file, line 23.
This macro is declared in foils/hid_device.h source file, line 12.
This struct is declared in foils/hid_device.h source file, line 30.
this struct describes a device to the library context.
| Field | Description |
|---|---|
| char name[64]; | Device product name |
| uint16_t version; | Device version, in 2-byte hex format (e.g. 0x100 is 1.00 |
| void *descriptor; | Device report descriptor |
| size_t descriptor_size; | Device report descriptor size |
| void *physical; | Device physical descriptor |
| size_t physical_size; | Device physical descriptor size |
| void *strings; | Device strings descriptor |
| size_t strings_size; | Device strings descriptor size |
foils/rudp_hid_client.h header reference
[HID rudp client module]
Human interface device low-level client More
Header inclusion
Members
Types
- struct rudp_hid_client
- struct rudp_hid_client_handler
Client context management
- void rudp_hid_client_deinit(struct rudp_hid_client *client)
- int rudp_hid_client_init(struct rudp_hid_client *client, struct rudp *rudp, const struct rudp_hid_client_handler *handler)
Connection management
- int rudp_hid_client_close(struct rudp_hid_client *client)
- int rudp_hid_client_connect(struct rudp_hid_client *client)
- rudp_error_t rudp_hid_client_set_hostname(struct rudp_hid_client *client, const char *hostname, const uint16_t port, uint32_t ip_flags)
- void rudp_hid_client_set_ipv4(struct rudp_hid_client *client, const struct in_addr *address, const uint16_t port)
- void rudp_hid_client_set_ipv6(struct rudp_hid_client *client, const struct in6_addr *address, const uint16_t port)
Protocol handlers
- int rudp_hid_device_dropped(struct rudp_hid_client *client, uint32_t device_id)
- int rudp_hid_device_new(struct rudp_hid_client *client, const struct foils_hid_device_descriptor *desc, uint32_t device_id)
- int rudp_hid_feature_report_send(struct rudp_hid_client *client, uint32_t device_id, uint8_t report_id, int reliable, const void *data, size_t datalen)
- int rudp_hid_input_report_send(struct rudp_hid_client *client, uint32_t device_id, uint8_t report_id, int reliable, const void *data, size_t datalen)
Description
This defines a wrapped Librudp client handling all the low-level protocol of HID devices transport over Librudp.
Members detail
This macro is declared in foils/rudp_hid_client.h source file, line 12.
This struct is declared in foils/rudp_hid_client.h source file, line 143.
Wrapped rudp HID client state
int rudp_hid_client_close(struct rudp_hid_client *client)
This function is declared in foils/rudp_hid_client.h source file, line 255.
this function makes the client disconnect its server, or cease trying to connect. rudp_hid_client_connect must have been called before this call.
Parameters list:
- client: Client context
The return value is 0 when done, or an error from errno(7)
int rudp_hid_client_connect(struct rudp_hid_client *client)
This function is declared in foils/rudp_hid_client.h source file, line 238.
this function makes the client attempt to connect to the server. The target address must be populated before this call.
Parameters list:
- client: Client context
The return value is 0 when done, or an error from errno(7)
void rudp_hid_client_deinit(struct rudp_hid_client *client)
This function is declared in foils/rudp_hid_client.h source file, line 270.
this function releases all context of the client.
Client must not be connecting nor connected when calling this function.
Parameters list:
- rlh: Client context
This struct is declared in foils/rudp_hid_client.h source file, line 35.
this struct defines the possible client callbacks.
| Field | Description |
|---|---|
| void (*connected)(struct rudp_hid_client *client) ; | this struct is called when the client connects to the server Parameters list:
|
| void (*server_lost)(struct rudp_hid_client *client) ; | this struct is called when the client gets dropped from the server Parameters list:
|
| void (*device_grab)(struct rudp_hid_client *client, uint32_t device_id, uint8_t report_id) ; | this struct is called when the server asks for device grab Parameters list:
|
| void (*device_release)(struct rudp_hid_client *client, uint32_t device_id, uint8_t report_id) ; | this struct is called when the server asks for device release Parameters list:
|
| void (*device_open)(struct rudp_hid_client *client, uint32_t device_id) ; | this struct is called when the server asks for device open Parameters list:
|
| void (*device_close)(struct rudp_hid_client *client, uint32_t device_id) ; | this struct is called when the server asks for device closure Parameters list:
|
| void (*feature_report)(struct rudp_hid_client *client, uint32_t device_id, uint8_t report_id, const void *data, size_t datalen) ; | this struct is called when the server sends a feature report to the client Parameters list:
|
| void (*output_report)(struct rudp_hid_client *client, uint32_t device_id, uint8_t report_id, const void *data, size_t datalen) ; | this struct is called when the server sends an output report to the client Parameters list:
|
| void (*feature_report_sollicit)(struct rudp_hid_client *client, uint32_t device_id, uint8_t report_id) ; | this struct is called when the server needs the device to send a feature report Parameters list:
|
int rudp_hid_client_init(struct rudp_hid_client *client, struct rudp *rudp, const struct rudp_hid_client_handler *handler)
This function is declared in foils/rudp_hid_client.h source file, line 162.
this function initializes a client structure in the given librudp context
Parameters list:
- client: Client structure to initialize
- rudp: Valid rudp context
- handler: Callback functions
The return value is 0 when done, or an error taken from errno(7)
rudp_error_t rudp_hid_client_set_hostname(struct rudp_hid_client *client, const char *hostname, const uint16_t port, uint32_t ip_flags)
This function is declared in foils/rudp_hid_client.h source file, line 183.
this function sets the target hostname which to connect to
Parameters list:
- client: Client context
- hostname: Host name to connect to. This is resolved through standard libc resolution.
- port: Port to connect to
- ip_flags: Librudp connection flags. See librudp documentation
The return value is 0 if OK, or an error taken from errno(7)
void rudp_hid_client_set_ipv4(struct rudp_hid_client *client, const struct in_addr *address, const uint16_t port)
This function is declared in foils/rudp_hid_client.h source file, line 202.
this function sets the IPv4 to connect to
Parameters list:
- client: Client context
- address: IPv4 address, in in_addr usual order
- port: Port to connect to
void rudp_hid_client_set_ipv6(struct rudp_hid_client *client, const struct in6_addr *address, const uint16_t port)
This function is declared in foils/rudp_hid_client.h source file, line 221.
this function sets the IPv6 to connect to
Parameters list:
- client: Client context
- address: IPv6 address, in in6_addr usual order
- port: Port to connect to
int rudp_hid_device_dropped(struct rudp_hid_client *client, uint32_t device_id)
This function is declared in foils/rudp_hid_client.h source file, line 298.
this function sends a message to the server signalling disapperance of a device.
Parameters list:
- rlh: Client context
- device_id: Device index
int rudp_hid_device_new(struct rudp_hid_client *client, const struct foils_hid_device_descriptor *desc, uint32_t device_id)
This function is declared in foils/rudp_hid_client.h source file, line 285.
this function sends a message to the server signalling presence for a new device
Parameters list:
- rlh: Client context
- desc: Device descriptor
- device_id: Device index
int rudp_hid_feature_report_send(struct rudp_hid_client *client, uint32_t device_id, uint8_t report_id, int reliable, const void *data, size_t datalen)
This function is declared in foils/rudp_hid_client.h source file, line 320.
this function sends a feature report from a given device.
User must ensure the payload correspond to the device's report descriptor.
Parameters list:
- client: Client state
- device_id: Device index
- report_id: Report index
- reliable: Whether this report may be lost in transport
- data: Report data
- datalen: Report data size
int rudp_hid_input_report_send(struct rudp_hid_client *client, uint32_t device_id, uint8_t report_id, int reliable, const void *data, size_t datalen)
This function is declared in foils/rudp_hid_client.h source file, line 342.
this function sends an input report from a given device.
User must ensure the payload correspond to the device's report descriptor.
Parameters list:
- client: Client state
- device_id: Device index
- report_id: Report index
- reliable: Whether this report may be lost in transport
- data: Report data
- datalen: Report data size