ATL / COM II

Active Template Library.

A set of C++ template classes designed for the creation of small / fast COM objects
Automatic support for IUnknown and other standard interfaces through a “stock code” approach.
ATL is supplied as source code, but MS also supply a DLL (atl.dll) which you can link to if you prefer.
Internally, ATL uses multiple-inheritance a lot (MFC does not)
If you need to access the C run time library from within an ATL project, remove the _ATL_MIN_CRT pre-processor definition from the release build configuration.

Files in an ATL project:

Resource.h, X.cpp, X.h, x.dws & X.dsp
As you would expect
X.rgs
Registry entries definition script. Holds the values and conditions used by the ATL to install / remove / reinstall the COM object. (As triggered by /regserver & /unregserver for an EXE and regsvr32 for a DLL.
X.idl
The Interface Definition Language file (as passed to the MIDL tool during compilation)
Xps.mk
The project file for the proxy stub DLL. This file is not generated unless needed (e.g. when creating an out of process EXE server). This file will also not be generated if you selected “Merge Proxy and Stub” in the Wizard.
Xps.def
The exported function list for the proxy stub DLL. This file is not generated unless needed (e.g. when creating an out of process EXE server). This file will also not be generated if you selected “Merge Proxy and Stub” in the Wizard.

ATL Object Wizard

Simple
Basic COM object
ActiveX Server
For IIS / ASP. Think CGI replacement.
Component Registrar
Only needed if we plan to include more than one COM object in a single DLL as ATL will use one of these with our RGS file anyway.

COM

If IB inherits from IA, and you want to use the IA interface on IB don’t just cast IB to IA. Although the cast will often work, it will fail if proxy or stub code is involved. Instead, you should use QueryInterface to obtain a pointer to IA, e.g.:

hr = pIB->QueryInterface(IID_IA, &pIA);

Note: QueryInterface cannot be used to obtain an unrelated interface – you have to use CoCreateInstance again.

Tear-off Interfaces: Interfaces that defer initialisation until the last minute – typically to conserve limited resources (such as database connections)

IDL

One of the key things provided by IDL to COM is the marshalling information

[in] / [out]
As per ever other language under the sun
[out, retval]
retval tells the client that it should give this as the return value to the developer even though the real return value is a HRESULT. It basically makes things more friendly in (for example) a VB environment.
[…, size_is(…)] and […, max_is(…)]
Since all an array is a pointer to a sequential series of values in memory, its obvious that COM will have no idea how long that sequence is. This is where size_is and max_is comes. Both of these attributes refer to a previous [in] parameter that documents the size. For example:

HRESULT ArraySum([in] SHORT iSize,
[in, size_is(iSize)] SHORT* piArray,

[out] LONG* lpResult);

The difference between size_is and max_is is simply the difference between defining the size of an array by the number of elements it contains (size_is) or its highest index (max_is). Therefore size_is(X) is always the same as max_is(X-1).

We’d then call the code something like this:

long result;
SHORT piData [5];

for (int i = 0; i<5; i++) piData[i] = i*i;

hr = I->ArraySum(5, piData, &result);

std::cout << result << std::endl;
[…, iid_is(…)]
Similarly, we can obtain a pointer to another COM object as a parameter using iid_is(…):

HRESULT MyMethod([in] REFIID riid,
[out, iid_is(riid)] IUnknown ** ppvObject);

Would return us a interface of type riid rather than IUnkown.

Properties

To implement properties, we have to implement accessors (get) and/or mutators (set). Like methods, properties can be added through a wizard. Since internally properties are implemented as a get function and a set function, IDL needs to be specified for each function specified. Just to be difficult, because these are functions, we can add parameters to our properties if we wish!

Having added a property through the wizard, it’s easy to flesh out the generated methods get_PropertyName and put_PropertyName as these are exactly the same as any other “STDMETHODIMP” function.

However, referring to a property through C++ is not so straightforward. The wizard will have added an IDispatch and handler to the code for us so (after a bit of messing around) I was able to do this:

VARIANT var;

DISPPARAMS dispparamsNoArgs = {NULL, NULL, 0, 0};

I->Invoke(5, IID_IFirst_ATL, NULL, DISPATCH_PROPERTYGET,

&dispparamsNoArgs, &var, NULL, NULL);

std::cout << var.lVal << std::endl;

Where 5 happens to be the dispatch ID for the DaveTest property (as specified in the id(…) IDL attribute in the .IDL file:

[propget, id(5), helpstring("property DaveTest")]
HRESULT DaveTest([out, retval] LONG* pVal);

[propput, id(5), helpstring("property DaveTest")]
HRESULT DaveTest([in] LONG newVal);

The equivalent in C# to the above was: Console.WriteLine(x.DaveTest)

Smart Pointers

CComPtr
The basic substitute for a pointer-to-an-interface.

Automatically supports AddRef and Release (Release is called as necessary if the pointer goes out of scope or has NULL assigned to it). The “real” pointer can be accessed through the “p” member.

Instead of:
IFirst_ATL *I;
hr = CoCreateInstance(CLSID_First_ATL, NULL,

CLSCTX_INPROC_SERVER, IID_IFirst_ATL, (void**) &I);

we have:
CComPtr<IFirst_ATL> IPtr;
hr = IPtr.CoCreateInstance(CLSID_First_ATL, NULL,

CLSCTX_INPROC_SERVER);
CComQIPtr
This pointer is designed to help obtain a pointer to parent interface class from an existing pointer to a child interface. This is normally done via QueryInterface as outlined previously.

CComQIPtr takes the parent type and parent interface IID as part of the template definition and the existing child interface pointer in the constructor:
CComQIPtr<IBase, &IID_IBase>
pINewBase(pIExistingChildInterface);

For example:
CComQIPtr<IFirst_ATL, &IID_IFirst_ATL> IQIPtr(IPtr.p);
IQIPtr->AddNumbers(10,20, &result);

This is basically the same as the following long hand:

IFirst_ATL *pI2;
IPtr.p->QueryInterface(IID_IFirst_ATL, (void**) &pI2);

pI2->AddNumbers(10,20, &result);
CComBSTR
Removes the hassle associated with memory and location management of BSTRs by supplying operator overloading for “=”, “+=”, “&” and “(BSTR)” plus the methods Copy(), Empty() [which releases the string], Length() and LoadString [for use with resource strings]

For example:
CComBSTR pTest = “Hello World”;

creates the word string 11, ‘H’, ‘e’, ‘l’, …, ‘d’ in memory with the result that:
- pTest returns a pointer to the memory location holding ‘H’
- (BSTR) pTest) returns a pointer to the same place
- pTest.Length() returns the value 11;