CAtlModule Class

 

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.

class ATL_NO_VTABLE CAtlModule : public _ATL_MODULE

Public Constructors

NameDescription
CAtlModule::CAtlModuleThe constructor.
CAtlModule::~CAtlModuleThe destructor.

Public Methods

NameDescription
CAtlModule::AddCommonRGSReplacementsOverride this method to add parameters to the ATL Registry Component (Registrar) replacement map.
CAtlModule::AddTermFuncAdds a new function to be called when the module terminates.
CAtlModule::GetGITPtrReturns the Global Interface Pointer.
CAtlModule::GetLockCountReturns the lock count.
CAtlModule::LockIncrements the lock count.
CAtlModule::TermReleases all data members.
CAtlModule::UnlockDecrements the lock count.
CAtlModule::UpdateRegistryFromResourceDRuns the script contained in a specified resource to register or unregister an object.
CAtlModule::UpdateRegistryFromResourceDHelperThis method is called by UpdateRegistryFromResourceD to perform the registry update.
CAtlModule::UpdateRegistryFromResourceSRuns 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

NameDescription
CAtlModule::m_libidContains the GUID of the current module.
CAtlModule::m_pGITPointer to the Global Interface Table.

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.

_ATL_MODULE

CAtlModule

Header: atlbase.h

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.

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.

The constructor.

CAtlModule() throw();

Remarks

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

The destructor.

~CAtlModule() throw();

Remarks

Releases all data members.

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.

Returns the lock count.

virtual LONG GetLockCount() throw();

Return Value

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

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.

Contains the GUID of the current module.

static GUID m_libid;

Pointer to the Global Interface Table.

IGlobalInterfaceTable* m_pGIT;

Releases all data members.

void Term() throw();

Remarks

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

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.

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.

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.

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).

_ATL_MODULE
Class Overview
Module Classes
Registry Component (Registrar)

Show: