Unit USBMOUSE
From Ultibo.org
Return to Unit Reference
Description
Ultibo USB Mouse Driver unit
USB Mouse Devices
The USB mouse driver in this unit uses HID Boot Protocol only and has been replaced by the HIDMouse unit which provides complete HID Report Protocol support for USB mice. It is retained here for legacy uses and backwards compatibility only.
To use this driver in place of the default HID Mouse driver set the following configuration variables in your application during system initialization.
HID_REGISTER_MOUSE := False; USB_MOUSE_REGISTER_DRIVER := True;
This driver does not recognize devices that do not report themselves as boot mice, does not correctly recognize the wheel on many devices and is known to be incompatible with the touch pad included in some portable wireless keyboards.
Constants
USB mouse specific constants
USBMOUSE_* USBMOUSE_DRIVER_NAME = 'USB Mouse Driver (HID boot protocol)';
|
Name of USB mouse driver |
USBMOUSE_MOUSE_DESCRIPTION = 'USB HID Mouse';
|
Description of USB mouse device |
USB HID types
USB_HID_* | HID Interface Subclass types (See USB HID v1.11 specification) | |
USB_HID_SUBCLASS_NONE = 0;
|
Section 4.2 |
USB_HID_SUBCLASS_BOOT = 1;
|
Section 4.2 |
| HID Interface Protocol types (See USB HID v1.11 specification) | |
USB_HID_BOOT_PROTOCOL_NONE = 0;
|
Section 4.3 |
USB_HID_BOOT_PROTOCOL_KEYBOARD = 1;
|
Section 4.3 |
USB_HID_BOOT_PROTOCOL_MOUSE = 2;
|
Section 4.3 |
| HID Class Descriptor Types (See USB HID v1.11 specification) | |
USB_HID_DESCRIPTOR_TYPE_HID = $21;
|
Section 7.1 |
USB_HID_DESCRIPTOR_TYPE_REPORT = $22;
|
Section 7.1 |
USB_HID_DESCRIPTOR_TYPE_PHYSICAL_DESCRIPTOR = $23;
|
Section 7.1 |
| HID Request types | |
USB_HID_REQUEST_GET_REPORT = $01;
|
|
USB_HID_REQUEST_GET_IDLE = $02;
|
|
USB_HID_REQUEST_GET_PROTOCOL = $03;
|
Section 7.2 |
USB_HID_REQUEST_SET_REPORT = $09;
|
|
USB_HID_REQUEST_SET_IDLE = $0A;
|
|
USB_HID_REQUEST_SET_PROTOCOL = $0B;
|
Section 7.2 |
| HID Protocol types | |
USB_HID_PROTOCOL_BOOT = 0;
|
Section 7.2.5 |
USB_HID_PROTOCOL_REPORT = 1;
|
Section 7.2.5 |
| HID Report types | |
USB_HID_REPORT_INPUT = 1;
|
Section 7.2.1 |
USB_HID_REPORT_OUTPUT = 2;
|
Section 7.2.1 |
USB_HID_REPORT_FEATURE = 3;
|
Section 7.2.1 |
| HID Report IDs | |
USB_HID_REPORTID_NONE = 0;
|
Section 7.2.1 |
| HID Boot Protocol Button bits | |
USB_HID_BOOT_LEFT_BUTTON = (1 shl 0);
|
|
USB_HID_BOOT_RIGHT_BUTTON = (1 shl 1);
|
|
USB_HID_BOOT_MIDDLE_BUTTON = (1 shl 2);
|
|
USB_HID_BOOT_SIDE_BUTTON = (1 shl 3);
|
|
USB_HID_BOOT_EXTRA_BUTTON = (1 shl 4);
|
|
| HID Boot Protocol Report data | |
USB_HID_BOOT_REPORT_SIZE = 3;
|
Appendix B of HID Device Class Definition 1.11 |
USB_HID_BOOT_DATA_SIZE = 8;
|
Allocate more than the minimum to allow for extra data |
Type definitions
USB HID descriptor
PUSBHIDDescriptor = ^TUSBHIDDescriptor;
TUSBHIDDescriptor = packed record
bLength:Byte;
|
|
bDescriptorType:Byte;
|
|
bcdHID:Word;
|
|
bCountryCode:Byte;
|
|
bNumDescriptors:Byte;
|
|
bHIDDescriptorType:Byte;
|
|
wHIDDescriptorLength:Word;
|
|
| Note: Up to two optional bHIDDescriptorType/wHIDDescriptorLength pairs after the Report descriptor details | |
USB mouse device
PUSBMouseDevice = ^TUSBMouseDevice;
TUSBMouseDevice = record
| Mouse Properties | |
Mouse:TMouseDevice;
|
|
| USB Properties | |
HIDInterface:PUSBInterface;
|
USB HID Mouse Interface |
ReportRequest:PUSBRequest;
|
USB request for mouse report data |
ReportEndpoint:PUSBEndpointDescriptor;
|
USB Mouse Interrupt IN Endpoint |
HIDDescriptor:PUSBHIDDescriptor;
|
USB HID Descriptor for mouse |
ReportDescriptor:Pointer;
|
USB HID Report Descriptor for mouse |
PendingCount:LongWord;
|
Number of USB requests pending for this mouse |
WaiterThread:TThreadId;
|
Thread waiting for pending requests to complete (for mouse detachment) |
Public variables
None defined
Function declarations
Initialization functions
procedure USBMouseInit;
Description: Initialize the USB mouse driver
| Note | Called only during system startup |
|---|
USB mouse functions
function USBMouseDriverBind(Device:PUSBDevice; Interrface:PUSBInterface):LongWord;
Description: Bind the Mouse driver to a USB device if it is suitable
| Device | The USB device to attempt to bind to |
|---|---|
| Interrface | The USB interface to attempt to bind to (or nil for whole device) |
| Return | USB_STATUS_SUCCESS if completed, USB_STATUS_DEVICE_UNSUPPORTED if unsupported or another error code on failure. |
function USBMouseDriverUnbind(Device:PUSBDevice; Interrface:PUSBInterface):LongWord;
Description: Unbind the Mouse driver from a USB device
| Device | The USB device to unbind from |
|---|---|
| Interrface | The USB interface to unbind from (or nil for whole device) |
| Return | USB_STATUS_SUCCESS if completed or another error code on failure |
procedure USBMouseReportWorker(Request:PUSBRequest);
Description: Called (by a Worker thread) to process a completed USB request from a USB mouse IN interrupt endpoint
| Request | The USB request which has completed |
|---|
procedure USBMouseReportComplete(Request:PUSBRequest);
Description: Called when a USB request from a USB mouse IN interrupt endpoint completes
| Request | The USB request which has completed |
|---|---|
| Note | Request is passed to worker thread for processing to prevent blocking the USB completion |
USB mouse helper functions
function USBMouseCheckDevice(Device:PUSBDevice):Boolean;
Description: Check if the supplied USB device is suitable for detection as a HID Mouse Device
| Device | The USB device to check |
|---|---|
| Return | True if the device is suitable or False if it is not |
function USBMouseDeviceSetProtocol(Mouse:PUSBMouseDevice; Protocol:Byte):LongWord;
Description: Set the report protocol for a USB mouse device
| Mouse | The USB mouse device to set the report protocol for |
|---|---|
| Protocol | The report protocol to set (eg USB_HID_PROTOCOL_BOOT) |
| Return | USB_STATUS_SUCCESS if completed or another USB error code on failure |
function USBMouseDeviceGetHIDDescriptor(Mouse:PUSBMouseDevice; Descriptor:PUSBHIDDescriptor):LongWord;
Description: Get the HID Descriptor for a USB mouse device
| Mouse | The USB mouse device to get the descriptor for |
|---|---|
| Descriptor | Pointer to a USB HID Descriptor structure for the returned data |
| Return | USB_STATUS_SUCCESS if completed or another USB error code on failure |
function USBMouseDeviceGetReportDescriptor(Mouse:PUSBMouseDevice; Descriptor:Pointer; Size:LongWord):LongWord;
Description: Get the Report Descriptor for a USB mouse device
| Mouse | The USB mouse device to get the descriptor for |
|---|---|
| Descriptor | Pointer to a buffer to return the USB Report Descriptor |
| Size | The size in bytes of the buffer pointed to by Descriptor |
| Return | USB_STATUS_SUCCESS if completed or another USB error code on failure |
Return to Unit Reference
