CComModule: Your Server s Housekeeper

ATL EXE servers call the same methods within the scope of _tWinMain(). Regardless of the type of component housing, these methods are used to set the internal state of the global level CComModule object (_Module) and deallocate any acquired resources.

CComModule::Init() takes three parameters: the object map (which is an array of _ATL_OBJMAP_ENTRY structures, hence _ATL_OBJMAP_ENTRY*), the instance of the DLL or EXE module, and the LIBID that defines the classes and interfaces defined in the server. If the LIBID is NULL, ATL assumes the *.tlb defined by your project contains the necessary information:

// Pass in object map, DLL/EXE instance, and LIBID to the CComModule object. HRESULT

Init

( _ATL_OBJMAP_ENTRY* p, // The object map. HINSTANCE h, // Module instance. const GUID* plibid = NULL) // LIBID.

CComModule::Term() takes no parameters, and is called when the server itself (DLL or EXE) is being removed from memory:

// Clean up CComModule instance when server is going down. void

Term

( );

Monitoring Active Locks and Active Objects

CComModule provides a number of methods used to monitor the number of server locks and currently active objects. When we were building in-proc servers by hand, we maintained two global counters for these purposes. When we were building our local server in Chapter 5, we combined these two counters into a single global variable. This is the approach of ATL. All of these locking methods are internally implemented to manipulate the public m_nLockCnt data member. When m_nLockCnt reaches zero, the server has no active objects and no server locks and can therefore be unloaded. Lock() and Unlock() calls are automatically called by the ATL framework; however, you may call them yourself if necessary:

// Active object/lock methods of CComModule. LONG Lock(); // Increments m_nLockCnt. LONG Unlock(); // Decrements m_nLockCnt. LONG GetLockCount(); // Returns current value of m_nLockCnt. LONG m_nLockCnt; // Active objects + server locks.

As we have seen, ATL DLLs make use of GetLockCount() from within the DllCanUnloadNow() export:

// The lock count is represented by m_nLockCnt and obtained via GetLockCount(). STDAPI DllCanUnloadNow(void) { return (_Module.

GetLockCount

()==0) ? S_OK : S_FALSE; }

Registration Duties

Registration of your COM server is also handled by methods of CComModule. Both CComModule::RegisterServer() and CComModule::UnregisterServer() define a defaulted NULL LPCLSID parameter, which informs ATL to enter (or remove) registry information for every coclass contained in the server-wide object map.

ATL allows you to tweak the behavior of the server's (un)registration. If you wish to insert or remove registry information on a more selective coclass-by-coclass basis, set the default NULL LPCLSID parameter to a specific CLSID . Furthermore, the BOOL parameter is used to determine if the type library itself is to be registered as part of the process:

// Enter/remove server information for each entry in the object map. HRESULT

RegisterServer

(BOOL bRegTypeLib = FALSE, CLSID* pCLSID = NULL ); HRESULT

UnregisterServer

(BOOL bUnRegTypeLib, const CLSID* pCLSID = NULL);

For in-proc servers, these methods are called from the DllRegisterServer() and DllUnregisterServer() exports:

// DllRegisterServer - Adds entries to the system registry STDAPI DllRegisterServer(void) { // Registers object, typelib, and all interfaces in typelib return _Module.

RegisterServer

(TRUE); } // DllUnregisterServer - Removes entries from the system registry STDAPI DllUnregisterServer(void) { return _Module.

UnregisterServer

(TRUE); }

Creating Class Factories

A handful of CComModule methods are used to create class factories per client request. Given what you already know about class factories created by DLL and EXE servers, I'd bet you could decipher the following CComModule methods:

// Return an IClassFactory pointer for a client (DLL servers only) HRESULT

GetClassObject

( REFCLSID rclsid, REFIID riid, LPVOID* ppv ); // Register a class object to the class table (EXE servers only) HRESULT

RegisterClassObjects

( DWORD dwClsContext, DWORD dwFlags ); // Remove a class object from the class table (EXE servers only) HRESULT

RevokeClassObjects

( );

// The single CComModule instance (DLL servers).

CComModule

_Module;

// The single CExeModule instance (EXE servers).

CExeModule

_Module;