xentara::utils::windows::Handle Class Reference

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

#include <xentara/utils/windows/Handle.hpp>

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

Classes
class	Setter
	Helper class for calling functions that take an output parameter. More...

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 (functional::function_ref< 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 (functional::function_ref< 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

using xentara::utils::windows::Handle::NativeType = HANDLE

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

nativeHandle

The 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

other

The 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

rhs	The 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

nativeHandle

The 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	(	functional::function_ref< 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

operation

The 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

event	The event to use in the OVERLAPPED structure.
timeout	The 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	(	functional::function_ref< 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

operation

The 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

waitObjects	The objects to wait for. The first position in the span must contain the event to use in the OVERLAPPED structure.
timeout	The 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_argument

waitObjects 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:

xentara::utils::windows::Handle newHandle;
DuplicateHandle(mySourceProcess, myOldHandle, myTargetProcess, newHandle.setter(), 0, 0, DUPLICATE_SAME_ACCESS);

Member Data Documentation

kInvalid

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

static

An invalid handle.