usbip-device.h File Reference

Device core API - descriptors, standard requests, endpoints, dispatch. More...

#include "usbip.h"

Macros
#define	USBIP_WINUSB_DEFAULT_GUID
	The DeviceInterfaceGUID advertised when enable_winusb() is passed NULL.

Typedefs
typedef struct usbip_device	usbip_device
	The virtual device
typedef struct usbip_ep	usbip_ep
	An endpoint (byte pipe)
typedef int(*	usbip_device_control_fn) (void *ctx, const usb_setup *setup, uint8_t *buf, uint16_t len)
	Class/vendor control handler (core form).
typedef int(*	usbip_device_set_alt_fn) (void *ctx, int ifnum, int alt)
	SET_INTERFACE handler: the host selected alternate setting alt on ifnum.
typedef void(*	usbip_ep_out_fn) (void *ctx, usbip_ep *ep, const void *data, int len)
	A bulk/interrupt OUT packet arrived from the host.
typedef int(*	usbip_ep_iso_fn) (void *ctx, usbip_ep *ep, int npkts, uint32_t *lens, uint8_t *buf)
	The isochronous data callback: one call handles one transfer's packets.

Functions
usbip_device *	usbip_device_create (uint16_t vid, uint16_t pid)
	Create a virtual device with the given vendor/product IDs.
void	usbip_device_set_strings (usbip_device *dev, const char *mfr, const char *product, const char *serial)
	Set the manufacturer / product / serial string descriptors (indices 1-3).
void	usbip_device_set_class (usbip_device *dev, uint8_t cls, uint8_t sub, uint8_t proto)
	Set the device-descriptor class triple.
void	usbip_device_set_bcd_device (usbip_device *dev, uint16_t bcd)
	Set the device release number (bcdDevice).
void	usbip_device_set_speed (usbip_device *dev, usb_speed speed)
	Report a link speed (default USB_SPEED_FULL).
usb_speed	usbip_device_get_speed (usbip_device *dev)
	The device's reported link speed (for speed-aware class code; a class reaches its device with usbip_function_device() from classes/usb_class.h).
int	usbip_device_add_string (usbip_device *dev, const char *str)
	Register an extra string descriptor (e.g.
void	usbip_device_set_composite (usbip_device *dev)
	Declare the device composite: several independent class functions on one device.
int	usbip_device_enable_winusb (usbip_device *dev, const char *guid)
	Advertise WinUSB via BOTH Microsoft OS 1.0 and Microsoft OS 2.0 descriptors.
int	usbip_device_enable_msos (usbip_device *dev, const char *compatible, const char *guid)
	Generalized Microsoft OS descriptor advertisement with any Compatible ID.
void	usbip_device_enable_webusb (usbip_device *dev, uint8_t vendor_code, const char *url)
	Advertise WebUSB so a capable browser can surface and open the device.
void	usbip_device_set_iso_pacing (usbip_device *dev, int enabled)
	Pace isochronous completions to real wall-clock time.
int	usbip_device_add_descriptor (usbip_device *dev, const void *descriptor)
	Append a typed descriptor (interface / endpoint / HID / class-specific) to the device's configuration, in wire order.
usbip_ep *	usbip_device_add_endpoint (usbip_device *dev, const void *ep_descriptor)
	Append an endpoint descriptor and return the pipe it created.
uint8_t	usbip_device_reserve_endpoint (usbip_device *dev, uint8_t want_addr)
	Claim an endpoint address now, for an endpoint declared later.
int	usbip_device_get_num_interfaces (usbip_device *dev)
	How many interface numbers the device has registered so far - i.e.
void	usbip_device_set_interface_string (usbip_device *dev, uint8_t ifnum, uint8_t alt, uint8_t istr)
	Patch iInterface in the (ifnum, alt) interface descriptor already appended.
void	usbip_device_on_control (usbip_device *dev, int ifnum, usbip_device_control_fn cb, void *ctx)
	Register the class/vendor control handler for one interface.
void	usbip_device_on_set_alt (usbip_device *dev, int ifnum, usbip_device_set_alt_fn cb, void *ctx)
	Register the SET_INTERFACE handler for one interface.
void	usbip_ep_on_out (usbip_ep *ep, usbip_ep_out_fn cb, void *ctx)
	Register the OUT-data callback for an endpoint.
void	usbip_ep_on_iso (usbip_ep *ep, usbip_ep_iso_fn cb, void *ctx)
	Register the isochronous data callback for an endpoint (either direction).
int	usbip_device_group_begin (usbip_device *dev)
	Open a new descriptor group: a run of descriptors that form one function of the device (what an IAD groups, and what one Microsoft OS advertisement covers).
void	usbip_device_group_abort (usbip_device *dev)
	Roll back everything appended since the last usbip_device_group_begin(): descriptors, endpoints, interface registrations, reservations, control/set-alt registrations, and the group's Microsoft OS advertisements.
int	usbip_device_enable_msos_group (usbip_device *dev, int group, const char *compatible, const char *guid)
	Advertise Microsoft OS descriptors scoped to one descriptor group.
uint8_t	usbip_endpoint_address (usbip_ep *ep)
	An endpoint's bEndpointAddress, as it appears in the descriptor the host reads.
int	usbip_device_read (usbip_ep *ep, void *buf, int len, unsigned timeout_ms)
	Read host-to-device (OUT) data from an endpoint, blocking up to timeout_ms.
int	usbip_device_write (usbip_ep *ep, const void *buf, int len, unsigned timeout_ms)
	Write device-to-host (IN) data to an endpoint, blocking up to timeout_ms.
void	usbip_ep_stall (usbip_ep *ep)
	Halt (STALL) a non-control endpoint.
int	usbip_device_plug (usbip_device *dev, usb_transport *transport)
	Plug the device onto a transport and start serving it.
void	usbip_device_unplug (usbip_device *dev)
	Stop serving a device previously passed to usbip_device_plug().
void	usbip_device_set_busid (usbip_device *dev, const char *busid)
	Name this device on the wire, instead of the 1-<n> assigned at plug time.
const char *	usbip_device_get_busid (usbip_device *dev)
	The busid this device is exported under - what usbip attach -b takes.
int	usbip_device_is_composite (usbip_device *dev)
	Whether the app declared this device composite (see usbip_device_set_composite()).

Detailed Description

Device core API - descriptors, standard requests, endpoints, dispatch.

Build a virtual device from typed descriptors and serve it over USB/IP. The core knows only generic USB: the config blob it assembles, the standard requests it answers, and the per-interface/per-endpoint callbacks it routes to. Reusable device classes (functions, interfaces, the usbip_device_class vtable) are a separate layer on top - see classes/usb_class.h. I/O is blocking; the library serves each attached host from its own thread.

Conventions: functions return USB_SUCCESS (0) on success and a negative USB_ERROR code on failure; constructors return a pointer or NULL. The prefix names the receiver of the first parameter; usbip_device_* covers the device itself plus the device-side data path (usbip_device_read()/usbip_device_write()), mirroring the host-side usbip_host_*.