aleitner commented on code in PR #610:
URL: https://github.com/apache/guacamole-server/pull/610#discussion_r2683196210
##########
src/libguac/guacamole/user-fntypes.h:
##########
@@ -499,5 +499,95 @@ typedef int guac_user_get_handler(guac_user* user,
guac_object* object,
typedef int guac_user_put_handler(guac_user* user, guac_object* object,
guac_stream* stream, char* mimetype, char* name);
-#endif
+/**
+ * Handler for Guacamole USB connect events, invoked when a "usbconnect"
+ * instruction has been received from a user. This indicates that the user
+ * has connected a USB device via WebUSB and it is available for redirection.
+ *
+ * @param device_id
+ * The unique identifier for the USB device. Required.
+ *
+ * @param vendor_id
+ * The vendor ID of the USB device. Required.
+ *
+ * @param product_id
+ * The product ID of the USB device. Required.
+ *
+ * @param device_name
+ * The human-readable name of the device. Required (may be empty string).
+ *
+ * @param serial_number
+ * The serial number of the device. Optional (may be NULL or empty string
+ * if not available).
+ *
+ * @param device_class
+ * The USB device class. Required.
+ *
+ * @param device_subclass
+ * The USB device subclass. Required.
+ *
+ * @param device_protocol
+ * The USB device protocol. Required.
+ *
+ * @param interface_data
+ * Encoded string containing interface and endpoint information. Required.
+ * Format:
"ifaceNum:class:subclass:protocol:ep1Num:ep1Dir:ep1Type:ep1Size;ep2...,iface2..."
+ * where multiple endpoints within an interface are separated by semicolons
+ * and multiple interfaces are separated by commas.
Review Comment:
The format
`ifaceNum:class:subclass:protocol:ep1Num:ep1Dir:ep1Type:ep1Size;ep2...,iface2...`
is not a USB standard. It's a custom encoding I set up for this Guacamole
protocol.
The data itself comes from standard USB descriptors that the browser's
WebUSB API provides automatically. We can see in
[ManagedUSB.js](https://github.com/aleitner/guacamole-client/blob/82a69a62b4d126d0905763ba6b00d806e7ef3307/guacamole/src/main/frontend/src/app/client/types/ManagedUSB.js#L116)
in our client PR that we're just reading properties that WebUSB gives us:
```iface.interfaceNumber // Standard USB interface number
alt.interfaceClass // Standard USB class code
alt.interfaceSubclass // Standard USB subclass code
alt.interfaceProtocol // Standard USB protocol code
ep.endpointNumber // Standard USB endpoint number
ep.direction // 'in' or 'out'
ep.type // 'bulk', 'interrupt', 'isochronous'
ep.packetSize // Max packet size in bytes
```
These are all standard USB descriptor fields defined in the USB
specification. We're just encoding them into a string format for sending over
the Guacamole protocol.
As you pointed out thoguh we can see that USB has class/subclass/protocol at
two levels.
These describe the overall device and are often set to 0 for composite
devices:
- `device_class`, `device_subclass`, `device_protocol`
Composite devices like webcams with microphones commonly use:
- Device class 0xEF (Miscellaneous Device)
- Device subclass 0x02 (Common Class)
- Device protocol 0x01 (Interface Association Descriptor)
-----
These describe each individual interface and is where the actual
functionality is usually defined:
- `interfaceClass`, `interfaceSubclass`, `interfaceProtocol`
HID devices like keyboards/mice commonly have:
- Device class 0x00 (defined at interface level)
- Interface class 0x03 (HID)
- Interface subclass 0x01 (Boot Interface)
- Interface protocol 0x01 (Keyboard) or 0x02 (Mouse)
- Interface 0: class=0x03 (HID), subclass=0x01 (Boot), protocol=0x01
(Keyboard)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
