SurgSim::Devices::FileHandle Class Reference

A wrapper for an Windows-style HANDLE file descriptor. More...

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

## Public Types

typedef void * | RawHandleType
| Type of the raw handle used by the operating system. More...

## Public Member Functions

| FileHandle ()
| Default constructor. More...
| FileHandle (FileHandle &&other)
| Move constructor. More...
FileHandle & | operator= (FileHandle &&other)
| Move assignment operator. More...
| ~FileHandle ()
| Destructor. More...
bool | isValid () const
| Checks if the file handle is valid, i.e. More...
bool | canRead () const
| Determines if the file handle can be read from. More...
bool | canWrite () const
| Determines if the file handle can be written to. More...
bool | hasDataToRead () const
| Checks whether this object has data available to be read. More...
bool | readBytes (void *dataBuffer, unsigned int bytesToRead, unsigned int *bytesActuallyRead)
| Reads bytes from the file handle. More...
RawHandleType | get () const
| Gets the raw underlying OS file handle. More...
bool | openForReadingAndWriting (const std::string &path)
| Attempts to open the file handle for reading and writing. More...
bool | openForReading (const std::string &path)
| Attempts to open the file handle for reading only. More...
bool | openForWriting (const std::string &path)
| Attempts to open the file handle for writing only. More...
bool | openForReadingAndMaybeWriting (const std::string &path)
| Attempts to open the file handle for reading and (if permissions allow it) writing. More...
void | setFileOpenFlags (uint64_t flags)
| Sets the flags that will be passed to CreateFile when opening the file. More...
uint64_t | getFileOpenFlags () const
| Gets the flags that will be passed to CreateFile when opening the file. More...
void | reset ()
| Resets the file handle back to an invalid state. More...

## Private Member Functions

| FileHandle (const FileHandle &other)
FileHandle & | operator= (const FileHandle &other)

## Private Attributes

RawHandleType | m_handle
bool | m_canRead
bool | m_canWrite
uint64_t | m_openFlags

## Detailed Description

A wrapper for an Windows-style HANDLE file descriptor.

Allows callers to implement RAII-style resource management.

## Member Typedef Documentation

## RawHandleType

typedef void* SurgSim::Devices::FileHandle::RawHandleType

Type of the raw handle used by the operating system.

Defined this way to avoid including <windows.h> just for the sake of defining HANDLE.

## Constructor & Destructor Documentation

## FileHandle() [1/3]

SurgSim::Devices::FileHandle::FileHandle | ( |  | ) |

Default constructor.

Initializes the file handle to an invalid state.

## FileHandle() [2/3]

SurgSim::Devices::FileHandle::FileHandle | ( | FileHandle && | other | ) |

Move constructor.

Parameters

  [in,out] | other | The object to move. The original object will be invalidated.

## ~FileHandle()

SurgSim::Devices::FileHandle::~FileHandle | ( |  | ) |

Destructor.

## FileHandle() [3/3]

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

private

## Member Function Documentation

## canRead()

bool SurgSim::Devices::FileHandle::canRead | ( |  | ) | const

Determines if the file handle can be read from.

Returns
  true if the handle has been open for reading.

## canWrite()

bool SurgSim::Devices::FileHandle::canWrite | ( |  | ) | const

Determines if the file handle can be written to.

Returns
  true if the handle has been open for writing.

## get()

FileHandle::RawHandleType SurgSim::Devices::FileHandle::get | ( |  | ) | const

Gets the raw underlying OS file handle.

Returns
  The raw file handle.

## getFileOpenFlags()

uint64_t SurgSim::Devices::FileHandle::getFileOpenFlags | ( |  | ) | const

Gets the flags that will be passed to CreateFile when opening the file.

Returns
  The value passed to setFileOpenFlags (or if never set, a default value).

## hasDataToRead()

bool SurgSim::Devices::FileHandle::hasDataToRead | ( |  | ) | const

Checks whether this object has data available to be read.

Returns
  true if there is data currently available.

## isValid()

bool SurgSim::Devices::FileHandle::isValid | ( |  | ) | const

Checks if the file handle is valid, i.e.

has been opened.

Returns
  true if valid, false if not.

## openForReading()

bool SurgSim::Devices::FileHandle::openForReading | ( | const std::string & | path | ) |

Attempts to open the file handle for reading only.

Parameters

  path | Full pathname of the file.

Returns
  true if it succeeds, false if it fails.

## openForReadingAndMaybeWriting()

bool SurgSim::Devices::FileHandle::openForReadingAndMaybeWriting | ( | const std::string & | path | ) |

Attempts to open the file handle for reading and (if permissions allow it) writing.

Parameters

  path | Full pathname of the file.

Returns
  true if it succeeds, false if it fails.

## openForReadingAndWriting()

bool SurgSim::Devices::FileHandle::openForReadingAndWriting | ( | const std::string & | path | ) |

Attempts to open the file handle for reading and writing.

Parameters

  path | Full pathname of the file.

Returns
  true if it succeeds, false if it fails.

## openForWriting()

bool SurgSim::Devices::FileHandle::openForWriting | ( | const std::string & | path | ) |

Attempts to open the file handle for writing only.

Parameters

  path | Full pathname of the file.

Returns
  true if it succeeds, false if it fails.

## operator=() [1/2]

FileHandle & SurgSim::Devices::FileHandle::operator= | ( | FileHandle && | other | ) |

Move assignment operator.

Parameters

  [in,out] | other | The object to move. The original object will be invalidated.

Returns
  A reference to this object.

## operator=() [2/2]

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

private

## readBytes()

bool SurgSim::Devices::FileHandle::readBytes | ( | void * | dataBuffer,
|  | unsigned int | bytesToRead,
|  | unsigned int * | bytesActuallyRead
| ) |  |

Reads bytes from the file handle.

Parameters

  [out] | dataBuffer | Buffer to read into. Must have room for at least bytesToRead bytes of data.
  | bytesToRead | The number of bytes to try reading. Actual number of bytes received may be smaller.
  [out] | bytesActuallyRead | The number of bytes that were actually read into the buffer.

Returns
  true if it succeeds, false if it fails.

## reset()

void SurgSim::Devices::FileHandle::reset | ( |  | ) |

Resets the file handle back to an invalid state.

If the handle was open, it will be closed.

## setFileOpenFlags()

void SurgSim::Devices::FileHandle::setFileOpenFlags | ( | uint64_t | flags | ) |

Sets the flags that will be passed to CreateFile when opening the file.

Parameters

  flags | The flags, a combination of zero or more Windows FILE_FLAG_* flags.

## Member Data Documentation

## m_canRead

bool SurgSim::Devices::FileHandle::m_canRead

private

## m_canWrite

bool SurgSim::Devices::FileHandle::m_canWrite

private

## m_handle

RawHandleType SurgSim::Devices::FileHandle::m_handle

private

## m_openFlags

uint64_t SurgSim::Devices::FileHandle::m_openFlags

private

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

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