xentara-utils v1.2.1
Xentara utilities library
Loading...
Searching...
No Matches
xentara::utils::windows::Handle Class Referencefinal

A Windows handle that closes itself on destruct. More...

#include <windows/Handle.hpp>

+ Inheritance diagram for xentara::utils::windows::Handle:

Classes

class  Setter
 

Public Types

using NativeType = HANDLE
 A native Windows handle.
 

Public Member Functions

constexpr Handle () noexcept=default
 Default constructor.
 
constexpr Handle (HANDLE nativeHandle) noexcept
 Conversion from a native handle.
 
constexpr Handle (Handle &&other) noexcept
 Move constructor.
 
 ~Handle ()
 Destructor. Silently closes the handle.
 
auto operator= (Handle &&rhs) noexcept -> Handle &
 Move assignment operator.
 
 operator HANDLE () const
 Conversion to a native handle.
 
constexpr operator bool () const noexcept
 Checks whether the object contains a handle.
 
auto operator= (HANDLE nativeHandle) noexcept -> Handle &
 Assignment from a native handle.
 
constexpr auto release () noexcept -> HANDLE
 Removes the handle and passes ownership to the caller.
 
auto close () noexcept -> bool
 Closes the handle, if any.
 
auto setter () noexcept -> Setter
 Gets a setter for use as an output parameter for C functions.
 
auto performOverlappedIo (const std::function< auto(HANDLE, OVERLAPPED *) → BOOL > &operation, HANDLE event, std::optional< std::chrono::nanoseconds > timeout=std::nullopt) -> std::optional< DWORD >
 Performs an overlapped I/O operation.
 
auto performOverlappedIo (const std::function< auto(HANDLE, OVERLAPPED *) → BOOL > &operation, std::span< HANDLE > waitObjects, std::optional< std::chrono::nanoseconds > timeout=std::nullopt) -> std::optional< OverlappedResult >
 Performs an overlapped I/O operation.
 

Static Public Attributes

static const HANDLE kInvalid { INVALID_HANDLE_VALUE }
 An invalid handle.
 

Detailed Description

A Windows handle that closes itself on destruct.

This class can be moved but not copied.

Windows file functions, like CreateFile2() return INVALID_HANDLE_VALUE (-1) if they fail. Others functions, like CreateEvent() return NULL (nullptr). This class always uses INVALID_HANDLE_VALUE to indicate an invalid handle, and will replace native handle values of nullptr with INVALID_HANDLE_VALUE.

Note
This class is only available under Windows

Member Typedef Documentation

◆ NativeType

A native Windows handle.

Constructor & Destructor Documentation

◆ Handle() [1/3]

constexpr xentara::utils::windows::Handle::Handle ( )
constexprdefaultnoexcept

Default constructor.

Creates an empty object that does not contain a handle.

◆ Handle() [2/3]

constexpr xentara::utils::windows::Handle::Handle ( HANDLE  nativeHandle)
constexprnoexcept

Conversion from a native handle.

Parameters
nativeHandleThe native handle, or INVALID_HANDLE_VALUE for none. nullptr is also accepted as an invalid handle, and will be treated the same as INVALID_HANDLE_VALUE.

◆ Handle() [3/3]

constexpr xentara::utils::windows::Handle::Handle ( Handle &&  other)
constexprnoexcept

Move constructor.

Takes ownership of the other object’s handle, if any.

Parameters
otherThe object to move. Will be reset and no longer contain a handle afterwards.

◆ ~Handle()

xentara::utils::windows::Handle::~Handle ( )

Destructor. Silently closes the handle.

Member Function Documentation

◆ close()

auto xentara::utils::windows::Handle::close ( ) -> bool
noexcept

Closes the handle, if any.

Returns
Returns true on success, or false on failure. The handle will be closed in either case, though.

◆ operator bool()

constexpr xentara::utils::windows::Handle::operator bool ( ) const
explicitconstexprnoexcept

Checks whether the object contains a handle.

◆ operator HANDLE()

xentara::utils::windows::Handle::operator HANDLE ( ) const

Conversion to a native handle.

Attention
This function always returns INVALID_HANDLE_VALUE (-1) to indicate an invalid handle, even if you passed nullptr to the constructor or assignment operator.
Returns
The contained handle, or INVALID_HANDLE_VALUE for none.

◆ operator=() [1/2]

auto xentara::utils::windows::Handle::operator= ( Handle &&  rhs) -> Handle &
noexcept

Move assignment operator.

Takes ownership of the other handle’s value. Any existing handle is silently closed.

Parameters
rhsThe object to move. Will be reset and no longer contain a handle afterwards.

◆ operator=() [2/2]

auto xentara::utils::windows::Handle::operator= ( HANDLE  nativeHandle) -> Handle &
noexcept

Assignment from a native handle.

Any existing handle is silently closed.

Parameters
nativeHandleThe native handle, or INVALID_HANDLE_VALUE for none. nullptr is also accepted as an invalid handle, and will be treated the same as INVALID_HANDLE_VALUE.

◆ performOverlappedIo() [1/2]

auto xentara::utils::windows::Handle::performOverlappedIo ( const std::function< auto(HANDLE, OVERLAPPED *) → BOOL > &  operation,
HANDLE  event,
std::optional< std::chrono::nanoseconds timeout = std::nullopt 
) -> std::optional< DWORD >

Performs an overlapped I/O operation.

This function creates an OVERLAPPED structure and calls a function object with it. The function object must call a Windows overlapped I/O function like ReadFile() or WriteFile(), passing the overlapped structure to it, and return the result. The function must also preserve the error code stored in GetLastError(), specifically the error code ERROR_IO_PENDING, which the function uses to determine if waiting is necessary.

Parameters
operationThe operation to perform. operation will be called with the handle and an overlapped structure as parameters. It must return TRUE on success or FALSE on error. If FALSE is returned, the last error code must be set to an appropriate error. If an overlapped I/O operation is pending, the function must return FALSE and set the last error to ERROR_IO_PENDING in the manner of overlapped I/O functions like ReadFile() and WriteFile().
Precondition
The handle must be an overlapped handle.
Parameters
eventThe event to use in the OVERLAPPED structure.
timeoutThe timeout, or std::nullopt for infinite. Negative timeouts are treated the same as a timeout of 0.
Returns

Returns the number of bytes transferred on success, or std::nullopt on error. To get extended error information, call GetLastError(). On timeout, the last error is set to ERROR_OPERATION_ABORTED.

The meaning of “number of bytes transferred” depends on the overlapped operation. See the documentation of the lpNumberOfBytesTransferred parameter of GetOverlappedResult().

See also
Synchronization and Overlapped Input and Output in the Windows technical documentation

◆ performOverlappedIo() [2/2]

auto xentara::utils::windows::Handle::performOverlappedIo ( const std::function< auto(HANDLE, OVERLAPPED *) → BOOL > &  operation,
std::span< HANDLE >  waitObjects,
std::optional< std::chrono::nanoseconds timeout = std::nullopt 
) -> std::optional< OverlappedResult >

Performs an overlapped I/O operation.

This function creates an OVERLAPPED structure and calls a function object with it. The function object must call a Windows overlapped I/O function like ReadFile() or WriteFile(), passing the overlapped structure to it, and return the result. The function must also preserve the error code stored in GetLastError(), specifically the error code ERROR_IO_PENDING, which the function uses to determine if waiting is necessary.

Parameters
operationThe operation to perform. operation will be called with the handle and an overlapped structure as parameters. It must return TRUE on success or FALSE on error. If FALSE is returned, the last error code must be set to an appropriate error. If an overlapped I/O operation is pending, the function must return FALSE and set the last error to ERROR_IO_PENDING in the manner of overlapped I/O functions like ReadFile() and WriteFile().
Precondition
The handle must be an overlapped handle.
Parameters
waitObjectsThe objects to wait for. The first position in the span must contain the event to use in the OVERLAPPED structure.
timeoutThe timeout, or std::nullopt for infinite. Negative timeouts are treated the same as a timeout of 0.
Returns
Returns the result of the operation on success, or std::nullopt on error. To get extended error information, call GetLastError(). On timeout, the last error is set to ERROR_OPERATION_ABORTED.
Exceptions
std::invalid_argumentwaitObjects is empty, or contains more objects than Windows can handle.
See also
Synchronization and Overlapped Input and Output in the Windows technical documentation

◆ release()

constexpr auto xentara::utils::windows::Handle::release ( ) -> HANDLE
constexprnoexcept

Removes the handle and passes ownership to the caller.

After this call, this object will no longer contain a handle.

Attention
This function always returns INVALID_HANDLE_VALUE (-1) to indicate an invalid handle, even if you passed nullptr to the constructor or assignment operator.
Returns
The native handle, or INVALID_HANDLE_VALUE for none. The caller must assume ownership of the handle and close it when it is no longer needed.

◆ setter()

auto xentara::utils::windows::Handle::setter ( ) -> Setter
noexcept

Gets a setter for use as an output parameter for C functions.

This function returns a helper object that can be passed to a function that takes an LPHANDLE as output parameter, like e.g. DuplicateHandle(). This provides a safe way of creating kernel objects using such a function without running the risk of leaking the created objects.

DuplicateHandle() can be called like this, for example:

DuplicateHandle(mySourceProcess, myOldHandle, myTargetProcess, newHandle.setter(), 0, 0, DUPLICATE_SAME_ACCESS);
A Windows handle that closes itself on destruct.
Definition Handle.hpp:57
auto setter() noexcept -> Setter
Gets a setter for use as an output parameter for C functions.
Definition Handle.hpp:269

Member Data Documentation

◆ kInvalid

const HANDLE xentara::utils::windows::Handle::kInvalid { INVALID_HANDLE_VALUE }
static

An invalid handle.