Unit HID

Return to Unit Reference

Description

---

Ultibo Human Interface Device (HID) Interface unit

The Human Interface Device (HID) class is intended to provide a flexible model that allows a wide range of control types to be expressed using a standard set of tags in a report descriptor that each device provides during initialization.

HID devices can represent common items such as mice, keyboards, touchscreens, gamepads and joysticks but can also appear as controls within many other types of devices.

A headset for example will primarily be an audio device but the volume and mute buttons can be defined using the HID standard and easily recognized by software without requiring a custom driver for each and every device.

The Ultibo HID implementation creates an intermediate device layer that is mostly agnostic to both the bus type being used by an underlying provider (such as USB) and the devices recognized by HID consumers such as mice and keyboards.

A provider such as USB HID locates devices from the provider specific bus and creates HID devices to represent them along with obtaining report descriptors and other information.

These HID devices are then passed to registered HID consumers (drivers) to determine if they recognize the collections, reports and usages described by the device. A consumer can accept a device and bind to it during this process and create its own devices to represent the functionality described by the HID device.

While HID itself is intended to be bus agnostic this implementation is based heavily on the USB HID standards as those are the most widely adopted at this time. It is anticipated that HID adoption will expand over time to include a range other bus types, Bluetooth is already using HID and there are existing implementations of HID over I2C, SPI and PCI.

Expanding the Ultibo HID support to other bus types simply requires a new HID provider for that bus to be written along with any necessary changes or extensions to the HID layer itself.

Constants

---

To be documented

Type definitions

---

HID descriptor

[Expand]

PHIDDescriptor = ^THIDDescriptor;

THIDDescriptor = packed record

See Section 6.2.1
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

HID report descriptor

[Expand]

PHIDReportDescriptor = Pointer;

See Section 6.2.2

HID physical descriptor

[Expand]

PHIDPhysicalDescriptor = ^THIDPhysicalDescriptor;

THIDPhysicalDescriptor = packed record

See Section 6.2.3
bDesignator:Byte;	Indicates which part of the body affects the item
bFlags:Byte;	Bits specifying flags (7..5 Qualifier / 4..0 Effort)

HID physical descriptor set0

[Expand]

PHIDPhysicalDescriptorSet0 = ^THIDPhysicalDescriptorSet0;

THIDPhysicalDescriptorSet0 = packed record

bNumber:Byte;	Number of Physical Descriptor sets not including Physical Descriptor set 0
wLength:Word;	Length of each Physical descriptor set

HID physical descriptor set

[Expand]

PHIDPhysicalDescriptorSet = ^THIDPhysicalDescriptorSet;

THIDPhysicalDescriptorSet = packed record

bPhysicalInfo:Byte;	Bits specifying physical information (7..5 Bias / 4..0 Preference)
wPhysicalDescriptor:array[0..0] of THIDPhysicalDescriptor;	Physical descriptor data

HID state

[Expand]

PHIDState = ^THIDState;

THIDState = record

Local State
Usage:LongWord;
UsageCount:LongWord;	Provides UsageMinimum/UsageMaximum
DesignatorIndex:LongWord;
DesignatorCount:LongWord;	Provides DesignatorMinimum/DesignatorMaximum
StringIndex:LongWord;
StringCount:LongWord;	Provides StringMinimum/StringMaximum
Delimiter:Boolean;
Global State
UsagePage:Word;
LogicalMinimum:LongInt;
LogicalMaximum:LongInt;
PhysicalMinimum:LongInt;
PhysicalMaximum:LongInt;
UnitType:LongWord;
UnitExponent:LongWord;
ReportSize:LongWord;
ReportId:LongWord;
ReportCount:LongWord;

HID stack

[Expand]

PHIDStack = ^THIDStack;

THIDStack = record

State:PHIDState;
Next:PHIDStack;

HID usages

[Expand]

PHIDUsages = ^THIDUsages;

THIDUsages = array[0..0] of PHIDUsage;

HID usage

[Expand]

PHIDUsage = ^THIDUsage;

THIDUsage = record

Page:Word;	The usage page this usage refers to
Usage:Word;	The usage within the usage page
Count:Word;	The total number of sequential usages where Usage represents the minimum value or 1 for a single usage (Usage range is from Usage to Usage + Count - 1)
Index:LongWord;	The index of this usage in the report (First usage is 0)
StringIndex:LongWord;	The string index for this usage
StringCount:LongWord;	The total number of sequential string index values where string index represents the minimum value or 1 for a single string
DesignatorIndex:LongWord;	The designator index for this usage
DesignatorCount:LongWord;	The total number of sequential designator index values where designator index represents the minimum value or 1 for a single designator
LogicalMinimum:LongInt;	The logical minimum value for this usage
LogicalMaximum:LongInt;	The logical maximum value for this usage
PhysicalMinimum:LongInt;	The physical minimum value for this usage (in Units)
PhysicalMaximum:LongInt;	The physical maximum value for this usage (in Units)
UnitType:LongWord;	The unit type for this usage
UnitExponent:LongWord;	The unit exponent index for this usage
Aliases:PHIDUsages;	The list of aliased usages for this control (See Delimiters in Section 6.2.2.8)
AliasCount:LongWord;	The number of aliased usages contained for this control
Report:PHIDReport;	The report this usage belongs to

HID reports

[Expand]

PHIDReports = ^THIDReports;

THIDReports = array[0..0] of PHIDReport;

HID report

[Expand]

PHIDReport = ^THIDReport;

THIDReport = record

Id:Byte;	The Id of this report
Kind:Byte;	The type of report (Input, Output or Feature) (eg HID_REPORT_INPUT)
Flags:LongWord;	The main item flags for this report (eg HID_MAIN_ITEM_VARIABLE)
Size:LongWord;	The number of bits per field in this report
Count:LongWord;	The number of fields in this report
Index:LongWord;	The index of this report in the collection (First report is 0)
Usages:PHIDUsages;	The list of usages contained in this report
UsageCount:LongWord;	The number of usages contained in this report
Collection:PHIDCollection;	The collection this report belongs to

HID collections

[Expand]

PHIDCollections = ^THIDCollections;

THIDCollections = array[0..0] of PHIDCollection;

HID collection

[Expand]

PHIDCollection = ^THIDCollection;

THIDCollection = record

Page:Word;	The usage page this collection refers to (eg HID_PAGE_GENERIC_DESKTOP)
Usage:Word;	The usage within the usage page (eg HID_DESKTOP_MOUSE)
Flags:LongWord;	The main item flags for this collection (eg HID_MAIN_COLLECTION_APPLICATION)
Start:LongWord;	The first byte of this collection in the report descriptor
Reports:PHIDReports;	The list of reports contained in this collection
ReportCount:LongWord;	The number of reports contained in this collection
Collections:PHIDCollections;	The list of collections contained in this collection
CollectionCount:LongWord;	The number of collections contained in this collection
Parent:PHIDCollection;	The parent collection or nil if this is a top level collection
Device:PHIDDevice;	The device this collection belongs to
Consumer:PHIDConsumer;	The consumer which is bound to this collection (or nil if not bound)
PrivateData:Pointer;	Private data for the consumer of this collection

HID device enumeration callback

THIDDeviceEnumerate = function(Device:PHIDDevice;Data:Pointer):LongWord;

HID device notification callback

THIDDeviceNotification = function(Device:PDevice; Data:Pointer; Notification:LongWord):LongWord;

HID device get idle

THIDDeviceGetIdle = function(Device:PHIDDevice; var Duration:Word; ReportId:Byte):LongWord;

HID device set idle

THIDDeviceSetIdle = function(Device:PHIDDevice; Duration:Word; ReportId:Byte):LongWord;

HID device get report

THIDDeviceGetReport = function(Device:PHIDDevice; ReportType,ReportId:Byte; ReportData:Pointer; ReportSize:LongWord):LongWord;

HID device set report

THIDDeviceSetReport = function(Device:PHIDDevice; ReportType,ReportId:Byte; ReportData:Pointer; ReportSize:LongWord):LongWord;

HID device allocate report

THIDDeviceAllocateReport = function(Device:PHIDDevice; Collection:PHIDCollection; ReportId:Byte; ReportSize:LongWord):LongWord;

HID device release report

THIDDeviceReleaseReport = function(Device:PHIDDevice; ReportId:Byte):LongWord;

HID device submit report

THIDDeviceSubmitReport = function(Device:PHIDDevice; ReportId:Byte):LongWord;

HID device cancel report

THIDDeviceCancelReport = function(Device:PHIDDevice; ReportId:Byte):LongWord;

HID device get protocol

THIDDeviceGetProtocol = function(Device:PHIDDevice; var Protocol:Byte):LongWord;

HID device set protocol

THIDDeviceSetProtocol = function(Device:PHIDDevice; Protocol:Byte):LongWord;

HID device get interval

THIDDeviceGetInterval = function(Device:PHIDDevice; var Interval:LongWord):LongWord;

HID device set interval

THIDDeviceSetInterval = function(Device:PHIDDevice; Interval:LongWord):LongWord;

HID device get report descriptor

THIDDeviceGetReportDescriptor = function(Device:PHIDDevice; Descriptor:PHIDReportDescriptor; Size:LongWord):LongWord;

HID device get physical descriptor set0

THIDDeviceGetPhysicalDescriptorSet0 = function(Device:PHIDDevice; Descriptor:PHIDPhysicalDescriptorSet0):LongWord;

HID device get physical descriptor set

THIDDeviceGetPhysicalDescriptorSet = function(Device:PHIDDevice; Descriptor:PHIDPhysicalDescriptorSet; Index:Byte; Size:LongWord):LongWord;

HID device

[Expand]

PHIDDevice = ^THIDDevice;

THIDDevice = record

Device Properties
Device:TDevice;	The Device entry for this HID
HID Properties
HIDId:LongWord;	Unique Id of this HID in the HID device table
HIDState:LongWord;	HID device state (eg HID_STATE_ATTACHED)
Consumer:PHIDConsumer;	The consumer which is bound to this device (or nil if not bound)
DeviceGetIdle:THIDDeviceGetIdle;	A device specific GetIdle method (If supported by provider)
DeviceSetIdle:THIDDeviceSetIdle;	A device specific SetIdle method (If supported by provider)
DeviceGetReport:THIDDeviceGetReport;	A device specific GetReport method (If supported by provider)
DeviceSetReport:THIDDeviceSetReport;	A device specific SetReport method (If supported by provider)
DeviceAllocateReport:THIDDeviceAllocateReport;	A device specific AllocateReport method (If supported by provider)
DeviceReleaseReport:THIDDeviceReleaseReport;	A device specific ReleaseReport method (If supported by provider)
DeviceSubmitReport:THIDDeviceSubmitReport;	A device specific SubmitReport method (If supported by provider)
DeviceCancelReport:THIDDeviceCancelReport;	A device specific CancelReport method (If supported by provider)
DeviceGetProtocol:THIDDeviceGetProtocol;	A device specific GetProtocol method (If supported by provider)
DeviceSetProtocol:THIDDeviceSetProtocol;	A device specific SetProtocol method (If supported by provider)
DeviceGetInterval:THIDDeviceGetInterval;	A device specific GetInterval method (If supported by provider)
DeviceSetInterval:THIDDeviceSetInterval;	A device specific SetInterval method (If supported by provider)
DeviceGetReportDescriptor:THIDDeviceGetReportDescriptor;	A device specific GetReportDescriptor method (If supported by provider)
DeviceGetPhysicalDescriptorSet0:THIDDeviceGetPhysicalDescriptorSet0;	A device specific GetPhysicalDescriptorSet0 method (If supported by provider)
DeviceGetPhysicalDescriptorSet:THIDDeviceGetPhysicalDescriptorSet;	A device specific GetPhysicalDescriptorSet method (If supported by provider)
Driver Properties
Lock:TMutexHandle;	HID device lock
PrivateData:Pointer;	Private data for the consumer of this HID device (If applicable)
Collections:PHIDCollections;	The parsed report descriptor with collections, reports and usages
CollectionCount:LongWord;	The number of top level collections contained in the report descriptor
Descriptor:PHIDReportDescriptor;	The raw report descriptor obtained from the device
DescriptorSize:LongWord;	The size of the data pointed to by Descriptor
Statistics Properties
ReceiveCount:LongWord;
ReceiveErrors:LongWord;
Internal Properties
Prev:PHIDDevice;	Previous entry in Device table
Next:PHIDDevice;	Next entry in Device table

HID consumer enumeration callback

THIDConsumerEnumerate = function(Consumer:PHIDConsumer; Data:Pointer):LongWord;

HID device bind

THIDDeviceBind = function(Device:PHIDDevice):LongWord;

HID device unbind

THIDDeviceUnbind = function(Device:PHIDDevice):LongWord;

HID collection bind

THIDCollectionBind = function(Device:PHIDDevice; Collection:PHIDCollection):LongWord;

HID collection unbind

THIDCollectionUnbind = function(Device:PHIDDevice; Collection:PHIDCollection):LongWord;

HID report receive

THIDReportReceive = function(Collection:PHIDCollection; ReportId:Byte; ReportData:Pointer; ReportSize:LongWord):LongWord;

HID consumer

[Expand]

PHIDConsumer = ^THIDConsumer;

THIDConsumer = record

Driver Properties
Driver:TDriver;	The Driver entry for this HID Consumer
Consumer Properties
DeviceBind:THIDDeviceBind;	A Device Bind method to be called when a HID device bind is requested by a provider (Optional)
DeviceUnbind:THIDDeviceUnbind;	A Device Ubind method to be called when a HID device unbind is requested by a provider (Optional)
CollectionBind:THIDCollectionBind;	A Collection Bind method to be called when a HID collection bind is requested by a provider (Mandatory)
CollectionUnbind:THIDCollectionUnbind;	A Collection Unbind method to be called when a HID collection unbind is requested by a provider (Mandatory)
ReportReceive:THIDReportReceive;	A Report Receive method to be called when a HID input report is received by a provider (Mandatory)
Interface Properties
Lock:TMutexHandle;	Consumer lock
Internal Properties
Prev:PHIDConsumer;	Previous entry in Consumer table
Next:PHIDConsumer;	Next entry in Consumer table

HID report field

[Expand]

PHIDField = ^THIDField;

THIDField = record

Page:Word;	The usage page of this field
Usage:Word;	The usage within the usage page
Count:LongWord;	The total number of sequential usages where Usage represents the minimum value or 1 for a single usage (Usage range is from Usage to Usage + Count - 1)
Flags:LongWord;	The flags for this field
Size:LongWord;	The length in bytes of this field within the input, output or feature report
Bits:LongWord;	The length in bits of this field within the input, output or feature report
Offset:LongWord;	The byte offset of this field within the input, output or feature report
Shift:LongWord;	The number shift bits to access this field in the input, output or feature report
Minimum:LongInt;	The minimum value for this field (either in logical or physical units)
Maximum:LongInt;	The maximum value for this field (either in logical or physical units)
Multiplier:Double;	The conversion multiplier for this field from logical to physical units
Resolution:Double;	The unit resolution for this field in counts per physical unit
Next:PHIDField;	The next field in the list

HID report definition

[Expand]

PHIDDefinition = ^THIDDefinition;

THIDDefinition = record

Id:Byte;	The Id of this report
Kind:Byte;	The type of this report (Input, Output or Feature)
Size:LongWord;	The total length of this input, output or feature report in bytes (Including the Id byte)
Fields:PHIDField;	Linked list of fields in this input, output or feature report
Next:PHIDDefinition;	The next definition in the list

Public variables

---

HID logging

HID_DEFAULT_LOG_LEVEL:LongWord = HID_LOG_LEVEL_DEBUG;

Minimum level for HID messages. Only messages with level greater than or equal to this will be printed.

HID_LOG_ENABLED:Boolean;

Function declarations

---

Initialization functions

[Expand]

procedure HIDInit;

Description: Initialize the HID unit, device and consumer tables

Note	Called only during system startup

HID functions

[Expand]

function HIDParserParseCollections(Device:PHIDDevice; var Collections:PHIDCollections; var Count:LongWord):LongWord;

Description: Parse the HID report descriptor of the provided device and popuplate the collections, reports and usages

Device	The HID device to parse collections for
Collections	A pointer to the top level collections array to be populated
Count	A variable to return the number of top level collections
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function HIDParserFreeCollections(Collections:PHIDCollections; Count:LongWord):LongWord;

Description: Free the collections, reports and usages parsed from a HID report descriptor

Collections	A pointer to the top level collections array to be freed
Count	The number of top level collections in the array
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function HIDParserCountCollections(Device:PHIDDevice; Parent:PHIDCollection):LongWord;

Description: Count the number of collections found in the HID report descriptor of the provided device

Device	The HID device to count collections for
Parent	The parent HID collection, if supplied count child collections else count top level collections
Return	The number of collections found, 0 if none for or on error

[Expand]

function HIDParserCountReports(Device:PHIDDevice; Collection:PHIDCollection):LongWord;

Description: Count the number of reports found in the HID report descriptor of the supplied device and collection

Device	The HID device to count reports for
Collection	The HID collection to count reports for
Return	The number of reports found, 0 if none for or on error

[Expand]

function HIDParserCountUsages(Device:PHIDDevice; Report:PHIDReport):LongWord;

Description: Count the number of usages found in the HID report descriptor for the supplied device and report

Device	The HID device to count usages for
Report	The HID report to count usages for
Return	The number of usages found, 0 if none for or on error

[Expand]

function HIDParserAllocateCollection(Device:PHIDDevice; Parent:PHIDCollection; State:PHIDState; Flags,Start:LongWord):PHIDCollection;

Description: Allocate a HID collection to contain a set of reports and usages from a HID report descriptor

Device	The HID device containing the collection
Parent	The HID collection containing the collection (or nil for a top level collection)
State	The current HID parser state
Flags	The flags for the collection from the HID report descriptor
Start	The starting byte offset of the collection in the HID report descriptor
Return	A pointer to the HID collection or nil on error

[Expand]

function HIDParserAllocateReport(Device:PHIDDevice; Collection:PHIDCollection; State:PHIDState; Kind:Byte; Flags,Index:LongWord):PHIDReport;

Description: Allocate a HID report to contain a set of usages from a HID report descriptor

Device	The HID device containing the report
Collection	The HID collection containing the report
State	The current HID parser state
Kind	The report kind (eg HID_REPORT_INPUT)
Flags	The flags for the report from the HID report descriptor
Index	The index of this report in the collection (First report is 0)
Return	A pointer to the HID report or nil on error

[Expand]

function HIDParserAllocateUsage(Device:PHIDDevice; Report:PHIDReport; State:PHIDState; Index:LongWord):PHIDUsage;

Description: Allocate a HID usage from a HID report descriptor

Device	The HID device containing the usage
Report	The HID report containing the usage
State	The current HID parser state
Index	The index of this usage in the report (First usage is 0)
Return	A pointer to the HID usage or nil on error

[Expand]

function HIDParserUpdateUsage(Device:PHIDDevice; Report:PHIDReport; State:PHIDState; Usage:PHIDUsage):Boolean;

Description: Update a HID usage from a HID report descriptor

Device	The HID device containing the usage
Report	The HID report containing the usage
State	The current HID parser state
Usage	The HID usage to update
Return	True if completed or False on error
Note	As usages must precede the main item they relate to in the HID report descriptor they need to be allocated before all the required information is known, this function updates the usage after the main item is found.

[Expand]

function HIDParserPopStack(var Stack:PHIDStack; var State:PHIDState):LongWord;

Description: Replace the current HID parser state with the top item from the parser stack

Stack	The HID parser stack
State	The HID parser state to replace
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function HIDParserPushStack(Stack:PHIDStack):LongWord;

Description: Place a copy of the current HID parser state on top of the parser stack

Stack	The HID parser stack
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function HIDParserFreeStack(Stack:PHIDStack):LongWord;

Description: Free the HID parser stack and state

Stack	The HID parser stack
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function HIDParserResetState(State:PHIDState):LongWord;

Description: Clear the Local and Global HID parser state

State	The HID parser state to reset
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function HIDParserCleanState(State:PHIDState):LongWord;

Description: Clear the Local HID parser state

State	The HID parser state to clean
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function HIDFindCollection(Device:PHIDDevice; Page,Usage:Word):PHIDCollection;

Description: Find the first HID collection matching the specified page and usage

Device	The HID device to find collections from
Page	The HID Usage Page to match (eg HID_PAGE_GENERIC_DESKTOP)
Usage	The HID Usage to match (eg HID_DESKTOP_MOUSE)
Return	A pointer to the first matching collection or nil if not matched

[Expand]

function HIDFindReportIds(Device:PHIDDevice; Collection:PHIDCollection; var MinId,MaxId:Byte):LongWord;

Description: Find the minimum and maximum report ids contained in the specified HID collection or all collections

Device	The HID device to find report ids from
Collection	The HID collection to find report ids from (or nil to find from all collections)
MinId	A variable to receive the minimum report id number
MaxId	A variable to receive the maximum report id number
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function HIDAllocateDefinition(Device:PHIDDevice; Collection:PHIDCollection; Kind,Id:Byte):PHIDDefinition;

Description: Allocate a HID defintion to describe an input, output or feature report contained in the specified collection

Device	The HID device to create the report definition from
Collection	The HID collection to create the report definition from
Kind	The report kind to create a definition for (eg HID_REPORT_INPUT)
Id	The report id to create a definition for (must be less than or equal to the maximum report id)
Return	A pointer to the allocated definition or nil on error

[Expand]

function HIDFreeDefinition(Definition:PHIDDefinition):LongWord;

Description: Free a HID definition to describing an input, output or feature report

Definition	The HID definition to be freed
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function HIDInsertBitField(Field:PHIDField; Buffer:Pointer; Size:LongWord; Value:Boolean):LongWord;

Description: Insert a bit field value into a report buffer

Field	The field to insert into the report
Buffer	A pointer to the report buffer
Size	The size in bytes of the report buffer
Value	The value to insert into the buffer
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function HIDInsertSignedField(Field:PHIDField; Buffer:Pointer; Size:LongWord; Value:LongInt):LongWord;

Description: Insert a signed field value into a report buffer

Field	The field to insert into the report
Buffer	A pointer to the report buffer
Size	The size in bytes of the report buffer
Value	The value to insert into the buffer
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function HIDInsertUnsignedField(Field:PHIDField; Buffer:Pointer; Size,Value:LongWord):LongWord;

Description: Insert an unsigned field value into a report buffer

Field	The field to insert into the report
Buffer	A pointer to the report buffer
Size	The size in bytes of the report buffer
Value	The value to insert into the buffer
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function HIDExtractBitField(Field:PHIDField; Buffer:Pointer; Size:LongWord; var Value:Boolean):LongWord;

Description: Extract a bit field value from a report buffer

Field	The field to extract from the report
Buffer	A pointer to the report buffer
Size	The size in bytes of the report buffer
Value	A variable to receive the extracted value
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function HIDExtractSignedField(Field:PHIDField; Buffer:Pointer; Size:LongWord; var Value:LongInt):LongWord;

Description: Extract a signed field value from a report buffer

Field	The field to extract from the report
Buffer	A pointer to the report buffer
Size	The size in bytes of the report buffer
Value	A variable to receive the extracted value
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function HIDExtractUnsignedField(Field:PHIDField; Buffer:Pointer; Size:LongWord; var Value:LongWord):LongWord;

Description: Extract an unsigned field value from a report buffer

Field	The field to extract from the report
Buffer	A pointer to the report buffer
Size	The size in bytes of the report buffer
Value	A variable to receive the extracted value
Return	ERROR_SUCCESS if completed or another error code on failure

HID Device functions

[Expand]

function HIDDeviceSetState(Device:PHIDDevice; State:LongWord):LongWord;

Description: Set the state of the specified HID device and send a notification

Device	The HID device to set the state for
State	The new state to set and notify (eg HID_STATE_ATTACHED)
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function HIDDeviceGetIdle(Device:PHIDDevice; var Duration:Word; ReportId:Byte):LongWord;

Description: Get the idle rate from a HID device for the specified report id

Device	The HID device to get the idle rate from
Duration	A variable to receive the idle rate (in Milliseconds)
ReportId	The report id to get the idle rate from
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function HIDDeviceSetIdle(Device:PHIDDevice; Duration:Word; ReportId:Byte):LongWord;

Description: Set the idle rate on a HID device for the specified report id

Device	The HID device to set the idle rate for
Duration	The idle rate to set (in Milliseconds)
ReportId	The report id to set the idle rate for
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function HIDDeviceGetReport(Device:PHIDDevice; ReportType,ReportId:Byte; ReportData:Pointer; ReportSize:LongWord):LongWord;

Description: Read a report by type and id from a HID device

Device	The HID device to read the report from
ReportType	The report type to read (eg HID_REPORT_INPUT)
ReportId	The report id to read (eg HID_REPORTID_NONE)
ReportData	A pointer to a buffer to receive the report data
ReportSize	The size in bytes of the buffer pointed to by report data
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function HIDDeviceSetReport(Device:PHIDDevice; ReportType,ReportId:Byte; ReportData:Pointer; ReportSize:LongWord):LongWord;

Description: Write a report by type and id to a HID device

Device	The HID device to write the report to
ReportType	The report type to write (eg HID_REPORT_OUTPUT)
ReportId	The report id to write (eg HID_REPORTID_NONE)
ReportData	A pointer to a buffer containing the report data
ReportSize	The size in bytes of the buffer pointed to by report data
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function HIDDeviceAllocateReport(Device:PHIDDevice; Collection:PHIDCollection; ReportId:Byte; ReportSize:LongWord):LongWord;

Description: Allocate and initialize an input report by id on a HID device

Device	The HID device to allocate the report on
Collection	The HID collection this request corresponds to
ReportId	The report id to allocate (eg HID_REPORTID_NONE)
ReportSize	The size in bytes to allocate for the report (Provider will handle alignment and other requirements)
Return	ERROR_SUCCESS if completed or another error code on failure
Note	An allocated report must be submitted before reports will be received from the device

[Expand]

function HIDDeviceReleaseReport(Device:PHIDDevice; ReportId:Byte):LongWord;

Description: Release an input report by id from a HID device

Device	The HID device to release the report from
ReportId	The report id to allocate (eg HID_REPORTID_NONE)
Return	ERROR_SUCCESS if completed or another error code on failure
Note	If the report has been submitted it must be cancelled before being released

[Expand]

function HIDDeviceSubmitReport(Device:PHIDDevice; ReportId:Byte):LongWord;

Description: Submit an input report by id on a HID device

Device	The HID device to submit the report on
ReportId	The report id to submit (eg HID_REPORTID_NONE)
Return	ERROR_SUCCESS if completed or another error code on failure
Note	The report must be allocated then submitted before reports will be received from the device

[Expand]

function HIDDeviceCancelReport(Device:PHIDDevice; ReportId:Byte):LongWord;

Description: Cancel an input report by id on a HID device

Device	The HID device to cancel the report on
ReportId	The report id to cancel (eg HID_REPORTID_NONE)
Return	ERROR_SUCCESS if completed or another error code on failure
Note	The report should be cancelled then released to stop receiving reports from the device

[Expand]

function HIDDeviceGetProtocol(Device:PHIDDevice; var Protocol:Byte):LongWord;

Description: Get the report protocol from a HID device

Device	The HID device to get the report protocol from
Protocol	A variable to receive the report protocol (eg HID_PROTOCOL_REPORT)
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function HIDDeviceSetProtocol(Device:PHIDDevice; Protocol:Byte):LongWord;

Description: Set the report protocol for a HID device

Device	The HID device to set the report protocol for
Protocol	The report protocol to set (eg HID_PROTOCOL_REPORT)
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function HIDDeviceGetInterval(Device:PHIDDevice; var Interval:LongWord):LongWord;

Description: Get the polling interval from a HID device

Device	The HID device to get the polling interval from
Interval	A variable to receive the polling interval (in Milliseconds)
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function HIDDeviceSetInterval(Device:PHIDDevice; Interval:LongWord):LongWord;

Description: Set the polling interval for a HID device

Device	The HID device to set the polling interval for
Interval	The polling interval to set (in Milliseconds)
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function HIDDeviceGetReportDescriptor(Device:PHIDDevice; Descriptor:PHIDReportDescriptor; Size:LongWord):LongWord;

Description: Get the Report Descriptor for a HID device

Device	The HID device to get the descriptor for
Descriptor	Pointer to a buffer to return the HID Report Descriptor
Size	The size in bytes of the buffer pointed to by Descriptor
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function HIDDeviceGetPhysicalDescriptorSet0(Device:PHIDDevice; Descriptor:PHIDPhysicalDescriptorSet0):LongWord;

Description: Get the HID Physical Descriptor Set 0 for a HID device

Device	The HID device to get the descriptor for
Descriptor	Pointer to a HID Physical Descriptor Set 0 structure for the returned data
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function HIDDeviceGetPhysicalDescriptorSet(Device:PHIDDevice; Descriptor:PHIDPhysicalDescriptorSet; Index:Byte; Size:LongWord):LongWord;

Description: Get a HID Physical Descriptor Set for a HID device

Device	The HID device to get the descriptor for
Descriptor	Pointer to a HID Physical Descriptor Set structure for the returned data
Index	The index of the physical descriptor set to return
Size	The size in bytes of the buffer pointed to by Descriptor
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function HIDDeviceBindDevice(Device:PHIDDevice):LongWord;

Description: Attempt to bind a HID device to one of the registered consumers

Device	The HID device to attempt to bind a consumer to
Return	ERROR_SUCCESS if completed, ERROR_NOT_SUPPORTED if unsupported or another error code on failure

[Expand]

function HIDDeviceUnbindDevice(Device:PHIDDevice; Consumer:PHIDConsumer):LongWord;

Description: Unbind a HID device from a consumer

Device	The HID device to unbind a consumer from
Consumer	The consumer to unbind the device from (nil to unbind from current consumer)
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function HIDDeviceBindCollections(Device:PHIDDevice):LongWord;

Description: Attempt to bind the HID collections in the specified device to one of the registered consumers

Device	The HID device containing the collections to attempt to bind a consumer to
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function HIDDeviceUnbindCollections(Device:PHIDDevice; Consumer:PHIDConsumer):LongWord;

Description: Unbind the HID collections in the specified device from a consumer

Device	The HID device containing the collections to unbind a consumer from
Consumer	The consumer to unbind the collections from (nil to unbind from current consumer)
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function HIDDeviceCreate:PHIDDevice;

Description: Create a new HID device entry

Return	Pointer to new HID device entry or nil if HID device could not be created

[Expand]

function HIDDeviceCreateEx(Size:LongWord):PHIDDevice;

Description: Create a new HID device entry

Size	Size in bytes to allocate for new HID device (Including the HID device entry)
Return	Pointer to new HID device entry or nil if HID device could not be created

[Expand]

function HIDDeviceDestroy(Device:PHIDDevice):LongWord;

Description: Destroy an existing HID device entry

Device	The HID device to destroy
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function HIDDeviceRegister(Device:PHIDDevice):LongWord;

Description: Register a new HID device in the HID device table

Device	The HID device to register
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function HIDDeviceDeregister(Device:PHIDDevice):LongWord;

Description: Deregister a HID device from the HID device table

Device	The HID device to deregister
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function HIDDeviceFind(HIDId:LongWord):PHIDDevice;

Description: Find a HID device by ID in the HID device table

HIDId	The ID number of the HID device to find
Return	Pointer to HID device entry or nil if not found

[Expand]

function HIDDeviceFindByName(const Name:String):PHIDDevice; inline;

Description: Find a HID device by name in the device table

Name	The name of the HID device to find (eg HID0)
Return	Pointer to HID device entry or nil if not found

[Expand]

function HIDDeviceFindByDescription(const Description:String):PHIDDevice; inline;

Description: Find a HID device by description in the device table

Description	The description of the HID to find (eg Optical USB Mouse)
Return	Pointer to HID device entry or nil if not found

[Expand]

function HIDDeviceEnumerate(Callback:THIDDeviceEnumerate; Data:Pointer):LongWord;

Description: Enumerate all HID devices in the HID device table

Callback	The callback function to call for each HID device in the table
Data	A private data pointer to pass to callback for each HID device in the table
Return	ERROR_SUCCESS if completed or another error code on failure

[Expand]

function HIDDeviceNotification(Device:PHIDDevice; Callback:THIDDeviceNotification; Data:Pointer; Notification,Flags:LongWord):LongWord;

Description: Register a notification for HID device changes

Device	The HID device to notify changes for (Optional, pass nil for all HID devices)
Callback	The function to call when a notification event occurs
Data	A private data pointer to pass to callback when a notification event occurs
Notification	The events to register for notification of (eg DEVICE_NOTIFICATION_REGISTER)
Flags	The flags to control the notification (eg NOTIFIER_FLAG_WORKER)

HID consumer functions

[Expand]

function HIDConsumerCreate:PHIDConsumer;

Description: Create a new HID Consumer entry

Return	Pointer to new Consumer entry or nil if consumer could not be created

[Expand]

function HIDConsumerCreateEx(Size:LongWord):PHIDConsumer;

Description: Create a new HID Consumer entry

Size	Size in bytes to allocate for new consumer (Including the consumer entry)
Return	Pointer to new Consumer entry or nil if consumer could not be created

[Expand]

function HIDConsumerDestroy(Consumer:PHIDConsumer):LongWord;

Description: Destroy an existing HID Consumer entry

Note	None documented

[Expand]

function HIDConsumerRegister(Consumer:PHIDConsumer):LongWord;

Description: Register a new Consumer in the HID Consumer table

Note	None documented

[Expand]

function HIDConsumerDeregister(Consumer:PHIDConsumer):LongWord;

Description: Deregister a Consumer from the HID Consumer table

Note	None documented

[Expand]

function HIDConsumerFind(ConsumerId:LongWord):PHIDConsumer;

Description: Find a consumer by Id in the HID Consumer table

Note	None documented

[Expand]

function HIDConsumerFindByName(const Name:String):PHIDConsumer; inline;

Description: Find a consumer by name in the Driver table

Note	None documented

[Expand]

function HIDConsumerEnumerate(Callback:THIDConsumerEnumerate; Data:Pointer):LongWord;

Description: Enumerate all consumers in the HID Consumer table

Note	None documented

HID helper functions

[Expand]

function HIDIsBitField(Field:PHIDField):Boolean;

Description: Return True if the supplied field contains a 1 bit value

Note	None documented

[Expand]

function HIDIsByteField(Field:PHIDField):Boolean;

Description: Return True if the supplied HID field contains a 1 byte value

Note	None documented

[Expand]

function HIDIsWordField(Field:PHIDField):Boolean;

Description: Return True if the supplied HID field contains a 2 byte value

Note	None documented

[Expand]

function HIDIsLongField(Field:PHIDField):Boolean;

Description: Return True if the supplied HID field contains a 3 or 4 byte value

Note	None documented

[Expand]

function HIDIsSignedField(Field:PHIDField):Boolean;

Description: Return True if the supplied HID field contains a signed value

Note	None documented

[Expand]

function HIDPageToString(Page:Word):String;

Description: Return a string describing a HID usage page

Note	None documented

[Expand]

function HIDUsageToString(Page,Usage,Count:Word):String;

Description: Return a string describing a HID usage within the given page

Note	None documented

[Expand]

function HIDUnitTypeToString(UnitType:LongWord):String;

Description: Return a string describing a HID unit type

Note	None documented

[Expand]

function HIDReportKindToString(Kind:Byte):String;

Description: Return a string describing a HID report type

Note	None documented

[Expand]

function HIDReportFlagsToString(Flags:LongWord):String;

Description: Return a string describing the flags of a HID report

Note	None documented

[Expand]

function HIDCollectionFlagsToString(Flags:LongWord):String;

Description: Return a string describing the flags of a HID collection

Note	None documented

[Expand]

procedure HIDLog(Level:LongWord; Device:PHIDDevice; const AText:String);

Description: To be documented

Note	None documented

[Expand]

procedure HIDLogInfo(Device:PHIDDevice; const AText:String); inline;

Description: To be documented

Note	None documented

[Expand]

procedure HIDLogWarn(Device:PHIDDevice; const AText:String); inline;

Description: To be documented

Note	None documented

[Expand]

procedure HIDLogError(Device:PHIDDevice; const AText:String); inline;

Description: To be documented

Note	None documented

[Expand]

procedure HIDLogDebug(Device:PHIDDevice; const AText:String); inline;

Description: To be documented

Note	None documented

HID device helper functions

[Expand]

function HIDDeviceGetCount:LongWord; inline;

Description: Get the current HID Device count

Note	None documented

[Expand]

function HIDDeviceCheck(Device:PHIDDevice):PHIDDevice;

Description: Check if the supplied HID Device is in the device table

Note	None documented

[Expand]

function HIDDeviceTypeToString(HIDType:LongWord):String;

Description: Return a string describing the HID device type (eg HID_TYPE_USB)

Note	None documented

[Expand]

function HIDDeviceStateToString(HIDState:LongWord):String;

Description: Return a string describing the HID device state (eg HID_STATE_ATTACHED)

Note	None documented

[Expand]

function HIDDeviceStateToNotification(State:LongWord):LongWord;

Description: Convert a Device state value into the notification code for device notifications

Note	None documented

HID consumer helper functions

[Expand]

function HIDConsumerGetCount:LongWord; inline;

Description: Get the current HID Consumer count

Note	None documented

[Expand]

function HIDConsumerCheck(Consumer:PHIDConsumer):PHIDConsumer;

Description: Check if the supplied HID Consumer is in the consumer table

Note	None documented

Return to Unit Reference