Windows NT Systems Programming: Spring 2000

[ Home | Syllabus | Course Notes | Assignments | Search]

Active Template Library (ATL)

• COM in C++ can inheritance to relate Interface with Implementation
• MFC uses MACROS and nested classes with support in CCmdTarget.
  But MFC is a large system.
• ATL is a smaller library primarily for building servers.

Smart Pointers

• Fix some of the problems with points by wrapping them in a class.
• Make that class a template to increase reusability.
• Override member selection ("->"), dereferencing ("*"), assignment ("=") operators.
• Initialize pointers, setting pointers to NULL
• With COM, can handle addref/release in constructor, destructor.
• ATL has a pair of smart poitners. CComPtr and CComQIPtr

CComPtr (ATL\Include\ATLBASE.H)

template <class T>
class CComPtr
{
public:
	typedef T _PtrClass;
	CComPtr() 	{ p=NULL;} // Initialize when constructed
	CComPtr(T* lp) 	{ //constructor (copying unwrapped pointer)
		if ((p = lp) != NULL) p->AddRef(); // if not NULL, increase reference count
	}
	CComPtr(const CComPtr<T>& lp) 	{ //copy constructor (copying pointer)
		if ((p = lp.p) != NULL)	p->AddRef(); // if not NULL, increase reference count
	}
	~CComPtr() 	{
		if (p) p->Release(); // if pointing at something, release it (instead of "delete")
	}
	void Release() {
		IUnknown* pTemp = p; // all COM objects have IUnKnown at beginning
		if (pTemp) {
			p = NULL; // set to NULL because might be destroyed anytime
			pTemp->Release();
		}
	}
	operator T*() const { // cast ??
		return (T*)p;
	}
	T& operator*() const	{ // dereference (check to NULL)
		ATLASSERT(p!=NULL);
		return *p;
	}

	T** operator&()	{ // call by reference and such
		ATLASSERT(p==NULL);
		return &p;
	}

	T* operator=(T* lp) { // assignment is tricky since the LHS may be destroyed
		return (T*)AtlComPtrAssign((IUnknown**)&p, lp);
	}

	T* operator=(const CComPtr<T>& lp)	{
		return (T*)AtlComPtrAssign((IUnknown**)&p, lp.p);
	}

	// Compare two objects for equivalence
	bool IsEqualObject(IUnknown* pOther)
	{
		if (p == NULL && pOther == NULL)
			return true; // They are both NULL objects

		if (p == NULL || pOther == NULL)
			return false; // One is NULL the other is not

		CComPtr<IUnknown> punk1;
		CComPtr<IUnknown> punk2;
		p->QueryInterface(IID_IUnknown, (void**)&punk1);
		pOther->QueryInterface(IID_IUnknown, (void**)&punk2);
		return punk1 == punk2; // check their vtables
	}

	T* p; // only data member - the "real" pointer
};

ATLAPI_(IUnknown*) AtlComPtrAssign(IUnknown** pp, IUnknown* lp)
{
	if (lp != NULL) // if assigning non-null, record new reference
		lp->AddRef(); 
	if (*pp) // if LHS is already pointing to something, release it.
		(*pp)->Release();
	*pp = lp;
	return lp;
}

Server: example (SpaceShip)

Page 823 discusses the project creation procedures (And I will give a cookbook for creating this object):

• Start visual c++
• Choose New/ATL Com AppWizard (in Projects tab)
• Choose working directory and name project "spaceshipsvr", select OK
• Choose DLL (the most flexible choice) and
• Allow merging of proxy-stub code (saves one DLL where the proxy/stub is normally stored)
• Can also allows MFC and MTS (microsoft transaction server) support, but don't need here, click "Finish"
• Gives you IDL support

IDL file created at this point

// spaceshipsvr.idl : IDL source for spaceshipsvr.dll
//

// This file will be processed by the MIDL tool to
// produce the type library (spaceshipsvr.tlb) and marshalling code.

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

[
	uuid(38E81745-04BD-11D4-80B1-0050DA0C5D58), // generates UUID for this new COM object
	version(1.0),
	helpstring("spaceshipsvr 1.0 Type Library")
]
library SPACESHIPSVRLib
{
	importlib("stdole32.tlb");
	importlib("stdole2.tlb");

};

• Use ATL object wizard to create COM objects (creates necessary IDL as well)
  • Insert/New ATL object/select Simple Object
  • Type name "MySpaceShip"
    (changed name so no conflict in registry with example form book -will generate a bunch of classes)

Update IDL file

	[
		object,
		uuid(38E81753-04BD-11D4-80B1-0050DA0C5D58),
		dual,
		helpstring("IMySpaceShip Interface"),
		pointer_default(unique)
	]
	interface IMySpaceShip : IDispatch
	{
	};

[
	uuid(38E81745-04BD-11D4-80B1-0050DA0C5D58),
	version(1.0),
	helpstring("spaceshipsvr 1.0 Type Library")
]
library SPACESHIPSVRLib
{
	importlib("stdole32.tlb");
	importlib("stdole2.tlb");

	[
		uuid(38E81754-04BD-11D4-80B1-0050DA0C5D58),
		helpstring("MySpaceShip Class")
	]
	coclass MySpaceShip
	{
		[default] interface IMySpaceShip;
	};
};

• Because the wizard doesn't do this yet, Edit ".idl" file to add IMotion and IDisplay interfaces p. 844-5
  NOTE: I changed the UUID by called guidgen.exe (Start/Run)

   [
        object,
        uuid(01BCDE31-04C3-11d4-80B1-0050DA0C5D58),
        dual,
        helpstring("IMotion interface")
    ]
    interface IMotion : IDispatch // for this interface derive from IDispatch
    {
	
    };

    [
        object,
        uuid(01BCDE32-04C3-11d4-80B1-0050DA0C5D58),
        helpstring("IVisual interface")
    ]
    interface IVisual : IUnknown // derive from IKnown - to differ from above
    {
	
    };

• Compile the idl file (Build/Compile) - you will see the new classes in the class view
• Change class definition of SpaceShip to inherit the new interface classes (p. 845)
• Change interface map p. 846 (last will change class view by adding these interfaces under CMySpaceShip)
  NOTE: make sure you use the changed name IMySpaceShip
• Now we add methods to the new interface classes
  You can use the ClassView, right click on either the "IDisplay" interface itself or that under the CMySpaceShip object and select "Add Method" you will see a dialog like that in figure 29-5.
  • Add method "Display" with no parameters, select OK
  • right click on "IMotion", add method "Fly", no parameters, OK
  • right click on "IMotion", add method "GetPosition", in Parameter box add
    [out, retval] long* nPosition
    select OK
• Now we have the skeletal structure. you can register it using
  • Tools/Register Control

  Instead of using "RegComp" from CD

Adding Properties and Funcionality

• Let's deviate from the book and change accelleration to velocity. Either by editing by hand or using the class view add two "long" class members to CMySpaceShip
• Initialize these members in the constructor (make velocity non 0 to be interesting)
• Add some code to Fly which changes the position by the velocity.
  m_lPosition += m_lVelocity;
• Add code to "getPosition" to return m_lPosition as the reference parameter.
• Also let's add new functions to get/set the velocity.
  You can use the ClassView, right click on either the "IMotion" interface itself or that under the CMySpaceShip object and select "Add Method" you will see a dialog like that in figure 29-5.
  • Add method "SetVelocity" with one in parameter
    [in] long velocity
    select OK
  • right click on "IMotion", add method "GetVelocity", in Parameter box add
    [out, retval] long* velocity
    select OK
• Add code to get/set m_lVelocity accordingly.

Developing a C++ client

We will develop a client which "flys" the spaceship.
This client features:

• Dialog box as main window
• Spin Control to set velocity.
• Slider Bar to show position of spaceship
• Timer to allow continuous updates of position.

Here are the steps:

• start visual c++
• file/new/MFC appWizard(exe)
• Step 1: select "dialog based"
• Set up the main dialog box with (as shown below)
  • spin control for velocity
  • Slider bar for position
  • CEdit box to show position numerically

• Using class wizard or by hand, set variables for
  • Velocity CEdit (int m_nVelocity)
  • Position CEdit (int m_nShowPos)
  • Position CSliderStrl's position (int m_nPosition)

Accessing the COM specifications

Need to include two files from the spaceshpisvr - generated by the MIDL

• spaceshipsvr.h: contains COM object and its interfaces
• spaceshipsvr_i.c: contains the UUIDs
• The including of these files must be done carefully to avoid multiple defines, I included the second in Dialog's implementation file following an include of the header file (which must be included first).
  These were followed by the includes for the header for the main dialog class (required because the dialog class has member data to remember the interface v-tables - as shown here)

  IMySpaceShip* m_pSpaceShip;
  IMotion* m_pMotion;
  IVisual* m_pVisual;

• InitDialog is most interesting

BOOL CFlySpaceShipDlg::OnInitDialog()
{
	CDialog::OnInitDialog();
	
// skip wizard stuff

	// TODO: Add extra initialization here
	CSliderCtrl* pSlide1 =
		(CSliderCtrl*) GetDlgItem(IDC_POSITION);
	pSlide1->SetRange(-1000, 1000); // the limits of civilized space travel
	pSlide1->SetPos(m_nPosition); // initialized to 0 in constructor
	CSpinButtonCtrl* pSpin =
		(CSpinButtonCtrl*) GetDlgItem(IDC_SPIN1);
	pSpin->SetRange(-10, 10);
	pSpin->SetPos(m_nVelocity); // initialized to 0 in constructor
	
	HRESULT hr;
	hr = CoCreateInstance(CLSID_MySpaceShip, 
		NULL, 
		CLSCTX_INPROC_SERVER, 
		IID_IMySpaceShip, 
		(void**)&m_pSpaceShip);
	
	if(m_pSpaceShip) {
		m_pSpaceShip->QueryInterface(IID_IVisual, (void**)&m_pVisual); // not used in this program
		m_pSpaceShip->QueryInterface(IID_IMotion, (void**)&m_pMotion);
	}
	m_pMotion->SetVelocity(m_nVelocity); // set the initial velocity
	SetTimer(1,50,NULL); // update position every 50 milliseconds
		
	return TRUE;  // return TRUE  unless you set the focus to a control
}

void CFlySpaceShipDlg::OnTimer(UINT nIDEvent) 
{
	long pos;
	m_pMotion->Fly();// fly for another time period
	m_pMotion->GetPosition(&pos); // and get your new position
	m_nPosition = (int)pos; // update member variables
	m_nShowPos = pos;
	this->UpdateData(FALSE); //what does this do?
}

void CFlySpaceShipDlg::OnVScroll(UINT nSBCode, UINT nPos, CScrollBar* pScrollBar) 
{
   
		m_nVelocity = nPos;
		m_pMotion->SetVelocity(long(m_nVelocity)); // change velocity
		UpdateData(FALSE);
   
}

• Source code here.

Adding Smart Pointers to the above

• Replace the declarations of m_pMotion in the header file by the following (see client2 in teh above source code zip)
  • Before the class definition add the following macro

    _COM_SMARTPTR_TYPEDEF(IMotion, __uuidof(IMotion));

    You will need to add the header file (#include "comdef.h")

  • Replace "IMotion* m_pMotion;" by "IMotionPtr m_pMotion;"
• In the defintion of "InitDialog" replace

  HRESULT hr;
  	hr = CoCreateInstance(CLSID_MySpaceShip, 
  		NULL, 
  		CLSCTX_INPROC_SERVER, 
  		IID_IMySpaceShip, 
  		(void**)&m_pSpaceShip);
  	
  	if(m_pSpaceShip) {
  		m_pSpaceShip->QueryInterface(IID_IVisual, (void**)&m_pVisual); // not used in this program
  		m_pSpaceShip->QueryInterface(IID_IMotion, (void**)&m_pMotion);
  	}

  // by

  	m_pMotion = new IMotionPtr( _T("Spaceshipsvr.MySpaceShip.1")) ;
  

Threading Models

Need to be concerned about thread safety with COM objects if they are to be used simultaneously.

ATL supports several threading models.
Nomenclature is a little strange and confusing here.
Basic issue is thread safety. Can enforce safety while giving up opportunity for multithreading.

• Apartment (single threaded apartment): Object executes in one thread and is serialized by the remoting architecture.
  DOES NOT have to be thread safe.
• Multi-threaded apartment means several threads can be active simultaneously and can access global data. Must be thread safe
• Single: Class executes in main thread
• Both: can execute in either single or multi threaded apartments.
• Free: executes in multi-threaded apartment. program must guarantee thread safety

Free threading marshalling allows cross apartment calls more efficiently by passing pointer to data.

Copyright chris wild 1999/2000.
For problems or questions regarding this web contact [Dr. Wild].
Last updated: March 29, 2000.