Windows Systems Programming: Spring 2002

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

COM Basics

• Microsoft's binary standard (Language independent)
• Objects must be registered in local system registry
• Accesses Object through interfaces (local or remote)
• Groups functions into interfaces which can be named and registered
• Identified by IIDs and CLSIDs (Interface ID and Class ID)
• Static and dynamic invocation (IDISPATCH)
• Can start COM server as needed
• Supports naming, persistence, object lifetime.
• Binary Specification Uses an array of function pointers to access methods
• COM Class implements one or more interfaces
• COM objects are instantiated from COM classes
• Every COM object must implement the interface IUnknown
  Key to object lifetime management

IUnknown

HRESULT QueryInterface(REFIID iid, void** ppvObject);
ULONG AddRef(void);
ULONG Release(void);

• Object lifetime is managed through a reference count
• AddRef increases and Release decreases
• QueryInterface also increments the reference count
• C++ object + IUnknown = Com object

Identifiers

• Uses OSF DCE UUID (Universally Unique ID)
• Created using UuidCreate( ) = statistically unique 128 bit number
• Or can use "guidgen" using the Start/Run
• IID = Interface ID
• CLSID = Class ID
• ProgID is a meaningful string which maps to the CLSID: in Registry
  in HKEY_CLASSES_ROOT

Using COM

• Initialize COM: CoInitialize
• Create COM Object (Class Factory Object): CoCreateInstance

COM Servers

• InProc Servers: Server in DLL (in InprocServer32 in registry)
• Local Servers: Server in separate process (in LocalServer32 in registry)
  Uses Proxy DLL in client and Stub DLL in server to connect (usually RPC)
• Remote Servers: Use RPC

Some Definitions

interface:

a set of semantically related methods (function calls). Can be used to provide access to the public member functions of an object. A COM interface is implemented as a C++ V-table (in C++ programs) However the COM interface is language independent.

virtual function:

a function that can be redefined in a derived class and which can be dynamically bound to any object in the inheritance hierarchy. Thus a pointer to the base class could point to any object of a derived class and any function referenced by that pointer is dynamically bound to the function of the correct derived class. This ability of a function to be dynamically bound permits polymorphism.

pure virtual function:

A virtual function is undefined in the base class and must be defined in any derived class. This allows a abstract base class to place requirements on any inherited object class.

polymorphism:

The ability of a function in a program to work with any object in an inheritance chain without recompilation. This implies that the run-time system must be able to find the address of the function based on the type of the object at the time the function is invoked (dynamic or late binding).

v-table:

a table containing the address of virtual functions. A v-table is associated with each class.

component:

set of (possibly) related COM classes. Housed either in a DLL (Dynamically Linked Library) or an executable file.

idl (interface definition language):

langauge independent/ platform independent means of specifiying a function's prototype. Adapted from Open Software Foundation (OSF) RPC standard.

 

Let's develop a simple COM class, exploring the problems and solutions to them.  

Project: write a simple COM object which contains a simple student record (just grade)

We want this object to be language independent and location independent (distributed).

PROBLEM: how to specify a language independent header file.
SOLUTION: Use IDL. The IDL file is compiled into language dependent code by MIDL (Microsoft's IDL compiler)

• In your favorite editor write the following file (student.idl)

// component.idl
import "unknwn.idl";

[ object, uuid(477CF9EC-8A08-4a8e-B304-67076C64FA54) ]
interface IStudent : IUnknown
{
	HRESULT SetGrade([in] int grade);
	HRESULT GetGrade([out,retval] int* grade);
};

• F1: Identifies this as a Com interface instead of a RPC specification.
• F2: Universally Unique identifier (128 bit ), unique across space and time.
• F3: Imported from "unknwn.idl" - All COM objects are derived from this base class
  the UUID of IUnknown is always 00000000-0000-0000-C000-0000000000046) - so it can be found on every computer.
• F4: Information on movement of parameters
  • in: parameter is input only (like call by value)
  • out: parameter is output only (don't need to pass initial value to object) like call by reference
  • in, out: parameter is copied in and copied out.
  • retval: this is the return value of the function for expression languages to use as the "real" return value.
    HRESULT is used by the COM run time system to check for COM errors.

• Compile student.idl using the command
  midl student.idl
  in a command prompt window

• student_i.c: defines UUID structure
• student.h: defines C++ code to access COM object from client program

/* this ALWAYS GENERATED file contains the definitions for the interfaces */


/* File created by MIDL compiler version 5.01.0164 */
/* at Thu Feb 15 09:23:59 2001
 */
/* Compiler settings for student.idl:
    Os (OptLev=s), W1, Zp8, env=Win32, ms_ext, c_ext
    error checks: allocation ref bounds_check enum stub_data 
*/
//@@MIDL_FILE_HEADING(  )


/* verify that the <rpcndr.h> version is high enough to compile this file*/
#ifndef __REQUIRED_RPCNDR_H_VERSION__
#define __REQUIRED_RPCNDR_H_VERSION__ 440
#endif

#include "rpc.h"
#include "rpcndr.h"

#ifndef __RPCNDR_H_VERSION__
#error this stub requires an updated version of <rpcndr.h>
#endif // __RPCNDR_H_VERSION__

#ifndef COM_NO_WINDOWS_H
#include "windows.h"
#include "ole2.h"
#endif /*COM_NO_WINDOWS_H*/

#ifndef __student_h__
#define __student_h__

#ifdef __cplusplus
extern "C"{
#endif 

/* Forward Declarations */ 

#ifndef __IStudent_FWD_DEFINED__
#define __IStudent_FWD_DEFINED__
typedef interface IStudent IStudent;
#endif 	/* __IStudent_FWD_DEFINED__ */


/* header files for imported files */
#include "unknwn.h"

void __RPC_FAR * __RPC_USER MIDL_user_allocate(size_t);
void __RPC_USER MIDL_user_free( void __RPC_FAR * ); 

#ifndef __IStudent_INTERFACE_DEFINED__
#define __IStudent_INTERFACE_DEFINED__

/* interface IStudent */
/* [uuid][object] */ 


EXTERN_C const IID IID_IStudent;

#if defined(__cplusplus) && !defined(CINTERFACE)
    
    MIDL_INTERFACE("477CF9EC-8A08-4a8e-B304-67076C64FA54")
    IStudent : public IUnknown
    {
    public:
        virtual HRESULT STDMETHODCALLTYPE SetGrade( 
            /* [in] */ int grade) = 0;
        
        virtual HRESULT STDMETHODCALLTYPE GetGrade( 
            /* [retval][out] */ int __RPC_FAR *grade) = 0;
        
    };
    
#else 	/* C style interface */

    typedef struct IStudentVtbl
    {
        BEGIN_INTERFACE
        
        HRESULT ( STDMETHODCALLTYPE __RPC_FAR *QueryInterface)( 
            IStudent __RPC_FAR * This,
            /* [in] */ REFIID riid,
            /* [iid_is][out] */ void __RPC_FAR *__RPC_FAR *ppvObject);
        
        ULONG ( STDMETHODCALLTYPE __RPC_FAR *AddRef)( 
            IStudent __RPC_FAR * This);
        
        ULONG ( STDMETHODCALLTYPE __RPC_FAR *Release)( 
            IStudent __RPC_FAR * This);
        
        HRESULT ( STDMETHODCALLTYPE __RPC_FAR *SetGrade )( 
            IStudent __RPC_FAR * This,
            /* [in] */ int grade);
        
        HRESULT ( STDMETHODCALLTYPE __RPC_FAR *GetGrade )( 
            IStudent __RPC_FAR * This,
            /* [retval][out] */ int __RPC_FAR *grade);
        
        END_INTERFACE
    } IStudentVtbl;

    interface IStudent
    {
        CONST_VTBL struct IStudentVtbl __RPC_FAR *lpVtbl;
    };

    

#ifdef COBJMACROS


#define IStudent_QueryInterface(This,riid,ppvObject)	\
    (This)->lpVtbl -> QueryInterface(This,riid,ppvObject)

#define IStudent_AddRef(This)	\
    (This)->lpVtbl -> AddRef(This)

#define IStudent_Release(This)	\
    (This)->lpVtbl -> Release(This)


#define IStudent_SetGrade(This,grade)	\
    (This)->lpVtbl -> SetGrade(This,grade)

#define IStudent_GetGrade(This,grade)	\
    (This)->lpVtbl -> GetGrade(This,grade)

#endif /* COBJMACROS */


#endif 	/* C style interface */



HRESULT STDMETHODCALLTYPE IStudent_SetGrade_Proxy( 
    IStudent __RPC_FAR * This,
    /* [in] */ int grade);


void __RPC_STUB IStudent_SetGrade_Stub(
    IRpcStubBuffer *This,
    IRpcChannelBuffer *_pRpcChannelBuffer,
    PRPC_MESSAGE _pRpcMessage,
    DWORD *_pdwStubPhase);


HRESULT STDMETHODCALLTYPE IStudent_GetGrade_Proxy( 
    IStudent __RPC_FAR * This,
    /* [retval][out] */ int __RPC_FAR *grade);


void __RPC_STUB IStudent_GetGrade_Stub(
    IRpcStubBuffer *This,
    IRpcChannelBuffer *_pRpcChannelBuffer,
    PRPC_MESSAGE _pRpcMessage,
    DWORD *_pdwStubPhase);



#endif 	/* __IStudent_INTERFACE_DEFINED__ */


/* Additional Prototypes for ALL interfaces */

/* end of Additional Prototypes */

#ifdef __cplusplus
}
#endif

#endif

• F5: generated from "import "unknwn.idl" in IDL file
• F6: allocation /deallocation function calls
• F7: defined in component_i.c
• F8: forces use of v-table
• F9: if this is C - build a virtual table by hand
• F10: In c++ this is derived from IUnknown
• F11: Simulates object's This pointer in C programs
• F12: Hide v-table and function pointers
• F13: for RPC access

Now let's see how a client can access this  COM object:

PROBLEM: Creating an object in a language independent manner
SOLUTION: CoCreateInstance

PROBLEM: Returning an interface to the COM Object (like attaching a v-table)
SOLUTION: QueryInterface Method

PROBLEM: managing a shared interface's lifetime
SOLUTION: AddRef and Release Methods

• In visual c++, create an empty console project and add a new source file called "client.cpp"
• Edit the following into this file

// client.cpp
#include <iostream.h>
#include "student.h" // Generated by MIDL(see above)

// {A873BF78-A5DA-4a7b-B4F7-3CB51C5D210B} // generated by guidgen
static const CLSID CLSID_SimpleStudent = 
{ 0xa873bf78, 0xa5da, 0x4a7b, { 0xb4, 0xf7, 0x3c, 0xb5, 0x1c, 0x5d, 0x21, 0xb };

void main()
{
	cout << "Client: Calling CoInitialize()" << endl;
	HRESULT hr = CoInitialize(NULL);
	if(FAILED(hr))
		cout << "CoInitialize failed" << endl;
	
	IUnknown* pUnknown;
	IStudent* pStudent;

	cout << "Client: Calling CoCreateInstance()" << endl;
	hr = CoCreateInstance(CLSID_SimpleStudent , NULL, CLSCTX_INPROC_SERVER, IID_IUnknown, (void**)&pUnknown);
	if(FAILED(hr))
		cout << "CoCreateInstance failed" << endl;

	cout << "Client: Calling QueryInterface() for ISum on " << pUnknown << endl;
	hr = pUnknown->QueryInterface(IID_IStudent, (void**)&pStudent); 
           // missing reference operator could crash the appliation
	if(FAILED(hr))
		cout << "IID_IStudent not supported" << endl;

	hr = pUnknown->Release();
	cout << "Client: Calling pUnknown->Release() reference count = " << hr << endl;

	int grade;
	cout << "type grade to set:";
	cin >> grade;
	hr = pStudent->SetGrade(grade);
	if(SUCCEEDED(hr))
		cout << "Client: SetGrade to " << grade << endl;
	int gradeOut;
	hr = pStudent->GetGrade(gradeOut);
	if(SUCCEEDED(hr))
		cout << "Client: GetGrade is " << gradeOut << endl;

	hr = pStudent->Release();
	cout << "Client: Calling pStudent->Release() reference count = " << hr << endl;

	cout << "Client: Calling CoUninitialize()" << endl;
	CoUninitialize();
}

• F14: Initializes the COM library, argument must be NULL
• F15: defined in unknwn.h - need pointer - because CoCreateInstance will actually create the object
• F16: "Co" prefix is for "component Object Model"
  • First parameter is UUID of COM class (Class ID: CLSID)
  • second is Aggregation object
  • third is context (inprocess as DLL, local or remote server
  • fourth is interface ID in the class
  • fifth is return value containing pointer to table of function calls
• F17: No can ask the COM object if it supports the IStudent interface
• F18: No longer need the IUnknown interface
• F19: Call the object's SetGrade/GetGrade method
• F20: Closes COM library, breaks RPC connections if any

Implementing the Component SimpleStudent/IStudent

Could use any language - Let's use C++ first

• In visualC++, create a win32 DLL project called SimpleStudent
  (source code is here).

Remember that the IStudent interface object is an abstract class because its four functions are pure virtual.

(What are the four functions?)

Therefore we need to derive a implementation class from it.

class CSimpleStudent : public IStudent // remember this is derived from IUnknown
{
public:
   // IUnknown
   ULONG __stdcall AddRef(); // COM functions NOT returning HRESULT
   ULONG __stdcall Release();
   HRESULT __stdcall QueryInterface(REFIID iid, void** ppv);

   // IStudent
   HRESULT __stdcall SetGrade(int grade);
   HRESULT __stdcall GetGrade(int* grade);


   CSimpleStudent () : m_cRef(1) { g_cComponents++; }
   ~CSimpleStudent () { cout << "Component: CSimpleStudent ::CSimpleStudent ()" << endl, g_cComponents--; }

private:
   ULONG m_cRef;
   int m_grade; // remember this student's grade
};

• F1: Implements functions from both the base class and the derived class
  Addref and Release return current reference count
• F2: Keep track of how many clients access this implementation object.
• F3: Keep track of how many components in this DLL are active.

Implementing IUnknown Functions

ULONG CSimpleStudent::AddRef()
{
   return ++m_cRef;
}

ULONG CSimpleStudent::Release()
{
   if(--m_cRef != 0) // test if last reference
      return m_cRef;
   delete this; // "calls" destructor
   return 0;
}

HRESULT CSimpleStudent::QueryInterface(REFIID iid, void** ppv)
{
   if(iid == IID_IUnknown) {
      *ppv = (IUnknown*)this;
   }
   else if(iid == IID_IStudent) {
      *ppv = (IStudent*)this;
   }
   else {
      *ppv = NULL;
      return E_NOINTERFACE;
   }
   AddRef();
   return S_OK;
}

• F4: Mainly for debugging purposes - may not be accurate - why?
• F5: Only two Interfaces belonging to this object.
• F6: Interface asked for is not supported by this object
• F7: This implementation object (CSimpleStudent) supports all its interfaces
• F8: Constructor initializes to 1, this "exrra" reference count is used by a trick to get rid of objects which would have taken one of the earlier returns (see CreateInstance code below)
• F9: Overloads this operator in objbase.h for GUID objects

QueryInterface Rules

QueryInterface on any interface of a component, must produce the same results.
You can query IStudent for IUnknown for instance.

• Symmetric: Calls for the same interface must return the same pointer value.
  If a call fails one time, it must fail everytime.

• Reflexive: If queries on one interface for a for a second succeed, then queries on the second for the first must also succeed.

• Transitive: If a query on interface one gives interface two and a query on interface two gives interface three, then a query for interface three on interface one must succeed.

SetGrade/GetGrade implementation

HRESULT CSimpleStudent::SetGrade(int grade)
{
   m_grade = grade;
   return S_OK;
}

HRESULT CSimpleStudent::GetGrade(int* grade)
{
   *grade = m_grade;
   return S_OK;
}

Creating a  "Location Transparent"  to IUnknown

IClassFactory:

A COM object for creating other COM objects of a given type.

Used by CoCreateInstance, calls CreateInstance.

class CFactory : public IClassFactory
{
public:
	// IUnknown
	ULONG __stdcall AddRef();
	ULONG __stdcall Release();
	HRESULT __stdcall QueryInterface(REFIID iid, void** ppv);

	// IClassFactory
	HRESULT __stdcall CreateInstance(IUnknown *pUnknownOuter, REFIID iid, void** ppv);
	HRESULT __stdcall LockServer(BOOL bLock);

	CFactory() : m_cRef(1) { }
	~CFactory() { }

private:
	ULONG m_cRef;
};

HRESULT CFactory::CreateInstance(IUnknown *pUnknownOuter, REFIID iid, void** ppv)
{
	if(pUnknownOuter != NULL)
		return CLASS_E_NOAGGREGATION;

	CSimpleStudent *pSimpleStudent = new CSimpleStudent;
	cout << "Component: CFactory::CreateInstance() " << pSimpleStudent << endl;

	if(pSimpleStudent== NULL)
		return E_OUTOFMEMORY;

	// QueryInterface probably for IID_IUNKNOWN
	HRESULT hr = pSimpleStudent->QueryInterface(iid, ppv);
	pSimpleStudent->Release();
	return hr;
}

• F10: This classfactory does not support COM aggregation
• F11: Finally we create the object using good old "new"
• F12: way to tell client out of memory
• F13: Could query for IID_ISTUDENT - but not the "COM" way - always IID_IUNKNOWN which is "guaranteed" to work
• F14: Get the v-table for the student's IUnknown interface
• F15: trick to get rid of object if QueryInterface failed (If succeeded, Addref makes extra reference count (one comes from constructor) - else release gets rid of object created above by "new"

//// code for dealing with DLL management

HRESULT CFactory::LockServer(BOOL bLock)
{
	if(bLock)
		g_cServerLocks++;
	else
		g_cServerLocks--;
	return S_OK;
}

HRESULT __stdcall DllCanUnloadNow()
{
	cout << "Component: DllCanUnloadNow() " << (g_cServerLocks == 0 && g_cComponents == 0 ? "Yes" : "No") << endl;
	if(g_cServerLocks == 0 && g_cComponents == 0)
		return S_OK;
	else
		return S_FALSE;
}

HRESULT __stdcall DllGetClassObject(REFCLSID clsid, REFIID iid, void** ppv)
{
	cout << "Component: DllGetClassObject" << endl;
	
	if(clsid != CLSID_SimpleStudent)
		return CLASS_E_CLASSNOTAVAILABLE;

	CFactory* pFactory = new CFactory;
	if(pFactory == NULL)
		return E_OUTOFMEMORY;

	// QueryInterface probably for IClassFactory
	HRESULT hr = pFactory->QueryInterface(iid, ppv);
	pFactory->Release();
	return hr;
}

• F16: allows programmer to keep DLL in memory even if no COM objects are active.
• F17: Called by the runtime system to see if OK to get rid of DLL from memory
• F18: Somebody has to get the ball rolling and create the classfactory so that you can call it's CreateInstance (see diagram below)
• F19: This DLL only supports the SimpleStudent COM object
• F20: this interface will allow the run-time system to call CreateInstance

Registering the Component

• Define a file called "component.reg" containing the following instructions

REGEDIT4

[HKEY_CLASSES_ROOT\CLSID\{A873BF78-A5DA-4a7b-B4F7-3CB51C5D210B}]
@="Simple Student"

[HKEY_CLASSES_ROOT\CLSID\{A873BF78-A5DA-4a7b-B4F7-3CB51C5D210B}\InprocServer32]
@="D:\\Courses\\CS495NT\\Spring01\\Examples\\Student1\\component\\Debug\\component.dll"

• register the component using the command
  regedit component.reg

• Or double click the file name in the file manager

• Define a file called "component.def" containing

; component.def
LIBRARY         component.dll
DESCRIPTION     '(c) 2001 Chris Wild'
EXPORTS
                DllGetClassObject   @2	PRIVATE
                DllCanUnloadNow     @3	PRIVATE

Copyright chris wild 1999-2002.
For problems or questions regarding this web contact [Dr. Wild].
Last updated: February 17, 2002.