MRPT  1.9.9
xswinusb.cpp
Go to the documentation of this file.
1 /* +------------------------------------------------------------------------+
2  | Mobile Robot Programming Toolkit (MRPT) |
3  | https://www.mrpt.org/ |
4  | |
5  | Copyright (c) 2005-2019, Individual contributors, see AUTHORS file |
6  | See: https://www.mrpt.org/Authors - All rights reserved. |
7  | Released under BSD License. See: https://www.mrpt.org/License |
8  +------------------------------------------------------------------------+ */
9 #ifdef _WIN32 // patch for MRPT
10 
11 #include "xswinusb.h"
12 #include <xslibraryloader.h>
13 
14 /*! \class XsWinUsb
15  \brief Class for dynamic loading of winusb
16 */
18 {
20  initLibrary();
21 }
22 
25 {
26  if (!m_libraryLoader->isLoaded()) m_libraryLoader->load("winusb.dll");
27 
28  m_winUsb.AbortPipe = nullptr;
29  m_winUsb.Initialize = nullptr;
30  m_winUsb.Free = nullptr;
32  m_winUsb.GetDescriptor = nullptr;
37  m_winUsb.QueryPipe = nullptr;
38  m_winUsb.SetPipePolicy = nullptr;
39  m_winUsb.GetPipePolicy = nullptr;
40  m_winUsb.ReadPipe = nullptr;
41  m_winUsb.WritePipe = nullptr;
42  m_winUsb.ControlTransfer = nullptr;
43  m_winUsb.ResetPipe = nullptr;
44  m_winUsb.AbortPipe = nullptr;
45  m_winUsb.FlushPipe = nullptr;
46  m_winUsb.SetPowerPolicy = nullptr;
47  m_winUsb.GetPowerPolicy = nullptr;
48  m_winUsb.GetOverlappedResult = nullptr;
49 
50  if (m_libraryLoader->isLoaded())
51  {
53  (WinUSB_AbortPipe*)m_libraryLoader->resolve("WinUsb_AbortPipe");
55  (WinUSB_Initialize*)m_libraryLoader->resolve("WinUsb_Initialize");
56  m_winUsb.Free = (WinUSB_Free*)m_libraryLoader->resolve("WinUsb_Free");
59  "WinUsb_GetAssociatedInterface");
62  "WinUsb_GetDescriptor");
65  "WinUsb_QueryInterfaceSettings");
68  "WinUsb_QueryDeviceInformation");
71  "WinUsb_SetCurrentAlternateSetting");
74  "WinUsb_GetCurrentAlternateSetting");
76  (WinUSB_QueryPipe*)m_libraryLoader->resolve("WinUsb_QueryPipe");
79  "WinUsb_SetPipePolicy");
82  "WinUsb_GetPipePolicy");
84  (WinUSB_ReadPipe*)m_libraryLoader->resolve("WinUsb_ReadPipe");
86  (WinUSB_WritePipe*)m_libraryLoader->resolve("WinUsb_WritePipe");
89  "WinUsb_ControlTransfer");
91  (WinUSB_ResetPipe*)m_libraryLoader->resolve("WinUsb_ResetPipe");
93  (WinUSB_AbortPipe*)m_libraryLoader->resolve("WinUsb_AbortPipe");
95  (WinUSB_FlushPipe*)m_libraryLoader->resolve("WinUsb_FlushPipe");
98  "WinUsb_SetPowerPolicy");
101  "WinUsb_GetPowerPolicy");
104  "WinUsb_GetOverlappedResult");
105  }
106 }
107 
108 /*! \brief Creates/opens a WinUsb interface handle from the device list.
109 
110  \param[out] InterfaceHandle Receives a handle configured to the first
111  (default) interface on the device. This handle is required by other WinUsb
112  routines that perform operations on the default interface. The handle is
113  opaque. To release this handle, call the \a Free function.
114  \param[in] DevInfo The device list element to open.
115 
116  \returns On success, TRUE. Otherwise FALSE. Use GetLastError() to get
117  extended error information.
118 */
120  HANDLE DeviceHandle, PWINUSB_INTERFACE_HANDLE InterfaceHandle)
121 {
122  if (m_winUsb.Initialize)
123  return m_winUsb.Initialize(DeviceHandle, InterfaceHandle);
124  else
125  return FALSE;
126 }
127 
128 /*! \brief Frees a WinUsb interface handle.
129  \param[in] InterfaceHandle Handle to an interface on the device. This
130  handle must be created by a previous call to see \a Initialize or \a
131  GetAssociatedInterface.
132 
133  \returns TRUE
134 
135  \sa GetAssociatedInterface.
136 */
137 BOOL XsWinUsb::Free(WINUSB_INTERFACE_HANDLE InterfaceHandle)
138 {
139  if (m_winUsb.Free)
140  return m_winUsb.Free(InterfaceHandle);
141  else
142  return FALSE;
143 }
144 
145 /*! \brief Retrieves a handle for an associated interface.
146  \param[in] InterfaceHandle An initialized usb handle, see \a Initialize.
147  \param[in] AssociatedInterfaceIndex An index that specifies the
148  associated interface to retrieve. A value of 0 indicates the first associated
149  interface, a value of 1 indicates the second associated interface, and so on.
150  \param[out] AssociatedInterfaceHandle A handle for the associated
151  interface. Callers must pass this interface handle to WinUsb Functions
152  exposed by WinUsb.dll. To close this handle, call Free.
153 
154  \returns On success, TRUE. Otherwise FALSE. Use GetLastError() to get
155  extended error information.
156 */
158  WINUSB_INTERFACE_HANDLE InterfaceHandle, UCHAR AssociatedInterfaceIndex,
159  PWINUSB_INTERFACE_HANDLE AssociatedInterfaceHandle)
160 {
163  InterfaceHandle, AssociatedInterfaceIndex,
164  AssociatedInterfaceHandle);
165  else
166  return FALSE;
167 }
168 
169 /*! \brief Gets the requested descriptor. This is a synchronous operation.
170  \param[in] InterfaceHandle An initialized usb handle, see \a Initialize.
171  \param[in] DescriptorType A value that specifies the type of
172  descriptor to return. This parameter corresponds to the bDescriptorType field
173  of a standard device descriptor, whose values are described in the Universal
174  Serial Bus specification.
175  \param[in] Index The descriptor index. For an explanation of the
176  descriptor index, see the Universal Serial Bus specification (www.usb.org).
177  \param[in] LanguageID A value that specifies the language identifier,
178  if the requested descriptor is a string descriptor.
179  \param[out] Buffer A caller-allocated buffer that receives the
180  requested descriptor.
181  \param[in] BufferLength The length, in bytes, of Buffer.
182  \param[out] LengthTransferred The number of bytes that were copied
183  into Buffer.
184 
185  \returns On success, TRUE. Otherwise FALSE. Use GetLastError() to get
186  extended error information.
187 */
189  WINUSB_INTERFACE_HANDLE InterfaceHandle, UCHAR DescriptorType, UCHAR Index,
190  USHORT LanguageID, PUCHAR Buffer, ULONG BufferLength,
191  PULONG LengthTransferred)
192 {
194  return m_winUsb.GetDescriptor(
195  InterfaceHandle, DescriptorType, Index, LanguageID, Buffer,
196  BufferLength, LengthTransferred);
197  else
198  return FALSE;
199 }
200 
201 /*! \brief Retrieves the interface descriptor for the specified alternate
202  interface settings for a particular interface handle.
203 
204  The \a QueryInterfaceSettings call searches the current/default interface
205  array for the alternate interface specified by the caller in the \a
206  AltSettingIndex.
207  If the specified alternate interface is found, the function populates the
208  caller-allocated USB_INTERFACE_DESCRIPTOR structure.
209  If the specified alternate interface is not found, then the call fails with
210  the ERROR_NO_MORE_ITEMS code.
211 
212  \param[in] InterfaceHandle An initialized usb handle, see \a Initialize.
213  \param[in] AltSettingIndex A value that indicates which alternate
214  setting index to return. A value of 0 indicates the first alternate setting,
215  a value of 1 indicates the second alternate setting, and so on.
216  \param[out] UsbAltInterfaceDescriptor A pointer to a caller-allocated
217  USB_INTERFACE_DESCRIPTOR structure that contains information about the
218  interface that AltSettingNumber specified.
219 
220  \returns On success, TRUE. Otherwise FALSE. Use GetLastError() to get
221  extended error information.
222 */
224  WINUSB_INTERFACE_HANDLE InterfaceHandle, UCHAR AlternateInterfaceNumber,
225  PUSB_INTERFACE_DESCRIPTOR UsbAltInterfaceDescriptor)
226 {
229  InterfaceHandle, AlternateInterfaceNumber,
230  UsbAltInterfaceDescriptor);
231  else
232  return FALSE;
233 }
234 
235 /*! \brief Retrieves information about the physical device that is associated
236  with a WinUSB handle.
237  \param[in] InterfaceHandle An initialized usb handle, see \a Initialize.
238  \param[in] InformationType A value that specifies which interface
239  information value to retrieve. On input, InformationType must have the
240  following value: DEVICE_SPEED (0x01).
241  \param[in,out] BufferLength The maximum number of bytes to read. This
242  number must be less than or equal to the size, in bytes, of Buffer. On
243  output, BufferLength is set to the actual number of bytes that were copied
244  into Buffer.
245  \param[in,out] Buffer A caller-allocated buffer that receives the
246  requested value. On output, Buffer indicates the device speed:
247  (0x01) low/full speed device.
248  (0x03) high speed device.
249 
250  \returns On success, TRUE. Otherwise FALSE. Use GetLastError() to get
251  extended error information.
252 */
254  WINUSB_INTERFACE_HANDLE InterfaceHandle, ULONG InformationType,
255  PULONG BufferLength, PVOID Buffer)
256 {
259  InterfaceHandle, InformationType, BufferLength, Buffer);
260  else
261  return FALSE;
262 }
263 
264 /*! \brief Sets the alternate setting of an interface.
265  Sets the active \a bAlternateSetting for the current/default interface.
266 
267  \param[in] InterfaceHandle An initialized usb handle, see \a Initialize.
268  \param[in] AltSettingNumber The value that is contained in the \a
269  bAlternateSetting member of the USB_INTERFACE_DESCRIPTOR structure. This
270  structure can be populated by the \a QueryInterfaceSettings routine.
271 
272  \returns On success, TRUE. Otherwise FALSE. Use GetLastError() to get
273  extended error information.
274 
275  \sa QueryInterfaceSettings
276 */
278  WINUSB_INTERFACE_HANDLE InterfaceHandle, UCHAR SettingNumber)
279 {
282  InterfaceHandle, SettingNumber);
283  else
284  return FALSE;
285 }
286 
287 /*! \brief Gets the current alternate interface setting for an interface.
288  Gets the active bAlternateSetting for the current/default interface.
289 
290  \param[in] InterfaceHandle An initialized usb handle, see \a Initialize.
291  \param[out] AltSettingNumber A pointer to an unsigned character that
292  receives an integer that indicates the current alternate setting.
293 
294  \returns On success, TRUE. Otherwise FALSE. Use GetLastError() to get
295  extended error information.
296 */
298  WINUSB_INTERFACE_HANDLE InterfaceHandle, PUCHAR SettingNumber)
299 {
302  InterfaceHandle, SettingNumber);
303  else
304  return FALSE;
305 }
306 
307 /*! \brief Retrieves information about a pipe that is associated with an
308  interface.
309  The \a QueryPipe function does not retrieve information about the control
310  pipe.
311 
312  Each interface on the USB device can have multiple endpoints. To communicate
313  with each of these endpoints, the bus driver creates pipes for each endpoint
314  on the interface.
315  The pipe indices are zero-based. Therefore for n number of endpoints, the
316  pipes' indices are set from n-1.
317  \a QueryPipe parses the configuration descriptor to get the interface
318  specified by the caller.
319  It searches the interface descriptor for the endpoint descriptor associated
320  with the caller-specified pipe.
321  If the endpoint is found, the function populates the caller-allocated
322  WINUSB_PIPE_INFORMATION structure with information from the endpoint
323  descriptor.
324 
325  \param[in] InterfaceHandle An initialized usb handle, see \a Initialize.
326  \param[in] AltSettingNumber A value that specifies the alternate
327  interface to return the information for.
328  \param[in] PipeIndex A value that specifies the pipe to return
329  information about. This value is not the same as the bEndpointAddress field
330  in the endpoint descriptor.
331  A PipeIndex value of 0 signifies the first endpoint that is
332  associated with the interface, a value of 1 signifies the second endpoint,
333  and so on.
334  PipeIndex must be less than the value in the bNumEndpoints field
335  of the interface descriptor.
336  \param[out] PipeInformation A pointer, on output, to a
337  caller-allocated WINUSB_PIPE_INFORMATION structure that contains pipe
338  information.
339 
340  \returns On success, TRUE. Otherwise FALSE. Use GetLastError() to get
341  extended error information.
342 */
344  WINUSB_INTERFACE_HANDLE InterfaceHandle, UCHAR AlternateInterfaceNumber,
345  UCHAR PipeIndex, PWINUSB_PIPE_INFORMATION PipeInformation)
346 {
347  if (m_winUsb.QueryPipe)
348  return m_winUsb.QueryPipe(
349  InterfaceHandle, AlternateInterfaceNumber, PipeIndex,
350  PipeInformation);
351  else
352  return FALSE;
353 }
354 
355 /*! \brief Sets the policy for a specific pipe associated with an endpoint on
356  the device. This is a synchronous operation.
357  \param[in] InterfaceHandle An initialized usb handle, see \a Initialize.
358  \param[in] PipeID An 8-bit value that consists of a 7-bit address and
359  a direction bit. This parameter corresponds to the bEndpointAddress field in
360  the endpoint descriptor.
361  \param[in] PolicyType A UINT variable that specifies the policy
362  parameter to change. The Value parameter contains the new value for the
363  policy parameter.
364  See the remarks section for information about each of the pipe
365  policies and the resulting behavior.
366  \param[in] ValueLength The size, in bytes, of the buffer at Value.
367  \param[in] Value The new value for the policy parameter that
368  PolicyType specifies. The size of this input parameter depends on the policy
369  to change. For information about the size of this parameter, see the
370  description of the PolicyType parameter.
371 
372  \remarks
373  The following list describes symbolic constants for \a PolicyType
374 
375  - SHORT_PACKET_TERMINATE (0x01)
376  - The default value is FALSE.
377  - To enable SHORT_PACKET_TERMINATE, in Value pass the address of a
378  caller-allocated UCHAR variable set to TRUE (nonzero).
379  - Enabling SHORT_PACKET_TERMINATE causes the driver to send a
380  zero-length packet at the end of every write request to the host controller.
381 
382  - AUTO_CLEAR_STALL (0x02)
383  - The default value is FALSE. To enable AUTO_CLEAR_STALL, in Value pass
384  the address of a caller-allocated UCHAR variable set to TRUE (nonzero).
385  - Enabling AUTO_CLEAR_STALL causes winUSB to reset the pipe in order to
386  automatically clear the stall condition. Data continues to flow on the bulk
387  and interrupt IN endpoints again as soon as a new or a queued transfer
388  arrives on the endpoint. This policy parameter does not affect control pipes.
389  - Disabling AUTO_CLEAR_STALL causes all transfers (that arrive to the
390  endpoint after the stalled transfer) to fail until the caller manually resets
391  the endpoint's pipe by calling ResetPipe.
392 
393  - PIPE_TRANSFER_TIMEOUT (0x03)
394  - The default value is zero. To set a time-out value, in Value pass the
395  address of a caller-allocated UINT variable that contains the time-out
396  interval.
397  - The PIPE_TRANSFER_TIMEOUT value specifies the time-out interval, in
398  milliseconds. The host controller cancels transfers that do not complete
399  within the specified time-out interval.
400  - A value of zero (default) indicates that transfers do not time out
401  because the host controller never cancels the transfer.
402 
403  - IGNORE_SHORT_PACKETS (0x04)
404  - The default value is FALSE. To enable IGNORE_SHORT_PACKETS, in Value
405  pass the address of a caller-allocated UCHAR variable set to TRUE (nonzero).
406  - Enabling IGNORE_SHORT_PACKETS causes the host controller to not
407  complete a read operation after it receives a short packet. Instead, the host
408  controller completes the operation only after the host has read the specified
409  number of bytes.
410  - Disabling IGNORE_SHORT_PACKETS causes the host controller to complete
411  a read operation when either the host has read the specified number of bytes
412  or the host has received a short packet.
413 
414  - ALLOW_PARTIAL_READS (0x05)
415  - The default value is TRUE (nonzero). To disable ALLOW_PARTIAL_READS,
416  in Value pass the address of a caller-allocated UCHAR variable set to FALSE
417  (zero).
418  - Disabling ALLOW_PARTIAL_READS causes the read requests to fail
419  whenever the device returns more data (on bulk and interrupt IN endpoints)
420  than the caller requested.
421  - Enabling ALLOW_PARTIAL_READS causes winUSB to save or discard the
422  extra data when the device returns more data (on bulk and interrupt IN
423  endpoints) than the caller requested. This behavior is defined by setting the
424  AUTO_FLUSH value.
425 
426  - AUTO_FLUSH (0x06)
427  - The default value is FALSE (zero). To enable AUTO_FLUSH, in Value pass
428  the address of a caller-allocated UCHAR variable set to TRUE (nonzero).
429  - AUTO_FLUSH must be used with ALLOW_PARTIAL_READS enabled. If
430  ALLOW_PARTIAL_READS is TRUE, the value of AUTO_FLUSH determines the action
431  taken by winUSB when the device returns more data than the caller requested.
432  - Disabling ALLOW_PARTIAL_READS causes winUSB to ignore the AUTO_FLUSH
433  value.
434  - Disabling AUTO_FLUSH with ALLOW_PARTIAL_READS enabled causes winUSB to
435  save the extra data, add the data to the beginning of the caller's next read
436  request, and send it to the caller in the next read operation.
437  - Enabling AUTO_FLUSH with ALLOW_PARTIAL_READS enabled causes winUSB to
438  discard the extra data remaining from the read request.
439 
440  - RAW_IO (0x07)
441  - The default value is FALSE (zero). To enable RAW_IO, in Value pass the
442  address of a caller-allocated UCHAR variable set to TRUE (nonzero).
443  - Enabling RAW_IO causes winUSB to send data directly to the USB driver
444  stack, bypassing winUSB's queuing and error handling mechanism.
445  - The buffers that are passed to \a ReadPipe must be configured by the
446  caller as follows:
447  - The buffer length must be a multiple of the maximum endpoint packet
448  size.
449  - The length must be less than or equal to the value of
450  MAXIMUM_TRANSFER_SIZE retrieved by GetPipePolicy.
451  - Disabling RAW_IO (FALSE) does not impose any restriction on the
452  buffers that are passed to \a ReadPipe.
453 
454  - RESET_PIPE_ON_RESUME (0x09)
455  - The default value is FALSE (zero). To enable RESET_PIPE_ON_RESUME, in
456  Value pass the address of a caller-allocated UCHAR variable set to TRUE
457  (nonzero).
458  - TRUE (or a nonzero value) indicates that on resume from suspend,
459  winUSB resets the endpoint before it allows the caller to send new requests
460  to the endpoint.
461 
462 
463  \returns On success, TRUE. Otherwise FALSE. Use GetLastError() to get
464  extended error information.
465 */
467  WINUSB_INTERFACE_HANDLE InterfaceHandle, UCHAR PipeID, ULONG PolicyType,
468  ULONG ValueLength, PVOID Value)
469 {
471  return m_winUsb.SetPipePolicy(
472  InterfaceHandle, PipeID, PolicyType, ValueLength, Value);
473  else
474  return FALSE;
475 }
476 
477 /*! \brief Gets the policy for a specific pipe (endpoint).
478  \param[in] InterfaceHandle An initialized usb handle, see \a Initialize.
479  \param[in] PipeID An 8-bit value that consists of a 7-bit address and
480  a direction bit. This parameter corresponds to the bEndpointAddress field in
481  the endpoint descriptor.
482  \param[in] PolicyType A UINT variable that specifies the policy
483  parameter to retrieve. The current value for the policy parameter is
484  retrieved the Value parameter.
485  \param[in,out] ValueLength A pointer to the size, in bytes, of the
486  buffer that Value points to. On output, ValueLength receives the size, in
487  bytes, of the data that was copied into the Value buffer.
488  \param[out] Value A pointer to a buffer that receives the specified
489  pipe policy value.
490 
491  \returns On success, TRUE. Otherwise FALSE. Use GetLastError() to get
492  extended error information.
493 */
495  WINUSB_INTERFACE_HANDLE InterfaceHandle, UCHAR PipeID, ULONG PolicyType,
496  PULONG ValueLength, PVOID Value)
497 {
499  return m_winUsb.GetPipePolicy(
500  InterfaceHandle, PipeID, PolicyType, ValueLength, Value);
501  else
502  return FALSE;
503 }
504 
505 /*! \brief Reads data from the specified pipe.
506  \param[in] InterfaceHandle An initialized usb handle, see \a Initialize.
507  \param[in] PipeID An 8-bit value that consists of a 7-bit address and
508  a direction bit. This parameter corresponds to the bEndpointAddress field in
509  the endpoint descriptor.
510  \param[out] Buffer A caller-allocated buffer that receives the data
511  that is read.
512  \param[in] BufferLength The maximum number of bytes to read. This
513  number must be less than or equal to the size, in bytes, of Buffer.
514  \param[out] LengthTransferred A pointer to a UINT variable that
515  receives the actual number of bytes that were copied into Buffer. For more
516  information, see Remarks.
517  \param[in] Overlapped An optional pointer to an overlapped structure
518  for asynchronous operations. This can be a KOVL_HANDLE or a pointer to a
519  standard windows OVERLAPPED structure.
520  If this parameter is specified, \a ReadPipe returns immediately
521  rather than waiting synchronously for the operation to complete before
522  returning. An event is signaled when the operation is complete.
523 
524  \returns On success, TRUE. Otherwise FALSE. Use GetLastError() to get
525  extended error information.
526 */
528  WINUSB_INTERFACE_HANDLE InterfaceHandle, UCHAR PipeID, PUCHAR Buffer,
529  ULONG BufferLength, PULONG LengthTransferred, LPOVERLAPPED Overlapped)
530 {
531  if (m_winUsb.ReadPipe)
532  return m_winUsb.ReadPipe(
533  InterfaceHandle, PipeID, Buffer, BufferLength, LengthTransferred,
534  Overlapped);
535  else
536  return FALSE;
537 }
538 
539 /*! \brief Writes data to a pipe.
540  \param[in] InterfaceHandle An initialized usb handle, see \a Initialize.
541  \param[in] PipeID An 8-bit value that consists of a 7-bit address and
542  a direction bit. This parameter corresponds to the bEndpointAddress field in
543  the endpoint descriptor.
544  \param[in] Buffer A caller-allocated buffer the data is written from.
545  \param[in] BufferLength The maximum number of bytes to write. This
546  number must be less than or equal to the size, in bytes, of Buffer.
547  \param[out] LengthTransferred A pointer to a UINT variable that
548  receives the actual number of bytes that were transferred from Buffer.
549  \param[in] Overlapped An optional pointer to an overlapped structure
550  for asynchronous operations. This can be a KOVL_HANDLE or a pointer to a
551  standard windows OVERLAPPED structure.
552  If this parameter is specified, \a WritePipe returns immediately
553  rather than waiting synchronously for the operation to complete before
554  returning. An event is signaled when the operation is complete.
555 
556  \returns On success, TRUE. Otherwise FALSE. Use GetLastError() to get
557  extended error information.
558 */
560  WINUSB_INTERFACE_HANDLE InterfaceHandle, UCHAR PipeID, PUCHAR Buffer,
561  ULONG BufferLength, PULONG LengthTransferred, LPOVERLAPPED Overlapped)
562 {
563  if (m_winUsb.WritePipe)
564  return m_winUsb.WritePipe(
565  InterfaceHandle, PipeID, Buffer, BufferLength, LengthTransferred,
566  Overlapped);
567  else
568  return FALSE;
569 }
570 
571 /*! \brief Transmits control data over a default control endpoint.
572  A ControlTransfer is never cached. These requests always go directly to the
573  usb device.
574 
575  \param[in] InterfaceHandle A valid winUSB interface handle returned by:
576  - Initialize
577  - GetAssociatedInterface
578  \param[in] SetupPacket The 8-byte setup packet of type WINUSB_SETUP_PACKET.
579  \param[in,out] Buffer A caller-allocated buffer that contains the data
580  to transfer.
581  \param[in] BufferLength The number of bytes to transfer, not including
582  the setup packet. This number must be less than or equal to the size, in
583  bytes, of Buffer.
584  \param[out] LengthTransferred A pointer to a UINT variable that
585  receives the actual number of transferred bytes. If the application does not
586  expect any data to be transferred during the data phase (BufferLength is
587  zero), LengthTransferred can be NULL.
588  \param[in] Overlapped An optional pointer to an OVERLAPPED structure,
589  which is used for asynchronous operations. If this parameter is specified,
590  ControlTransfer immediately returns, and the event is signaled when the
591  operation is complete. If Overlapped is not supplied, the ControlTransfer
592  function transfers data synchronously.
593 
594  \returns On success, TRUE. Otherwise FALSE. Use GetLastError() to get
595  extended error information. If an Overlapped member is supplied and the
596  operation succeeds this function returns FALSE and sets last error to
597  ERROR_IO_PENDING.
598 */
600  WINUSB_INTERFACE_HANDLE InterfaceHandle, WINUSB_SETUP_PACKET SetupPacket,
601  PUCHAR Buffer, ULONG BufferLength, PULONG LengthTransferred,
602  LPOVERLAPPED Overlapped)
603 {
605  return m_winUsb.ControlTransfer(
606  InterfaceHandle, SetupPacket, Buffer, BufferLength,
607  LengthTransferred, Overlapped);
608  else
609  return FALSE;
610 }
611 
612 /*! \brief Resets the data toggle and clears the stall condition on a pipe.
613  \param[in] InterfaceHandle An initialized usb handle, see \a Initialize.
614  \param[in] PipeID An 8-bit value that consists of a 7-bit address and
615  a direction bit. This parameter corresponds to the \a bEndpointAddress field
616  in the endpoint descriptor.
617 
618  \returns On success, TRUE. Otherwise FALSE. Use GetLastError() to get
619  extended error information.
620 */
621 BOOL XsWinUsb::ResetPipe(WINUSB_INTERFACE_HANDLE InterfaceHandle, UCHAR PipeID)
622 {
623  if (m_winUsb.ResetPipe)
624  return m_winUsb.ResetPipe(InterfaceHandle, PipeID);
625  else
626  return FALSE;
627 }
628 
629 /*! \brief Aborts all of the pending transfers for a pipe.
630  \param[in] InterfaceHandle An initialized usb handle, see \a Initialize.
631  \param[in] PipeID An 8-bit value that consists of a 7-bit address and
632  a direction bit. This parameter corresponds to the \a bEndpointAddress field
633  in the endpoint descriptor.
634 
635  \returns On success, TRUE. Otherwise FALSE. Use GetLastError() to get
636  extended error information.
637 */
638 BOOL XsWinUsb::AbortPipe(WINUSB_INTERFACE_HANDLE InterfaceHandle, UCHAR PipeID)
639 {
640  if (m_winUsb.AbortPipe)
641  return m_winUsb.AbortPipe(InterfaceHandle, PipeID);
642  else
643  return FALSE;
644 }
645 
646 /*! \brief Discards any data that is cached in a pipe.
647  \param[in] InterfaceHandle An initialized usb handle, see \a Initialize.
648  \param[in] PipeID An 8-bit value that consists of a 7-bit address and
649  a direction bit. This parameter corresponds to the \a bEndpointAddress field
650  in the endpoint descriptor.
651 
652  \returns On success, TRUE. Otherwise FALSE. Use GetLastError() to get
653  extended error information.
654 */
655 BOOL XsWinUsb::FlushPipe(WINUSB_INTERFACE_HANDLE InterfaceHandle, UCHAR PipeID)
656 {
657  if (m_winUsb.FlushPipe)
658  return m_winUsb.FlushPipe(InterfaceHandle, PipeID);
659  else
660  return FALSE;
661 }
662 
663 /*! \brief Sets the power policy for a device.
664  The following list summarizes the effects of changes to power management
665  states:
666 
667  - All pipe handles, interface handles, locks, and alternate settings are
668  preserved across power management events.
669  - Any transfers that are in progress are suspended when a device transfers
670  to a low power state, and they are resumed when the device is restored to a
671  working state.
672  - The device and system must be in a working state before the client can
673  restore a device-specific configuration. Clients can determine whether the
674  device and system are in a working state from the WM_POWERBROADCAST message.
675  - The client can indicate that an interface is idle by calling \a
676  SetPowerPolicy.
677 
678  \param[in] InterfaceHandle An initialized usb handle, see \a Initialize.
679  \param[in] PolicyType A value that specifies the power policy to set.
680  The following table describes symbolic constants.
681  - AUTO_SUSPEND (0x81)
682  - Specifies the auto-suspend policy type; the power policy
683  parameter must be specified by the caller in the Value parameter.
684  - For auto-suspend, the Value parameter must point to a
685  UCHAR variable.
686  - If Value is TRUE (nonzero), the USB stack suspends the
687  device if the device is idle. A device is idle if there are no transfers
688  pending, or if the only pending transfers are IN transfers to interrupt or
689  bulk endpoints.
690  - The default value is determined by the value set in the
691  DefaultIdleState registry setting. By default, this value is TRUE.
692 
693  - SUSPEND_DELAY (0x83)
694  - Specifies the suspend-delay policy type; the power policy
695  parameter must be specified by the caller in the Value parameter.
696  - For suspend-delay, Value must point to a UINT variable.
697  - Value specifies the minimum amount of time, in
698  milliseconds, that the driver must wait post transfer before it can suspend
699  the device.
700  - The default value is determined by the value set in the
701  DefaultIdleTimeout registry setting. By default, this value is five seconds.
702 
703  \param[in] ValueLength The size, in bytes, of the buffer at Value.
704  \param[in] Value The new value for the power policy parameter. Data
705  type and value for Value depends on the type of power policy passed in
706  PolicyType. For more information, see PolicyType.
707 
708  \returns On success, TRUE. Otherwise FALSE. Use GetLastError() to get
709  extended error information.
710 */
712  WINUSB_INTERFACE_HANDLE InterfaceHandle, ULONG PolicyType,
713  ULONG ValueLength, PVOID Value)
714 {
716  return m_winUsb.SetPowerPolicy(
717  InterfaceHandle, PolicyType, ValueLength, Value);
718  else
719  return FALSE;
720 }
721 
722 /*! \brief Gets the power policy for a device.
723  \param[in] InterfaceHandle An initialized usb handle, see \a Initialize
724  \param[in] PolicyType A value that specifies the power policy
725  parameter to retrieve in Value. The following table describes symbolic
726  constants that are valid.
727  - AUTO_SUSPEND (0x81)
728  - If the caller specifies a power policy of AUTO_SUSPEND, \a
729  GetPowerPolicy returns the value of the auto suspend policy parameter in the
730  Value parameter.
731  - If Value is TRUE (that is, nonzero), the USB stack
732  suspends the device when no transfers are pending or the only transfers
733  pending are IN transfers on an interrupt or bulk endpoint.
734  - The value of the DefaultIdleState registry value
735  determines the default value of the auto suspend policy parameter.
736  - The Value parameter must point to a UCHAR variable.
737 
738  - SUSPEND_DELAY (0x83)
739  - If the caller specifies a power policy of SUSPEND_DELAY,
740  \a GetPowerPolicy returns the value of the suspend delay policy parameter in
741  Value.
742  - The suspend delay policy parameter specifies the minimum
743  amount of time, in milliseconds, that the driver must wait after any transfer
744  before it can suspend the device.
745  - Value must point to a UINT variable.
746 
747  \param[in,out] ValueLength A pointer to the size of the buffer that
748  Value. On output, ValueLength receives the size of the data that was copied
749  into the Value buffer.
750  \param[out] Value A buffer that receives the specified power policy
751  parameter. For more information, see PolicyType.
752 
753  \returns On success, TRUE. Otherwise FALSE. Use GetLastError() to get
754  extended error information.
755 */
757  WINUSB_INTERFACE_HANDLE InterfaceHandle, ULONG PolicyType,
758  PULONG ValueLength, PVOID Value)
759 {
761  return m_winUsb.GetPowerPolicy(
762  InterfaceHandle, PolicyType, ValueLength, Value);
763  else
764  return FALSE;
765 }
766 
767 /*! \brief Retrieves the results of an overlapped operation on the specified
768  winUSB handle.
769 
770  This function is like the Win32 API routine, GetOverlappedResult, with one
771  difference; instead of passing a file handle that is returned from
772  CreateFile, the caller passes an interface handle that is returned from \a
773  Initialize, or \a GetAssociatedInterface. The caller can use either API
774  routine, if the appropriate handle is passed. The \a GetOverlappedResult
775  function extracts the file handle from the interface handle and then calls
776  GetOverlappedResult.
777  The results that are reported by the GetOverlappedResult function are those
778  from the specified handle's last overlapped operation to which the specified
779  standard windows OVERLAPPED structure was provided, and for which the
780  operation's results were pending. A pending operation is indicated when the
781  function that started the operation returns FALSE, and the GetLastError
782  routine returns ERROR_IO_PENDING. When an I/O operation is pending, the
783  function that started the operation resets the hEvent member of the standard
784  windows OVERLAPPED structure to the nonsignaled state. Then when the pending
785  operation has been completed, the system sets the event object to the
786  signaled state.
787  The caller can specify that an event object is manually reset in the
788  standard windows OVERLAPPED structure. If an automatic reset event object is
789  used, the event handle must not be specified in any other wait operation in
790  the interval between starting the overlapped operation and the call to \a
791  GetOverlappedResult. For example, the event object is sometimes specified in
792  one of the wait routines to wait for the operation to be completed. When the
793  wait routine returns, the system sets an auto-reset event's state to
794  nonsignaled, and a successive call to \a GetOverlappedResult with the bWait
795  parameter set to TRUE causes the function to be blocked indefinitely.
796  If the bWait parameter is TRUE, GetOverlappedResult determines whether the
797  pending operation has been completed by waiting for the event object to be in
798  the signaled state.
799 
800  If the hEvent member of the standard windows OVERLAPPED structure is
801  nullptr, the system uses the state of the file handle to signal when the
802  operation has been completed. Do not use file handles for this purpose. It is
803  better to use an event object because of the confusion that can occur when
804  multiple concurrent overlapped operations are performed on the same file. In
805  this situation, you cannot know which operation caused the state of the
806  object to be signaled.
807 
808  \param[in] InterfaceHandle An initialized usb handle, see \a Initialize
809  \param[in] Overlapped A pointer to a standard windows OVERLAPPED
810  structure that was specified when the overlapped operation was started.
811  \param[out] lpNumberOfBytesTransferred A pointer to a variable that
812  receives the number of bytes that were actually transferred by a read or
813  write operation.
814  \param[in] bWait If this parameter is TRUE, the function does not
815  return until the operation has been completed. If this parameter is FALSE and
816  the operation is still pending, the function returns FALSE and the
817  GetLastError function returns ERROR_IO_INCOMPLETE.
818 
819  \returns On success, TRUE. Otherwise FALSE. Use GetLastError() to get
820  extended error information.
821 */
823  WINUSB_INTERFACE_HANDLE InterfaceHandle, LPOVERLAPPED lpOverlapped,
824  LPDWORD lpNumberOfBytesTransferred, BOOL bWait)
825 {
828  InterfaceHandle, lpOverlapped, lpNumberOfBytesTransferred, bWait);
829  else
830  return FALSE;
831 }
832 
833 #endif // patch for MRPT
BOOL __stdcall WinUSB_ResetPipe(WINUSB_INTERFACE_HANDLE InterfaceHandle, UCHAR PipeID)
BOOL __stdcall WinUSB_GetPipePolicy(WINUSB_INTERFACE_HANDLE InterfaceHandle, UCHAR PipeID, ULONG PolicyType, PULONG ValueLength, PVOID Value)
BOOL __stdcall WinUSB_GetCurrentAlternateSetting(WINUSB_INTERFACE_HANDLE InterfaceHandle, PUCHAR AltSettingNumber)
WinUSB_SetPipePolicy * SetPipePolicy
WinUSB_Free Free
Frees a WinUsb interface handle.
WinUSB_AbortPipe AbortPipe
Aborts all of the pending transfers for a pipe.
BOOL __stdcall WinUSB_GetAssociatedInterface(WINUSB_INTERFACE_HANDLE InterfaceHandle, UCHAR AssociatedInterfaceIndex, WINUSB_INTERFACE_HANDLE *AssociatedInterfaceHandle)
WinUSB_GetPipePolicy GetPipePolicy
Gets the policy for a specific pipe (endpoint).
WINUSB_API m_winUsb
WinUSB_GetAssociatedInterface * GetAssociatedInterface
BOOL __stdcall WinUSB_GetOverlappedResult(WINUSB_INTERFACE_HANDLE InterfaceHandle, LPOVERLAPPED Overlapped, LPDWORD lpNumberOfBytesTransferred, BOOL bWait)
struct XsLibraryLoader XsLibraryLoader
XsLibraryLoader * m_libraryLoader
WinUSB_QueryPipe QueryPipe
Retrieves information about a pipe that is associated with an interface. The QueryPipe function does ...
WinUSB_SetCurrentAlternateSetting SetCurrentAlternateSetting
Sets the alternate setting of an interface. Sets the active bAlternateSetting for the current/default...
WinUSB_Initialize * Initialize
BOOL __stdcall WinUSB_Initialize(HANDLE DeviceHandle, WINUSB_INTERFACE_HANDLE *InterfaceHandle)
WinUSB_GetPowerPolicy GetPowerPolicy
Gets the power policy for a device.
WinUSB_GetDescriptor * GetDescriptor
int BOOL
Definition: xstypedefs.h:77
WinUSB_GetPowerPolicy * GetPowerPolicy
XsWinUsb(void)
Definition: xswinusb.cpp:17
BOOL __stdcall WinUSB_GetDescriptor(WINUSB_INTERFACE_HANDLE InterfaceHandle, UCHAR DescriptorType, UCHAR Index, USHORT LanguageID, PUCHAR Buffer, ULONG BufferLength, PULONG LengthTransferred)
WinUSB_SetCurrentAlternateSetting * SetCurrentAlternateSetting
BOOL __stdcall WinUSB_ReadPipe(WINUSB_INTERFACE_HANDLE InterfaceHandle, UCHAR PipeID, PUCHAR Buffer, ULONG BufferLength, PULONG LengthTransferred, LPOVERLAPPED Overlapped)
BOOL __stdcall WinUSB_SetPowerPolicy(WINUSB_INTERFACE_HANDLE InterfaceHandle, ULONG PolicyType, ULONG ValueLength, PVOID Value)
WinUSB_ReadPipe ReadPipe
Reads data from the specified pipe.
BOOL __stdcall WinUSB_FlushPipe(WINUSB_INTERFACE_HANDLE InterfaceHandle, UCHAR PipeID)
BOOL __stdcall WinUSB_ControlTransfer(WINUSB_INTERFACE_HANDLE InterfaceHandle, WINUSB_SETUP_PACKET SetupPacket, PUCHAR Buffer, ULONG BufferLength, PULONG LengthTransferred, LPOVERLAPPED Overlapped)
BOOL __stdcall WinUSB_QueryInterfaceSettings(WINUSB_INTERFACE_HANDLE InterfaceHandle, UCHAR AltSettingIndex, PUSB_INTERFACE_DESCRIPTOR UsbAltInterfaceDescriptor)
WinUSB_Initialize Initialize
Creates/opens a WinUsb interface handle from the device list.
WinUSB_ResetPipe ResetPipe
Resets the data toggle and clears the stall condition on a pipe.
WinUSB_AbortPipe * AbortPipe
WinUSB_GetCurrentAlternateSetting * GetCurrentAlternateSetting
~XsWinUsb(void)
Definition: xswinusb.cpp:23
BOOL __stdcall WinUSB_GetPowerPolicy(WINUSB_INTERFACE_HANDLE InterfaceHandle, ULONG PolicyType, PULONG ValueLength, PVOID Value)
WinUSB_GetOverlappedResult GetOverlappedResult
Retrieves the results of an overlapped operation on the specified winUSB handle.
WinUSB_FlushPipe FlushPipe
Discards any data that is cached in a pipe.
void initLibrary()
Definition: xswinusb.cpp:24
BOOL __stdcall WinUSB_SetCurrentAlternateSetting(WINUSB_INTERFACE_HANDLE InterfaceHandle, UCHAR AltSettingNumber)
WinUSB_GetDescriptor GetDescriptor
Gets the requested descriptor. This is a synchronous operation.
BOOL __stdcall WinUSB_AbortPipe(WINUSB_INTERFACE_HANDLE InterfaceHandle, UCHAR PipeID)
WinUSB_QueryPipe * QueryPipe
WinUSB_SetPowerPolicy SetPowerPolicy
Sets the power policy for a device. The following list summarizes the effects of changes to power man...
WinUSB_QueryInterfaceSettings QueryInterfaceSettings
Retrieves the interface descriptor for the specified alternate interface settings for a particular in...
WinUSB_ResetPipe * ResetPipe
WinUSB_QueryDeviceInformation QueryDeviceInformation
Retrieves information about the physical device that is associated with a WinUSB handle.
WinUSB_WritePipe * WritePipe
WinUSB_GetAssociatedInterface GetAssociatedInterface
Retrieves a handle for an associated interface.
WinUSB_SetPipePolicy SetPipePolicy
Sets the policy for a specific pipe associated with an endpoint on the device. This is a synchronous ...
#define FALSE
Definition: xmlParser.h:230
WinUSB_ReadPipe * ReadPipe
WinUSB_QueryInterfaceSettings * QueryInterfaceSettings
BOOL __stdcall WinUSB_QueryPipe(WINUSB_INTERFACE_HANDLE InterfaceHandle, UCHAR AltSettingNumber, UCHAR PipeIndex, PWINUSB_PIPE_INFORMATION PipeInformation)
WinUSB_QueryDeviceInformation * QueryDeviceInformation
WinUSB_FlushPipe * FlushPipe
BOOL __stdcall WinUSB_SetPipePolicy(WINUSB_INTERFACE_HANDLE InterfaceHandle, UCHAR PipeID, ULONG PolicyType, ULONG ValueLength, PVOID Value)
WinUSB_ControlTransfer * ControlTransfer
WinUSB_GetPipePolicy * GetPipePolicy
WinUSB_SetPowerPolicy * SetPowerPolicy
WinUSB_WritePipe WritePipe
Writes data to a pipe.
BOOL __stdcall WinUSB_Free(WINUSB_INTERFACE_HANDLE InterfaceHandle)
WinUSB_ControlTransfer ControlTransfer
Transmits control data over a default control endpoint. A ControlTransfer is never cached...
BOOL __stdcall WinUSB_QueryDeviceInformation(WINUSB_INTERFACE_HANDLE InterfaceHandle, ULONG InformationType, PULONG BufferLength, PVOID Buffer)
WinUSB_GetOverlappedResult * GetOverlappedResult
BOOL __stdcall WinUSB_WritePipe(WINUSB_INTERFACE_HANDLE InterfaceHandle, UCHAR PipeID, PUCHAR Buffer, ULONG BufferLength, PULONG LengthTransferred, LPOVERLAPPED Overlapped)
WinUSB_GetCurrentAlternateSetting GetCurrentAlternateSetting
Gets the current alternate interface setting for an interface. Gets the active bAlternateSetting for ...



Page generated by Doxygen 1.8.14 for MRPT 1.9.9 Git: 8fe78517f Sun Jul 14 19:43:28 2019 +0200 at lun oct 28 02:10:00 CET 2019