COM Utility Library
[Utility Library, COMSTL]

Detailed Description

This library defines classes and functions for COM that are used by other libraries and/or have no other obvious grouping.

The components in the COM Utility library provide the following services (all components are in the comstl namespace):

Facades: bstr, guid, variant
Library initialisation: initialiser
Object creation: co_create_instance()
Interface control: addref(), safe_addref(), release(), safe_release()
Running Object Table: Rot_Register(), Rot_Revoke(), Rot_IsRunning(), Rot_GetObject(), Rot_NoteChangeTime(), Rot_GetTimeOfLastChange(), Rot_EnumRunning()
Marshalling: MarshalInterThreadInterfaceInStream(), GetInterfaceAndReleaseStream()

Classes

class bstr

Facade for the COM BSTR type. More...

class guid

Facade for the COM GUID type. More...

class initialiser

Initialises the COM libraries. More...

struct CoInitialize_policy

A policy type, for use with comstl::initialiser, that causes initialisation/uninitialisation of the COM libraries with CoInitialize()/CoInitializeEx() and CoUninitialize(). More...

struct OleInitialize_policy

A policy type, for use with comstl::initialiser, that causes initialisation/uninitialisation of the COM libraries with OleInitialize() and OleUninitialize(). More...

struct IID_traits

Interface identifier traits. More...

struct GUID_policy

Value policy for GUID. More...

struct BSTR_policy

Value policy for BSTR. More...

struct LPOLESTR_policy

Value policy for LPOLESTR. More...

struct VARIANT_policy

Value policy for VARIANT. More...

struct interface_policy

Value policy for interface. More...

struct LPUNKNOWN_policy

Value policy for LPUNKNOWN. More...

struct STATSTG_policy

Value policy for STATSTG. More...

struct FORMATETC_policy

Value policy for FORMATETC. More...

class variant

Facade for the COM VARIANT type. More...

Typedefs

typedef initialiser
< CoInitialize_policy,
ignore_initialisation_exception_policy > com_init_nothrow

Specialisation of comstl::initialiser that initialises via CoInitialize() but does not throw on failure.

typedef initialiser
< OleInitialize_policy,
ignore_initialisation_exception_policy > ole_init_nothrow

Specialisation of comstl::initialiser that initialises via OleInitialize() but does not throw on failure.

typedef initialiser
< CoInitialize_policy,
com_initialisation_exception_policy > com_init

Specialisation of comstl::initialiser that initialises via CoInitialize() and throws on failure.

typedef initialiser
< OleInitialize_policy,
com_initialisation_exception_policy > ole_init

Specialisation of comstl::initialiser that initialises via OleInitialize() and throws on failure.

typedef com_init_nothrow com_initialiser

[DEPRECATED] Specialisation of comstl::initialiser that initialises via CoInitialize() but does not throw on failure.

typedef ole_init_nothrow ole_initialiser

[DEPRECATED] Specialisation of comstl::initialiser that initialises via OleInitialize() but does not throw on failure.

typedef com_initialiser com_initializer

Equivalent to com_initialiser.

typedef ole_initialiser ole_initializer

Equivalent to ole_initialiser.

Functions

template<typename I>

HRESULT co_create_instance (REFCLSID clsid, I **ppi, DWORD dwClsContext=CLSCTX_ALL)

Type-safe creation of a COM object, acquiring the requisite interface pointer.

template<typename I>

HRESULT co_create_instance (LPCOLESTR id, I **ppi, DWORD dwClsContext=CLSCTX_ALL)

Type-safe creation of a COM object from a Programmatic Id, acquiring the requisite interface pointer.

template<typename T, typename I, typename U>

HRESULT co_create_instance (REFCLSID clsid, stlsoft::ref_ptr< T, I, U > &wi, DWORD dwClsContext=CLSCTX_ALL)

Type-safe creation of a COM object, acquiring the requisite interface pointer into an interface wrapper instance.

template<typename T, typename I, typename U>

HRESULT co_create_instance (LPCOLESTR id, stlsoft::ref_ptr< T, I, U > &wi, DWORD dwClsContext=CLSCTX_ALL)

Type-safe creation of a COM object from a Programmatic Id, acquiring the requisite interface wrapper instance.

STLSOFT_INLINE int comstl__CY_compare (CY const *lhs, CY const *rhs)

[C only] Compares two CY structures

int CY_compare (CY const *lhs, CY const *rhs)

[C++ only] Compares two CY structures

int CY_compare (CY const &lhs, CY const &rhs)

[C++ only] Compares two CY structures

STLSOFT_INLINE int comstl__DECIMAL_compare (DECIMAL const *lhs, DECIMAL const *rhs)

[C only] Compares two DECIMAL structures

int DECIMAL_compare (DECIMAL const *lhs, DECIMAL const *rhs)

[C++ only] Compares two DECIMAL structures

int DECIMAL_compare (DECIMAL const &lhs, DECIMAL const &rhs)

[C++ only] Compares two DECIMAL structures

STLSOFT_INLINE void comstl__addref (LPUNKNOWN punk)

[C only] Adds a reference on the interface pointer

STLSOFT_INLINE void comstl__release (LPUNKNOWN punk)

[C only] Releases a reference on the interface pointer

STLSOFT_INLINE void comstl__safe_addref (LPUNKNOWN punk)

[C only] Adds a reference on the interface pointer

STLSOFT_INLINE void comstl__safe_release (LPUNKNOWN punk)

[C only] Releases a reference on the interface pointer

void addref (LPUNKNOWN punk)

Adds a reference on the interface pointer.

void release (LPUNKNOWN punk)

Releases a reference on the interface pointer.

void safe_addref (LPUNKNOWN punk)

Adds a reference on the interface pointer.

void safe_release (LPUNKNOWN punk)

Releases a reference on the interface pointer.

template<typename T>

void release_set_null (T *&pt)

Releases a reference on the interface pointer, and resets the pointer.

STLSOFT_INLINE HRESULT comstl_C_Rot_Register (DWORD grfFlags, LPUNKNOWN punkObject, LPMONIKER pmkObjectName, DWORD *pdwRegister)

[C only] Registers an object in the Running Object Table

STLSOFT_INLINE HRESULT comstl_C_Rot_Revoke (DWORD dwRegister)

[C only] Removes an object from the Running Object Table

STLSOFT_INLINE HRESULT comstl_C_Rot_IsRunning (LPMONIKER pmkObjectName)

[C only] Determines if object current in the Running Object Table

STLSOFT_INLINE HRESULT comstl_C_Rot_GetObject (LPMONIKER pmkObjectName, LPUNKNOWN *ppunkObject)

[C only] Retrieves the object from the Running Object Table

STLSOFT_INLINE HRESULT comstl_C_Rot_NoteChangeTime (DWORD dwRegister, FILETIME *lpfiletime)

[C only] Retrieves the last modification time of a running object in the Running Object Table

STLSOFT_INLINE HRESULT comstl_C_Rot_GetTimeOfLastChange (LPMONIKER pmkObjectName, FILETIME *lpfiletime)

[C only] Retrieves the last modification time of an object in the Running Object Table

STLSOFT_INLINE HRESULT comstl_C_Rot_EnumRunning (IEnumMoniker **ppenumMoniker)

[C only] Queries the current set of objects in the Running Object Table

HRESULT Rot_Register (DWORD grfFlags, LPUNKNOWN punkObject, LPMONIKER pmkObjectName, DWORD *pdwRegister)

Registers an object in the Running Object Table.

HRESULT Rot_Revoke (DWORD dwRegister)

Removes an object from the Running Object Table.

HRESULT Rot_IsRunning (LPMONIKER pmkObjectName)

Determines if object current in the Running Object Table.

HRESULT Rot_GetObject (LPMONIKER pmkObjectName, LPUNKNOWN *ppunkObject)

Retrieves the object from the Running Object Table.

HRESULT Rot_NoteChangeTime (DWORD dwRegister, FILETIME *lpfiletime)

Retrieves the last modification time of a running object in the Running Object Table.

HRESULT Rot_GetTimeOfLastChange (LPMONIKER pmkObjectName, FILETIME *lpfiletime)

Retrieves the last modification time of an object in the Running Object Table.

HRESULT Rot_EnumRunning (IEnumMoniker **ppenumMoniker)

Queries the current set of objects in the Running Object Table.

STLSOFT_INLINE HRESULT comstl__get_stream_size (LPSTREAM pstm, ULARGE_INTEGER *psize)

[C only] Gets the size of a stream

HRESULT get_stream_size (LPSTREAM pstm, ULARGE_INTEGER *psize)

Gets the size of a stream.

HRESULT get_stream_size (LPSTREAM pstm, ULARGE_INTEGER &size)

Gets the size of a stream.

HRESULT get_stream_size (LPSTREAM pstm, cs_uint64_t &size)

Gets the size of a stream.

template<typename I>

HRESULT MarshalInterThreadInterfaceInStream (I *pitf, LPSTREAM *ppstm)

Marshal a interface to a stream.

template<typename I>

HRESULT GetInterfaceAndReleaseStream (LPSTREAM pstm, I **ppitf)

Retrieve a marshaled interface pointer from a stream.

STLSOFT_INLINE int comstl__VARIANT_equal (VARIANT const *lhs, VARIANT const *rhs, HRESULT *comparisonSucceeded)

[C only] Indicates whether two VARIANT structures are equal

bool VARIANT_equal (VARIANT const *lhs, VARIANT const *rhs, HRESULT *comparisonSucceeded)

[C++ only] Indicates whether two VARIANT structures are equal

bool VARIANT_equal (VARIANT const &lhs, VARIANT const &rhs, HRESULT *comparisonSucceeded)

[C++ only] Indicates whether two VARIANT structures are equal

Typedef Documentation

typedef initialiser<CoInitialize_policy, com_initialisation_exception_policy> com_init

Specialisation of comstl::initialiser that initialises via CoInitialize() and throws on failure.

See also:: comstl::initialiser

typedef initialiser<CoInitialize_policy, ignore_initialisation_exception_policy> com_init_nothrow

Specialisation of comstl::initialiser that initialises via CoInitialize() but does not throw on failure.

See also:: comstl::initialiser

typedef com_init_nothrow com_initialiser

[DEPRECATED] Specialisation of comstl::initialiser that initialises via CoInitialize() but does not throw on failure.

Deprecated:: Use com_init_nothrow instead.

See also:: comstl::initialiser

typedef com_initialiser com_initializer

Equivalent to com_initialiser.

typedef initialiser<OleInitialize_policy, com_initialisation_exception_policy> ole_init

Specialisation of comstl::initialiser that initialises via OleInitialize() and throws on failure.

See also:: comstl::initialiser

typedef initialiser<OleInitialize_policy, ignore_initialisation_exception_policy> ole_init_nothrow

Specialisation of comstl::initialiser that initialises via OleInitialize() but does not throw on failure.

See also:: comstl::initialiser

typedef ole_init_nothrow ole_initialiser

[DEPRECATED] Specialisation of comstl::initialiser that initialises via OleInitialize() but does not throw on failure.

Deprecated:: Use ole_init_nothrow instead.

See also:: comstl::initialiser

typedef ole_initialiser ole_initializer

Equivalent to ole_initialiser.

Function Documentation

void comstl::addref ( LPUNKNOWN punk ) [inline]

Adds a reference on the interface pointer.

Parameters:

punk

The interface pointer on which to add the reference. Cannot be null

Precondition:: punk must not be NULL.

References comstl__addref().

Referenced by interface_cast_base< I, comstl::addref_release< I >, X >::interface_cast_base().

HRESULT comstl::co_create_instance	(	LPCOLESTR	id,
		stlsoft::ref_ptr< T, I, U > &	wi,
		DWORD	dwClsContext = `CLSCTX_ALL`
	)			`[inline]`

Type-safe creation of a COM object from a Programmatic Id, acquiring the requisite interface wrapper instance.

Parameters:

	id	Can be the Programatic Identifier (ProgId) - e.g. pantheios.com.LoggerManager - or the string form of the class id - e.g. {4E7D5C47-8F96-45DE-905D-AA3E9E592DE3}
	wi	A mutable (non-const) reference to an interface wrapper instance. The wrapper's `interface_type` determines the interface queried by the COM runtime's creation facilities on the created instance.
	dwClsContext	Class creation context

The following example demonstrates how to use the function to create an instance of the Pantheios.COM Logger Manager component by specifying the string form of its CLSID, and requesting the IDispatch interface:

stlsoft::ref_ptr<IDispatch> logmgr;
if(SUCCEEDED(comstl::co_create_instance(L"{4E7D5C47-8F96-45DE-905D-AA3E9E592DE3}", logmgr)))
{
  . . .
} // Release() automatically invoked here

The following example demonstrates how to use the function to create an instance of the Pantheios.COM Logger Manager component by specifying the Programmatic Identifier (ProgID), and requesting the IDispatch interface:

stlsoft::ref_ptr<IDispatch> logmgr;
if(SUCCEEDED(comstl::co_create_instance(L"pantheios.COM.LoggerManager", logmgr)))
{
  . . .
} // Release() automatically invoked here

References comstl::co_create_instance(), and stlsoft_ns_qual.

HRESULT comstl::co_create_instance	(	REFCLSID	clsid,
		stlsoft::ref_ptr< T, I, U > &	wi,
		DWORD	dwClsContext = `CLSCTX_ALL`
	)			`[inline]`

Type-safe creation of a COM object, acquiring the requisite interface pointer into an interface wrapper instance.

Parameters:

	clsid	The CLSID of the component to be created.
	wi	A mutable (non-const) reference to an interface wrapper instance. The wrapper's `interface_type` determines the interface queried by the COM runtime's creation facilities on the created instance.
	dwClsContext	Class creation context

The following example demonstrates how to use the function to create an instance of the Pantheios.COM Logger Manager component by specifying its CLSID, and requesting the IDispatch interface:

const CLSID CLSID_pantheios_COM_LoggerManager  = { 0x4E7D5C47, 0x8F96, 0x45DE, { 0x90, 0x5D, 0xAA, 0x3E, 0x9E, 0x59, 0x2D, 0xE3 } };

stlsoft::ref_ptr<IDispatch> logmgr;
if(SUCCEEDED(comstl::co_create_instance(CLSID_pantheios_COM_LoggerManager, logmgr)))
{
  . . .
} // Release() automatically invoked here

References comstl::co_create_instance().

HRESULT comstl::co_create_instance	(	LPCOLESTR	id,
		I **	ppi,
		DWORD	dwClsContext = `CLSCTX_ALL`
	)			`[inline]`

Type-safe creation of a COM object from a Programmatic Id, acquiring the requisite interface pointer.

Parameters:

	id	Can be the Programatic Identifier (ProgId) - e.g. pantheios.com.LoggerManager - or the string form of the class id - e.g. {4E7D5C47-8F96-45DE-905D-AA3E9E592DE3}
	ppi	Pointer to the interface pointer.
	dwClsContext	Class creation context

The following example demonstrates how to use the function to create an instance of the Pantheios.COM Logger Manager component by specifying the string form of its CLSID, and requesting the IDispatch interface:

IDispatch* logmgr;
if(SUCCEEDED(comstl::co_create_instance(L"{4E7D5C47-8F96-45DE-905D-AA3E9E592DE3}", &logmgr)))
{
  logmgr->Release();
}

The following example demonstrates how to use the function to create an instance of the Pantheios.COM Logger Manager component by specifying the Programmatic Identifier (ProgID), and requesting the IDispatch interface:

IDispatch* logmgr;
if(SUCCEEDED(comstl::co_create_instance(L"pantheios.COM.LoggerManager", &logmgr)))
{
  logmgr->Release();
}

References comstl::co_create_instance().

HRESULT comstl::co_create_instance	(	REFCLSID	clsid,
		I **	ppi,
		DWORD	dwClsContext = `CLSCTX_ALL`
	)			`[inline]`

Type-safe creation of a COM object, acquiring the requisite interface pointer.

Parameters:

	clsid	The CLSID of the component to be created.
	ppi	Pointer to the interface pointer.
	dwClsContext	Class creation context

The following example demonstrates how to use the function to create an instance of the Pantheios.COM Logger Manager component by specifying its CLSID, and requesting the IDispatch interface:

const CLSID CLSID_pantheios_COM_LoggerManager  = { 0x4E7D5C47, 0x8F96, 0x45DE, { 0x90, 0x5D, 0xAA, 0x3E, 0x9E, 0x59, 0x2D, 0xE3 } };

IDispatch* logmgr;
if(SUCCEEDED(comstl::co_create_instance(CLSID_pantheios_COM_LoggerManager, &logmgr)))
{
  logmgr->Release();
}

Examples:: by_library/com_utility/creation_functions/creation_functions.cpp, and by_project/comstl/comstl.cpp.

Referenced by comstl::co_create_instance().

STLSOFT_INLINE void comstl__addref ( LPUNKNOWN punk )

[C only] Adds a reference on the interface pointer

Parameters:

punk

The interface pointer on which to add the reference. Cannot be null

Precondition:: punk must not be NULL.

References COMSTL_ITF_CALL, COMSTL_ITF_THIS0, and COMSTL_MESSAGE_ASSERT.

Referenced by comstl::addref(), and comstl__safe_addref().

STLSOFT_INLINE int comstl__CY_compare	(	CY const *	lhs,
		CY const *	rhs
	)

[C only] Compares two CY structures

Parameters:

	lhs	Pointer to the left-hand instances to compare
	lhs	Pointer to the right-hand instances to compare

Precondition:: lhs must not be NULL.
rhs must not be NULL.

References COMSTL_MESSAGE_ASSERT.

Referenced by comstl__VARIANT_equal(), and comstl::CY_compare().

STLSOFT_INLINE int comstl__DECIMAL_compare	(	DECIMAL const *	lhs,
		DECIMAL const *	rhs
	)

[C only] Compares two DECIMAL structures

Parameters:

	lhs	Pointer to the left-hand instances to compare
	lhs	Pointer to the right-hand instances to compare

Precondition:: lhs must not be NULL.
rhs must not be NULL.

References COMSTL_ACCESS_VARIANT_MEM_BYREF, COMSTL_ACCESS_VARIANT_vt_BYREF, and COMSTL_MESSAGE_ASSERT.

Referenced by comstl__VARIANT_equal(), and comstl::DECIMAL_compare().

STLSOFT_INLINE HRESULT comstl__get_stream_size	(	LPSTREAM	pstm,
		ULARGE_INTEGER *	psize
	)

[C only] Gets the size of a stream

See also:: comstl::get_stream_size

References COMSTL_ITF_CALL, and COMSTL_ITF_THIS.

Referenced by comstl::get_stream_size().

STLSOFT_INLINE void comstl__release ( LPUNKNOWN punk )

[C only] Releases a reference on the interface pointer

Parameters:

punk

The interface pointer on which to release the reference. Cannot be null

References COMSTL_ITF_CALL, and COMSTL_ITF_THIS0.

Referenced by comstl__safe_release(), and comstl::release().

STLSOFT_INLINE void comstl__safe_addref ( LPUNKNOWN punk )

[C only] Adds a reference on the interface pointer

Parameters:

punk

The interface pointer on which to add the reference. Can be null

References comstl__addref().

Referenced by comstl::safe_addref().

STLSOFT_INLINE void comstl__safe_release ( LPUNKNOWN punk )

[C only] Releases a reference on the interface pointer

Parameters:

punk

The interface pointer on which to release the reference. Can be null

References comstl__release().

Referenced by comstl::safe_release().

STLSOFT_INLINE int comstl__VARIANT_equal	(	VARIANT const *	lhs,
		VARIANT const *	rhs,
		HRESULT *	comparisonSucceeded
	)

[C only] Indicates whether two VARIANT structures are equal

Parameters:

	lhs	Pointer to the left-hand instances to compare
	lhs	Pointer to the right-hand instances to compare
	comparisonSucceeded	Pointer to a result-code instance that will have an HRESULT value not equal to S_OK if the comparison cannot be made. May be NULL if the caller does not care

Returns:: a value indicating whether the values are equal

Return values:

	0	The structures are not equal
	>0	The structures are equal

Precondition:: lhs must not be NULL.
rhs must not be NULL.

References comstl__bstr_compare(), comstl__CY_compare(), comstl__DECIMAL_compare(), comstl__is_same_object(), COMSTL_MESSAGE_ASSERT, and stlsoft_static_cast.

Referenced by comstl::VARIANT_equal().

STLSOFT_INLINE HRESULT comstl_C_Rot_EnumRunning ( IEnumMoniker ** ppenumMoniker )

[C only] Queries the current set of objects in the Running Object Table

Creates and returns a pointer to an enumerator that can list the monikers of all the objects currently registered in the Running Object Table (ROT).

Parameters:

ppenumMoniker

Address of output variable that receives the IEnumMoniker interface pointer

Returns:: An HRESULT indicating success or failure

References COMSTL_ITF_CALL, COMSTL_ITF_THIS, COMSTL_ITF_THIS0, and STLSOFT_NS_GLOBAL.

STLSOFT_INLINE HRESULT comstl_C_Rot_GetObject	(	LPMONIKER	pmkObjectName,
		LPUNKNOWN *	ppunkObject
	)

[C only] Retrieves the object from the Running Object Table

Determines whether the object identified by the specified moniker is running, and if it is, retrieves a pointer to that object. This method looks for the moniker in the Running Object Table (ROT), and retrieves the pointer registered there.

Parameters:

	pmkObjectName	Pointer to the moniker of the object
	ppunkObject	Address of output variable that receives the IUnknown interface pointer

Returns:: An HRESULT indicating success or failure

References COMSTL_ITF_CALL, COMSTL_ITF_THIS, COMSTL_ITF_THIS0, and STLSOFT_NS_GLOBAL.

STLSOFT_INLINE HRESULT comstl_C_Rot_GetTimeOfLastChange	(	LPMONIKER	pmkObjectName,
		FILETIME *	lpfiletime
	)

[C only] Retrieves the last modification time of an object in the Running Object Table

Returns the time that an object was last modified. The object must have previously been registered with the Running Object Table (ROT). This method looks for the last change time recorded in the ROT.

Parameters:

	pmkObjectName	Pointer to moniker on the object whose status is desired
	lpfiletime	Pointer to structure containing object's last change time

Returns:: An HRESULT indicating success or failure

References COMSTL_ITF_CALL, COMSTL_ITF_THIS, COMSTL_ITF_THIS0, and STLSOFT_NS_GLOBAL.

STLSOFT_INLINE HRESULT comstl_C_Rot_IsRunning ( LPMONIKER pmkObjectName )

[C only] Determines if object current in the Running Object Table

Determines whether the object identified by the specified moniker is currently running. This method looks for the moniker in the Running Object Table (ROT).

Parameters:

pmkObjectName

Pointer to the moniker of the object whose status is desired

Returns:: An HRESULT indicating success or failure

References COMSTL_ITF_CALL, COMSTL_ITF_THIS, COMSTL_ITF_THIS0, and STLSOFT_NS_GLOBAL.

STLSOFT_INLINE HRESULT comstl_C_Rot_NoteChangeTime	(	DWORD	dwRegister,
		FILETIME *	lpfiletime
	)

[C only] Retrieves the last modification time of a running object in the Running Object Table

Records the time that a running object was last modified. The object must have previously been registered with the Running Object Table (ROT). This method stores the time of last change in the ROT.

Parameters:

	dwRegister	Value identifying registration being updated
	lpfiletime	Pointer to structure containing object's last change time

Returns:: An HRESULT indicating success or failure

References COMSTL_ITF_CALL, COMSTL_ITF_THIS, COMSTL_ITF_THIS0, and STLSOFT_NS_GLOBAL.

STLSOFT_INLINE HRESULT comstl_C_Rot_Register	(	DWORD	grfFlags,
		LPUNKNOWN	punkObject,
		LPMONIKER	pmkObjectName,
		DWORD *	pdwRegister
	)

[C only] Registers an object in the Running Object Table

Registers an object and its identifying moniker in the Running Object Table (ROT).

Parameters:

	grfFlags	Registration options
	punkObject	Pointer to the object being registered
	pmkObjectName	Pointer to the moniker of the object being registered
	pdwRegister	Pointer to the value identifying the registration

Returns:: An HRESULT indicating success or failure

References COMSTL_ITF_CALL, COMSTL_ITF_THIS, COMSTL_ITF_THIS0, and STLSOFT_NS_GLOBAL.

STLSOFT_INLINE HRESULT comstl_C_Rot_Revoke ( DWORD dwRegister )

[C only] Removes an object from the Running Object Table

Removes from the Running Object Table (ROT) an entry that was previously registered by a call to Rot_Register().

Parameters:

dwRegister

Value identifying registration to be revoked

Returns:: An HRESULT indicating success or failure

References COMSTL_ITF_CALL, COMSTL_ITF_THIS, COMSTL_ITF_THIS0, and STLSOFT_NS_GLOBAL.

int comstl::CY_compare	(	CY const &	lhs,
		CY const &	rhs
	)			`[inline]`

[C++ only] Compares two CY structures

Parameters:

	lhs	Reference to the left-hand instances to compare
	lhs	Reference to the right-hand instances to compare

References comstl__CY_compare().

int comstl::CY_compare	(	CY const *	lhs,
		CY const *	rhs
	)			`[inline]`

[C++ only] Compares two CY structures

Parameters:

	lhs	Pointer to the left-hand instances to compare
	lhs	Pointer to the right-hand instances to compare

Precondition:: lhs must not be NULL.
rhs must not be NULL.

References comstl__CY_compare().

int comstl::DECIMAL_compare	(	DECIMAL const &	lhs,
		DECIMAL const &	rhs
	)			`[inline]`

[C++ only] Compares two DECIMAL structures

Parameters:

	lhs	Reference to the left-hand instances to compare
	lhs	Reference to the right-hand instances to compare

References comstl__DECIMAL_compare().

int comstl::DECIMAL_compare	(	DECIMAL const *	lhs,
		DECIMAL const *	rhs
	)			`[inline]`

[C++ only] Compares two DECIMAL structures

Parameters:

	lhs	Pointer to the left-hand instances to compare
	lhs	Pointer to the right-hand instances to compare

Precondition:: lhs must not be NULL.
rhs must not be NULL.

References comstl__DECIMAL_compare().

HRESULT comstl::get_stream_size	(	LPSTREAM	pstm,
		cs_uint64_t &	size
	)			`[inline]`

Gets the size of a stream.

References comstl__get_stream_size().

HRESULT comstl::get_stream_size	(	LPSTREAM	pstm,
		ULARGE_INTEGER &	size
	)			`[inline]`

Gets the size of a stream.

References comstl__get_stream_size().

HRESULT comstl::get_stream_size	(	LPSTREAM	pstm,
		ULARGE_INTEGER *	psize
	)			`[inline]`

Gets the size of a stream.

References comstl__get_stream_size().

HRESULT comstl::GetInterfaceAndReleaseStream	(	LPSTREAM	pstm,
		I **	ppitf
	)			`[inline]`

Retrieve a marshaled interface pointer from a stream.

This function loads a serialised marshalled interface pointer from the given stream, queries for the interface of the given pointer, and returns the pointer if successful, and an error code if not. The stream is always released, irrespective of the success status of the function as a whole.

Parameters:

	pstm	An IStream pointer from which object is to be unmarshaled
	ppitf	A pointer to the interface pointer to be unmarshaled

Returns:: An HRESULT indicating success or failure

Return values:

	E_INVALIDARG	The argument was invalid
	S_OK	The operation completed successfully

HRESULT comstl::MarshalInterThreadInterfaceInStream	(	I *	pitf,
		LPSTREAM *	ppstm
	)			`[inline]`

Marshal a interface to a stream.

This function marshals the given interface into a new stream instance, which is returned to the caller. The stream may then be passed directly to another thread in the process, from which GetInterfaceAndReleaseStream() may be called.

Parameters:

	pitf	The interface pointer to marshal
	ppstm	A pointer to an IStream pointer to receive the stream

Returns:: An HRESULT indicating success or failure

Return values:

	E_OUTOFMEMORY	Sufficient memory could not be acquired
	S_OK	The operation completed successfully

void comstl::release ( LPUNKNOWN punk ) [inline]

Releases a reference on the interface pointer.

Parameters:

punk

The interface pointer on which to release the reference. Cannot be null

References comstl__release().

Referenced by noaddref_release::operator()(), and comstl::release_set_null().

void comstl::release_set_null ( T *& pt ) [inline]

Releases a reference on the interface pointer, and resets the pointer.

Parameters:

pt

The interface pointer on which to release the reference. Can be null

References comstl::release().

HRESULT comstl::Rot_EnumRunning ( IEnumMoniker ** ppenumMoniker ) [inline]

Queries the current set of objects in the Running Object Table.

Creates and returns a pointer to an enumerator that can list the monikers of all the objects currently registered in the Running Object Table (ROT).

Parameters:

ppenumMoniker

Address of output variable that receives the IEnumMoniker interface pointer

Returns:: An HRESULT indicating success or failure

Examples:: by_library/com_utility/rot_functions/rot_functions.cpp.

References comstl__Rot_EnumRunning.

HRESULT comstl::Rot_GetObject	(	LPMONIKER	pmkObjectName,
		LPUNKNOWN *	ppunkObject
	)			`[inline]`

Retrieves the object from the Running Object Table.

Determines whether the object identified by the specified moniker is running, and if it is, retrieves a pointer to that object. This method looks for the moniker in the Running Object Table (ROT), and retrieves the pointer registered there.

Parameters:

	pmkObjectName	Pointer to the moniker of the object
	ppunkObject	Address of output variable that receives the IUnknown interface pointer

Returns:: An HRESULT indicating success or failure

References comstl__Rot_GetObject.

HRESULT comstl::Rot_GetTimeOfLastChange	(	LPMONIKER	pmkObjectName,
		FILETIME *	lpfiletime
	)			`[inline]`

Retrieves the last modification time of an object in the Running Object Table.

Returns the time that an object was last modified. The object must have previously been registered with the Running Object Table (ROT). This method looks for the last change time recorded in the ROT.

Parameters:

	pmkObjectName	Pointer to moniker on the object whose status is desired
	lpfiletime	Pointer to structure containing object's last change time

Returns:: An HRESULT indicating success or failure

References comstl__Rot_GetTimeOfLastChange.

HRESULT comstl::Rot_IsRunning ( LPMONIKER pmkObjectName ) [inline]

Determines if object current in the Running Object Table.

Determines whether the object identified by the specified moniker is currently running. This method looks for the moniker in the Running Object Table (ROT).

Parameters:

pmkObjectName

Pointer to the moniker of the object whose status is desired

Returns:: An HRESULT indicating success or failure

References comstl__Rot_IsRunning.

HRESULT comstl::Rot_NoteChangeTime	(	DWORD	dwRegister,
		FILETIME *	lpfiletime
	)			`[inline]`

Retrieves the last modification time of a running object in the Running Object Table.

Records the time that a running object was last modified. The object must have previously been registered with the Running Object Table (ROT). This method stores the time of last change in the ROT.

Parameters:

	dwRegister	Value identifying registration being updated
	lpfiletime	Pointer to structure containing object's last change time

Returns:: An HRESULT indicating success or failure

References comstl__Rot_NoteChangeTime.

HRESULT comstl::Rot_Register	(	DWORD	grfFlags,
		LPUNKNOWN	punkObject,
		LPMONIKER	pmkObjectName,
		DWORD *	pdwRegister
	)			`[inline]`

Registers an object in the Running Object Table.

Registers an object and its identifying moniker in the Running Object Table (ROT).

Parameters:

	grfFlags	Registration options
	punkObject	Pointer to the object being registered
	pmkObjectName	Pointer to the moniker of the object being registered
	pdwRegister	Pointer to the value identifying the registration

Returns:: An HRESULT indicating success or failure

References comstl__Rot_Register.

HRESULT comstl::Rot_Revoke ( DWORD dwRegister ) [inline]

Removes an object from the Running Object Table.

Removes from the Running Object Table (ROT) an entry that was previously registered by a call to Rot_Register().

Parameters:

dwRegister

Value identifying registration to be revoked

Returns:: An HRESULT indicating success or failure

References comstl__Rot_Revoke.

void comstl::safe_addref ( LPUNKNOWN punk ) [inline]

Adds a reference on the interface pointer.

Parameters:

punk

The interface pointer on which to add the reference. Can be null

References comstl__safe_addref().

Referenced by interface_addref::operator()().

void comstl::safe_release ( LPUNKNOWN punk ) [inline]

Releases a reference on the interface pointer.

Parameters:

punk

The interface pointer on which to release the reference. Can be null

References comstl__safe_release().

Referenced by interface_release::operator()().

bool comstl::VARIANT_equal	(	VARIANT const &	lhs,
		VARIANT const &	rhs,
		HRESULT *	comparisonSucceeded
	)			`[inline]`

[C++ only] Indicates whether two VARIANT structures are equal

Parameters:

	lhs	Reference to the left-hand instances to compare
	lhs	Reference to the right-hand instances to compare
	comparisonSucceeded	Pointer to a result-code instance that will have an HRESULT value not equal to S_OK if the comparison cannot be made. May be NULL if the caller does not care

Returns:: a value indicating whether the values are equal

Return values:

	0	The structures are not equal
	>0	The structures are equal

References comstl__VARIANT_equal().

bool comstl::VARIANT_equal	(	VARIANT const *	lhs,
		VARIANT const *	rhs,
		HRESULT *	comparisonSucceeded
	)			`[inline]`

[C++ only] Indicates whether two VARIANT structures are equal

Parameters:

	lhs	Pointer to the left-hand instances to compare
	lhs	Pointer to the right-hand instances to compare
	comparisonSucceeded	Pointer to a result-code instance that will have an HRESULT value not equal to S_OK if the comparison cannot be made. May be NULL if the caller does not care

Returns:: a value indicating whether the values are equal

Return values:

	0	The structures are not equal
	>0	The structures are equal

Precondition:: lhs must not be NULL.
rhs must not be NULL.

References comstl__VARIANT_equal().


Classes
class	bstr
	Facade for the COM BSTR type. More...
class	guid
	Facade for the COM GUID type. More...
class	initialiser
	Initialises the COM libraries. More...
struct	CoInitialize_policy
	A policy type, for use with comstl::initialiser, that causes initialisation/uninitialisation of the COM libraries with `CoInitialize()`/`CoInitializeEx()` and `CoUninitialize()`. More...
struct	OleInitialize_policy
	A policy type, for use with comstl::initialiser, that causes initialisation/uninitialisation of the COM libraries with `OleInitialize()` and `OleUninitialize()`. More...
struct	IID_traits
	Interface identifier traits. More...
struct	GUID_policy
	Value policy for GUID. More...
struct	BSTR_policy
	Value policy for BSTR. More...
struct	LPOLESTR_policy
	Value policy for LPOLESTR. More...
struct	VARIANT_policy
	Value policy for VARIANT. More...
struct	interface_policy
	Value policy for interface. More...
struct	LPUNKNOWN_policy
	Value policy for LPUNKNOWN. More...
struct	STATSTG_policy
	Value policy for STATSTG. More...
struct	FORMATETC_policy
	Value policy for FORMATETC. More...
class	variant
	Facade for the COM VARIANT type. More...
Typedefs
typedef initialiser < CoInitialize_policy, ignore_initialisation_exception_policy >	com_init_nothrow
	Specialisation of comstl::initialiser that initialises via CoInitialize() but does not throw on failure.
typedef initialiser < OleInitialize_policy, ignore_initialisation_exception_policy >	ole_init_nothrow
	Specialisation of comstl::initialiser that initialises via OleInitialize() but does not throw on failure.
typedef initialiser < CoInitialize_policy, com_initialisation_exception_policy >	com_init
	Specialisation of comstl::initialiser that initialises via CoInitialize() and throws on failure.
typedef initialiser < OleInitialize_policy, com_initialisation_exception_policy >	ole_init
	Specialisation of comstl::initialiser that initialises via OleInitialize() and throws on failure.
typedef com_init_nothrow	com_initialiser
	[DEPRECATED] Specialisation of comstl::initialiser that initialises via CoInitialize() but does not throw on failure.
typedef ole_init_nothrow	ole_initialiser
	[DEPRECATED] Specialisation of comstl::initialiser that initialises via OleInitialize() but does not throw on failure.
typedef com_initialiser	com_initializer
	Equivalent to com_initialiser.
typedef ole_initialiser	ole_initializer
	Equivalent to ole_initialiser.
Functions
template<typename I>
HRESULT	co_create_instance (REFCLSID clsid, I **ppi, DWORD dwClsContext=CLSCTX_ALL)
	Type-safe creation of a COM object, acquiring the requisite interface pointer.
template<typename I>
HRESULT	co_create_instance (LPCOLESTR id, I **ppi, DWORD dwClsContext=CLSCTX_ALL)
	Type-safe creation of a COM object from a Programmatic Id, acquiring the requisite interface pointer.
template<typename T, typename I, typename U>
HRESULT	co_create_instance (REFCLSID clsid, stlsoft::ref_ptr< T, I, U > &wi, DWORD dwClsContext=CLSCTX_ALL)
	Type-safe creation of a COM object, acquiring the requisite interface pointer into an interface wrapper instance.
template<typename T, typename I, typename U>
HRESULT	co_create_instance (LPCOLESTR id, stlsoft::ref_ptr< T, I, U > &wi, DWORD dwClsContext=CLSCTX_ALL)
	Type-safe creation of a COM object from a Programmatic Id, acquiring the requisite interface wrapper instance.
STLSOFT_INLINE int	comstl__CY_compare (CY const lhs, CY const rhs)
	[C only] Compares two CY structures
int	CY_compare (CY const lhs, CY const rhs)
	[C++ only] Compares two CY structures
int	CY_compare (CY const &lhs, CY const &rhs)
	[C++ only] Compares two CY structures
STLSOFT_INLINE int	comstl__DECIMAL_compare (DECIMAL const lhs, DECIMAL const rhs)
	[C only] Compares two DECIMAL structures
int	DECIMAL_compare (DECIMAL const lhs, DECIMAL const rhs)
	[C++ only] Compares two DECIMAL structures
int	DECIMAL_compare (DECIMAL const &lhs, DECIMAL const &rhs)
	[C++ only] Compares two DECIMAL structures
STLSOFT_INLINE void	comstl__addref (LPUNKNOWN punk)
	[C only] Adds a reference on the interface pointer
STLSOFT_INLINE void	comstl__release (LPUNKNOWN punk)
	[C only] Releases a reference on the interface pointer
STLSOFT_INLINE void	comstl__safe_addref (LPUNKNOWN punk)
	[C only] Adds a reference on the interface pointer
STLSOFT_INLINE void	comstl__safe_release (LPUNKNOWN punk)
	[C only] Releases a reference on the interface pointer
void	addref (LPUNKNOWN punk)
	Adds a reference on the interface pointer.
void	release (LPUNKNOWN punk)
	Releases a reference on the interface pointer.
void	safe_addref (LPUNKNOWN punk)
	Adds a reference on the interface pointer.
void	safe_release (LPUNKNOWN punk)
	Releases a reference on the interface pointer.
template<typename T>
void	release_set_null (T *&pt)
	Releases a reference on the interface pointer, and resets the pointer.
STLSOFT_INLINE HRESULT	comstl_C_Rot_Register (DWORD grfFlags, LPUNKNOWN punkObject, LPMONIKER pmkObjectName, DWORD *pdwRegister)
	[C only] Registers an object in the Running Object Table
STLSOFT_INLINE HRESULT	comstl_C_Rot_Revoke (DWORD dwRegister)
	[C only] Removes an object from the Running Object Table
STLSOFT_INLINE HRESULT	comstl_C_Rot_IsRunning (LPMONIKER pmkObjectName)
	[C only] Determines if object current in the Running Object Table
STLSOFT_INLINE HRESULT	comstl_C_Rot_GetObject (LPMONIKER pmkObjectName, LPUNKNOWN *ppunkObject)
	[C only] Retrieves the object from the Running Object Table
STLSOFT_INLINE HRESULT	comstl_C_Rot_NoteChangeTime (DWORD dwRegister, FILETIME *lpfiletime)
	[C only] Retrieves the last modification time of a running object in the Running Object Table
STLSOFT_INLINE HRESULT	comstl_C_Rot_GetTimeOfLastChange (LPMONIKER pmkObjectName, FILETIME *lpfiletime)
	[C only] Retrieves the last modification time of an object in the Running Object Table
STLSOFT_INLINE HRESULT	comstl_C_Rot_EnumRunning (IEnumMoniker **ppenumMoniker)
	[C only] Queries the current set of objects in the Running Object Table
HRESULT	Rot_Register (DWORD grfFlags, LPUNKNOWN punkObject, LPMONIKER pmkObjectName, DWORD *pdwRegister)
	Registers an object in the Running Object Table.
HRESULT	Rot_Revoke (DWORD dwRegister)
	Removes an object from the Running Object Table.
HRESULT	Rot_IsRunning (LPMONIKER pmkObjectName)
	Determines if object current in the Running Object Table.
HRESULT	Rot_GetObject (LPMONIKER pmkObjectName, LPUNKNOWN *ppunkObject)
	Retrieves the object from the Running Object Table.
HRESULT	Rot_NoteChangeTime (DWORD dwRegister, FILETIME *lpfiletime)
	Retrieves the last modification time of a running object in the Running Object Table.
HRESULT	Rot_GetTimeOfLastChange (LPMONIKER pmkObjectName, FILETIME *lpfiletime)
	Retrieves the last modification time of an object in the Running Object Table.
HRESULT	Rot_EnumRunning (IEnumMoniker **ppenumMoniker)
	Queries the current set of objects in the Running Object Table.
STLSOFT_INLINE HRESULT	comstl__get_stream_size (LPSTREAM pstm, ULARGE_INTEGER *psize)
	[C only] Gets the size of a stream
HRESULT	get_stream_size (LPSTREAM pstm, ULARGE_INTEGER *psize)
	Gets the size of a stream.
HRESULT	get_stream_size (LPSTREAM pstm, ULARGE_INTEGER &size)
	Gets the size of a stream.
HRESULT	get_stream_size (LPSTREAM pstm, cs_uint64_t &size)
	Gets the size of a stream.
template<typename I>
HRESULT	MarshalInterThreadInterfaceInStream (I pitf, LPSTREAM ppstm)
	Marshal a interface to a stream.
template<typename I>
HRESULT	GetInterfaceAndReleaseStream (LPSTREAM pstm, I **ppitf)
	Retrieve a marshaled interface pointer from a stream.
STLSOFT_INLINE int	comstl__VARIANT_equal (VARIANT const lhs, VARIANT const rhs, HRESULT *comparisonSucceeded)
	[C only] Indicates whether two VARIANT structures are equal
bool	VARIANT_equal (VARIANT const lhs, VARIANT const rhs, HRESULT *comparisonSucceeded)
	[C++ only] Indicates whether two VARIANT structures are equal
bool	VARIANT_equal (VARIANT const &lhs, VARIANT const &rhs, HRESULT *comparisonSucceeded)
	[C++ only] Indicates whether two VARIANT structures are equal

COM Utility Library [Utility Library, COMSTL]

Detailed Description

Classes

Typedefs

Functions

Typedef Documentation

Function Documentation

COM Utility Library
[Utility Library, COMSTL]