Share via

CAtlModule Class

  • Article

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at CAtlModule Class.

This class provides methods used by several ATL module classes.

Syntax

class ATL_NO_VTABLE CAtlModule : public _ATL_MODULE

Members

Public Constructors

Name Description
CAtlModule::CAtlModule The constructor.
CAtlModule::~CAtlModule The destructor.

Public Methods

Name Description
CAtlModule::AddCommonRGSReplacements Override this method to add parameters to the ATL Registry Component (Registrar) replacement map.
CAtlModule::AddTermFunc Adds a new function to be called when the module terminates.
CAtlModule::GetGITPtr Returns the Global Interface Pointer.
CAtlModule::GetLockCount Returns the lock count.
CAtlModule::Lock Increments the lock count.
CAtlModule::Term Releases all data members.
CAtlModule::Unlock Decrements the lock count.
CAtlModule::UpdateRegistryFromResourceD Runs the script contained in a specified resource to register or unregister an object.
CAtlModule::UpdateRegistryFromResourceDHelper This method is called by UpdateRegistryFromResourceD to perform the registry update.
CAtlModule::UpdateRegistryFromResourceS Runs the script contained in a specified resource to register or unregister an object. This method statically links to the ATL Registry Component.

Public Data Members

Name Description
CAtlModule::m_libid Contains the GUID of the current module.
CAtlModule::m_pGIT Pointer to the Global Interface Table.

Remarks

This class is used by CAtlDllModuleT Class, CAtlExeModuleT Class, and CAtlServiceModuleT Class to provide support for DLL applications, EXE applications, and Windows services, respectively.

For more information on modules in ATL, see ATL Module Classes.

This class replaces the obsolete CComModule Class used in earlier versions of ATL.

Inheritance Hierarchy

_ATL_MODULE

CAtlModule

Requirements

Header: atlbase.h

CAtlModule::AddCommonRGSReplacements

Override this method to add parameters to the ATL Registry Component (Registrar) replacement map.

virtual HRESULT AddCommonRGSReplacements(IRegistrarBase* /* pRegistrar*/) throw() = 0;

Parameters

pRegistrar
Reserved.

Return Value

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

Remarks

Replaceable parameters allow a Registrar's client to specify run-time data. To do this, the Registrar maintains a replacement map into which it enters the values associated with the replaceable parameters in your script. The Registrar makes these entries at run time.

See the topic Using Replaceable Parameters (The Registrar's Preprocessor) for more details.

CAtlModule::AddTermFunc

Adds a new function to be called when the module terminates.

HRESULT AddTermFunc(_ATL_TERMFUNC* pFunc, DWORD_PTR dw) throw();

Parameters

pFunc
Pointer to the function to add.

dw
User-defined data, passed to the function.

Return Value

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

CAtlModule::CAtlModule

The constructor.

CAtlModule() throw();

Remarks

Initializes data members and initiates a critical section around the module's thread.

CAtlModule::~CAtlModule

The destructor.

~CAtlModule() throw();

Remarks

Releases all data members.

CAtlModule::GetGITPtr

Retrieves a pointer to the Global Interface Table.

virtual HRESULT GetGITPtr(IGlobalInterfaceTable** ppGIT) throw();

Parameters

ppGIT
Pointer to the variable which will receive the pointer to the Global Interface Table.

Return Value

Returns S_OK on success, or an error code on failure. E_POINTER is returned if ppGIT is equal to NULL.

Remarks

If the Global Interface Table object does not exist, it is created, and its address is stored in the member variable CAtlModule::m_pGIT.

In debug builds, an assertion error will occur if ppGIT is equal to NULL, or if the Global Interface Table pointer cannot be obtained.

See IGlobalInterfaceTable for information on the Global Interface Table.

CAtlModule::GetLockCount

Returns the lock count.

virtual LONG GetLockCount() throw();

Return Value

Returns the lock count. This value may be useful for diagnostics and debugging.

CAtlModule::Lock

Increments the lock count.

virtual LONG Lock() throw();

Return Value

Increments the lock count and returns the updated value. This value may be useful for diagnostics and debugging.

CAtlModule::m_libid

Contains the GUID of the current module.

static GUID m_libid;

CAtlModule::m_pGIT

Pointer to the Global Interface Table.

IGlobalInterfaceTable* m_pGIT;

CAtlModule::Term

Releases all data members.

void Term() throw();

Remarks

Releases all data members. This method is called by the destructor.

CAtlModule::Unlock

Decrements the lock count.

virtual LONG Unlock() throw();

Return Value

Decrements the lock count and returns the updated value. This value may be useful for diagnostics and debugging.

CAtlModule::UpdateRegistryFromResourceD

Runs the script contained in a specified resource to register or unregister an object.

HRESULT WINAPI UpdateRegistryFromResourceD(
    UINT nResID,
    BOOL bRegister,
    struct _ATL_REGMAP_ENTRY* pMapEntries = NULL) throw();

HRESULT WINAPI UpdateRegistryFromResourceD(  
    LPCTSTR lpszRes,
    BOOL bRegister,
    struct _ATL_REGMAP_ENTRY* pMapEntries = NULL) throw();

Parameters

lpszRes
A resource name.

nResID
A resource ID.

bRegister
TRUE if the object should be registered; FALSE otherwise.

pMapEntries
A pointer to the replacement map storing values associated with the script's replaceable parameters. ATL automatically uses %MODULE%. To use additional replaceable parameters, see CAtlModule::AddCommonRGSReplacements. Otherwise, use the NULL default value.

Return Value

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

Remarks

Runs the script contained in the resource specified by lpszRes or nResID. If bRegister is TRUE, this method registers the object in the system registry; otherwise it removes the object from the registry.

To statically link to the ATL Registry Component (Registrar), see CAtlModule::UpdateRegistryFromResourceS.

This method calls CAtlModule::UpdateRegistryFromResourceDHelper.

CAtlModule::UpdateRegistryFromResourceDHelper

This method is called by UpdateRegistryFromResourceD to perform the registry update.

inline HRESULT WINAPI UpdateRegistryFromResourceDHelper(  
    LPCOLESTR lpszRes,
    BOOL bRegister,
    struct _ATL_REGMAP_ENTRY* pMapEntries = NULL) throw();

Parameters

lpszRes
A resource name.

bRegister
Indicates whether the object should be registered.

pMapEntries
A pointer to the replacement map storing values associated with the script's replaceable parameters. ATL automatically uses %MODULE%. To use additional replaceable parameters, see CAtlModule::AddCommonRGSReplacements. Otherwise, use the NULL default value.

Return Value

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

Remarks

This method provides the implementation of CAtlModule::UpdateRegistryFromResourceD.

CAtlModule::UpdateRegistryFromResourceS

Runs the script contained in a specified resource to register or unregister an object. This method statically links to the ATL Registry Component.

HRESULT WINAPI UpdateRegistryFromResourceS(  
    UINT nResID,
    BOOL bRegister,
    struct _ATL_REGMAP_ENTRY* pMapEntries = NULL) throw();

HRESULT WINAPI UpdateRegistryFromResourceS(  
    LPCTSTR lpszRes,
    BOOL bRegister,
    struct _ATL_REGMAP_ENTRY* pMapEntries = NULL) throw();

Parameters

nResID
A resource ID.

lpszRes
A resource name.

bRegister
Indicates whether the resource script should be registered.

pMapEntries
A pointer to the replacement map storing values associated with the script's replaceable parameters. ATL automatically uses %MODULE%. To use additional replaceable parameters, see CAtlModule::AddCommonRGSReplacements. Otherwise, use the NULL default value.

Return Value

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

Remarks

Similar to CAtlModule::UpdateRegistryFromResourceD except CAtlModule::UpdateRegistryFromResourceS creates a static link to the ATL Registry Component (Registrar).

See Also

_ATL_MODULE
Class Overview
Module Classes
Registry Component (Registrar)