Let's turn our attention to the implementation of Release. When it comes to releasing an object, different languages impose different degrees of responsibility on the object developer. In C++, for example, the language has no inherent garbage collection functionality, so the developer must deallocate the object himself. Unlike many 4GL languages, in C++, an equality operator does not natively have an overloaded meaning. So, the following line means that a 0 is placed in the pointer variable pICalc:

   pICalc=NULL; //BAD!

This does not inform the Calc object of anything; in fact, you have made an orphan out of the object because you no longer hold a reference to it. How then, can you tell Calc that its services are no longer required? Because the ICalc interface you hold is inherited from IUnknown, it must support a function called Release().This is exactly what Release() does—it informs the object that someone has just lost interest in it. Therefore, to ask your object to destroy itself when you are done with it, you simply use the following code:

   pICalc->Release();

The object now destroys itself. If you wonder how IUnknown got involved with ICalc, just remember that ICalc is inherited from IUnknown. Look again at the type library in Listing 2.1.

    [
        object,
        uuid(638094E5-758F-11d1-8366-0000E83B6EF3),
        oleautomation,
        helpstring("ICalc Interface"),
        pointer_default(unique)
    ]
    interface ICalc : IUnknown
    {
    [id(1), helpstring("method Add")] HRESULT Add([in] int x, [in] int y,
                                                  [out,retval] int * r );
    [id(2), helpstring("method Subtract")] HRESULT Subtract([in] int x, [in] int y,
                                                            [out,retval] int * r );

Remember that MIDL.EXE was run on this IDL file, and a header file containing an ICalc proxy class was generated. This header file is to be included in the client application so that it is possible to declare ICalc pointers. Thus, the following line is possible:

ICalc * pICalc;

This line is possible because just above it in the source file is the following line, which includes the MIDL-generated header file:

#include "calc.h" //MIDL generated this from the type library

If you look in this header file, you will find the code shown in Listing 2.2.

MIDL_INTERFACE("638094E5-758F-11d1-8366-0000E83B6EF3")
    ICalc : public IUnknown
    {
    public:
        virtual /* [helpstring][id] */ HRESULT STDMETHODCALLTYPE Add(
            /* [in] */ int x,
            /* [in] */ int y,
            /* [retval][out] */ int __RPC_FAR *r) = 0;

        virtual /* [helpstring][id] */ HRESULT STDMETHODCALLTYPE Divide(
            /* [in] */ int x,
            /* [in] */ int y,
            /* [retval][out] */ int __RPC_FAR *r) = 0;


    } ;

There is no escape from the unknown (or IUnknown). Every interface inherits from IUnknown, so every interface must support AddRef(), Release(), and QueryInterface(). Normally, however, every interface just delegates all of its method calls to the derived object as shown in Figure 2.1.

The point is that every object supports and implements the methods of IUnknown, and the methods of IUnknown can be called from any interface the object supports.

This means that every COM object ever written must know what to do when Release() is called on any of its interfaces. In the C++ case, this responsibility often falls on the developer (unless he is using the Active Template Library [ATL]), and it is typically addressed as shown in Listing 2.3.

SomeObject::Release()
{
    m_ObjectCount--,
    if(m_ObjectCount==0)
        delete this;
}

In VB and VJ++, this code is generated automatically, and the developer doesn't have to write it.

A client is solely responsible for the lifetime of an object. Always remember that AddRef() and Release() are member functions implemented by the object itself; they are not COM system functions. They are available to your client only after the object is instantiated and one of its interfaces is delivered to the client. When a client calls AddRef() on any interface, the object should take note of it and increment its internal reference count by one. If Release() is called, the object should decrement its reference count by one. AddRef() never initiates any other kind of action, creation or otherwise. It simply means add one to the reference. Likewise, Release() does nothing more than decrement the reference count until the reference count is 0. When this happens, the object should destroy itself because a reference count of 0 indicates that no clients hold any interface pointers to it.

The following are some guidelines for when these functions should be called:

This is traditional COM. COM+, however, throws a big wrench in all this. Lifetimes are no longer so clear; the reference counting rules should still be followed, but COM+ might elect to keep an object alive even when there are no longer any clients for it and its reference count is zero. I'll explain exactly how this works in Appendix C, "Object Pooling."

Let's use QueryInterface() in a more common context. If you recall our earlier Calc example in Chapter 1, "COM+: An Evolution," we proposed that the object have two interfaces, ICalc and IFinancial. In this way, the object can partition its functionality into two distinct groups or interfaces, each of which contains methods grouped by functionality. If the client is interested in basic arithmetic functions, it can ask for ICalc. If it is interested in financial functions, it can ask for IFinancial. If your COMCalc supports both interfaces, the IDL file would look like Listing 2.4.

import "oaidl.idl";
import "ocidl.idl";

    [
        object,
        uuid(638094E5-758F-11d1-8366-0000E83B6EF3),
        dual,
        oleautomation,
        helpstring("ICalc Interface"),
        pointer_default(unique)
    ]
    interface ICalc : IUnknown
    {
        [id(1), helpstring("method Add")] HRESULT Add([in] int x, [in] int y,
                                         [out,retval] int * r );
        [id(2), helpstring("method Divide")] HRESULT Divide([in] int x,
                                         [in] int y, [out,retval] int * r);
    } ;

    [
        object,
        uuid(638094E4-758F-11d1-8366-0000E83B6EF3),
        dual,
        helpstring("IFinancial Interface"),
        pointer_default(unique),

    ]

    interface IFinancial : IUnknown
    {
        [id(1), helpstring("method MortgagePayment")]
        HRESULT MortgagePayment([in] double amount, [in] double percent,
                                [in] int period,
                                [out,retval]float * payment);
        [id(2), helpstring("method GetPrimeRate")]
        HRESULT GetPrimeRate( [out,retval]double * rate);

    } ;


 [
    uuid(638094E1-758F-11d1-8366-0000E83B6EF3),
    version(1.0),
    helpstring("COMCalc 1.0 Type Library")
]
library COMCALCLib
{
    importlib("stdole32.tlb");
    importlib("stdole2.tlb");

    [
        uuid(638094E0-758F-11d1-8366-0000E83B6EF3),
        helpstring("Calc Class")
    ]
    CoClass COMCalc
    {
        [default] interface ICalc;
        interface IFinancial;

    };

} ;

The C++ client can choose which interface it wants (see Listing 2.5).

ICalc * pICalc;
IFinancial * pIFin;

CoCreateInstance(CLSID_COMCalc, 0,CLSCTX_INPROC_SERVER , IID_ICalc, (void**)&pICalc);

int result=pICalc->Add(1,2);
pICalc->QueryInterface(IID_IFinancial, (void**)&pIfin);
float rate=pIFin->GetPrimeRate();
pICalc->Release();
pIFinancial->Release();

A Visual Basic client is much simpler and can be written as shown in Listing 2.6.

Dim myCalc as new VBCalc.COMCalc
Dim Financial as IFinancial

Result=myCalc.Add (1,2)
Set  Financial = myCalc

In Visual Basic, the Set keyword usually translates to a QueryInterface() method call. Although you do not see or work directly with the GUIDs as you do in C++, they are present and maintained by the development environment. Specifically, by including your component's type library in your project by choosing Project, References, the component's GUIDs are included and implicitly used. The resulting list of type libraries is shown in Figure 2.2.

VB knows all the GUIDs, objects, and so on that it needs. So, the VB line

Set Financial = myCalc

is translated behind the scenes to something like

pICalc->QueryInterface({ 0x638094e4,0x758f,0x11d1,{ 0x83,0x66,0x00,0x00,0xe8,
    0x3b,0x6e,0xf3} } ,(void**)&pIFin);

When prefaced by the Set keyword, VB reads the left side of the =, looks up the GUID for the object (IFinancial) in the object's type library, and uses that GUID in a QueryInterface call made on the object to the right of the = (which is myCalc).

Figure 2.2. Visual Basic lists all the registered type libraries.

So, what does all this have to do with type libraries? Well, another benefit of the resource section of DLLs (and EXEs) is that they are extensible in terms of the kind of data they allow you to store. Think of the resource section as the kitchen junk drawer—it usually has extra twisty-ties, crazy glue, and usually a tape measure, but it can really have just about anything in it. Although there is built-in Win32 support for bitmaps, dialog boxes, icons, and the like, you can put anything you want in the resource section. Some application designers stuff .WAV files or .AVI movie files in the resource section so that they can ship a single DLL or EXE with no dependencies.

COM takes advantage of this fact, and there is support for stuffing type libraries in the resource section. Remember, this is just a convenience. No one says that type libraries must be in the resources of your DLL. Although most COM DLLs do include type libraries in their resources, you can ship two files: your COM DLL and a separate type library. Microsoft Excel does this. Although Excel is a traditional application EXE, it also supports a host of COM objects that you can use to remote control Excel. The type library for Excel is greater than 0.5MB. That's a lot of IDL, and unless you want to make the EXE that much bigger, shipping the type library as a separate file is not a bad idea.

The discussion of type libraries in the previous section begs the following question: If the type library and the component can be two separate things and can even be in separate files, how can COM associate the two? The answer is the component must be officially registered with COM. In the good old days of 16-bit VB 3, the late-cretaceous ancestor of modern ActiveX controls, the VBX roamed the OS. If you wanted to add a new component to the system so that you could use it in VB 3, all you had to do was put a new VBX file in the C: Windows System directory, and that was all there was to it. There would be a new control on your tool palette which you could just drag and drop onto your form. I must admit, sometimes I miss the simplicity of this. Modern COM, however, is more exacting. VBXs are gone and replaced by OCXs, which are really just DLLs with COM objects and a type library inside them. The path to the COM DLL, the objects inside of it, and the location of its type library (whether the TLB path is the same as the DLL or is a separate file) must be known to COM before they can be used. COM DLLs, therefore, are self-registering. By this, I mean that COM DLLs know exactly what COM needs to know and have the capability to put the appropriate entries in the Registry so that COM knows about them and can use them.

Although COM DLLs know how to put the appropriate entries in the Registry, they are powerless to do so themselves. DLLs are always loaded and acted upon by a host process (EXE), so a COM DLL needs to be loaded by an application and askedto register itself. This creates a chicken-or-egg scenario for COM clients: a client needs to know what DLL an object is in if it were to ask the DLL to register itself; but if it knows what DLL the object is in, there is no need for the DLL to register itself. The solution is COM clients do not register COM DLLs—either you do it manually using a utility called regsvr32.exe or some Windows Setup.EXE program performs the registration behind the scenes. In the former case, if I syou a COM DLL called comcalc.dll and promise you that there is a calculator object in it, you would register it by going to the command prompt and typing the following:

regsvr32.exe comcalc.dll

Regsvr32.exe is a very simple program. It simply loads the DLL, looks for an exported function that all COM DLLs have called DLLRegister(), and the DLL does the rest. When DLLRegisterServer() is complete, the function returns and regsvr32.exe exits. The approximate code in C for regsvr32.exe is something like that shown in Listing 2.7.

main(int argc, char **argv)
{
HMODULE h;
HRESULT (STDAPICALLTYPE *v)(void);

h=LoadLibrary(argv[1]);
(FARPROC&)v = GetProcAddress(h, "DllRegisterServer");

(*v)();

}

You get the idea. DLLRegisterServer() takes the ball and runs with it. In VB and VJ++, the code for this function is created for you. In C++, you write it yourself unless you are using a class library like ATL and using the accompanying VC++ IDE ATL wizard support. Fundamentally, DLLRegisterServer() must do the following two things:

The first point is not that complex. COM needs to know where the DLL can be located, what the coclasses (objects) are, and what their GUIDs are. It must also indicate how thread-safe the DLL is—that is, can it handle concurrent access from many different threads at once. If the answer is no, COM automatically makes the component thread-safe by providing protection for it. Threads and thread safety are discussed in depth in Chapter 4, "Threading and Apartment Models." Specifically, the minimum Registry entries a DLL enters are shown in Figure 2.4.

Figure 2.4. Registry settings for a typical component.

The second point is also simple. Type libraries must be separately registered. As I said, they might very well be located in the same DLL as the objects it describes, but this doesn't matter. When registering, the DLL registers its type library by calling a Win32 function called, appropriately, RegisterTypeLib(). This function takes as an argument the path of the type library, and from here, Windows performs some magic. This magic takes the form of placing the type library path and GUID in the Registry in a section called TypeLib, shown in Figure 2.5.

This list is what you see when you select Project, References in VB. This Registry entry, however, is not all that happens. COM reads the type library and also registers additional information about the interfaces contained in the type library. In fact, if you look in HKEY_CLASSES_ROOT Interface , you will find your ICalc and IFinancial interfaces listed by their GUID, as shown in Figure 2.6.

Figure 2.5. The section of the Registry where type libraries are listed (HKEY_CLASSES_ROOT TypeLib).

Figure 2.6. Information on interfaces are kept in the Registry at HKEY_CLASSES_ROOT Interface.