xentara::utils::windows::com::ObjectHandle< ObjectClass > Class Template Reference

A handle to a COM object. More...

#include <xentara/utils/windows/com/ObjectHandle.hpp>

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

Public Types
using	element_type = std::remove_cv_t< ObjectClass >
	The object type.
using	pointer = element_type *
	A pointer to an object.

Public Member Functions
	ObjectHandle () noexcept=default
	Default Constructor.
	ObjectHandle (std::nullptr_t) noexcept
	Constructor for a null handle.
	ObjectHandle (ObjectClass *object) noexcept
	Constructor that sets the object.
	ObjectHandle (ObjectHandle &&other) noexcept=default
	Move constructor.
auto	operator= (ObjectHandle &&rhs) noexcept -> ObjectHandle &=default
	Move assignment operator.
auto	operator= (std::nullptr_t) noexcept -> ObjectHandle &
	Turns the handle into a null handle.
auto	reset (ObjectClass *object=nullptr) noexcept -> void
	Resets the handle.
auto	get () const noexcept -> ObjectClass *
	Accesses the object.
auto	operator* () const noexcept -> ObjectClass &
	Accesses the object.
	operator bool () const noexcept
	Checks if the handle contains an object.
auto	operator-> () const noexcept -> ObjectClass *
	Accesses the object.
auto	release () noexcept -> ObjectClass *
	Gives up ownership of the object and returns it.
void	swap (ObjectHandle &other) noexcept
	Swaps objects with another handle.
auto	setter () noexcept -> Setter
	Gets a setter for use as an output parameter for C functions.

Detailed Description

template<typename ObjectClass>
requires std::is_class_v<ObjectClass>
class xentara::utils::windows::com::ObjectHandle< ObjectClass >

A handle to a COM object.

This class stores a handle to a Component Object Model (COM) object, and autoreleases that handle in it's destructor.

Member Typedef Documentation

element_type

template<typename ObjectClass >

using xentara::utils::windows::com::ObjectHandle< ObjectClass >::element_type = std::remove_cv_t<ObjectClass>

The object type.

pointer

template<typename ObjectClass >

using xentara::utils::windows::com::ObjectHandle< ObjectClass >::pointer = element_type *

A pointer to an object.

Constructor & Destructor Documentation

ObjectHandle() [1/4]

template<typename ObjectClass >

xentara::utils::windows::com::ObjectHandle< ObjectClass >::ObjectHandle ( )

defaultnoexcept

Default Constructor.

Creates a null handle that does not contain an object

ObjectHandle() [2/4]

template<typename ObjectClass >

xentara::utils::windows::com::ObjectHandle< ObjectClass >::ObjectHandle ( std::nullptr_t  )

noexcept

Constructor for a null handle.

ObjectHandle() [3/4]

template<typename ObjectClass >

xentara::utils::windows::com::ObjectHandle< ObjectClass >::ObjectHandle ( ObjectClass *  object )

explicitnoexcept

Constructor that sets the object.

Parameters

object

The new object, or nullptr to create a null handle. The handle assumes ownership of the object, so that it will be released in the destructor.

ObjectHandle() [4/4]

template<typename ObjectClass >

xentara::utils::windows::com::ObjectHandle< ObjectClass >::ObjectHandle ( ObjectHandle< ObjectClass > &&  other )

defaultnoexcept

Move constructor.

Transfers the object from another handle

Member Function Documentation

get()

template<typename ObjectClass >

auto xentara::utils::windows::com::ObjectHandle< ObjectClass >::get ( ) const -> ObjectClass *

noexcept

Accesses the object.

Returns

The object, or nullpt if the handle was a null handle.

operator bool()

template<typename ObjectClass >

xentara::utils::windows::com::ObjectHandle< ObjectClass >::operator bool ( ) const

explicitnoexcept

Checks if the handle contains an object.

Returns

Return true if the handle contains an object, or false if it is a null handle.

operator*()

template<typename ObjectClass >

auto xentara::utils::windows::com::ObjectHandle< ObjectClass >::operator* ( ) const -> ObjectClass &

noexcept

Accesses the object.

Precondition

This method must not be called on a null handle

Returns

A reference to the object.

operator->()

template<typename ObjectClass >

auto xentara::utils::windows::com::ObjectHandle< ObjectClass >::operator-> ( ) const -> ObjectClass *

noexcept

Accesses the object.

Returns

The object, or nullpt if the handle was a null handle.

operator=() [1/2]

template<typename ObjectClass >

auto xentara::utils::windows::com::ObjectHandle< ObjectClass >::operator= ( ObjectHandle< ObjectClass > &&  rhs ) -> ObjectHandle &=default

defaultnoexcept

Move assignment operator.

Releases any existing handle and transfers the object from another handle

operator=() [2/2]

template<typename ObjectClass >

auto xentara::utils::windows::com::ObjectHandle< ObjectClass >::operator= ( std::nullptr_t  ) -> ObjectHandle &

noexcept

Turns the handle into a null handle.

Releases any existing handle and turns the object into a null handle.

release()

template<typename ObjectClass >

auto xentara::utils::windows::com::ObjectHandle< ObjectClass >::release ( ) -> ObjectClass *

noexcept

Gives up ownership of the object and returns it.

This method turns the handle into a null handle

Returns

The object, or nullpt if the handle was already a null handle. The object must be released by the caller.

reset()

template<typename ObjectClass >

auto xentara::utils::windows::com::ObjectHandle< ObjectClass >::reset ( ObjectClass *  object = nullptr ) -> void

noexcept

Resets the handle.

Releases any existing handle and accepts ownership of a new object

Parameters

object

The new object, or nullptr to turn the object into a null handle. The handle assumes ownership of the object, so that it will be released in the destructor.

setter()

template<typename ObjectClass >

auto xentara::utils::windows::com::ObjectHandle< ObjectClass >::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 ObjectClass **, a void **, or an LPVOID * as output parameter, like e.g. CoCreateInstance(). This provides a safe way of creating objects using such a function without running the risk of leaking the created object.

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

xentara::utils::windows::com::ObjectHandle object;
CoCreateInstance(CLSID_TaskbarList, nullptr, CLSCTX_ALL, IID_ITaskbarList3,, object.setter());

swap()

template<typename ObjectClass >

void xentara::utils::windows::com::ObjectHandle< ObjectClass >::swap ( ObjectHandle< ObjectClass > &  other )

noexcept

Swaps objects with another handle.