SurgSim::Devices::WdkHidDeviceHandle Class Reference

Access to an input/HID device using the HID API from the Windows Driver Kit. More...

`#include <SurgSim/Devices/MultiAxis/win32/WdkHidDeviceHandle.h>`

Inheritance diagram for SurgSim::Devices::WdkHidDeviceHandle:

## Classes

struct | State

## Public Member Functions

| ~WdkHidDeviceHandle ()
| Destructor. More...
std::string | getDeviceName () const override
| Gets the name returned by the operating system for this device. More...
bool | getDeviceIds (int *vendorId, int *productId) const override
| Gets the device identifiers. More...
bool | hasTranslationAndRotationAxes () const override
| Queries if this device has 3 translation and 3 rotation axes. More...
bool | updateStates (AxisStates *axisStates, ButtonStates *buttonStates, bool *updated) override
| Updates the axis and states from the device input, if any. More...
void | prepareForShutdown () override
| Prepares the handle for sampling thread shutdown. More...
Public Member Functions inherited from SurgSim::Devices::SystemInputDeviceHandle
virtual | ~SystemInputDeviceHandle ()
| Destructor. More...

## Static Public Member Functions

static std::vector< std::string > | enumeratePaths (SurgSim::Framework::Logger *logger)
| Enumerates input devices. More...
static std::unique_ptr< WdkHidDeviceHandle > | open (const std::string &path, std::shared_ptr< SurgSim::Framework::Logger > logger)
| Opens the given path and creates an access wrapper for the device. More...

## Private Member Functions

| WdkHidDeviceHandle (std::shared_ptr< SurgSim::Framework::Logger > &&logger)
| Constructor. More...
| WdkHidDeviceHandle (const WdkHidDeviceHandle &other)
WdkHidDeviceHandle & | operator= (const WdkHidDeviceHandle &other)
bool | getCapabilities (struct _HIDP_CAPS *capabilities) const
| Gets the device capabilities. More...
bool | startAsynchronousRead ()
| Starts an asynchronous read from the device. More...
bool | finishAsynchronousRead (size_t *numBytesRead)
| Checks if an asynchronous read from the device has completed. More...
void | cancelAsynchronousRead ()
| Cancels an asynchronous read from the device. More...
void | decodeStateUpdates (const unsigned char *rawData, size_t rawDataSize, AxisStates *axisStates, ButtonStates *buttonStates, bool *updated)
| Decode the raw state update data received from the device. More...

## Private Attributes

std::unique_ptr< State > | m_state

## Additional Inherited Members

Public Types inherited from SurgSim::Devices::SystemInputDeviceHandle
typedef std::array< int, MAX_NUM_AXES > | AxisStates
| Type used to store axis states. More...
typedef std::array< bool, MAX_NUM_BUTTONS > | ButtonStates
| Type used to store button states. More...
Static Public Attributes inherited from SurgSim::Devices::SystemInputDeviceHandle
static const size_t | MAX_NUM_AXES = 6
| The maximum number of axes supported by any device object. More...
static const size_t | MAX_NUM_BUTTONS = 4
| The maximum number of buttons supported by any device object. More...
Protected Member Functions inherited from SurgSim::Devices::SystemInputDeviceHandle
| SystemInputDeviceHandle ()
| Default constructor. More...

## Detailed Description

Access to an input/HID device using the HID API from the Windows Driver Kit.

See also
  SystemInputDeviceHandle

## Constructor & Destructor Documentation

## ~WdkHidDeviceHandle()

SurgSim::Devices::WdkHidDeviceHandle::~WdkHidDeviceHandle | ( |  | ) |

Destructor.

## WdkHidDeviceHandle() [1/2]

SurgSim::Devices::WdkHidDeviceHandle::WdkHidDeviceHandle | ( | std::shared_ptr< SurgSim::Framework::Logger > && | logger | ) |

explicit private

Constructor.

Cannot be called directly.

See also
  open

## WdkHidDeviceHandle() [2/2]

SurgSim::Devices::WdkHidDeviceHandle::WdkHidDeviceHandle | ( | const WdkHidDeviceHandle & | other | ) |

private

## Member Function Documentation

## cancelAsynchronousRead()

void SurgSim::Devices::WdkHidDeviceHandle::cancelAsynchronousRead | ( |  | ) |

private

Cancels an asynchronous read from the device.

Should be executed in the context of the thread that called startAsynchronousRead.

## decodeStateUpdates()

void SurgSim::Devices::WdkHidDeviceHandle::decodeStateUpdates | ( | const unsigned char * | rawData,
|  | size_t | rawDataSize,
|  | AxisStates * | axisStates,
|  | ButtonStates * | buttonStates,
|  | bool * | updated
| ) |  |

private

Decode the raw state update data received from the device.

Parameters

  | rawData | Raw state update data.
  | rawDataSize | Size of the raw state update data.
  [in,out] | axisStates | The states for each axis of the device.
  [in,out] | buttonStates | The states for each device button.
  [out] | updated | True if any states were actually updated. (Note that even if this value is true, the states may not have changed value; one or more states could have been updated to the same value.)

## enumeratePaths()

std::vector< std::string > SurgSim::Devices::WdkHidDeviceHandle::enumeratePaths | ( | SurgSim::Framework::Logger * | logger | ) |

static

Enumerates input devices.

Parameters

  logger | The logger to be used during enumeration.

Returns
  A list of device paths.

## finishAsynchronousRead()

bool SurgSim::Devices::WdkHidDeviceHandle::finishAsynchronousRead | ( | size_t * | numBytesRead | ) |

private

Checks if an asynchronous read from the device has completed.

Updates the internal flags to indicate the state of the device I/O.

Parameters

  [out] | numBytesRead | If the function returns true, the number of bytes read from the device.

Returns
  true if data has been received; false if the asynchronous read is still pending or an error has occurred.

## getCapabilities()

bool SurgSim::Devices::WdkHidDeviceHandle::getCapabilities | ( | struct _HIDP_CAPS * | capabilities | ) | const

private

Gets the device capabilities.

Parameters

  [out] | capabilities | The capabilities data for the device.

Returns
  true if it succeeds.

## getDeviceIds()

bool SurgSim::Devices::WdkHidDeviceHandle::getDeviceIds | ( | int * | vendorId,
|  | int * | productId
| ) |  | const

override virtual

Gets the device identifiers.

Parameters

  [out] | vendorId | The USB or PCI vendor identifier.
  [out] | productId | The USB or PCI product identifier.

Returns
  true if it succeeds.

Implements SurgSim::Devices::SystemInputDeviceHandle.

## getDeviceName()

std::string SurgSim::Devices::WdkHidDeviceHandle::getDeviceName | ( |  | ) | const

override virtual

Gets the name returned by the operating system for this device.

Returns
  The reported name, or "???" if no name information could be found.

Implements SurgSim::Devices::SystemInputDeviceHandle.

## hasTranslationAndRotationAxes()

bool SurgSim::Devices::WdkHidDeviceHandle::hasTranslationAndRotationAxes | ( |  | ) | const

override virtual

Queries if this device has 3 translation and 3 rotation axes.

Returns
  true if the desired axes are present.

Implements SurgSim::Devices::SystemInputDeviceHandle.

## open()

std::unique_ptr< WdkHidDeviceHandle > SurgSim::Devices::WdkHidDeviceHandle::open | ( | const std::string & | path,
|  | std::shared_ptr< SurgSim::Framework::Logger > | logger
| ) |  |

static

Opens the given path and creates an access wrapper for the device.

Parameters

  path | Full pathname for the device.
  logger | The logger to be used by the device.

Returns
  The created device object, or an empty unique_ptr on failure.

## operator=()

WdkHidDeviceHandle& SurgSim::Devices::WdkHidDeviceHandle::operator= | ( | const WdkHidDeviceHandle & | other | ) |

private

## prepareForShutdown()

void SurgSim::Devices::WdkHidDeviceHandle::prepareForShutdown | ( |  | ) |

override virtual

Prepares the handle for sampling thread shutdown.

Should be called from the same thread that was calling updateStates, after the calls to updateStates have been stopped, but before object destruction.

Reimplemented from SurgSim::Devices::SystemInputDeviceHandle.

## startAsynchronousRead()

bool SurgSim::Devices::WdkHidDeviceHandle::startAsynchronousRead | ( |  | ) |

private

Starts an asynchronous read from the device.

Updates the internal flags to indicate the state of the device I/O.

Returns
  true if an asynchronous read has been started, or the read has already completed synchronously.

## updateStates()

bool SurgSim::Devices::WdkHidDeviceHandle::updateStates | ( | AxisStates * | axisStates,
|  | ButtonStates * | buttonStates,
|  | bool * | updated
| ) |  |

override virtual

Updates the axis and states from the device input, if any.

Parameters

  [in,out] | axisStates | The states for each axis of the device.
  [in,out] | buttonStates | The states for each device button.
  [out] | updated | True if any states were actually updated. (Note that even if this value is true, the states may not have changed value; one or more states could have been updated to the same value.)

Returns
  true if the operation was successful; false if the device is no longer in a usable state.

Implements SurgSim::Devices::SystemInputDeviceHandle.

## Member Data Documentation

## m_state

std::unique_ptr<State> SurgSim::Devices::WdkHidDeviceHandle::m_state

private

The documentation for this class was generated from the following files:

- SurgSim/Devices/MultiAxis/win32/WdkHidDeviceHandle.h
- SurgSim/Devices/MultiAxis/win32/WdkHidDeviceHandle.cpp