Jan Axelson, USB Complete
Подождите немного. Документ загружается.
Chapter 13
326
8% Definitions
internal struct HIDP_CAPS
{
internal Int16 Usage;
internal Int16 UsagePage;
internal Int16 InputReportByteLength;
internal Int16 OutputReportByteLength;
internal Int16 FeatureReportByteLength;
[ MarshalAs( UnmanagedType.ByValArray, SizeConst=17 ) ]
internal Int16[] Reserved;
internal Int16 NumberLinkCollectionNodes;
internal Int16 NumberInputButtonCaps;
internal Int16 NumberInputValueCaps;
internal Int16 NumberInputDataIndices;
internal Int16 NumberOutputButtonCaps;
internal Int16 NumberOutputValueCaps;
internal Int16 NumberOutputDataIndices;
internal Int16 NumberFeatureButtonCaps;
internal Int16 NumberFeatureValueCaps;
internal Int16 NumberFeatureDataIndices;
}
[ DllImport( "hid.dll", SetLastError=true ) ]
internal static extern Int32 HidP_GetCaps
( IntPtr PreparsedData,
ref HIDP_CAPS Capabilities );
Use
internal HIDP_CAPS Capabilities;
Int32 result = 0;
result = HidP_GetCaps( preparsedData, ref Capabilities );
&GVCKNU
The preparsedData parameter is the pointer returned by
HidD_GetPreparsedData. When the function returns, the application can
examine and use whatever values are of interest in the Capabilities structure.
For example, to look for a joystick, look for UsagePage = 0001h and Usage =
0004h.
The ReportByteLength items are useful when setting buffer sizes for sending
and receiving reports.
Human Interface Devices: Host Application
327
)GVVKPIVJG%CRCDKNKVKGUQHVJG$WVVQPUCPF8CNWGU
An application can also retrieve the capabilities of each button and value in a
report. HidP_GetValueCaps returns a pointer to an array of structures contain-
ing information about the values in a report. The NumberInputValueCaps
property of the HIDP_CAPS structure is the number of structures returned by
HidP_GetValueCaps.
The items in the structures include many values obtained from the HID’s
report descriptor as described in Chapter 12. The items include the Report ID,
whether a value is absolute or relative, whether a value has a null state, and log-
ical and physical minimums and maximums. A LinkCollection identifier dis-
tinguishes between controls with the same Usage and Usage Page in the same
collection. In a similar way, the HidP_GetButtonCaps function can retrieve
information about a report’s buttons. The information is stored in a
HidP_ButtonCaps structure. Not every application needs to retrieve this infor-
mation.
5GPFKPICPF4GEGKXKPI4GRQTVU
The previous API functions help in finding and learning about a device that
matches what the application is looking for. On finding a device of interest, the
application and device are ready to exchange data in reports.
Table 13-3 showed API functions for exchanging reports. Table 13-6 summa-
rizes the transfer types the host uses with different report types. The application
doesn’t have to know or care which transfer type or endpoint the driver uses.
Table 13-6: The transfer type used to send or receive a report can vary
with the API function, operating system edition, and available endpoints.
4GRQTV6[RG #2+(WPEVKQP 6TCPUHGT6[RG
Input ReadFile Interrupt IN
HidD_GetInputReport
(Windows XP and later)
Control with Get Report request
Output WriteFile Interrupt OUT if available; otherwise
control with Set Report request
HidD_SetOutputReport
(Windows XP and later)
Control with Set Report request
Feature IN HidD_GetFeature Control with Get Report request
Feature OUT HidD_SetFeature Control with Set Report request
Chapter 13
328
5GPFKPICP1WVRWV4GRQTVVQVJG&GXKEG
On obtaining a handle and learning the number of bytes in an Output report,
an application can send a report to the HID. The application places the data to
send in a buffer and calls WriteFile.
8$ Definitions
<DllImport("kernel32.dll", SetLastError:=True)> _
Shared Function WriteFile _
(ByVal hFile As SafeFileHandle, _
ByVal lpBuffer() As Byte, _
ByVal nNumberOfBytesToWrite As Int32, _
ByRef lpNumberOfBytesWritten As Int32, _
ByVal lpOverlapped As IntPtr) _
As Boolean
End Function
Use
Dim numberOfBytesWritten As Int32 = 0
Dim outputReportBuffer() As Byte = Nothing
Dim success As Boolean
' Set the size of the Output report buffer.
Array.Resize(outputReportBuffer, Capabilities.OutputReportByteLength)
' Store the Report ID in the first byte of the buffer:
outputReportBuffer(0) = 0
' Store the report data following the Report ID. Example:
outputReportBuffer(1) = 85
outputReportBuffer(2) = 83
outputReportBuffer(3) = 66
' Send the report.
success = WriteFile _
(deviceHandle, _
outputReportBuffer, _
outputReportBuffer.Length, _
numberOfBytesWritten, _
IntPtr.Zero)
Human Interface Devices: Host Application
329
8% Definitions
[ DllImport( "kernel32.dll", SetLastError=true ) ]
internal static extern Boolean WriteFile
( SafeFileHandle hFile,
Byte[] lpBuffer,
Int32 nNumberOfBytesToWrite,
ref Int32 lpNumberOfBytesWritten,
IntPtr lpOverlapped );
Use
Int32 numberOfBytesWritten = 0;
Byte[] outputReportBuffer = null;
Boolean success = false;
// Set the size of the Output report buffer.
Array.Resize(ref outFeatureReportBuffer, Capabilities.FeatureReportByteLength);
// Store the Report ID in the first byte of the buffer:
outputReportBuffer[ 0 ] = 0;
// Store the report data following the Report ID. Example:
outputReportBuffer[ 1 ] = 85;
outputReportBuffer[ 2 ] = 83;
outputReportBuffer[ 3 ] = 66;
// Send the report.
success = WriteFile
(deviceHandle,
outputReportBuffer,
outputReportBuffer.Length,
ref numberOfBytesWritten,
IntPtr.Zero);
&GVCKNU
In the call to WriteFile, the hFile parameter is a handle returned by CreateFile.
The lpBuffer parameter is a byte array that contains the report ID followed by
the report data. The nNumberOfBytesToWrite parameter specifies how many
bytes to write and should equal the OutputReportByteLength property of the
Chapter 13
330
HIDP_CAPS structure retrieved with HidP_GetCaps. This value is the report
size in bytes plus one byte for the Report ID.
The lpOverlapped parameter is a null pointer in this example, but WriteFile
can use overlapped I/O as described in the following section on ReadFile. Over-
lapped I/O can prevent the application’s thread from hanging if the HID’s
interrupt OUT endpoint NAKs endlessly. In normal operation, the endpoint
should accept received data with little delay.
On success, the function returns true with lpNumberOfBytesWritten pointing
to the number of bytes the function wrote to the HID.
If the interface supports only the default Report ID of zero, the Report ID
doesn’t transmit on the bus, but the Report ID must always be the first byte in
the buffer the application passes to WriteFile.
When sending a report to an interrupt endpoint, WriteFile returns on success
or error and will wait endlessly if the endpoint continues to NAK the report
data. When sending a report via the control endpoint, WriteFile returns on suc-
cess, an error, or a timeout if the endpoint continues to NAK the report data.
A returned error message of CRC Error indicates that the host controller
attempted to send the report, but the device didn’t respond as expected. Despite
the message, the problem isn’t likely to be due to an error detected in a CRC
calculation. The error is more likely to be due to a firmware problem that keeps
the endpoint from accepting the report data. If WriteFile doesn’t return at all,
the interrupt OUT endpoint possibly isn’t configured to ACK the report data.
4GCFKPICP+PRWV4GRQTVHTQOVJG&GXKEG
The complement to WriteFile is ReadFile. After obtaining a handle to the HID
interface and learning the size of the largest Input report, an application can use
ReadFile to read an Input report from a device.
When called using non-overlapped I/O, ReadFile is a blocking call. If an appli-
cation calls the function when the HID driver’s Input buffer is empty, the call-
ing thread waits until a report is available, the user closes the application from
the Task Manager, or the user removes the device from the bus. An overlapped,
or asynchronous, read operation can keep an application’s main thread from
hanging as it waits for a report.
With an overlapped read, ReadFile returns immediately whether a report is
available or not. If the function doesn’t return a report, the application can call
WaitForSingleObject with a specified timeout. WaitForSingleObject returns
Human Interface Devices: Host Application
331
when a report is available or on a timeout or other error. On a timeout or error,
the application can try again or call the CancelIo function to cancel the read
operation. This approach works well if reports are normally available without
delay but the application needs to regain control if for some reason there is no
report.
To prevent long delays waiting for WaitForSingleObject to return, an applica-
tion can set the timeout to zero and call the function repeatedly in a loop or at
intervals, triggered by a timer. The function returns immediately whether or
not a report is available, and the application can perform other tasks in the loop
or between timer events.
To improve performance, an application can call ReadFile in a separate thread
that notifies the main thread when a report is available. A .NET application can
define an asynchronous delegate and use the BeginInvoke method to call a
method that calls ReadFile in a different thread. BeginInvoke can specify a call-
back routine that executes in the application’s main thread when the method
that has called ReadFile returns. The callback routine can retrieve the returned
report and use the received data as needed.
This example uses overlapped reads with a timeout:
8$ Definitions
Friend Const FILE_FLAG_OVERLAPPED As Int32 = &H40000000
Friend Const GENERIC_READ As UInt32 = &H80000000UL
Friend Const GENERIC_WRITE As UInt32 = &H40000000
Friend Const WAIT_OBJECT_0 As Int32 = 0
Friend Const WAIT_TIMEOUT As Int32 = &H102
<DllImport("kernel32.dll", SetLastError:=True)> _
Shared Function CancelIo _
(ByVal hFile As SafeFileHandle) _
As Int32
End Function
<DllImport("kernel32.dll", CharSet:=CharSet.Auto, SetLastError:=True)> _
Shared Function CreateEvent _
(ByVal SecurityAttributes As IntPtr, _
ByVal bManualReset As Boolean, _
ByVal bInitialState As Boolean, _
ByVal lpName As String) _
As IntPtr
End Function
Chapter 13
332
<DllImport("kernel32.dll", CharSet:=CharSet.Auto, SetLastError:=True)> _
Shared Function GetOverlappedResult _
(ByVal hFile As SafeFileHandle, _
ByVal lpOverlapped As IntPtr, _
ByRef lpNumberOfBytesTransferred As Int32, _
ByVal bWait As Boolean) _
As Boolean
End Function
<DllImport("kernel32.dll", SetLastError:=True)> _
Shared Function ReadFile _
(ByVal hFile As SafeFileHandle, _
ByVal lpBuffer As IntPtr, _
ByVal nNumberOfBytesToRead As Int32, _
ByRef lpNumberOfBytesRead As Int32, _
ByVal lpOverlapped As IntPtr) _
As Boolean
End Function
<DllImport("kernel32.dll", SetLastError:=True)> _
Shared Function WaitForSingleObject _
(ByVal hHandle As IntPtr, _
ByVal dwMilliseconds As Int32) _
As Int32
End Function
Use
Dim eventObject As IntPtr
Dim HidOverlapped As New NativeOverlapped
Dim inputReportBuffer() As Byte = Nothing
Dim numberOfBytesRead As Int32
Dim result As Int32
Dim success As Boolean
Dim unManagedBuffer As IntPtr
Dim unManagedOverlapped As IntPtr
Array.Resize(inputReportBuffer, Capabilities.InputReportByteLength)
Human Interface Devices: Host Application
333
eventObject = CreateEvent
(IntPtr.Zero,
False,
False,
String.Empty)
HidOverlapped.OffsetLow = 0
HidOverlapped.OffsetHigh = 0
HidOverlapped.EventHandle = eventObject
unManagedBuffer = Marshal.AllocHGlobal(inputReportBuffer.Length)
unManagedOverlapped = Marshal.AllocHGlobal(Marshal.SizeOf(HidOverlapped))
Marshal.StructureToPtr(HidOverlapped, unManagedOverlapped, False)
readHandle = CreateFile _
(devicePathName, _
GENERIC_READ, _
FILE_SHARE_READ Or FILE_SHARE_WRITE, _
IntPtr.Zero, _
OPEN_EXISTING, _
FILE_FLAG_OVERLAPPED, _
0)
success = ReadFile _
(readHandle, _
unManagedBuffer, _
inputReportBuffer.Length, _
numberOfBytesRead, _
unManagedOverlapped)
Chapter 13
334
' If ReadFile returned True, a report is available. Otherwise, check for completion.
If Not (success) Then
result = WaitForSingleObject(eventObject, 3000)
Select Case result
Case WAIT_OBJECT_0
success = True
GetOverlappedResult _
(readHandle, _
unManagedOverlapped, _
numberOfBytesRead, _
False)
Case WAIT_TIMEOUT
CancelIo(readHandle)
Case Else
CancelIo(readHandle)
End Select
End If
If success Then
' A report was received.
' Copy the received data to inputReportBuffer for the application to use.
Marshal.Copy _
(unManagedBuffer, inputReportBuffer, 0, numberOfBytesRead)
End If
Marshal.FreeHGlobal(unManagedOverlapped)
Marshal.FreeHGlobal(unManagedBuffer)
8%
Definitions
internal const Int32 FILE_FLAG_OVERLAPPED = 0X40000000;
internal const UInt32 GENERIC_READ = 0X80000000;;
internal const UInt32 GENERIC_WRITE = 0X40000000;
internal const Int32 WAIT_OBJECT_0 = 0;
internal const Int32 WAIT_TIMEOUT = 0X102;
Human Interface Devices: Host Application
335
[ DllImport( "kernel32.dll", SetLastError=true ) ]
internal static extern Int32 CancelIo
( SafeFileHandle hFile );
[ DllImport( "kernel32.dll", CharSet=CharSet.Auto, SetLastError=true ) ]
internal static extern IntPtr CreateEvent
( IntPtr SecurityAttributes,
Boolean bManualReset,
Boolean bInitialState,
String lpName );
[DllImport("kernel32.dll", CharSet = CharSet.Auto, SetLastError = true)]
internal static extern Boolean GetOverlappedResult
(SafeFileHandle hFile,
IntPtr lpOverlapped,
ref Int32 lpNumberOfBytesTransferred,
Boolean bWait);
[ DllImport( "kernel32.dll", SetLastError=true ) ]
internal static extern Boolean ReadFile
( SafeFileHandle hFile,
IntPtr lpBuffer,
Int32 nNumberOfBytesToRead,
ref Int32 lpNumberOfBytesRead,
IntPtr lpOverlapped );
[ DllImport( "kernel32.dll", SetLastError=true ) ]
internal static extern Int32 WaitForSingleObject
( IntPtr hHandle,
Int32 dwMilliseconds );
Use
IntPtr eventObject= IntPtr.Zero;
NativeOverlapped HidOverlapped = new NativeOverlapped();
Byte[] inputReportBuffer = null;
Int32 numberOfBytesRead = 0;
Int32 result = 0;
Boolean success = false;
IntPtr unManagedBuffer = IntPtr.Zero;
IntPtr unManagedOverlapped = IntPtr.Zero;
Array.Resize(ref inputReportBuffer, Capabilities.InputReportByteLength);