class CComModule : public _ATL_MODULE
CComModule implements a COM server module, thus allowing a client to access the module's components. CComModule supports both DLL (in-process) and EXE (local) modules.
A CComModule instance uses an object map to maintain a set of class object definitions. This object map is implemented as an array of _ATL_OBJMAP_ENTRY structures, and contains information for:
When you run the ATL COM AppWizard, the wizard automatically generates _Module, a global instance of CComModule or a class derived from it. For more information about the ATL COM AppWizard, see the article Creating an ATL Project.
In addition to CComModule, ATL provides CComAutoThreadModule, which implements an apartment-model module for EXEs and Windows NT services. Derive your module from CComAutoThreadModule when you want to create objects in multiple apartments.
#include <atlbase.h>
Methods | |
GetClassObject | Creates an object of a specified CLSID. For DLLs only. |
GetLockCount | Returns the current lock count on the module. |
GetModuleInstance | Returns m_hInst. |
GetResourceInstance | Returns m_hInstResource. |
GetTypeLibInstance | Returns m_hInstTypeLib. |
Init | Initializes data members. |
Lock | Increments the module lock count. |
RegisterClassHelper | Enters an object's standard class registration in the system registry. |
RegisterClassObjects | Registers the class factory in the Running Object Table. For EXEs only. |
RegisterServer | Updates the system registry for each object in the object map. |
RegisterTypeLib | Registers a type library. |
RevokeClassObjects | Removes the class factory from the Running Object Table. For EXEs only. |
Term | Releases data members. |
Unlock | Decrements the module lock count. |
UnregisterClassHelper | Removes an object's standard class registration from the system registry. |
UnregisterServer | Unregisters each object in the object map. |
UpdateRegistryClass | Registers or unregisters an object's standard class registration.. |
UpdateRegistryFromResourceD | Runs the script contained in a specified resource to register or unregister an object. |
UpdateRegistryFromResourceS | Statically links to the ATL Registry Component. Runs the script contained in a specified resource to register or unregister an object. |
Data Members | |
m_csObjMap | Ensures synchronized access to the object map information. |
m_csTypeInfoHolder | Ensures synchronized access to the type library information. |
m_csWindowCreate | Ensures synchronized access to window class information and to static data used during window creation. |
m_hHeap | Contains the handle to the heap managed by the module. |
m_hInst | Contains the handle to the module instance. |
m_hInstResource | By default, contains the handle to the module instance. |
m_hInstTypeLib | By default, contains the handle to the module instance. |
m_nLockCnt | Contains the current lock count on the module. |
m_pObjMap | Points to the object map maintained by the module instance. |
HRESULT GetClassObject( REFCLSID rclsid, REFIID riid, LPVOID* ppv );
Return Value
A standard HRESULT value.
Parameters
rclsid [in] The CLSID of the object to be created.
riid [in] The IID of the requested interface.
ppv [out] A pointer to the interface pointer identified by riid. If the object does not support this interface, ppv is set to NULL.
Remarks
Creates an object of the specified CLSID and retrieves an interface pointer to this object.
Note GetClassObject is only available to DLLs.
CComModule Overview | Class Members
LONG GetLockCount( );
Return Value
The lock count on the module.
Remarks
Returns the current lock count on the module. CComModule uses the lock count to determine whether any clients are accessing the module. When the lock count reaches zero, the module can be unloaded.
CComModule Overview | Class Members
See Also CComModule::Lock, CComModule::Unlock, CComModule::m_nLockCnt
HINSTANCE GetModuleInstance( );
Return Value
The HINSTANCE identifying this module.
Remarks
Returns the m_hInst data member.
CComModule Overview | Class Members
See Also CComModule::GetResourceInstance, CComModule::GetTypeLibInstance
HINSTANCE GetResourceInstance( );
Return Value
An HINSTANCE.
Remarks
Returns the m_hInstResource data member.
CComModule Overview | Class Members
See Also CComModule::GetModuleInstance, CComModule::GetTypeLibInstance
HINSTANCE GetTypeLibInstance( );
Return Value
An HINSTANCE.
Remarks
Returns the m_hInstTypeLib data member.
CComModule Overview | Class Members
See Also CComModule::GetModuleInstance, CComModule::GetResourceInstance
void Init( _ATL_OBJMAP_ENTRY* p, HINSTANCE h );
Parameters
p [in] A pointer to an array of object map entries.
h [in] The HINSTANCE passed to DLLMain or WinMain.
Remarks
Initializes all data members.
CComModule Overview | Class Members
See Also CComModule::Term
LONG Lock( );
Return Value
A value that may be useful for diagnostics or testing.
Remarks
Performs an atomic increment on the module's lock count. CComModule uses the lock count to determine whether any clients are accessing the module.
CComModule Overview | Class Members
See Also CComModule::Unlock, CComModule::GetLockCount, CComModule::m_nLockCnt
HRESULT RegisterClassHelper( const CLSID& clsid, LPCTSTR lpszProgID, LPCTSTR lpszVerIndProgID, UINT nDescID, DWORD dwFlags );
Return Value
A standard HRESULT value.
Parameters
clsid [in] The CLSID of the object to be registered.
lpszProgID [in] The ProgID associated with the object.
lpszVerIndProgID [in] The version-independent ProgID associated with the object.
nDescID [in] The identifier of the string resource for the object's description.
dwFlags [in] Specifies the threading model to enter in the registry. Possible values are THREADFLAGS_APARTMENT, THREADFLAGS_BOTH, or AUTPRXFLAG.
Remarks
Enters an object's standard class registration in the system registry. The UpdateRegistryClass method calls RegisterClassHelper.
CComModule Overview | Class Members
See Also CComModule::UnregisterClassHelper
HRESULT RegisterClassObjects( DWORD dwClsContext, DWORD dwFlags );
Return Value
A standard HRESULT value.
Parameters
dwClsContext [in] Specifies the context in which the class object is to be run. Possible values are CLSCTX_INPROC_SERVER, CLSCTX_INPROC_HANDLER, or CLSCTX_LOCAL_SERVER. For a description of these values, see CLSCTX in the Win32 SDK.
dwFlags [in] Determines the connection types to the class object. Possible values are REGCLS_SINGLEUSE, REGCLS_MULTIPLEUSE, or REGCLS_MULTI_SEPARATE. For a description of these values, see REGCLS in the Win32 SDK.
Remarks
Registers the class factory in the Running Object Table.
Note RegisterClassObjects is only available to EXEs.
CComModule Overview | Class Members
See Also CComModule::RevokeClassObjects
HRESULT RegisterServer( BOOL bRegTypeLib = FALSE, const CLSID* pCLSID = NULL );
Return Value
A standard HRESULT value.
Parameters
bRegTypeLib [in] Indicates whether the type library will be registered.
pCLSID [in] Points to the CLSID of the object to be registered. If NULL (the default value), all objects in the object map will be registered.
Remarks
Depending on the pCLSID parameter, updates the system registry for a single class object or for all objects in the object map. If bRegTypeLib is TRUE, the type library information will also be updated.
The BEGIN_OBJECT_MAP macro starts your object map definition.
RegisterServer will be called automatically by DLLRegisterServer for a DLL or by WinMain for an EXE run with the /RegServer command line option.
CComModule Overview | Class Members
See Also CComModule::UnregisterServer
HRESULT RegisterTypeLib( );
HRESULT RegisterTypeLib( LPCTSTR lpszIndex );
Return Value
A standard HRESULT value.
Parameters
lpszIndex [in] Specifies the name of a type library resource.
Remarks
Adds information about a type library to the system registry. If the module instance contains multiple type libraries, use the second version of this method to specify which type library should be used.
CComModule Overview | Class Members
HRESULT RevokeClassObjects( );
Return Value
A standard HRESULT value.
Remarks
Removes the class factory from the Running Object Table.
Note RevokeClassObjects is only available to EXEs.
CComModule Overview | Class Members
See Also CComModule::RegisterClassObjects
void Term( );
Remarks
Releases all data members.
CComModule Overview | Class Members
See Also CComModule::Init
LONG Unlock( );
Return Value
A value that may be useful for diagnostics or testing.
Remarks
Performs an atomic decrement on the module's lock count. CComModule uses the lock count to determine whether any clients are accessing the module. When the lock count reaches zero, the module can be unloaded.
CComModule Overview | Class Members
See Also CComModule::Lock, CComModule::GetLockCount, CComModule::m_nLockCnt
HRESULT UnregisterClassHelper( const CLSID& clsid, LPCTSTR lpszProgID, LPCTSTR lpszVerIndProgID );
Return Value
A standard HRESULT value.
Parameters
clsid [in] The CLSID of the object to be unregistered.
lpszProgID [in] The ProgID associated with the object.
lpszVerIndProgID [in] The version-independent ProgID associated with the object.
Remarks
Removes an objects standard class registration from the system registry. The UpdateRegistryClass method calls UnregisterClassHelper.
CComModule Overview | Class Members
See Also CComModule::RegisterClassHelper
HRESULT UnregisterServer( const CLSID* pCLSID = NULL );
Return Value
A standard HRESULT value.
Parameters
pCLSID [in] Points to the CLSID of the object to be unregistered. If NULL (the default value), all objects in the object map will be unegistered.
Remarks
Depending on the pCLSID parameter, unregisters either a single class object or all objects in the object map. The BEGIN_OBJECT_MAP macro starts your object map definition.
UnregisterServer will be called automatically by DLLUnregisterServer for a DLL or by WinMain for an EXE run with the /UnregServer command line option.
CComModule Overview | Class Members
See Also CComModule::RegisterServer
HRESULT UpdateRegistryClass( const CLSID& clsid, LPCTSTR lpszProgID, LPCTSTR lpszVerIndProgID, UINT nDescID, DWORD dwFlags, BOOL bRegister );
Return Value
A standard HRESULT value.
Parameters
clsid [in] The CLSID of the object to be registered or unregistered.
lpszProgID [in] The ProgID associated with the object.
lpszVerIndProgID [in] The version-independent ProgID associated with the object.
nDescID [in] The identifier of the string resource for the object's description.
dwFlags [in] Specifies the threading model to enter in the registry. Possible values are THREADFLAGS_APARTMENT, THREADFLAGS_BOTH, or AUTPRXFLAG.
bRegister [in] Indicates whether the object should be registered.
Remarks
If bRegister is TRUE, this method enters the objects standard class registration in the system registry. If bRegister is FALSE, it removes the objects registration.
Depending on the value of bRegister, UpdateRegistryClass calls either RegisterClassHelper or UnregisterClassHelper.
By specifying the DECLARE_REGISTRY macro, UpdateRegistryClass will be invoked automatically when your object map is processed.
CComModule Overview | Class Members
HRESULT UpdateRegistryFromResourceD( LPCTSTR lpszRes, BOOL bRegister, struct _ATL_REGMAP_ENTRY* pMapEntries = NULL );
HRESULT UpdateRegistryFromResourceD( UINT nResID, BOOL bRegister, struct _ATL_REGMAP_ENTRY* pMapEntries = NULL );
Return Value
A standard HRESULT value.
Parameters
lpszRes [in] A resource name.
nResID [in] A resource ID.
bRegister [in] Indicates whether the resource script should be registered.
pMapEntries [in] 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 Remarks for details. Otherwise, use the NULL default value.
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 unregisters the object.
By specifying the DECLARE_REGISTRY_RESOURCE or DECLARE_REGISTRY_RESOURCEID macro, UpdateRegistryFromResourceD will be invoked automatically when your object map is processed.
Note To substitute replacement values at run time, do not specify the DECLARE_REGISTRY_RESOURCE or DECLARE_REGISTRY_RESOURCEID macro. Instead, create an array of _ATL_REGMAP_ENTRIES structures, where each entry contains a variable placeholder paired with a value to replace the placeholder at run time. Then call UpdateRegistryFromResourceD, passing the array for the pMapEntries parameter. This adds all the replacement values in the _ATL_REGMAP_ENTRIES structures to the Registrars replacement map.
Note To statically link to the ATL Registry Component (Registrar), see UpdateRegistryFromResourceS.
For more information about replaceable parameters and scripting, see the article The ATL Registry Component (Registrar).
CComModule Overview | Class Members
See Also BEGIN_OBJECT_MAP
HRESULT UpdateRegistryFromResourceS( LPCTSTR lpszRes, BOOL bRegister, struct _ATL_REGMAP_ENTRY* pMapEntries = NULL );
HRESULT UpdateRegistryFromResourceS( UINT nResID, BOOL bRegister, struct _ATL_REGMAP_ENTRY* pMapEntries = NULL );
Return Value
A standard HRESULT value.
Parameters
lpszRes [in] A resource name.
nResID [in] A resource ID.
bRegister [in] Indicates whether the resource script should be registered.
pMapEntries [in] 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 Remarks for details. Otherwise, use the NULL default value.
Remarks
Similar to UpdateRegistryFromResourceD except UpdateRegistryFromResourceS creates a static link to the ATL Registry Component (Registrar).
UpdateRegistryFromResourceS will be invoked automatically when your object map is processed, provided you and #define _ATL_STATIC_REGISTRY to your stdafx.h.
Note To substitute replacement values at run time, do not specify the DECLARE_REGISTRY_RESOURCE or DECLARE_REGISTRY_RESOURCEID macro. Instead, create an array of _ATL_REGMAP_ENTRIES structures, where each entry contains a variable placeholder paired with a value to replace the placeholder at run time. Then call UpdateRegistryFromResourceS, passing the array for the pMapEntries parameter. This adds all the replacement values in the _ATL_REGMAP_ENTRIES structures to the Registrars replacement map.
For more information about replaceable parameters and scripting, see the article The ATL Registry Component (Registrar).
CComModule Overview | Class Members
See Also BEGIN_OBJECT_MAP
CRITICAL_SECTION m_csObjMap;
Remarks
Ensures synchronized access to the object map.
CComModule Overview | Class Members
CRITICAL_SECTION m_csTypeInfoHolder;
Remarks
Ensures synchronized access to the type library.
CComModule Overview | Class Members
CRITICAL_SECTION m_csWindowCreate;
Remarks
Ensures synchronized access to window class information and to static data used during window creation.
CComModule Overview | Class Members
HANDLE m_hHeap;
Remarks
Contains a handle to the heap managed by the module.
CComModule Overview | Class Members
HINSTANCE m_hInst;
Remarks
Contains a handle to the module instance. The Init method sets m_hInst to the handle passed to DLLMain or WinMain.
CComModule Overview | Class Members
HINSTANCE m_hInstResource;
Remarks
By default, contains a handle to the module instance. The Init method sets m_hInstResource to the handle passed to DLLMain or WinMain. You can explicitly set m_hInstResource to the handle to a resource.
The GetResourceInstance method returns the handle stored in m_hInstResource.
CComModule Overview | Class Members
HINSTANCE m_hInstTypeLib;
Remarks
By default, contains a handle to the module instance. The Init method sets m_hInstTypLib to the handle passed to DLLMain or WinMain. You can explicitly set m_hInstTypeLib to the handle to a type library.
The GetTypeLibInstance method returns the handle stored in m_hInstTypeLib.
CComModule Overview | Class Members
LONG m_nLockCnt;
Remarks
Contains the current lock count on the module. CComModule uses the lock count to determine whether any clients are accessing the module. When the lock count reached zero, the module can be unloaded.
CComModule Overview | Class Members
See Also CComModule::GetLockCount, CComModule::Lock, CComModule::Unlock
_ATL_OBJMAP_ENTRY* m_pObjMap;
Remarks
Points to the object map maintained by the module instance.