Active Template Library (ATL)

In this topic

• ATL in Brief
• ATL and Direct To COM
• ATL and Attributes
• Handling Errors in ATL
• Debugging ATL Code
• Boolean Types
• String Types
• Implementing private COM classes (noncreatable)
• Other features in Visual Studio
• ATL References

ATL in Brief

• ATL Project—Used to initialize an ATL C++ project.
• ATL Simple Object—Used to create COM objects. In case the Attributed option of the project has been enabled the COM class will be created with the [coclass] attribute which will provide the IDL code at compile time.
• Add Variable—Used to add properties to interfaces.
• Add Function—Used to add methods to interfaces; both the Property and Method Wizards require you to know some IDL syntax.
• Implement Interface—Used to implement stub functions for existing interfaces.
• Add Connection Point—Used to implement outbound events' interfaces.

ATL and DTC

ATL and Attributes

Why using Attributes in ATL projects

• IDL file - contains the interface description
• RGS file - for additional registration information
• the ATL class itself - specifies implemented interfaces through interface map

How to use Attributes

// ATL 3

class ATL_NO_VTABLE CManager: public CComObjectRootEx < CComSingleThreadModel >
  , public CComCoClass < CManager, &CLSID_Manager > , public IDispatchImpl <
  IEmployee, &IID_IEmployee > 
{
  public:
    DECLARE_REGISTRY_RESOURCEID(IDR_MANAGER)BEGIN_COM_MAP(CManager)
      COM_INTERFACE_ENTRY(IEmployee)COM_INTERFACE_ENTRY(IDispatch)END_COM_MAP()
      STDMETHOD(DoWork)(BSTR bstrTask);
};

// ATL 8

// in manager.h
[coclass]class ATL_NO_VTABLE CManager: public IEmployee
{
  public:
    STDMETHODIMP DoWork(BSTR bstrTask);
};

• inheritance from CComObjectRootEx, CComCoClass, IDispatchImpl
• binding an RGS script through the macro DECLARE_REGISTRY_RESOURCEID()
• information about implemented interfaces through BEGIN_COM_MAP and END_COM_MAP

Attributes and IDL

Attributes and Registration

UUIDs

Module

// The module attribute causes WinMain to be automatically implemented for you
[module(exe, name="exe module class")]class CMyClass
{
  public:
    int WINAPI WinMain(int nShowCmd)
    {
        //todo: add your code here
        return true;
    }
};

[module(dll, name="dll module class")]
// module attribute now applies to this class
class CMyClass
{
  public:
    BOOL WINAPI DllMain(DWORD dwReason, LPVOID lpReserved)
    {
        // add your own code here
        return true;
    }
};

RGS Files

[coclass, registration_script(script="Counted.rgs")]class CCounted: public
  ICount
{
     /* other code */
};

Component Categories

• placing the GUIDs for component categories beneath an Implemented Categories key in an RGS file

• using ATL macros in an objects header file (BEGIN_CATEGORY_MAP, IMPLEMENTED_CATEGORY, END_CATEGORY_MAP)

[coclass, implements_category("CATID_Insertable")]class CCounted: public ICount
{
     /* other code */
};

• [uuid()]—Can be applied to a class with the UUID of the class that is passed in as a parameter in parenthesis.

[coclass, uuid("53A583E1-18B7-4194-A969-8C1BFA7A3F03")]

[coclass, vi_progid("Walkthrough1VC7.ZoomIn")]

[coclass, progid("Walkthrough1VC7.ZoomIn.1")]

[coclass, registration_script(script="Counted.rgs")]

[coclass, implements_category("CATID_Insertable")]

• [requires_category()]—This attribute can be used to specify the category a container requires to be able to contain the class.

Conclusion

Handling Errors in ATL

STDMETHODIMP MyClass::InterfaceSupportsErrorInfo(REFIID riid)
{
  static const IID *arr[]=
  {
     &IID_IMyClass, 
  };

  for (int i=0; i < sizeof(arr) / sizeof(arr[0]); i++)
  {
    if (InlineIsEqualGUID(*arr[i], riid))
      return S_OK;
  }

  return S_FALSE;
}

// Return a simple string
AtlReportError(CLSID_MyClass, _T("No connection to Database."), IID_IMyClass,
  E_FAIL);
// Get the Error Text from a resource string
AtlReportError(CLSID_MyClass, IDS_DBERROR, IID_IMyClass, E_FAIL,
  _Module.m_hInstResource);

Debugging ATL Code

extern "C"BOOL WINAPI DllMain(HINSTANCE hInstance, DWORD dwReason, LPVOID
  /*lpReserved*/)
{
  if (dwReason == DLL_PROCESS_ATTACH)
  {
    _Module.Init(ObjectMap, hInstance, &LIBID_HISTORYLib);
    DisableThreadLibraryCalls(hInstance);
    _Module.m_nIndexBreakAt=10;
  }
  else if (dwReason == DLL_PROCESS_DETACH)
  {
    _Module.Term();
  }
  return TRUE;
}

Boolean Types

String Types

// Initialize some fixed length strings
char *pNameANSI="Bill"; // 5 bytes (4 characters plus a terminator)
wchar_t *pNameUNICODE=L "Bill"; 
  // 10 bytes (4 16-bit characters plus a 16-bit terminator)
TCHAR *pNameTCHAR=_T("Bill"); // either 5 or 10 depending on compiler settings

STDMETHODIMP CFoo::put_WindowTitle(BSTR bstrTitle)
{
  USES_CONVERSION;
  if (::SysStringLen(bstrTitle) == 0)
    return E_INVALIDARG;

  ::SetWindowText(m_hWnd, OLE2CT(bstrTitle));

  return S_OK;
}

Implementing private COM classes (noncreatable)

// Foo is a CoCreateable object
IFooPtr ipFoo;
HRESULT hr=ipFoo.CreateInstance(CLSID_Foo);

// Bar is a noncreatable object, cannot use ipBar.CreateInstance(CLSID_Bar)
IBarPtr ipBar;
// Use a method on Foo to create a new Bar object
hr=ipFoo->CreateBar(&ipBar);
ipBar->DoSomething();

• noncreatable COM class with attributes  
  Add the [noncreatable] attribute to the header file of the COM class:

// in manager.h
[coclass, noncreatable]class ATL_NO_VTABLE CBar
{
  public:
    STDMETHODIMP DoSomething(BSTR bstrTask);
};

[uuid(DCB87952 - 0716-4873-852B - F56AE8F9BC42), noncreatable] coclass Bar
{
  [default] interface IUnknown;
  interface IBar;
};

BEGIN_OBJECT_MAP(ObjectMap)OBJECT_ENTRY(CLSID_Foo, CFoo) // Creatable object
OBJECT_ENTRY_NON_CREATEABLE(CLSID_Bar, CBar) // Noncreatable object
END_OBJECT_MAP()

// Get NonCreatable object Bar (implementing IBar) from COM object Foo
STDMETHODIMP CFoo::CreateBar(IBar **pVal)
{
  if (pVal == 0)
    return E_POINTER;

  // Smart pointer to non-creatable object Bar
  IBarPtr ipBar=0;

  // C++ Pointer to Bar, with ATL template to supply CreateInstance implementation
  CComObject < CBar >  *pBar=0;

  HRESULT hr=CComObject < CBar > ::CreateInstance(&pBar);
  if (SUCCEEDED(hr))
  {
    // Increment the ref count from 0 to 1 to protect the object
    // from being released in any initialization code.
    pBar->AddRef();

    // Call C++ methods (not exposed to COM) to initialize the Bar object
    pBar->InitialiseBar(10);

    // QI to IBar and hold a smart pointer reference to the object Bar
    hr=pBar->QueryInterface(IID_IBar, (void **) &ipBar);

    pBar->Release();
  }

  // return IBar pointer to the caller
  *pVal=ipBar.Detach();

  return S_OK;
}

Other features in VS8

ATL References

1. Grimes, Richard. ATL COM Programmer's Reference. Chicago: Wrox Press Inc., 1988.
2. Grimes, Richard. Professional ATL COM Programming. Chicago: Wrox Press Inc., 1988.
3. Grimes, Richard, Reilly Stockton, Alex Stockton, and Julian Templeman. Beginning ATL 3 COM Programming. Chicago: Wrox Press Inc., 1999.
4. King, Brad, and George Shepherd. Inside ATL. Redmond, WA: Microsoft Press, 1999.
5. Rector, Brent, Chris Sells, and Jim Springfield. ATL Internals. Reading, MA: Addison-Wesley, 1999.