Chapter 5. COM Servers

A Review of COM Servers

After you create one or more COM classes, you need to package the classes and install them on a system. The package is called a COM Server, which is a dynamically activated collection of the implementations of one or more COM classes. Modern Win32 versions of COM enable you to create a COM server as an in-process (inproc) server (a dynamic link library), an out-of-process server (an executable), or, on the Windows NT/2000/XP/2003 operating system, a system service executable. [1]

[1]

Here “Modern Win32 versions of COM” refers to Windows NT 4.0 and greater, Windows 98 and greater, and Windows 95 with the DCOM95 upgrade.

A COM server has three jobs, in addition to hosting the implementations of its classes:

• Register and unregister all classes in the server and, potentially, the server itself.

• Provide the COM Service Control Manager (SCM) access to all COM class objects implemented by the server (often called exposing the class objects). Class objects are frequently called class factory objects because they generally implement the IClassFactory interface.

• Manage the server’s lifetime. This typically means allowing the SCM to unload an inproc server from memory when it’s no longer used. A local server often terminates when there are no more references to objects managed by the server.

Technically, the first and third items are optional, but all COM servers should implement this functionality. Exactly how a server does this depends on the type of server.

Inproc Servers

An inproc server is a dynamic link library (DLL) that contains five well-known entry points, one for the Win32 operating systems and the other four for COM:

BOOL WINAPI DllMain(HINSTANCE hInstance, DWORD dwReason,
    LPVOID lpReserved);

STDAPI DllRegisterServer(void);
STDAPI DllUnregisterServer(void);
STDAPI DllGetClassObject(REFCLSID rclsid, REFIID riid,
    LPVOID* ppv);
STDAPI DllCanUnloadNow(void);

Each of the Win32 operating systems calls a DLL’s DllMain function when it loads a DLL into a process and removes a DLL from a process. The operating system also calls DllMain each time the current process creates a new thread and when a thread terminates cleanly. This function is optional but present in all ATL inproc servers.

The DllRegisterServer and DllUnregisterServer functions create and remove, respectively, in the Windows Registry all entries necessary for the correct operation of the server and its classes. When you use the REGSVR32 utility to register or unregister an inproc server, the utility loads the DLL and calls the appropriate one of these function in the DLL. Technically, both of these functions are optional, but, in practice, you want to have them in your server.

The COM SCM calls a server’s DllGetClassObject function when it requires a class object exposed by the server. The server should return the requested interface, riid, on the specified class object, rclsid.

When you call the CoFreeUnusedLibraries API, COM asks each inproc server in your process whether COM should unload the DLL by calling the DllCanUnloadNow function. An S_OK return value means that the server permits COM to unload the server. An S_FALSE return value indicates that the server is busy and COM cannot unload it.

Local Servers and Service-Based Servers

A local server or Windows service is an executable image (EXE) server that contains one well-known entry point:

extern "C"
int WINAPI _tWinMain(HINSTANCE hInstance,
    HINSTANCE hPrevInstance, LPTSTR lpCmdLine, int nShowCmd);

Executables cannot provide multiple specialized entry points as DLLs can, so a local server must use a different technique to implement the three requirements of a COM server: registration, exposed class objects, and lifetime management.

A local server registers and unregisters itself, and then immediately terminates when the server parses its command line and finds the well-known (noncase-sensitive) command-line switches Regserver and UnregServer, respectively.

A local server exposes its class objects by calling the CoRegisterClassObject API and handing an IUnknown interface pointer to each of the server’s class objects to the SCM. A local server must call this API after the SCM starts the server process. [2] When the server is ready to shut down, it must first call CoRevokeClassObject to notify the SCM that each of the server’s class objects is no longer available for use.

[2]

As of this writing, a local server must register its class objects within 120 seconds. The time was shorter in previous software releases. It might change again in the future, so simply register your class objects as quickly as possible.

A local server manages its own lifetime. When a server detects that there are no references to any of the objects managed by the server, the server can shut down – or not, as desired. As you’ll see later in this chapter, detecting that there are no references is a little trickier than you might think.

COM Createable and Noncreateable Classes

A COM createable class is a COM object class that supports using the CoCreateInstance API to create instances. This implies that the class must provide a class object and that the class object implements the IClassFactory interface.

A noncreateable class typically provides no class object, so calling CoCreateInstance using the class’s CLSID fails. In many designs, far more noncreateable classes exist than createable ones. For example, one version of Microsoft Excel had approximately 130 classes, only 3 of which were createable. You typically access interfaces on noncreateable classes through properties or methods on createable classes or on classes that have already been created by other means.

The Object Map and the CAtlModule Class

ATL uses two constructs to support the functionality all types of servers require: the object map and one of three CAtlModule-derived classes. As you’ll see shortly, the behavior of a COM server differs considerably depending upon whether that server is an inproc server, a local server, or a Windows service. ATL has factored server functionality into CAtlDllModuleT, CAtlExeModuleT, and CAtlServiceModuleT, each of which extends the CAtlModule base class. The discussion that follows refers to CAtlModule directly, but you should realize that one of the derived classes actually does most of the work. The object map (more properly entitled a class map) is a table of all classes implemented in the server.

Various methods of the CAtlModule class use the object map to do the following:

• Find each class and ask it to register and unregister itself

• Create the class object, if any, for each createable class

• Register and unregister the class objects with the SCM

• Find a table of implemented and required component categories for a class

• Call the static initialization and termination member functions for each class

The basic idea is that you describe the classes that you are implementing in a server using the object map. Whenever you need basic server functionality, there is probably a method of the CAtlModule class that implements much, if not all, of the required functionality.

Many methods in the CAtlModule class iterate over the entries in the object map and either ask each class to perform the required function or ask each class to provide the information needed to allow the method to do it.

The Object Map

ATL manages the object map by allocating a custom data segment within the PE file itself. Each coclass adds an entry to the object map by allocating the _ATL_OBJMAP_ENTRY structure (discussed in detail shortly) within that same data segment. This produces a series of _ATL_OBJMAP_ENTRY structures that are contiguous in memory and, thus, can easily be iterated over by CAtlModule when it needs to perform registration, class object creation, and other class-management services. Each class inserts an item into the object map via the OBJECT_ENTRY_AUTO macro declared in the class header file outside the class declaration itself, as in the following:

class CMyClass : public CComCoClass< ... >, ...
{
public:


   ...
};

OBJECT_ENTRY_AUTO(__uuidof(MyClass), CMyClass)

Here the coclass name declared in the IDL file is MyClass, so the __uuidof keyword returns the CLSID.

Readers familiar with previous versions of ATL will recall that the object map was implemented as a global C++ object declared in the server’s .cpp file with macros such as BEGIN_OBJECT_MAP and END_OBJECT_MAP. This required each class to add information (namely, an OBJECT_ENTRY macro) to a separate header file not associated with the class, which complicates maintenance and causes every class in the server to be compiled twice. The nice thing about the new approach is that the file in which the OBJECT_ENTRY_AUTO macro appears doesn’t matter; all classes that declare one contribute entries that are contiguous in memory. This means that information about each class can be located next to the class definition, where it logically belongs. The discussion of the OBJECT_ENTRY_AUTO macro later in this chapter reveals how ATL accomplishes this nifty trick.

The Object Map Macros

_ATL_OBJMAP_ENTRY Structure

The object map is an array of _ATL_OBJMAP_ENTRY structures that look like this:

struct _ATL_OBJMAP_ENTRY30 {
    const CLSID* pclsid;
    HRESULT (WINAPI *pfnUpdateRegistry)(BOOL bRegister);
    _ATL_CREATORFUNC* pfnGetClassObject;
    _ATL_CREATORFUNC* pfnCreateInstance;
    IUnknown* pCF;
    DWORD dwRegister;
    _ATL_DESCRIPTIONFUNC* pfnGetObjectDescription;
    _ATL_CATMAPFUNC* pfnGetCategoryMap;
    void (WINAPI *pfnObjectMain)(bool bStarting);
};


typedef _ATL_OBJMAP_ENTRY30 _ATL_OBJMAP_ENTRY;

The structure contains the following fields, many of which are pointers to functions:

Field	Description
pclsid	Pointer to CLSID for this class entry
pfnUpdateRegistry	The function that registers and unregisters the class
pfnGetClassObject	The Creator function that creates an instance of the class object
pfnCreateInstance	The Creator function that creates an instance of the class
pCF	Pointer to the class object instance – NULL if not yet created
dwRegister	Registration cookie CoRegisterClassObject returns
pfnGetObjectDescription	The function that returns the object description for the class
pfnGetCategoryMap	The function that returns the component category map
pfnObjectMain	The class initialization/termination function

OBJECT_ENTRY_AUTO Macro

You use the OBJECT_ENTRY_AUTO macro to specify a COM-createable class. Typically, this means the specified class derives from the CComCoClass base class. Often these are top-level objects in an object model. Clients typically create such top-level objects using CoCreateInstance.

#define OBJECT_ENTRY_AUTO(clsid, class) \
    __declspec(selectany) ATL::_ATL_OBJMAP_ENTRY \
    __objMap_##class = \
    {&clsid, class::UpdateRegistry, \
    class::_ClassFactoryCreatorClass::CreateInstance, \
    class::_CreatorClass::CreateInstance, NULL, 0, \
    class::GetObjectDescription, class::GetCategoryMap, \
    class::ObjectMain }; \
    extern "C" __declspec(allocate("ATL$__m"))\
    __declspec(selectany) \
    ATL::_ATL_OBJMAP_ENTRY* const __pobjMap_##class = \
    &__objMap_##class; \
    OBJECT_ENTRY_PRAGMA(class)

A key part of the previous OBJECT_ENTRY_AUTO macro definition is the __declspec(allocate) modifier used to allocate an item of type _ATL_OBJMAP_ENTRY in a data segment named ATL$__m. All classes in the server use this same macro (or the NON_CREATEABLE version discussed shortly), so they all add items to the same contiguous ATL$__m data segment, which lays out the _ATL_OBJMAP_ENTRY structures contiguously in memory. The OBJECT_ENTRY_PRAGMA is the bit that actually forces the linker to include a symbol pointing to the _ATL_OBJMAP_ENTRY. OBJECT_ENTRY_PRAGMA is defined as follows:

#if defined(_M_IX86)
#define OBJECT_ENTRY_PRAGMA(class)
  __pragma(comment(linker,"/include:___pobjMap_" #class));
...
#endif

The pragma shown in the macro definition has the same effect as passing the /include option to the command line of the linker. You might have noticed the __declspec(selectany) attribute adorning the __objMap_##class and __pobj-Map_##class variables in the OBJECT_ENTRY_AUTO macro. This construct appears in many places in ATL, and it’s convenient because it instructs the linker to ignore multiple definitions of a global data item that it finds in a single object file. For instance, if more than one .cpp file included a class definition that contained the OBJECT_ENTRY_AUTO macro, both expansions of the __objMap_##class and __pobj-Map_##class globals would be defined multiple times and would produce linker errors.

Having each _ATL_OBJMAP_ENTRY from every class aligned contiguously in memory is part of what’s needed to build an object map that CAtlModule can iterate over. The remaining parts are pointers that mark where in memory the map starts and where it ends. ATL is clever here as well. It creates two additional data segments named ATL$__a and ATL$__z and allocates a single NULL _ATL_OBJMAP_ENTRY pointer within each. The linker then arranges the three data segments alphabetically so that the ATL$__m segment containing all the server’s _ATL_OBJMAP_ENTRY structures is sandwiched between two NULL s. The code in atlbase.h that does this is shown here:

#pragma section("ATL$__a", read, shared)
#pragma section("ATL$__z", read, shared)
#pragma section("ATL$__m", read, shared)
extern "C" {
__declspec(selectany) __declspec(allocate("ATL$__a"))
    _ATL_OBJMAP_ENTRY* __pobjMapEntryFirst = NULL;
__declspec(selectany) __declspec(allocate("ATL$__z"))
    _ATL_OBJMAP_ENTRY* __pobjMapEntryLast = NULL;
}

#if !defined(_M_IA64)
#pragma comment(linker, "/merge:ATL=.rdata")
#endif

The alphabetical order of sections in the resulting file is guaranteed through a special naming rule enforced by the linker. If a section name has a $ character in it, the linker goes through some odd but, in this case, useful gyrations. First, it arranges the segments in order alphabetically. Then, it strips the $ character and all characters after the $ in the section name and merges the sections. This way, you’re guaranteed that the data in the ATL$__a segment comes first, then the ATL$__m segment comes next, and finally the ATL$__z segment. The actual linked PE format file then would have a single ATL segment instead of three separate ones. [3]

[3]

This also explains why the ATL team used ATL$__a, ATL$__m, and ATL$__z. It gives them future flexibility to add sections and make sure they show up in the right places.

The final step is the /merge switch added by the final #pragma directive. This causes everything in the ATL segment to be merged into the standard .rdata section (which explains why you won’t find the ATL section if you go looking with dumpbin).

Take a look at the following three class definitions:

class CDog : public CComCoClass< ... >, ...
{ };
OBJECT_ENTRY_AUTO(__uuidof(Dog), CDog)

class CCat: public CComCoClass< ... >, ...
{ };
OBJECT_ENTRY_AUTO(__uuidof(Cat), CCat)

class CMouse: public CComCoClass< ... >, ...
{ };
OBJECT_ENTRY_AUTO(__uuidof(Mouse), CMouse)

The actual layout of the object map in memory looks something like Figure5.1.

Figure 5.1. The ATL object map

The beginning of the map is marked by _pobjMapEntryFirst and its value is set to NULL. It’s not possible to set _pobjMapEntryFirst to one of the first “real” entries in the map because each is a global object, and the order of global object construction in C++ is not guaranteed. As you’ll see later when we peer into the CAtlModule-derived classes, all these classes must do to walk the object map is start at __pobjMapEntryFirst and increment a pointer until that pointer is NULL.

OBJECT_ENTRY_NON_CREATEABLE_EX_AUTO macro

You use the OBJECT_ENTRY_NON_CREATEABLE_EX_AUTO macro to specify a class that does not have an associated class object. Often these are non-top-level objects in an object model. Clients typically must call a method on a higher-level object in the object hierarchy to obtain an instance of this class. Because the specified class does not have an associated class object, clients cannot create an instance by calling CoCreateInstance.

#defineOBJECT_ENTRY_NON_CREATEABLE_EX_AUTO(clsid, class) \
    __declspec(selectany) ATL::_ATL_OBJMAP_ENTRY \
    __objMap_##class = \
    {&clsid, class::UpdateRegistry, NULL, NULL, NULL, 0, NULL, \
    class::GetCategoryMap, class::ObjectMain }; \
    extern "C"  __declspec(allocate("ATL$__m" )) \
    __declspec(selectany) \
    ATL::_ATL_OBJMAP_ENTRY* const __pobjMap_##class = \
    &__objMap_##class; \
    OBJECT_ENTRY_PRAGMA(class)

You use the OBJECT_ENTRY_NON_CREATEABLE_EX_AUTO macro primarily for noncreateable classes that need class-level initialization and uninitialization. Occasionally, you might want to have a noncreateable class maintain Registry entries, possibly persistent class configuration information and component categories.

Methods Required of an Object Map Class

The CAtlModule class registers, unregisters, initializes, and uninitializes noncreateable object map entries. In addition, it creates class objects and class instances for regular object map entries.

A class listed in the object map using the OBJECT_ENTRY_NON_CREATEABLE_EX_AUTO macro must provide the first three well-known static methods listed in Table 5.1. A class listed in the object map that uses the OBJECT_ENTRY_AUTO macro must provide the same three methods as a noncreateable class, plus the additional well-known static methods listed in Table 5.1.

Table 5.1. Object Map Support Functions

Static Member Function	Description
UpdateRegistry	Registers and unregisters the class. The DECLARE_REGISTRY_RESOURCE macros provide various implementations of this method for nonattributed projects. Attributed projects have an implementation injected by the attribute provider.
ObjectMain	Initializes and uninitializes the class. CComObjectRootBase provides a default implementation of this method.
GetCategoryMap	Returns a pointer to a component category map. The BEGIN_CATEGORY_MAP macro provides an implementation. CComObjectRootBase provides a default implementation of this method.
_CreatorClass::CreateInstance	The DECLARE_AGGREGATABLE macros set the _CreatorClass typedef to the name of the class that creates instances. CComCoClass provides a default definition of this typedef.
_ClassFactoryCreatorClass:: CreateInstance	The DECLARE_CLASSFACTORY macros set the _ClassFactoryCreatorClass typedef to the name of the class that creates class objects. CComCoClass provides a default definition of this typedef.
GetObjectDescription	Returns the object description text string. CComCoClass provides a default implementation of this method.

All classes listed in the object map must define an UpdateRegistry method, which is the only method not provided by any base class. As you’ll see soon, ATL contains various macros that expand to different implementations of this method, so the method is not difficult to provide.

All ATL objects derive from CComObjectRootBase, so they already have a default implementation of the ObjectMain method.

Most createable ATL classes also derive from CComCoClass, which provides the implementation of all four remaining methods that an object map entry requires, as well as both of the required typedefs. ATL also contains a set of macros that define and implement GetCategoryMap.

Class Registration Support Methods

When a server registers all the COM classes it contains, ATL iterates over the object map. The pfnUpdateRegistry field in the object map contains a pointer to the class’s UpdateRegistry method. For each entry, ATL calls the UpdateRegistry method to register or unregister the class. Then, it registers or unregisters the component categories for the class using the table of required and implemented categories that the GetCategoryMap method provides.

The GetObjectDescription Method

The GetObjectDescription static method retrieves the text description for your class object. As shown previously, the default implementation returns NULL. You can override this method with the DECLARE_OBJECT_DESCRIPTION macro. For example:

class CMyClass : public CComCoClass< ... >, ... {
public:
   DECLARE_OBJECT_DESCRIPTION("MyClass Object Description")

   ...
};

The UpdateRegistry Method

Every class that you list in the object map, whether createable or noncreateable, must provide an UpdateRegistry static member function. The ATL server implementation calls this method to ask the class to register and unregister itself, depending on the value of bRegister.

static HRESULT WINAPI UpdateRegistry(BOOL bRegister) ;

When you ask a COM server to register its classes, it registers all of them. You can’t ask a server to register just one class or some subset of its classes. To register or unregister a subset of the classes in a server, you need to provide a Component Registrar object. This is a COM-createable class that implements the IComponentRegistrar interface. At one time, Microsoft Transaction Server was going to use the Component Registrar object to register and unregister individual classes in a server. However, I can find no references describing if, when, or how MTS/COM+ uses the Component Registrar object. Basically, as of this writing, the Component Registrar object and class object descriptions seem to be an unused feature, and you shouldn’t use them.

The DECLARE_REGISTRY Macros

You can provide a custom implementation of UpdateRegistry (a.k.a. write it yourself) or use an ATL-provided implementation. ATL provides an implementation of this method when you use one of the following macros in your class declaration:

#define DECLARE_NO_REGISTRY() \
    static HRESULT WINAPI UpdateRegistry(BOOL /*bRegister*/) \
    {return S_OK;}


#define DECLARE_REGISTRY(class, pid, vpid, nid, flags)\
    static HRESULT WINAPI UpdateRegistry(BOOL bRegister) {\
        return _Module.UpdateRegistryClass(GetObjectCLSID(), \
           pid, vpid, nid,\
           flags, bRegister);\
    }


#define DECLARE_REGISTRY_RESOURCE(x)\
    static HRESULT WINAPI UpdateRegistry(BOOL bRegister) {\
    ...
    return ATL::_pAtlModule->UpdateRegistryFromResource(_T(#x), \
        bRegister); \
    ...
    }


#define DECLARE_REGISTRY_RESOURCEID(x)\
    static HRESULT WINAPI UpdateRegistry(BOOL bRegister) {\
    ...
    return ATL::_pAtlModule->UpdateRegistryFromResource(x, \
        bRegister); \
    ...
    }

In most circumstances, you shouldn’t use two of these Registry macros. The DECLARE_REGISTRY macro relies upon the old ATL 3 CComModule class to do its work. CComModule is no longer used as of ATL 7; if you try to use DECLARE_REGISTRY in an ATL 7 or 8 project, you’ll see compile errors resulting from references to the deprecated CComModule class. Unless you’re porting an ATL 3 project to ATL 7+, you should not use DECLARE_REGISTRY.

The second Registry macro to steer clear of is the DECLARE_NO_REGISTRY macro. This macro simply returns S_OK from the UpdateRegistry method, so no class information is entered in the Registry. The intent was that noncreateable classes can’t be created, so you shouldn’t put their CLSID information in the Registry. The problem is that any class that wants to throw COM exceptions still needs the CLSID-ProgId association in the Registry. ATL’s support code for populating COM exception objects relies upon the ProgIdFromCLSID function, which fails for any class that uses DECLARE_NO_REGISTRY.

The most flexible registration technique for ATL servers is to use Registry scripts. When asked to register or unregister, a server using Registry scripts uses an interpreter object to parse the script and make the appropriate Registry changes. The interpreter object implements the IRegistrar interface. ATL provides such an object, which can be either statically linked to reduce dependencies or dynamically loaded for the smallest code size. The choice is made via the _ATL_STATIC_REGISTRY macro, which is discussed later in this chapter.

The DECLARE_REGISTRY_RESOURCE and DECLARE_REGISTRY_RESOURCEID macros provide an implementation of UpdateRegistry that delegates the call to the CAtlModule::UpdateRegistryFromResource method. You specify a string resource name when you use the first macro. The second macro expects an integer resource identifier. The UpdateRegistryFromResource runs the script contained in the specified resource. When bRegister is TRUE, this method adds the script entries to the system Registry; otherwise, it removes the entries.

Registry Script Files

Registry scripts are text files that specify what Registry changes must be made for a given CLSID. Wizard-generated code uses an RGS extension by default for Registry script files. Your server contains the script file as a custom resource of type REGISTRY in your executable or DLL.

Registry script syntax isn’t complicated; it can be summarized as follows:

[NoRemove | ForceRemove | val] Name [ = s | d | m | b 'Value']
{
  ... optional script entries for subkeys
}

The NoRemove prefix specifies that the parser should not remove the key when unregistering. The ForceRemove prefix specifies that the parser should remove the current key and any subkeys before writing the key. [4] The val prefix specifies that the entry is a named value, not a key. The s and d value prefixes indicate REG_SZ and REG_DWORD, respectively. The m value prefix indicates a multistring (REG_MULTI_SZ), and the b value prefix denotes a binary value (REG_BINARY). The Name token is the string for the named value or key. It must be surrounded by apostrophes when the string contains spaces; otherwise, the apostrophes are optional. ATL’s parser recognizes the standard Registry keys – for example, HKEY_CLASSES_ROOT – as well as their four character abbreviations (HKCR).

[4]

Be careful when writing Registry scripts by hand. For example, don’t put the ForceRemove prefix on the node for HKEY_CLASSES_ROOT\CLSID. More than one developer machine has had to be repaved because a Registry script removed a lot more than was intended.

Here’s a REGEDIT4 sample for the nontrivial class registration for a sample class named Demagogue. Watch out: A few lines are too long to list on the page and have wrapped.

REGEDIT4
[HKEY_CLASSES_ROOT\ATLInternals.Demagogue.1]
@="Demagogue Class"
[HKEY_CLASSES_ROOT\ATLInternals.Demagogue.1\CLSID]
@="{95CD3731-FC5C-11D1-8CC3-00A0C9C8E50D}"
[HKEY_CLASSES_ROOT\ATLInternals.Demagogue]
@="Demagogue Class"
[HKEY_CLASSES_ROOT\ATLInternals.Demagogue\CLSID]
@="{95CD3731-FC5C-11D1-8CC3-00A0C9C8E50D}"
[HKEY_CLASSES_ROOT\ATLInternals.Demagogue\CurVer]
@="ATLInternals.Demagogue.1"
[HKEY_CLASSES_ROOT\CLSID\{95CD3731-FC5C-11D1-8CC3-00A0C9C8E50D}]
@="Demagogue Class"
[HKEY_CLASSES_ROOT\CLSID\{95CD3731-FC5C-11D1-8CC3-00A0C9C8E50D}\ProgID]
@="ATLInternals.Demagogue.1"
[HKEY_CLASSES_ROOT\CLSID\{95CD3731-FC5C-11D1-8CC3-00A0C9C8E50D}\VersionIndependentProgID]
@="ATLInternals.Demagogue"
[HKEY_CLASSES_ROOT\CLSID\{95CD3731-FC5C-11D1-8CC3-00A0C9C8E50D}\Programmable]
[HKEY_CLASSES_ROOT\CLSID\{95CD3731-FC5C-11D1-8CC3-00A0C9C8E50D}\InprocServer32]
@="C:\\ATLINT~1\\Debug\\ATLINT~1.DLL"
"ThreadingModel"="Apartment"
[HKEY_CLASSES_ROOT\CLSID\{95CD3731-FC5C-11D1-8CC3-00A0C9C8E50D}\TypeLib]
@="{95CD3721-FC5C-11D1-8CC3-00A0C9C8E50D}"
[HKEY_CLASSES_ROOT\CLSID\{95CD3731-FC5C-11D1-8CC3-00A0C9C8E50D}\Implemented
Categories]
[HKEY_CLASSES_ROOT\CLSID\{95CD3731-FC5C-11D1-8CC3-00A0C9C8E50D}\Implemented
Categories\{0D22FF22-28CC-11D2-ABDD-00A0C9C8E50D}]

The corresponding Registry script looks like this:

HKCR
{
  ATLInternals.Demagogue.1 = s 'Demagogue Class'
  {
    CLSID = s '{95CD3731-FC5C-11D1-8CC3-00A0C9C8E50D}'
  }
  ATLInternals.Demagogue = s 'Demagogue Class'
  {
    CLSID = s '{95CD3731-FC5C-11D1-8CC3-00A0C9C8E50D}'
    CurVer = s 'ATLInternals.Demagogue.1'
  }
  NoRemove CLSID
  {
    ForceRemove {95CD3731-FC5C-11D1-8CC3-00A0C9C8E50D} = s 'Demagogue
      Class'
    {
      ProgID = s 'ATLInternals.Demagogue.1'
      VersionIndependentProgID = s 'ATLInternals.Demagogue'
      ForceRemove 'Programmable'
      InprocServer32 = s '%MODULE%'
      {
        val ThreadingModel = s 'Apartment'
      }
      'TypeLib' = s '{95CD3721-FC5C-11D1-8CC3-00A0C9C8E50D}'
      'Implemented Categories'
      {
        {0D22FF22-28CC-11D2-ABDD-00A0C9C8E50D}
      }
    }
  }
}

When you have the resource script file, you reference the file in your server’s resource (.rc) file. You can reference it using either an integer identifier or a string identifier. In a typical ATL project, each class can have a Registry script file, and the server as a whole typically has its own unique Registry script file.

In the following examples, the Demagogue script file uses the integer identifier IDR_DEMAGOGUE. The EarPolitic script file uses EARPOLITIC as its string identifier. ATL wizard-created classes use the DECLARE_REGISTRY_RESOURCEID macro to specify a resource by its integer identifier. You can use the DECLARE_REGISTRY_RESOURCE macro to identify a resource by its name.

// resource.h file
#define IDR_DEMAGOGUE                   102

// Server.rc file
IDR_DEMAGOGUE           REGISTRY DISCARDABLE    "Demagogue.rgs"
EARPOLITIC              REGISTRY DISCARDABLE    "EarPolitic.rgs"

// Demagogue.h file
class ATL_NO_VTABLE CDemagogue :
    public CComObjectRootEx<CComSingleThreadModel>,
    public CComCoClass<CDemagogue, &CLSID_Demagogue>,

...
public:
DECLARE_REGISTRY_RESOURCEID(IDR_DEMAGOGUE)

...
};

// EarPolitic.h file
class ATL_NO_VTABLE CEarPolitic :
    public CComObjectRootEx<CComSingleThreadModel>,
    public CComCoClass<CEarPolitic, &CLSID_EarPolitic>,

...
{
public:
DECLARE_REGISTRY_RESOURCE(EARPOLITIC)
...
};

Registry Script Variables

Note that in the Registry script, one of the lines references a symbol called %MODULE%.

InprocServer32 = s '%MODULE%'

When the parser evaluates the script, it replaces all occurrences of the Registry script variable %MODULE% with the actual results of a call to GetModuleFileName. So what the parser actually registered looked like this:

InprocServer32 = s 'C:\ATLInternals\Debug\ATLInternals.dll'

You can use additional, custom Registry script variables in your scripts. Your server must provide the Registry script parser with a table that maps variable names to replacement values when you ask the parser to parse the script. The parser substitutes the replacement values for the variable names before registration.

To use custom Registry script variables, first select the Registry script variable name, using percent signs to delimit the name. Here is a sample line from a Registry script:

DateInstalled = s '%INSTALLDATE%'

You now have two choices. If your script variables are global, you can provide an override of the AddCommonRGSReplacements method in your derived module class. An example implementation looks like this:

HRESULT AddCommonRGSReplacements(IRegistrarBase *pRegistrar) {
    BaseModule::AddCommonRGSReplacements( pRegistrar );
    OLECHAR wszDate [16]; SYSTEMTIME st;
    GetLocalTime(&st);
    wsprintfW(wszDate, L"%.4d/%.2d/%.2d", st.wYear,
        st.wMonth, st.wDay);
    pRegistrar->AddReplacement( OLESTR("INSTALLDATE"), wszDate );
}

You must call the base class’s version of AddCommonRGSReplacements to make sure the APPID variable gets added as well.

If you don’t want to have all of your replacements added in one place, you can define a custom UpdateRegistry method instead of using the DECLARE_REGISTRY_RESOURCEID macro in your class. In the method, build a table of replacement name-value pairs. Finally, call the CAtlModule::UpdateRegistryFromResource method, specifying the resource identifier, a register/unregister flag, and a pointer to the replacement name-value table. Note that ATL uses the provided table entries in addition to the default replacement map (which, as of this writing, contains only %MODULE% and %APPID%).

Here is an example from the Demagogue class that substitutes the variable %INSTALLDATE% with a string that contains the current date:

static HRESULT WINAPI UpdateRegistry(BOOL b) {
    OLECHAR wszDate [16]; SYSTEMTIME st;
    GetLocalTime(&st);
    wsprintfW(wszDate, L"%.4d/%.2d/%.2d", st.wYear,
        st.wMonth, st.wDay);
    _ATL_REGMAP_ENTRY rm[] = {
        { OLESTR("INSTALLDATE"), wszDate},
        { 0, 0 } };
    return _pAtlModule->UpdateRegistryFromResource(
        IDR_DEMAGOGUE, b, rm);
}

After registration of the class, the Registry key DateInstalled contains the year, month, and day, in the form yyyy/mm/dd, at the time of install.

The GetCategoryMap Method

The last step in the registration process for each class in the object map is to register the component categories for the class. The ATL server registration code calls each class’s GetCategoryMap method to ask the class for its list of required and implemented component categories. The method looks like this:

static const struct _ATL_CATMAP_ENTRY* GetCategoryMap() { return NULL; }

The ATL server registration code uses the standard component category manager object (CLSID_StdComponentCategoriesMgr) to register your class’s required and implemented categories. Older versions of Win32 operating systems do not have this component installed. When the category manager is not installed, your class’s registration of its component categories silently fails. Typically, this is not good. However, Microsoft permits you to redistribute the standard component category manager (comcat.dll) with your application.

The Component Category Map

Typically, you use ATL-provided category map macros for the implementation of this method. Here’s a typical category map:

// {0D22FF22-28CC-11d2-ABDD-00A0C9C8E50D}
static const GUID CATID_ATLINTERNALS_SAMPLES =
{0xd22ff22, 0x28cc, 0x11d2, {0xab, 0xdd, 0x0, 0xa0, 0xc9, 0xc8,
     0xe5, 0xd}};

BEGIN_CATEGORY_MAP(CDemagogue)
IMPLEMENTED_CATEGORY(CATID_ATLINTERNALS_SAMPLES)
END_CATEGORY_MAP()

This example defines a component category called CATID_ATLINTERNALS_SAMPLES. All examples in this book register themselves as a member of this category.

The Category Map Macros

The BEGIN_CATEGORY_MAP macro declares the GetCategoryMap static member function. This returns a pointer to an array of _ATL_CATMAP_ENTRY enTRies, each of which describes one component category that your class either requires or implements.

#define BEGIN_CATEGORY_MAP(x)\
    static const struct ATL::_ATL_CATMAP_ENTRY* GetCategoryMap() {\
    static const struct ATL::_ATL_CATMAP_ENTRY pMap[] = {

The IMPLEMENTED_CATEGORY and REQUIRED_CATEGORY macros populate the table with the appropriate entries:

#define IMPLEMENTED_CATEGORY(catid) { \
    _ATL_CATMAP_ENTRY_IMPLEMENTED, &catid },
#define REQUIRED_CATEGORY(catid) { \
    _ATL_CATMAP_ENTRY_REQUIRED, &catid },

The END_CATEGORY_MAP adds a delimiting entry to the table and completes the GetCategoryMap function:

#define END_CATEGORY_MAP()\
    { _ATL_CATMAP_ENTRY_END, NULL } };\
    return( pMap ); }

Each table entry contains a flag (indicating whether the entry describes a required category, an implemented category, and the end of table entry) and a pointer to the CATID.

struct _ATL_CATMAP_ENTRY {
    int iType;
    const CATID* pcatid;
};


#define _ATL_CATMAP_ENTRY_END         0
#define _ATL_CATMAP_ENTRY_IMPLEMENTED 1
#define _ATL_CATMAP_ENTRY_REQUIRED    2

The ATL helper function AtlRegisterClassCategoriesHelper iterates through the table and uses COM’s standard component category manager to register each CATID as a required or implemented category for your class. The ATL server registration code uses this helper function to register the component categories for each class in the object map.

Unfortunately, the category map logic does not add a category to a system before trying to enroll a class as a member of the (nonexistent) category. If you want to add categories that don’t already exist, you must enhance the registration of the server itself so that it registers any custom component categories your classes use. For example, the following Registry script registers the AppID for an inproc server and also adds a component category to the list of component categories on the system:

HKCR
{
    NoRemove AppID
    {
        {A11552A2-28DF-11d2-ABDD-00A0C9C8E50D} = s 'ATLInternals'
        'ATLInternals.DLL'
        {
            val AppID = s {A11552A2-28DF-11d2-ABDD-00A0C9C8E50D}

        }
    }
    NoRemove 'Component Categories'
    {
        {0D22FF22-28CC-11d2-ABDD-00A0C9C8E50D}
        {
            val 409 = s 'ATL Internals Example Components'
        }
    }
}

This technique defines all categories (just one in the previous example) that the classes implemented in this server in the System registry use. Separately, each class registers itself as a member of one or more of these categories.

Server, Not Class, Registration

Often, you need Registry entries for the server (inproc, local, or service) as a whole. For example, the HKCR/AppID Registry entries for a server apply to the entire DLL or EXE, and not to a specific class implemented in the DLL or EXE. As mentioned previously, you must register a new component category with the system before you can enroll a class as a member of the category. Until now, you’ve only seen support for registration of class-specific information.

This is simple enough. Write a Registry script that adds the entries the server requires, such as its AppID and component categories that the server’s classes use. Then, register the server’s script before registering all the classes implemented inthe server. The wizard-generated code for all three server types does precisely this for you.

The ATL wizard-generated code for a server creates a Registry script file for your server registration in addition to any Registry script files for your classes. By default, the server Registry script defines only an AppID for the server. Here are the entries for an ATL project called MathServer:

// In the resource.h file
#define IDR_MATHSERVER        100

// In the MathServer.rc file
IDR_MATHSERVER REGISTRY "MathServer.rgs"

// MathServer.rgs file
HKCR
{
    NoRemove AppID
{
        '%APPID%' = s 'MathServer'
        'MathServer.DLL'
        {
            val AppID = s '%APPID%'
        }
    }
}

The RGS files are similar for all three server types – inproc, local server, and Windows service. The mechanics used to invoke the registration code that executes the script differ among the three server types.

Inproc Server Registration

Inproc server registration for classes and for the server itself occurs in the call to the DllRegisterServer entry point. This method delegates the work to a specialization of CAtlModule that is used only for inproc servers; this class is called CAtlDllModuleT.

template <class T>
class ATL_NO_VTABLE CAtlDllModuleT : public CAtlModuleT<T> {
public:
    ...
    HRESULT DllRegisterServer(BOOL bRegTypeLib = TRUE) {
        ...
        T* pT = static_cast<T*>(this);
        HRESULT hr = pT->RegisterAppId(); // execute server script
        ...
        return hr;
    }
    ...
};

The RegisterAppId function ultimately calls the UpdateRegistryFromResource function through the UpdateRegistryAppId helper generated by the DECLARE_REGISTRY_APPID_RESOURCEID macro in our project.cpp file. This macro is discussed in more detail later in this chapter.

Local Server and Windows Service Registration

A local server specializes CAtlModule with a class called CAtlExeModuleT. A Windows service further extends CAtlExeModuleT with a derived class called CAtlServiceModuleT. Both classes supply WinMain code that registers the server’s resource script entries and then calls the _AtlModule object’s RegisterServer method to do the same for each class in the object map. These classes unregister each object in the server before running the server’s unregistration script.

template <class T>
class CAtlExeModuleT : public CAtlModuleT<T> {
public :

  int WinMain(int nShowCmd) throw() {
    ...
    HRESULT hr = S_OK;

    LPTSTR lpCmdLine = GetCommandLine();
    if (pT->ParseCommandLine(lpCmdLine, &hr) == true)
      hr = pT->Run(nShowCmd);

      ...
  }

  bool ParseCommandLine(LPCTSTR lpCmdLine, HRESULT* pnRetCode) {
    *pnRetCode = S_OK;

    TCHAR szTokens[] = _T("-/");

    T* pT = static_cast<T*>(this);
    LPCTSTR lpszToken = FindOneOf(lpCmdLine, szTokens);
    while (lpszToken != NULL) {
      if (WordCmpI(lpszToken, _T("UnregServer"))==0) {
        *pnRetCode = pT->UnregisterServer(TRUE); // all class script
        if (SUCCEEDED(*pnRetCode))
          *pnRetCode = pT->UnregisterAppId(); //  server scripts
        return false;
      }

      // Register as Local Server
      if (WordCmpI(lpszToken, _T("RegServer"))==0) {
        *pnRetCode = pT->RegisterAppId(); // server script
        if (SUCCEEDED(*pnRetCode))
          *pnRetCode = pT->RegisterServer(TRUE); // all class scripts
        return false;
      }

      lpszToken = FindOneOf(lpszToken, szTokens);
    }

    return true;
  }
};

Class Initialization and Uninitialization

The ObjectMain Method

In C++, constructors and destructors are used to provide instance-level initialization and cleanup – that is, code that runs each time an instance of a class is either created or destroyed. Often, it is useful to provide class-level initialization and cleanup codecode that runs only once per class, regardless of the number of class instances that are ultimately created. Some languages support such behavior directly through static constructors. Unfortunately, C++ is not one of those languages. So, ATL supports class-level initialization for all classes listed in the object map, createable and noncreateable, through the ObjectMain method. In fact, you’ll frequently add a noncreateable class entry to the object map solely because the noncreateable class needs class-level initialization. (A createable class must always be in the object map and thus always receives class-level initialization.)

When an ATL server initializes, it iterates over the object map and calls the ObjectMain static member function (with the bStarting parameter set to true) of each class in the map. When an ATL server terminates, it calls the ObjectMain function (with the bStarting parameter set to false) of each class in the map. Youalways have a default implementation, provided by CComObjectRootBase, that does nothing and looks like this:

static void WINAPI ObjectMain(bool /* bStarting */ ) {};

When you have class initialization and termination logic (compared to instance initialization and termination logic), define an ObjectMain static member function in your class and place the logic there. [5]

[5]

Instance initialization and termination logic should go in the FinalConstruct and FinalRelease methods, as Chapter 4, “Objects in ATL,” describes.)

class ATL_NO_VTABLE CSoapBox :
    public CComObjectRootEx<CComSingleThreadModel>,
    ...
{
public:
    DECLARE_NO_REGISTRY()
    ...
    static void WINAPI ObjectMain(bool bStarting) ;
};

Instantiation Requests

Having class initialization logic run may be useful, but if clients can’t create an instance, an initialized class is no help. Next, let’s look at how ATL supports creating COM class factories to bring your COM objects to life.

Class Object Registration

ATL creates the class objects for an inproc server slightly differently than it does the class objects for a local server or service. For an inproc server, ATL defers creating each class object until the SCM actually requests the class object via DllGetClassObject. For a local server or service, ATL creates all class objects during server initialization and then registers the objects with the SCM.

For an inproc server, ATL uses the AtlComModuleGetClassObject helper function to scan the object map; create the class object, if necessary; and return the requested interface on the class object.

ATLINLINE ATLAPI AtlComModuleGetClassObject(
       _ATL_COM_MODULE* pComModule, REFCLSID rclsid, REFIID riid,
       LPVOID* ppv) {
    ...
    for (_ATL_OBJMAP_ENTRY** ppEntry =
        pComModule->m_ppAutoObjMapFirst;
        ppEntry < pComModule->m_ppAutoObjMapLast; ppEntry++) {
        if (*ppEntry != NULL) {
            _ATL_OBJMAP_ENTRY* pEntry = *ppEntry;
            if ((pEntry->pfnGetClassObject != NULL) &&
                InlineIsEqualGUID(rclsid, *pEntry->pclsid)) {
                if (pEntry->pCF == NULL) {
                    CComCritSecLock<CComCriticalSection>
                        lock(pComModule->m_csObjMap, false);
                    hr = lock.Lock();
                    ...
                    if (pEntry->pCF == NULL)
                        hr = pEntry->pfnGetClassObject(
                            pEntry->pfnCreateInstance,
                            __uuidof(IUnknown),
                            (LPVOID*)&pEntry->pCF);
                }
                if (pEntry->pCF != NULL)
                    hr = pEntry->pCF->QueryInterface(riid, ppv);
                break;
            }
        }
    }
    if (*ppv == NULL && hr == S_OK)
        hr = CLASS_E_CLASSNOTAVAILABLE;
    return hr;
}

Notice how the logic checks to see if the class object has not already been created (pEntry->pCF == NULL), acquires the critical section that guards access to the object map, and then checks once more that pCF is still NULL. What might not be obvious is why ATL checks twice. This is to maximize concurrency by avoiding grabbing the critical section in the normal case (when the class factory has already been created).

Also notice that ATL caches the IUnknown interface for the class object in the object map entry’s pCF member variable. Because the SCM can make subsequent requests for the same class object, ATL caches the IUnknown pointer to the object in the pCF field of the object map entry for the class. Subsequent requests for the same class object reuse the cached interface pointer.

You can use the helper method, called GetClassObject, in your CAtlModuleT global object (discussed in detail later in the chapter) to retrieve a previously registered class object. However, this works only for inproc servers; the CAtlExeModuleT and CAtlServiceModuleT classes, used for local servers and services, respectively, don’t include this member function.

// Obtain a Class Factory (DLL only)
HRESULT GetClassObject(REFCLSID rclsid, REFIID riid,
    LPVOID* ppv);

You use it like this:

IClassFactory* pFactory;
HRESULT hr = _pAtlModule->GetClassObject (
 CLSID_Demagogue, IID_IClassFactory,
 reinterpret_cast< void** >(&pFactory));

A local server must register all its class objects during the server’s initialization. ATL uses the AtlComModuleRegisterClassObjects helper function to register all the class objects in a local server. This helper function iterates over the object map calling RegisterClassObject for each object map entry.

ATLINLINE ATLAPI AtlComModuleRegisterClassObjects(
    _ATL_COM_MODULE* pComModule,
    DWORD dwClsContext, DWORD dwFlags) {
    ...
    HRESULT hr = S_FALSE;
    for (_ATL_OBJMAP_ENTRY** ppEntry = pComModule->m_ppAutoObjMapFirst;
         ppEntry < pComModule->m_ppAutoObjMapLast && SUCCEEDED(hr);
         ppEntry++) {
        if (*ppEntry != NULL)
            hr = (*ppEntry)->RegisterClassObject(dwClsContext,
                dwFlags);
    }
    return hr;
}

RegisterClassObject is a method of the _ATL_OBJMAP_ENTRY structure. It basically encapsulates the process of creating and then registering a class object from an object map entry. First, it ignores entries with a NULL pfnGetClassObject function pointer. This skips the noncreateable class entries in the map. Then, RegisterClassObject creates the instance of the class object and registers it:

struct _ATL_OBJMAP_ENTRY {
    HRESULT WINAPI RegisterClassObject(DWORD dwClsContext,
        DWORD dwFlags) {
        IUnknown* p = NULL;
        if (pfnGetClassObject == NULL) return S_OK;
        HRESULT hRes = pfnGetClassObject(pfnCreateInstance,
            __uuidof(IUnknown), (LPVOID*) &p);
        if (SUCCEEDED(hRes))
            hRes = CoRegisterClassObject(*pclsid, p,
                dwClsContext, dwFlags, &dwRegister);
        if (p != NULL) p->Release();
        return hRes;
    }
};

Notice that the function does not cache the IUnknown interface pointer to the class object that it creates: It hands the interface to the SCM (which caches the pointer), stores the registration code in the object map, and releases the interface pointer. Because ATL does not cache class object interface pointers in an out-of-process server, the simplest method to obtain your own class object from within the server is to ask the SCM for it by calling CoGetClassObject.

The _ClassFactoryCreatorClass and _CreatorClass Typedefs

When ATL created a class object in the previous examples, it asked your class to instantiate the class object by calling indirectly through the function pointer pfnGetClassObject, which ATL stores in the object map entry for the class.

struct _ATL_OBJMAP_ENTRY30 {
  ...
  _ATL_CREATORFUNC* pfnGetClassObject; // Creates a class object
  _ATL_CREATORFUNC* pfnCreateInstance; // Create a class instance
  ...
};

This member variable is of type _ATL_CREATORFUNC* and is a creator function. [6] Notice that the pfnCreateInstance member variable is also a creator function pointer.

[6]

Although two types of creator functions logically exist (instance-creator functions and class-creator functions), all creator functions that the object map uses have a static member function with the example function signature. Chapter 4 discusses the various types of instance-creator functions in depth. This chapter discusses the various class-creator classes.

typedef HRESULT (WINAPI _ATL_CREATORFUNC)(void* pv, REFIID riid, LPVOID* ppv);

These function pointers are non-NULL only when you describe a COM-createable class using the OBJECT_ENTRY_AUTO macro.

#define OBJECT_ENTRY_AUTO(clsid, class) \
    __declspec(selectany) ATL::_ATL_OBJMAP_ENTRY \
    __objMap_##class = \
    {&clsid, class::UpdateRegistry, \
    class::_ClassFactoryCreatorClass::CreateInstance, \
    class::_CreatorClass::CreateInstance, NULL, 0, \
    class::GetObjectDescription, class::GetCategoryMap, \
    class::ObjectMain }; \
    extern "C" __declspec(allocate("ATL$__m"))\
    __declspec(selectany) \
    ATL::_ATL_OBJMAP_ENTRY* const __pobjMap_##class = \
    &__objMap_##class; \
    OBJECT_ENTRY_PRAGMA(class)

A createable class must define a typedef called _ClassFactoryCreatorClass, which ATL uses as the name of the class object’s creator class. The OBJECT_ENTRY_AUTO macro expects this creator class to have a static member function called CreateInstance, and it stores the address of this static member function in the pfnGetClassObject object map entry.

A createable class also must define a typedef called _CreatorClass, which ATL uses as the name of the class instance’s creator class. The OBJECT_ENTRY_AUTO macro expects this creator class to have a static member function called CreateInstance, and it stores the address of this static member function in the pfnCreateInstance object map entry.

DECLARE_CLASSFACTORY

Typically, your createable class inherits a definition of the _ClassFactoryCreatorClass typedef from its CComCoClass base class. CComCoClass uses the DECLARE_CLASSFACTORY macro to define an appropriate default class object creator class, based on the type of server.

template <class T, const CLSID* pclsid = &CLSID_NULL>
class CComCoClass {
public:
    DECLARE_CLASSFACTORY()
    DECLARE_AGGREGATABLE(T)
    ...
};

The _ClassFactoryCreatorClass Typedef

The DECLARE_CLASSFACTORY macro evaluates to the DECLARE_CLASSFACTORY_EX macro with CComClassFactory as the cf argument. The DECLARE_CLASSFACTORY_EX macro produces a typedef for the symbol _ClassFactoryCreatorClass. This typedef is the name of a creator class that ATL uses to create the class object for a class.

#define DECLARE_CLASSFACTORY() DECLARE_CLASSFACTORY_EX(ATL::CComClassFactory)

#if defined(_WINDLL) | defined(_USRDLL)
#define DECLARE_CLASSFACTORY_EX(cf) \
  typedef ATL::CComCreator< \
    ATL::CComObjectCached< cf > > _ClassFactoryCreatorClass;
#else
// don't let class factory refcount influence lock count
#define DECLARE_CLASSFACTORY_EX(cf) \
  typedef ATL::CComCreator< \
    ATL::CComObjectNoLock< cf > > _ClassFactoryCreatorClass;
#endif

When you build an inproc server, ATL standard build options define the _USRDLL preprocessor symbol. This causes the _ClassFactoryCreatorClass typedef to evaluate to a CComCreator class that creates a CComObjectCached<cf> version of your class object class cf. Out-of-process servers evaluate the typedef as a CComCreator class that creates a CComObjectNoLock<cf> version of the class object class cf.

Class Object Usage of CComObjectCached and CComObjectNoLock

As described in Chapter 4, “Objects in ATL,” the CComObjectCached::AddRef method does not increment the server’s lock count until the cached object’s reference count changes from 1 to 2. Similarly, Release doesn’t decrement the server’s lock count until the cached object’s reference count changes from 2 to 1.

ATL caches the IUnknown interface pointer to an inproc server’s class object in the object map. This cached interface pointer represents a reference. If this cached reference affects the server’s lock count, the DLL cannot unload until the server releases the interface pointer. However, the server doesn’t release the interface pointer until the server is unloading. In other words, the server would never unload in this case. By waiting to adjust the server’s reference count until there is a second reference to the class object, the reference in the object map isn’t sufficient to keep the DLL loaded.

Also described in Chapter 4, CComObjectNoLock never adjusts the server’s lock count. This means that an instance of CComObjectNoLock does not keep a server loaded. This is exactly what you need for a class object in a local server.

When ATL creates a class object for an out-of-process server, it registers the class object with the SCM; then ATL releases its reference. However, the SCM keeps an unknown number of references to the class object, where “unknown” means one or more. Therefore, the CComObjectCached class doesn’t work correctly for an out-of-process class object. ATL uses the CComObjectNoLock class for out-of-process class objects because references to such objects don’t affect the server’s lifetime in any way. However, in modern versions of COM, the marshaling stub calls the class object’s LockServer method when it marshals an interface pointer to a remote client (where “remote” is any other apartment or context). This keeps the server loaded when out-of-apartment clients have a reference to the class object.

Class Object Instantiation: CComCreator::CreateInstance Revisited

Earlier in this chapter, you saw the ATL class object registration helper functions AtlComModuleGetClassObject and RegisterClassObject. When they create a class object, they call the class object’s creator class’s CreateInstance method, like this:

// Inproc server class object instantiation
ATLINLINE ATLAPI AtlComModuleGetClassObject(_ATL_COM_MODULE* pM,
                                 REFCLSID rclsid,
                                 REFIID riid, LPVOID* ppv) {
    ...
    hr = pEntry->pfnGetClassObject(pEntry->pfnCreateInstance,
                                   __uuidof(IUnknown),
                                   (LPVOID*)&pEntry->pCF);
    ...
} ;

// Out of process server class object instantiation
struct _ATL_OBJMAP_ENTRY {
  HRESULT WINAPI RegisterClassObject(DWORD dwClsContext,
  DWORD dwFlags) {
    ...
    HRESULT hRes = pfnGetClassObject(pfnCreateInstance,
      _uuidof(IUnknown), (LPVOID*) &p);
    ...
  }
};

Recall that the pfnGetClassObject member variable is set by the OBJECT_ENTRY_AUTO macro and contains a pointer to the CreateInstance method of _ClassFactoryCreatorClass:

class::_ClassFactoryCreatorClass::CreateInstance

For an inproc server, this evaluates to the following (assuming that you’re using the default class factory class, which is CComClassFactory):

class::ATL::CComCreator<
    ATL::CComObjectCached< ATL::CComClassFactory >
    >::CreateInstance

For an out-of-process server, this evaluates to:

class::ATL::CComCreator<
    ATL::CComObjectNoLock< ATL::CComClassFactory >
    >::CreateInstance

This means that the pfnGetClassObject member points to the CreateInstance method of the appropriate parameterized CComCreator class. When ATL calls this CreateInstance method, the creator class creates the appropriate type of the CComClassFactory instance (cached or no lock) for the server. You learned the definition of the CComCreator class in Chapter 4, “Objects in ATL,” but let’s examine part of the code in depth:

template <class T1>
class CComCreator {
public:
    static HRESULT WINAPI CreateInstance(void* pv, REFIID riid,
        LPVOID* ppv) {
        ...
        ATLTRY(p = new T1(pv))
        if (p != NULL) {
            p->SetVoid(pv);
           ...
        }
        return hRes;
    }
};

After the creator class’s CreateInstance method creates the appropriate class object, the method calls the class object’s SetVoid method and passes it the pv parameter of the CreateInstance call.

Note that ATL uses a creator class to create both instances of class objects (sometimes called class factories) and instances of a class (often called COM objects). For regular COM objects, ATL defines the SetVoid method in CComObjectRootBase as a do-nothing method, so this creator class call to SetVoid has no effect on an instance of a class:

class CComObjectRootBase {
    ...
    void SetVoid(void*) {}
};

However, when a creator class creates an instance of a class factory, it typically creates a CComClassFactory instance. CComClassFactory overrides the SetVoid method. When a creator class calls the SetVoid method while creating a class factory instance, the method saves the pv parameter in its m_pfnCreateInstance member variable:

class CComClassFactory :
    public IClassFactory,
    public CComObjectRootEx<CComGlobalsThreadModel> {
public:
  ...
  void SetVoid(void* pv) { m_pfnCreateInstance = (_ATL_CREATORFUNC*)pv;}
  _ATL_CREATORFUNC* m_pfnCreateInstance;
};

Let’s look at the class object creation code in the ATL helper function again:

HRESULT hRes = pfnGetClassObject( pfnCreateInstance,
    __uuidof(IUnknown), (LPVOID*) &p);

The pfnGetClassObject variable points to the CreateInstance creator function that creates the appropriate instance of the class object for the server. The pfnCreateInstance variable points to the CreateInstance creator function that creates an instance of the class.

When ATL calls the pfnGetClassObject function, it passes the pfnCreateInstance object map entry member variable as the pv parameter to the CComClassFactory::CreateInstance method. The class object saves this pointer in its m_pfnCreateInstance member variable and calls the m_pfnCreateInstance function whenever a client requests the class object to create an instance of the class.

Whew! You must be wondering why ATL goes to all this trouble. Holding a function pointer to an instance-creation function increases the size of every class object by 4 bytes (the size of the m_pfnCreateInstance variable). Nearly everywhere else, ATL uses templates for this kind of feature. For example, we could define the CComClassFactory class to accept a template parameter that is the instance class to create. Then, each instance of the class object wouldn’t need the extra 4-byte function pointer. The code would look something like this:

template <class T>
class CComClassFactory :
...
{
  ...
  STDMETHOD(CreateInstance)(LPUNKNOWN pUnkOuter, REFIID riid,
      void** ppvObj) {
      ...
      ATLTRY(p = new T ());
      ...
  }
};

The problem with this alternative approach is that it actually takes more memory to implement. For example, let’s assume that you have a server that implements three classes: A, B, and C.

On Win32, ATL’s current approach takes 12 bytes per class object (4-byte vptr, 4-byte unused reference count, and 4-byte function pointer) times three class objects (A, B, and C), plus 20 bytes for a single CComClassFactory vtable (five entries of 4 bytes each). (All three classes objects are actually unique instances of the same CComClassFactory class, so all three share a single vtable. Each instance maintains a unique statea function pointerwhich creates different instance classes when called.) This is a total of 56 bytes for the three class objects. (Recall that ATL never creates more than one instance of a class object.)

The template approach takes 8 bytes per class object (4-byte vptr and 4-byte unused reference count) times three class objects (A, B, and C), plus 20 bytes each for three CComClassFactory vtables (one for CComClassFactory<A>, one for CComClassFactory<B>, and one for CComClassFactory<C>). In this case, the class object doesn’t maintain state to tell it what instance class to create. Therefore, each class must have its own unique vtable that points to a unique CreateInstance method that calls new on the appropriate class. This is a total of 84 bytes.

This is mostly a theoretical calculation, though. Most heap managers round allocations up to a multiple of 16 bytes, which makes the instance sizes the same. This more or less makes moot the issue that class objects carry around a reference count member variable that they never use.

However, the memory savings are real, mainly because of the single required vtable. The function pointer implementation requires only a single copy of the IClassFactory methods and, therefore, only one vtable, regardless of the number of classes implemented by a server. The template approach requires one copy of the IClassFactory methods per class and, therefore, one vtable per class. The memory savings increase as you have more classes in a server.

I know, that’s more detail than you wanted to know. Think of all the character and moral fiber you’re building. That’s why I’m here. Now, let’s look at how CComClassFactory and related classes actually work.

CComClassFactory and Friends

DECLARE_CLASSFACTORY and CComClassFactory

Typically, ATL objects acquire a class factory by deriving from CComCoClass. This class includes the macro DECLARE_CLASSFACTORY, which declares CComClassFactory as the default class factory.

The CComClassFactory class is the most frequently used of the ATL-supplied class object implementations. It implements the IClassFactory interface and also explicitly specifies that the class object needs the same level of thread safety, CComGlobalsThreadModel, that globally available objects require. This is because multiple threads can access a class object when the server’s threading model is apartment, free or both. Only when the server’s threading model is single does the class object not need to be thread safe.

class CComClassFactory :
    public IClassFactory,
    public CComObjectRootEx<CComGlobalsThreadModel> {
public:
    BEGIN_COM_MAP(CComClassFactory)
        COM_INTERFACE_ENTRY(IClassFactory)
    END_COM_MAP()

  // IClassFactory
  STDMETHOD(CreateInstance)(LPUNKNOWN pUnkOuter, REFIID riid,
    void** ppvObj);
  STDMETHOD(LockServer)(BOOL fLock);

  // helper
  void SetVoid(void* pv);

  _ATL_CREATORFUNC* m_pfnCreateInstance;
};

Your class object must implement a CreateInstance method that creates an instance of your class. The CComClassFactory implementation of this method does some error checking and then calls the m_pfnCreateInstance function pointer to create the appropriate instance.

STDMETHOD(CreateInstance)(LPUNKNOWN pUnkOuter, REFIID riid,
    void** ppvObj) {
    ...
        else hRes = m_pfnCreateInstance(pUnkOuter, riid, ppvObj);
    }
    return hRes;
}

As described earlier, the object map entry for your class contains the original value for this function pointer. It points to an instance-creator class, as described in Chapter4, “Objects in ATL,” and is set by the following part of the OBJECT_ENTRY_AUTO macro:

class::_CreatorClass::CreateInstance, NULL, 0, \

When your class derives from CComCoClass, you inherit a typedef for _CreatorClass, which is be used unless you override it with a new definition.

template <class T, const CLSID* pclsid = &CLSID_NULL>
class CComCoClass {
public:
    DECLARE_AGGREGATABLE(T)
    ...
};

The default DECLARE_AGGREGATABLE macro defines a creator class, of type CComCreator2, that it uses to create instances of your class. This creator class creates instances using one of two other creator classes, depending on whether the instance is aggregated. It uses a CComCreator to create instances of CComObject<YourClass> when asked to create a nonaggregated instance; it creates instances of CComAggObject<YourClass> when you want your class to be aggre-gatable. When your class derives from CComCoClass, you inherit a typedef for _CreatorClass that is used unless you override it with a new definition.

#define DECLARE_AGGREGATABLE(x) public:\
    typedef ATL::CComCreator2< \
        ATL::CComCreator< \
        ATL::CComObject< x > >, \
        ATL::CComCreator< \
        ATL::CComAggObject< x > > \
    > _CreatorClass;

DECLARE_CLASSFACTORY_EX

You can specify a custom class factory class for ATL to use when creating instances of your object class. To override the default specification of CComClassFactory, add the DECLARE_CLASSFACTORY_EX macro to your object class and, as the macro parameter, specify the name of your custom class factory class. This class must derive from CComClassFactory and override the CreateInstance method. For example

class CMyClass : ..., public CComCoClass< ... > {
public:
    DECLARE_CLASSFACTORY_EX(CMyClassFactory)
    ...
};

class CMyClassFactory : public CComClassFactory {
  ...
  STDMETHOD(CreateInstance)(LPUNKNOWN pUnkOuter, REFIID riid,
    void** ppvObj);
};

ATL also provides three other macros that declare a class factory:

• DECLARE_CLASSFACTORY2. Uses CComClassFactory2 to control creation through a license.

  #define DECLARE_CLASSFACTORY2(lic) \
    DECLARE_CLASSFACTORY_EX(CComClassFactory2<lic>)
  

• DECLARE_CLASSFACTORY_SINGLETON. Uses CComClassFactorySingleton to construct a single CComObjectCached object and return the object in response to all instantiation requests.

  #define DECLARE_CLASSFACTORY_SINGLETON(obj) \
    DECLARE_CLASSFACTORY_EX(CComClassFactorySingleton<obj>)
  

• DECLARE_CLASSFACTORY_AUTO_THREAD. Uses CComClassFactoryAutoThread to create new instances in a round-robin manner in multiple apartments.

  #define DECLARE_CLASSFACTORY_AUTO_THREAD() \
    DECLARE_CLASSFACTORY_EX(CComClassFactoryAutoThread)
  

DECLARE_CLASSFACTORY2 and CComClassFactory2<lic>

The DECLARE_CLASSFACTORY2 macro defines CComClassFactory2 as your object’s class factory implementation. CComClassFactory2 implements the IClassFactory2 interface, which controls object instantiation using a license. A CComClassFactory2 class object running on a licensed system can provide a runtime license key that a client can save. Later, when the client runs on a nonlicensed system, it can use the class object only by providing the previously saved license key.

template <class license>
class CComClassFactory2 :
    public IClassFactory2,
    public CComObjectRootEx<CComGlobalsThreadModel>,
    public license {
public:
    ...

  STDMETHOD(CreateInstance)(LPUNKNOWN pUnkOuter, REFIID riid,
    void** ppvObj) {
    ...
    if (!IsLicenseValid()) return CLASS_E_NOTLICENSED;
    ...
    return m_pfnCreateInstance(pUnkOuter, riid, ppvObj);
  }

  STDMETHOD(CreateInstanceLic)(IUnknown* pUnkOuter,
    IUnknown* pUnkReserved, REFIID riid, BSTR bstrKey,
    void** ppvObject);
  STDMETHOD(RequestLicKey)(DWORD dwReserved, BSTR* pbstrKey);
  STDMETHOD(GetLicInfo)(LICINFO* pLicInfo);
  ...
};

Note that the main difference between CComClassFactory and CComClassFactory2 is that the latter class’s CreateInstance method creates the instance only on a licensed system – that is, IsLicenseValid returns TRUE. The additional CreateInstanceLic method always creates an instance on a licensed system but creates an instance on an unlicensed system only when the caller provides the correct license key.

The template parameter to CComClassFactory2<license> must implement the following static functions:

VerifyLicenseKey	Returns TRUE if the argument is a valid license key.
GetLicenseKey	Returns a license key as a BSTR.
IsLicenseValid	Returns TRUE if the current system is licensed.

The following is an example of a simple license class:

const OLECHAR rlk[] = OLESTR("Some run-time license key") ;

class CMyLicense
{

protected:

  static BOOL VerifyLicenseKey(BSTR bstr) {
    return wcscmp (bstr, rlk) == 0;
  }

  static BOOL GetLicenseKey(DWORD dwReserved, BSTR* pBstr) {
    *pBstr = SysAllocString(rlk);
    return TRUE;
  }

  static BOOL IsLicenseValid() {
    // Validate that the current system is licensed...
    // May check for the presence of a specific license file, or
    // may check for a particular hardware device
    if (...) return TRUE;
  }
};

You specify this license class as the parameter to the DECLARE_CLASSFACTORY2 macro in your object class. It overrides the _ClassFactoryCreatorClass typedef inherited from CComCoClass.

class ATL_NO_VTABLE CEarPolitic :
    public CComObjectRootEx<CComSingleThreadModel>,
    public CComCoClass<CEarPolitic, &CLSID_EarPolitic>,
    ...
{
public:
    DECLARE_CLASSFACTORY2 (CMyLicense)
    ...
};

The client code required for creating instances of this licensed class depends upon whether the client machine is licensed or is an unlicensed machine that instead provides a runtime license key. Typically, development is performed on a licensed machine where CoCreateInstance is used as usual. Then a call to RequestLicenseKey is used on the licensed machine to obtain a runtime license key that is persisted to file (or some other medium). CComClassFactory2 invokes IsLicenseValid to ensure that the calling code is running on a licensed machine before it hands out a runtime license key via RequestLicenseKey. Clients on nonlicensed machines then use this runtime license key to create instances using IClassFactory2::CreateInstanceLic.

Here’s what the client code might look like for creating an instance of our licensed CEarPolitic class and obtaining a runtime license key:

// Obtain pointer to IClassFactory2 interface
CComPtr<IClassFactory2> pcf;
::CoGetClassObject(__uuidof(CEarPolitic), CLSCTX_ALL, NULL,
    __uuidof(pcf), (void**)&pcf);

// Request a run-time license key
// only succeeds on licensed machine
CComBSTR bstrKey;
pcf->RequestLicKey(NULL, &bstrKey);

// Save license key to a file for distribution
// to run-time clients
FILE* f = fopen("license.txt", "w+");
fwrite(bstrKey, sizeof(wchar_t), bstrKey.Length(), f);
fclose(f);

A user operating on a nonlicensed machine with a runtime license uses that license to create instances, like this:

// Obtain a pointer to the IClassFactory2 interface
CComPtr<IClassFactory2> pcf;
::CoGetClassObject(__uuidof(CEarPolitic), CLSCTX_ALL, NULL,
    __uuidof(pcf), (void**)&pcf);

// Read in the run-time license key from disk
WCHAR szKey[1025];
FILE* f = fopen("license.txt", "r");
int n = fread((void**)&szKey, sizeof(wchar_t), 1024, f);
szKey[n] = '\0';
fclose(f);

// Create an instance of the licensed object w/ the license key
CComBSTR bstrKey(szKey);
CComPtr<IEarPolitic> p;
hr = pcf->CreateInstanceLic(NULL, NULL, __uuidof(p), bstrKey,
    (void**)&p);

DECLARE_CLASSFACTORY_SINGLETON and CComClassFactorySingleton

The DECLARE_CLASSFACTORY_SINGLETON macro defines CComClassFactorySingleton as your object’s class factory implementation. This class factory creates only a single instance of your class. All instantiation requests return the requested interface pointer on this one (singleton) instance.

The template parameter specifies the class of the singleton. The class factory creates this singleton object as a member variable, m_spObj, of the class factory.

template <class T>
class CComClassFactorySingleton : public CComClassFactory {
public:
  // IClassFactory
  STDMETHOD(CreateInstance)(LPUNKNOWN pUnkOuter, REFIID riid,
    void** ppvObj) {
    ...
    hRes = m_spObj->QueryInterface(riid, ppvObj);
    ...
    return hRes;
  }
  CComPtr<IUnknown> m_spObj;
};

The following is an example of a simple singleton class:

class CMyClass : ..., public CComCoClass< ... > {
public:
  DECLARE_CLASSFACTORY_SINGLETON(CMyClass)

  ...
};

Singletons Are EvilOr, at the Very Least, Leaning Toward the Dark Side

You should avoid using singletons, if possible. A singleton in a DLL is unique only per process. A singleton in an out-of-process server is unique only per system, at best – and often not even then because of security and multiuse settings. Typically, most uses of a singleton are better modeled as multiple instances that share state instead of one shared instance.

In the current ATL implementation, the singleton class object does not marshal the interface pointer it produces to the calling apartment. This has subtle and potentially disastrous consequences. For example, imagine that you create an inproc singleton that resides in an STA. Every client from a different STA that “creates” the singleton receives a direct pointer to the singleton object, not to a proxy to the object, as you might expect. This has the following implications:

• An inproc singleton can be concurrently accessed by multiple threads, regardless of the apartment in which it lives.

• Therefore, the singleton must protect its state against such concurrent access.

• In addition, the singleton must be apartment neutral because, conceptually, it lives in all apartments.

• Therefore, an inproc singleton must not hold apartment-specific state, such as interface pointers, but instead should keep such pointers in the Global Interface Table (GIT).

• Finally, a singleton cannot be aggregated.

A preferable approach to using singletons is to use nonsingleton “accessor” objects to access some piece of shared state. These accessor objects operate on the shared state through a lock or synchronization primitive so that the data is protected from concurrent access by multiple instances of the accessor objects. In the next example, the shared state is modeled as a simple static variable that stores a bank account object. Instances of the CTeller class access the bank account only after successfully acquiring the account lock.

class CAccount {
public:
    void Audit() { ... }
    void Open() { ... }
    void Close() { ... }
    double Deposit(double dAmount) { ... }
    double Withdraw(double dAmount) { ... }
};

static CAccount s_account;             // shared state
static CComAutoCriticalSection s_lock; // lock for serializing
                                       // account access

class CTeller {
public:
    void Deposit(double dAmount) {
        s_lock.Lock();
        s_account.Deposit(dAmount);
        s_lock.Unlock();
    }
};

This technique of factoring out the shared state of the object still provides the semantics that most people seek when they turn to singletons, but it avoids the previous problems associated with singletons because the CTeller object itself is not a singleton. Each client that wants to manipulate the CAccount shared state creates a unique instance of the CTeller class. Consequently, a CTeller COM object can live in any apartment, can hold interface pointers, and need prevent only simultaneous access to the CAccount shared state instance.

DECLARE_CLASSFACTORY_AUTO_THREAD and CComClassFactoryAutoThread

The DECLARE_CLASSFACTORY_AUTO_THREAD macro defines CComClassFactoryAutoThread as your object’s class factory implementation. This class factory creates each instance in one of a number of apartments. You can use this class only in an out-of-process server. Essentially, this class factory passes every instantiation request to your server’s global instance of CAtlAutoThreadModuleT (discussed shortly), which does all the real work:

class CComClassFactoryAutoThread :
  ...
  STDMETHODIMP CreateInstance(LPUNKNOWN pUnkOuter, REFIID riid,
    void** ppvObj) {
    ...
    hRes = _pAtlAutoThreadModule.CreateInstance(
      m_pfnCreateInstance,riid, ppvObj);
    ...
  }
  ...
  _ATL_CREATORFUNC* m_pfnCreateInstance;
};

Whenever a server contains any classes using the DECLARE_CLASSFACTORY_AUTO_THREAD macro, the server’s project.cpp file must declare a global instance of CAtlAutoThreadModule. (The name of the global variable used is immaterial.) The _pAtlAutoThreadModule variable shown earlier in the implementation of CreateInstance points to the global instance of CAtlAutoThreadModule that you declare in your project.cpp file. CAtlAutoThreadModule implements a pool of single-thread apartments (STAs) in an out-of-process server. By default, the server creates four STAs per processor on the system. The class factory forwards each instantiation request, in a round-robin order, to one of the STAs. This allocates the class instances in multiple apartments, which, in certain situations, can provide greater concurrent execution without the complexity of writing a thread-safe object.

The following is an example of a class that uses this class factory:

class CMyClass : ..., public CComCoClass< ... > {
public:
  DECLARE_CLASSFACTORY_AUTO_THREAD()

  ...
};

CAtlAutoThreadModuleT implements the IAtlAutoThreadModule interface, which ATL uses to create instances within CComClassFactoryAutoThread. You can name the global variable anything you want, [7] so the following declaration works just fine.

[7]

However, names with leading underscores are reserved to the compiler and library vendor, so you should avoid using them so you don’t run into conflicts with your libraries.

// project.cpp
CAtlAutoThreadModule g_AtlAutoModule;    // any name will do

ATL declares a global variable of type IAtlAutoThreadModule in atlbase.h.

__declspec(selectany)
IAtlAutoThreadModule* _pAtlAutoThreadModule;

This global variable is set in the constructor of CAtlAutoThreadModuleT, which is the template base class for CAtlAutoThreadModule:

template <class T,
    class ThreadAllocator = CComSimpleThreadAllocator,
    DWORD dwWait = INFINITE>
class ATL_NO_VTABLE CAtlAutoThreadModuleT
    : public IAtlAutoThreadModule {
public:
    CAtlAutoThreadModuleT(
        int nThreads = T::GetDefaultThreads()) {
        // only one per server
        ATLASSERT(_pAtlAutoThreadModule == NULL);
       _pAtlAutoThreadModule = this;
       m_pApartments = NULL;
       m_nThreads= 0;
    }
    ...
};

CComClassFactoryAutoThread checks that this _pAtlAutoThreadModule global is non-NULL before delegating instantiation requests to it. Debug builds issues an assertion indicating that you have not declared an instance of CAtlAutoThreadModule. Release builds simply return E_FAIL from the CreateInstance call.

CAtlAutoThreadModule uses CComApartment to manage an apartment for each thread in the module. The template parameter defaults to CComSimpleThreadAllocator, which manages thread selection for CComAutoThreadModule.

class CComSimpleThreadAllocator {
public:
    CComSimpleThreadAllocator() { m_nThread = 0; }
    int GetThread(CComApartment* /*pApt*/, int nThreads) {
        if (++m_nThread == nThreads) m_nThread = 0;
        return m_nThread;
    }
    int m_nThread;
};

CComSimpleThreadAllocator provides one method, GetThread, which selects the thread on which CAtlAutoThreadModuleT creates the next object instance. You can write your own apartment selection algorithm by creating a thread allocator class and specify it as the parameter to CAtlAutoThreadModuleT.

For example, the following code selects the thread (apartment) for the next object instantiation randomly (though it has the downside that I’m using a C runtime library function to get the random number).

class CRandomThreadAllocator {
public:

   int GetThread(CComApartment* /*pApt*/, int nThreads) {
       return rand () % nThreads;
   }
};

Instead of selecting the default thread allocator by using CAtlAutoThreadModule, you create a new class that derives from CAtlAutoThreadModuleT and specify your new thread-selection class as the template parameter.

// project.cpp
class CRandomThreadModule :
public CAtlAutoThreadModuleT< CRandomThreadModule,
    CRandomThreadAllocator>
{
...
};

CRandomThreadModule g_RandomThreadModule; // name doesn't matter

Finally! You’ve seen the object map, which is a fundamental data structure in an ATL server. You’ve seen the various requirements and options for classes, both createable and noncreateable, for the classes to be listed in the object map. Now let’s look at the part of ATL that actually uses the object map: the CAtlModule class, its derived classes, and the global variable of that type called _AtlModule.

The CAtlModule Class

All COM servers need to support registration, class objects, and lifetime management. Each type of server provides its registration, class objects, and lifetime management slightly differently, but the basic required functionality is the same for all types of servers.

ATL defines the CAtlModule base class and three derived classes, along with numerous helper methods that support server registration, class objects, and lifetime management. Each of the three derived classes provides support for a specific COM server type. CAtlDllModuleT provides inproc server functionality; CAtlExeModuleT and CAtlServiceModuleT support local servers and Windows service applications, respectively. Many of the methods in these classes simply iterate over the entries in the object map and ask each class in the map to perform the real work.

When you create an ATL COM server project using the Visual C++ ATL project wizard, it generates relatively boilerplate code that uses functionality in one of the CAtlModule-derived classes to implement the server.

An ATL server contains one global instance of the CAtlModule class, which the ATL project wizard names _AtlModule. The _AtlModule instance also holds state global to the entire server. You can access this via the global pointer _pAtlModule.

The _AtlModule Global Variable

An ATL inproc server uses the CAtlDllModuleT class directly by declaring a global instance of a project-specific module class derived from the CAtlDllModuleT server’s project.cpp file. Here’s what the module class definition and global variable declaration look like in the wizard-generated code for an inproc server called Math:

class CMathModule : public CAtlDllModuleT< CMathModule > {
public:
    DECLARE_LIBID(LIBID_Math)
    DECLARE_REGISTRY_APPID_RESOURCEID(IDR_MATH,
        "{9CB95B71-536A-476a-9244-61363F5C60CA}")
};

CMathModule _AtlModule;

The DECLARE_LIBID macro simply sets the m_libid member variable of the CAtlModule base class to the GUID value supplied as the macro parameter. The DECLARE_REGISTRY_APPID_RESOURCEID macro declares an UpdateRegistryAppId method and helper functions for registering the AppId for the server.

The custom module class that the wizard generates provides a place for you to customize the functionality of ATL’s module classes. In many places, CAtlDllModuleT (as well as CExeModuleT and CServiceModuleT) downcasts to your custom module class so that a custom method is invoked if one is supplied. For instance, look at the implementation of DllRegisterServer that CAtlDllModuleT provides:

HRESULT DllRegisterServer(BOOL bRegTypeLib = TRUE) {
    T* pT = static_cast<T*>(this);
    HRESULT hr = pT->RegisterAppId();
    if (SUCCEEDED(hr))
        hr = pT->RegisterServer(bRegTypeLib);
    return hr;
}

Here, if your CMathModule had defined a custom version of RegisterAppId or RegisterServer, those custom versions would be invoked in lieu of the default implementation provided in CAtlDllModuleT.

A local server defines a specialized version of CAtlModule, called CAtlExeModuleT, in the server’s project.cpp file:

class CMathModule : public CAtlExeModuleT< CMathModule > {
public:
   DECLARE_LIBID(LIBID_Math)
   DECLARE_REGISTRY_APPID_RESOURCEID(IDR_MATH,
       "{9CB95B71-536A-476a-9244-61363F5C60CA}")
};

CMathModule _AtlModule;

A service-based server also defines a specialized version of CAtlModule, called CAtlServiceModuleT, in the server’s project.cpp file:

class CMathModule :
    public CAtlServiceModuleT< CMathModule, IDS_SERVICENAME >
{
public:
    DECLARE_LIBID(LIBID_Math)
    DECLARE_REGISTRY_APPID_RESOURCEID(IDR_MATH,
    "{9CB95B71-536A-476a-9244-61363F5C60CA}")
};

CMathModule _AtlModule;

The CAtlModule Registration Support

The CAtlModuleT class has extensive support for registration and unregistration of COM objects and servers.

The RegisterServer and UnregisterServer Methods

The RegisterServer and UnregisterServer methods add or remove standard class registration information (ProgID, version-independent ProgID, class description, and threading model) into or from the system Registry. These methods call upon a global instance of CAtlComModule, which, in turn, uses the AtlComModuleRegisterServer and AtlComModuleUnregisterServer helper functions to perform the actual task.

HRESULT RegisterServer(BOOL bRegTypeLib = FALSE,
    const CLSID* pCLSID = NULL);
HRESULT UnregisterServer(BOOL bUnRegTypeLib = FALSE,
    const CLSID* pCLSID= NULL);

The RegisterServer method updates the system Registry for a single class object when the pCLSID parameter is non-NULL. When the parameter is NULL, the method calls the UpdateRegistry method for all classes listed in the object map. When the bRegTypeLib parameter is TRUE, the method also registers the type library.

The UnregisterServer method removes the Registry entries for a single class when the pCLSID parameter is non-NULL. When the parameter is NULL, the method calls the UpdateRegistry method for all classes listed in the object map. The overloaded method that accepts a bUnRegTypeLib parameter also unregisters the type library when the parameter is TRUE.

Inproc servers call upon this support from their DllRegisterServer and DllUnregisterServer functions:

STDAPI DllRegisterServer(void) {
    return _AtlModule.DllRegisterServer();
}

STDAPI DllUnregisterServer(void) {
    return _AtlModule.DllUnregisterServer();
}

The calls to CAtlDllModuleT’s DllRegisterServer and DllUnregisterServer functions invoke RegisterServer and UnregisterServer on the CAtlModule base class. The calls to RegisterAppId and UnRegisterAppId execute the server’s registration script. The DECLARE_REGISTRY_APPID_AND_RESOURCEID macro we supplied in our CAtlModule-derived class defined an UpdateRegistryAppId function that runs the server’s registration script.

template <class T>
class ATL_NO_VTABLE CAtlDllModuleT : public CAtlModuleT<T> {
public :
      ...
    HRESULT DllRegisterServer(BOOL bRegTypeLib = TRUE) {
      T* pT = static_cast<T*>(this);
      // server script
      HRESULT hr = pT->RegisterAppId();
      if (SUCCEEDED(hr))
        // all class scripts
        hr = pT->RegisterServer(bRegTypeLib);
      return hr;
    }
    HRESULT DllUnregisterServer(BOOL bUnRegTypeLib = TRUE) {
      T* pT = static_cast<T*>(this);
      // all class scripts
      HRESULT hr = pT->UnregisterServer(bUnRegTypeLib);
      if (SUCCEEDED(hr))
        // server script
        hr = pT->UnregisterAppId();
      return hr;
    }
    ...
};

With a local server, the ATL wizard generates a WinMain that simply delegates to CAtlExeModuleT::WinMain. This code parses the command line to determine which action (register or unregister) to take and then delegates the work to CAtlModule.

bool CAtlExeModuleT< T >::ParseCommandLine(LPCTSTR lpCmdLine,
  HRESULT* pnRetCode) {
  ...

  if (WordCmpI(lpszToken, _T("UnregServer"))==0) {
    *pnRetCode = pT->UnregisterServer(TRUE);
    if (SUCCEEDED(*pnRetCode))
      *pnRetCode = pT->UnregisterAppId();
    return false;
  }

  // Register as Local Server
  if (WordCmpI(lpszToken, _T("RegServer"))==0) {
    *pnRetCode = pT->RegisterAppId();
    if (SUCCEEDED(*pnRetCode))
      *pnRetCode = pT->RegisterServer(TRUE);
    return false;
  }

  ...

  return true;
}

The UpdateRegistryFromResource Methods

Notice that a COM server first calls the RegisterAppId to register the server-specific entries before registering the class-specific entries. This method calls the UpdateRegistryAppId method that our DECLARE_REGISTRY_APPID_RESOURCEID macro generates. Ultimately, the real work is delegated to the UpdateRegistryFromResource member function.

When you define the preprocessor symbol _ATL_STATIC_REGISTRY, the UpdateRegistryFromResource method maps to UpdateRegistryFromResourceS. When you do not define this preprocessor symbol, the method maps to UpdateRegistryFromResourceD. (The S or D stands for Static or Dynamic.) The difference between the two functions is simple: UpdateRegistryFromResourceS eventually calls code in atlbase.h that updates the Registry. The implementation of UpdateRegistryFromResourceD, on the other hand, calls out to the ATL Registrar component in atl80.dll [8] to do the registration. As a result, if you don’t define _ATL_STATIC_REGISTRY, you need to distribute atl80.dll along with your COM server. [9]

[8]

Actually, this can be atl7.dll, atl71.dll, or atl80.dll, depending on the version of ATL you’re compiling against.

[9]

atl80.dll is about 93KB in size. Separate versions of the registrar DLL used to exist for Win9x and WinNT, but they appear to have merged in this version of the library. Personally, I recommend using static linking just to avoid the need to distribute another DLL because the size cost is fairly minor.

#ifdef _ATL_STATIC_REGISTRY
#define UpdateRegistryFromResource UpdateRegistryFromResourceS
#else
#define UpdateRegistryFromResource UpdateRegistryFromResourceD
#endif

    // Resource-based Registration
#ifdef _ATL_STATIC_REGISTRY
    // Statically linking to Registry Component
    HRESULT WINAPIUpdateRegistryFromResourceS(LPCTSTR lpszRes,
        BOOL bRegister,
        struct _ATL_REGMAP_ENTRY* pMapEntries = NULL);
    HRESULT WINAPIUpdateRegistryFromResourceS(UINT nResID,
        BOOL bRegister,
        struct _ATL_REGMAP_ENTRY* pMapEntries = NULL);
#else
    HRESULT WINAPIUpdateRegistryFromResourceD(LPCTSTR lpszRes,
        BOOL bRegister,
        struct _ATL_REGMAP_ENTRY* pMapEntries = NULL) {
            USES_CONVERSION;
            return UpdateRegistryFromResourceDHelper(T2COLE(lpszRes),
                               bRegister, pMapEntries);
    }
    HRESULT WINAPIUpdateRegistryFromResourceD(UINT nResID,
        BOOL bRegister,
        struct _ATL_REGMAP_ENTRY* pMapEntries = NULL) {
        return UpdateRegistryFromResourceDHelper(
                     (LPCOLESTR)MAKEINTRESOURCE(nResID),
                     bRegister, pMapEntries);
    }
#endif

The Type Library Registration Methods

ATL provides a few other registration helper methods:

// Registry support (helpers)
HRESULT RegisterTypeLib();
HRESULT RegisterTypeLib(LPCTSTR lpszIndex);
HRESULT UnRegisterTypeLib();
HRESULT UnRegisterTypeLib(LPCTSTR lpszIndex);

As you might expect, RegisterTypeLib registers the type library contained in your server’s resources. UnRegisterTypeLib unregisters it, of course. These two methods expect the type library to be present in your server’s resources as a custom resource of type TYPELIB with integer resource identifier 1. You create such a resource by adding the following line to your server’s .rc file.

1 TYPELIB "ATLInternals.tlb"

You can embed multiple type libraries in a server, although it’s an unusual thing to do. You simply need to give them unique integer resource identifiers.

1 TYPELIB "ATLInternals.tlb"
2 TYPELIB "ATLInternalsEx.tlb"

To register and unregister the second type library, you must call the RegisterTypeLib or UnRegisterTypeLib methods, respectively, and specify a string in the form ``”\N”``, where ``N`` is the integer index of the TYPELIB resource. The following lines register both type libraries from the previous resource script example:

_AtlModule.RegisterTypeLib ();
_AtlModule.RegisterTypeLib (_T ("\\2"));

CComCoClass Revisited

Earlier in this chapter, you saw how deriving from CComCoClass provided your class with a default implementation of a class factory, as well as default support for aggregation.

CComCoClass provides aggregation support via inheritance of the DECLARE_AGGREGATABLE macro’s typedef of _CreatorClass. It also provides the default implementation of a class factory via inheritance of the DECLARE_CLASS_FACTORY macro’s _ClassFactoryCreatorClass typedef.

The Error Methods

CComCoClass also provides a number of other useful static methods. Six of the methods are overloaded and call Error. They set up the COM Error object using its IErrorInfo interface to provide rich error information to the client. To call Error, your object must implement the ISupportErrorInfo interface.

When the hRes parameter is nonzero, Error returns the value of hRes. When hRes is zero, the first four versions of Error return DISP_E_EXCEPTION. The remaining two functions return the result of the macro MAKE_HRESULT(3, FACILITY_ITF, nID), creating a custom failure HRESULT.

static HRESULT WINAPI
Error(LPCOLESTR lpszDesc, const IID& iid = GUID_NULL,
    HRESULT hRes = 0);

static HRESULT WINAPI
Error(LPCOLESTR lpszDesc, DWORD dwHelpID, LPCOLESTR lpszHelpFile,
      const IID& iid = GUID_NULL, HRESULT hRes = 0);

static HRESULT WINAPI
Error(LPCSTR lpszDesc, const IID& iid = GUID_NULL,
    HRESULT hRes = 0);

static HRESULT WINAPI
Error(LPCSTR lpszDesc, DWORD dwHelpID, LPCSTR lpszHelpFile,
      const IID& iid = GUID_NULL, HRESULT hRes = 0);

static HRESULT WINAPI
Error(UINT nID, const IID& iid = GUID_NULL, HRESULT hRes = 0,
      HINSTANCE hInst = _AtlBaseModule.GetResourceInstance());

static HRESULT WINAPI
Error(UINT nID, DWORD dwHelpID, LPCOLESTR lpszHelpFile,
      const IID& iid = GUID_NULL, HRESULT hRes = 0,
      HINSTANCE hInst = _AtlBaseModule.GetResourceInstance());

It might seem odd that ATL includes the Error functionality in CComCoClass instead of in a more widely applicable place, such as CComObjectRootEx. The reason for this placement is that COM error reporting needs a CLSID, and the CLSID is stored in CComCoClass. If you need to generate rich error information when your class isn’t derived from CComCoClass, you can always call the ATL helper function AtlReportError. The CComCoClass::Error methods all use this helper function.

inline HRESULT WINAPI AtlReportError(const CLSID& clsid,
    UINT nID,
    const IID& iid = GUID_NULL,
    HRESULT hRes = 0,
    HINSTANCE hInst = _AtlBaseModule.GetResourceInstance());

inline HRESULT WINAPI AtlReportError(const CLSID& clsid,
    UINT nID, DWORD dwHelpID, LPCOLESTR lpszHelpFile,
    const IID& iid = GUID_NULL,
    HRESULT hRes = 0,
    HINSTANCE hInst = _AtlBaseModule.GetResourceInstance());

inline HRESULT WINAPI AtlReportError(const CLSID& clsid,
    LPCSTR lpszDesc,
    DWORD dwHelpID, LPCSTR lpszHelpFile,
    const IID& iid = GUID_NULL,
    HRESULT hRes = 0);

inline HRESULT WINAPI AtlReportError(const CLSID& clsid,
    LPCSTR lpszDesc,
    const IID& iid = GUID_NULL, HRESULT hRes = 0);

inline HRESULT WINAPI AtlReportError(const CLSID& clsid,
    LPCOLESTR lpszDesc,
    const IID& iid = GUID_NULL, HRESULT hRes = 0);

inline HRESULT WINAPI AtlReportError(const CLSID& clsid,
    LPCOLESTR lpszDesc, DWORD dwHelpID, LPCOLESTR lpszHelpFile,
    const IID& iid = GUID_NULL, HRESULT hRes = 0);

The Instantiation Methods

CComCoClass also provides two useful overloaded CreateInstance methods that create an instance of your class, one for creating an aggregated instance of your class and one that creates a nonaggregated instance:

template <class Q>
static HRESULT CreateInstance(IUnknown* punkOuter, Q** pp) {
  return T::_CreatorClass::CreateInstance(punkOuter, __uuidof(Q),
    (void**) pp);
}

template <class Q>
static HRESULT CreateInstance(Q** pp) {
  return T::_CreatorClass::CreateInstance(NULL, __uuidof(Q),
    (void**) pp);
}

You use these two methods like this.

ISpeaker* pSpeaker;
// Creates non-aggregated instance
HRESULT hr = CDemagogue::CreateInstance (&pSpeaker);
// Creates aggregated instance (assuming the class supports aggregation
HRESULT hr = CDemagogue::CreateInstance (punkOuter, &pSpeaker);

Note that the use of the __uuidof operator in the template functions means that you do not have to specify the interface ID for the interface that you want on the newly instantiated object. The compiler gets the ID from the type of the interface pointer variable you pass as an argument to the CreateInstance method.

ATL and the C Runtime Library

By default, ATL projects link with the C runtime library (CRT) in both debug and release configurations. Although linking with the CRT increases the size of each ATL server, the CRT provides useful functionality for memory management, string manipulation, and exception handling. Additionally, the CRT is responsible for calling the constructors of global objects when an executable is loaded. As a result, constructing anything but the most simplistic of projects without such important CRT functionality is impractical.

In the spirit of allowing developers to minimize the memory footprint of their COM servers, ATL provides a subset of CRT functionality that can be used in place of the CRT itself. By defining the preprocessor symbol _ATL_MIN_CRT, ATL projects will not link with the CRT. You can define this symbol from the project properties, as shown in Figure 5.2.

Figure 5.2. Defining _ATL_MIN_CRT in an ATL server

[View full size image]

Setting Minimize CRT Use in ATL causes _ATL_MIN_CRT to be defined and keeps your server from linking with the CRT. It’s important to realize that ATL does not make available all the functions that the CRT provides when this option is in use. If you happen to use a function that requires the CRT when _ATL_MIN_CRT is defined, you’ll get the following somewhat cryptic linker error:

LIBCMT.LIB(crt0.obj) : error LNK2001:
unresolved external symbol _main

In ATL 3 and earlier, using _ATL_MIN_CRT left out one very important feature of the CRT: static and global object initialization. Global and static objects would not have their constructors or destructors called. Thankfully, ATL 7 and later provide an implementation of this feature even without CRT support. Inproc ATL servers include an implementation of _DllMainCRTStartup that invokes global constructors and destructors. ATL itself relies upon global constructors and destructors in many key places throughout the framework. For instance, in the discussion of ObjectMain presented earlier in this chapter, I told you that ATL invokes ObjectMain when a server initializes without explaining precisely how this was done. With global constructors available both with and without _ATL_MIN_CRT defined, ATL is perfectly safe to invoke the ObjectMain methods of each class in the object map by using the constructor of the global CAtlModule instance:

template <class T>
class ATL_NO_VTABLE CAtlDllModuleT : public CAtlModuleT<T> {
public :
    CAtlDllModuleT() {
        _AtlComModule.ExecuteObjectMain(true);
    }

    ~CAtlDllModuleT() {
        _AtlComModule.ExecuteObjectMain(false);
    }
    ...
}

Summary

The object map is the primary data table that the CAtlModule-derived _AtlModule object uses to register and unregister the classes in the server. CAtlModule provides numerous helper methods you can use to register and unregister your server, the classes in the server, and the component categories in the classes.

An ATL server creates a class factory for a class, as needed, using the class-creator function entry in the object map. This class factory then creates instances of the class using the instance-creator function entry in the object map. Typically, you inherit a default specification for the implementation of these two creator classes when you derive your class from CComCoClass. However, with the appropriate macro entries in your class, you can override these defaults and provide a custom class factory and custom instance creator function.

CComCoClass has some useful utility functions for reporting rich errors to a client using the COM ErrorInfo protocol. The class also has convenient instantiation methods that create an instance and query for the proper interface based on the type of the provided interface pointer variable.