xentara::utils::windows::com::String Class Reference

An COM string object. More...

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

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

Public Member Functions
	String () noexcept=default
	Default constructor.
internal	String (BSTR string) noexcept
	Constructor that takes ownership of a native string.
auto	reset (BSTR string=nullptr) noexcept -> void
	Resets the string.
auto	c_str () const noexcept -> BSTR
	Accesses the string as a C string.
auto	data () const noexcept -> const wchar_t *
	Accesses the string.
	operator bool () const noexcept
	Checks if the string contains string data.
	operator std::wstring_view () const noexcept
	Conversion to a string view.
auto	empty () const noexcept
	Checks whether the string is empty.
auto	release () noexcept -> BSTR
	Gives up ownership of the string and returns it.
void	swap (String &other) noexcept
	Swaps objects with another string.
auto	setter () noexcept -> Setter
	Gets a setter for use as an output parameter for C functions.

Detailed Description

An COM string object.

This class stores a Component Object Model (COM) BSTR string that needs to be freed using SysFreeString.

See also

See section 2.2.23: BSTR in the Windows Open Specifications at docs.microsoft.com

Constructor & Destructor Documentation

String() [1/2]

xentara::utils::windows::com::String::String ( )

defaultnoexcept

Default constructor.

This constructor creates a null string

String() [2/2]

internal xentara::utils::windows::com::String::String ( BSTR  string )

explicitnoexcept

Constructor that takes ownership of a native string.

string The native string pointer. Must be nullptr, or must point to a string that needs to be freed using SysFreeString. If you pass nullptr as string, then this constructor creates a null string.

Member Function Documentation

c_str()

auto xentara::utils::windows::com::String::c_str ( ) const -> BSTR

noexcept

Accesses the string as a C string.

Attention

This function returns a BSTR, which is a pointer to modifyable string data. This is so that the string can be passed to COM functions that take a BSTR. The data of the returned string should not be modified.

Returns

The string, or an empty string if the string is a null string. This function never returns nullptr, even for a null string.

data()

auto xentara::utils::windows::com::String::data ( ) const -> const wchar_t *

noexcept

Accesses the string.

This function return nullptr for null strings. To return an empty string for null strings, used c_str().

Returns

The string, or nullptr if the string is a null string.

empty()

auto xentara::utils::windows::com::String::empty ( ) const

noexcept

Checks whether the string is empty.

Returns

Return true if the string is a null string or an empty string, or false if it contains at least one character (not including the terminating null).

operator bool()

xentara::utils::windows::com::String::operator bool ( ) const

explicitnoexcept

Checks if the string contains string data.

Returns

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

operator std::wstring_view()

xentara::utils::windows::com::String::operator std::wstring_view ( ) const

noexcept

Conversion to a string view.

release()

auto xentara::utils::windows::com::String::release ( ) -> BSTR

noexcept

Gives up ownership of the string and returns it.

This method turns the string into a null string

Returns

A pointer to the string, or nullpt if the string was already a null string. The returned string must be released by the caller using SysFreeString.

reset()

auto xentara::utils::windows::com::String::reset ( BSTR  string = nullptr ) -> void

noexcept

Resets the string.

Releases any existing string and accepts ownership of a new string

Parameters

string

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

setter()

auto xentara::utils::windows::com::String::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::String object;
CoCreateInstance(CLSID_TaskbarList, nullptr, CLSCTX_ALL, IID_ITaskbarList3, object.setter());

swap()

void xentara::utils::windows::com::String::swap ( String &  other )

noexcept

Swaps objects with another string.