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