CComGITPtr Class

 

For the latest documentation on Visual Studio 2017, see Visual Studio 2017 Documentation.

This class provides methods for dealing with interface pointers and the global interface table (GIT).

template <class T>  
class CComGITPtr

Parameters

T
The type of the interface pointer to be stored in the GIT.

Public Constructors

NameDescription
CComGITPtr::CComGITPtrThe constructor.
CComGITPtr::~CComGITPtrThe destructor.

Public Methods

NameDescription
CComGITPtr::AttachCall this method to register the interface pointer in the global interface table (GIT).
CComGITPtr::CopyToCall this method to copy the interface from the global interface table (GIT) to the passed pointer.
CComGITPtr::DetachCall this method to disassociate the interface from the CComGITPtr object.
CComGITPtr::GetCookieCall this method to return the cookie from the CComGITPtr object.
CComGITPtr::RevokeCall this method to remove the interface from the global interface table (GIT).

Public Operators

NameDescription
CComGITPtr::operator DWORDReturns the cookie from the CComGITPtr object.
CComGITPtr::operator =Assignment operator.

Public Data Members

NameDescription
CComGITPtr::m_dwCookieThe cookie.

Objects that aggregate the free threaded marshaler and need to use interface pointers obtained from other objects must take extra steps to ensure that the interfaces are correctly marshaled. Typically this involves storing the interface pointers in the GIT and getting the pointer from the GIT each time it is used. The class CComGITPtr is provided to help you use interface pointers stored in the GIT.

System_CAPS_ICON_note.jpg Note

The global interface table facility is only available on Windows 95 with DCOM version 1.1 and later, Windows 98, Windows NT 4.0 with Service Pack 3 and later, and Windows 2000.

Header: atlbase.h

Call this method to register the interface pointer in the global interface table (GIT).

HRESULT Attach(T* p) throw();

HRESULT Attach(DWORD dwCookie) throw();

Parameters

p
The interface pointer to be added to the GIT.

dwCookie
The cookie used to identify the interface pointer.

Return Value

Returns S_OK on success, or an error HRESULT on failure.

Remarks

In debug builds, an assertion error will occur if the GIT is not valid, or if the cookie is equal to NULL.

The constructor.

CComGITPtr() throw();
CComGITPtr(T* p);
CComGITPtr(const CComGITPtr& git);
explicit CComGITPtr(DWORD dwCookie) throw();
CComGITPtr(CComGITPtr&& rv);

Parameters

[in] p
An interface pointer to be stored in the global interface table (GIT).

[in] git
A reference to an existing CComGITPtr object.

[in] dwCookie
A cookie used to identify the interface pointer.

[in] rv
The source CComGITPtr object to move data from.

Remarks

Creates a new CComGITPtr object, optionally using an existing CComGITPtr object.

The constructor utilizing rv is a move constructor. The data is moved from the source, rv, and then rv is cleared.

The destructor.

~CComGITPtr() throw();

Remarks

Removes the interface from the global interface table (GIT), using CComGITPtr::Revoke.

Call this method to copy the interface from the global interface table (GIT) to the passed pointer.

HRESULT CopyTo(T** pp) const throw();

Parameters

pp
The pointer which is to receive the interface.

Return Value

Returns S_OK on success, or an error HRESULT on failure.

Remarks

The interface from the GIT is copied to the passed pointer. The pointer must be released by the caller when it is no longer required.

Call this method to disassociate the interface from the CComGITPtr object.

DWORD Detach() throw();

Return Value

Returns the cookie from the CComGITPtr object.

Remarks

It is up to the caller to remove the interface from the GIT, using CComGITPtr::Revoke.

Call this method to return the cookie from the CComGITPtr object.

DWORD GetCookie() const;

Return Value

Returns the cookie.

Remarks

The cookie is a variable used to identify an interface and its location.

The cookie.

DWORD m_dwCookie;

Remarks

The cookie is a member variable used to identify an interface and its location.

The assignment operator.

CComGITPtr& operator= (T* p);
CComGITPtr& operator= (const CComGITPtr& git);
CComGITPtr& operator= (DWORD dwCookie);
CComGITPtr& operator= (CComGITPtr&& rv);

Parameters

[in] p
A pointer to an interface.

[in] git
A reference to a CComGITPtr object.

[in] dwCookie
A cookie used to identify the interface pointer.

[in] rv
The CComGITPtr to move data from.

Return Value

Returns the updated CComGITPtr object.

Remarks

Assigns a new value to a CComGITPtr object, either from an existing object or from a reference to a global interface table.

Returns the cookie associated with the CComGITPtr object.

operator DWORD() const;

Remarks

The cookie is a variable used to identify an interface and its location.

Call this method to remove the current interface from the global interface table (GIT).

HRESULT Revoke() throw();

Return Value

Returns S_OK on success, or an error HRESULT on failure.

Remarks

Removes the interface from the GIT.

Free Threaded Marshaler
Accessing Interfaces Across Apartments
When to Use the Global Interface Table
Class Overview

Show: