ABSTRACT

Inside CoLib, a Component Object Library

Copyright © 2000 by Ernest Murphy ernie@surfree.com

For educational use only. All commercial use only by written license.

 

Revised 2/25/2001 for simplified class definition Version 1.1

 

ABSTRACT

 

"CoLib.Lib" is a library of functions to be used in the creation of COM servers. CoLib.Lib will make a dll server to support any number of COM objects with any number of COM interfaces. CoLib also provides a base to create COM objects in other environments, such as internal helper objects in either another COM object, or stand-alone. This document is an attempt to explain the logic behind this object file, and explain how to use it to create arbitrary COM objects.

 

CoLib.Lib is meant to be a reusable library of functions, to serve as the base of your object. It lets the programmer define what the object is, to create it and destroy it, supports the basic .DLL exports of a COM server, and the interfaces IUnknown, IClassFactory, and IDispatch. It optionally supports aggregation. CoLib will be an invaluable source of functionality for any in-process server.

 

CoLibis designed to work with the MASM32 assembly language package. This package is available free at http://www.pbq.com.au/home/hutch/masm.htm

 

Version 1.1 Notes

 

A few minor changes to CoLibwere made for the first service revision. Most notably, the requirement to create an object image structure has been removed, you need just define your custom data structure. It was realized the ClassItem held enough information to infer the full object size given the custom data object, hence the ClassItem definition has been revised.

 

This should not break older code. However, classes defined per the original spec will create objects that will waste some memory space.

 

The registrar code was revised some, a string pointer deletion invoke was accidentally removed, though registering is still a problem in NT, though less so.

 

The lib files were further subdividing so it is more useful in creating objects on the client side, without linking to unused code. Previously, if you linked to AllocObject, you also got a DllGetClassObject implementation due to the way the files cross-linked. This has been corrected to give the smallest builds possible.

 

Several typographical errors (and some just plain bad stuff) were also corrected in this document.

INTRODUCTION

Do not try to draw any correlation between the coserver library structures and those used by the Active Type Library (ATL). These two libraries have similar goals, but completely different implementations. The CoLib library structures have different meaning then the ATL structures, and a comparison should not be made.

 

 

When describing how the CoLib works, the following definitions are used:

 

CoLib or library: functionality implemented by the CoLib.Lib library

 

Project: a full dll COM server built using the CoLib library. Also used to illustrate named particulars a project must supply

 

Client: A separate program that invokes the compiled project dll

this_: a reference to the COM object to be returned from the COM

server to a client

CoLib OBJECT CREATION

 

Under Windows, when a COM client needs a COM object, it will invoke the CoCreate-Instance API, passing in the Class Identifier (clsid) and Interface Identifier (iid) of the required object. The CoCreateInstance function will load the DLL, then invokes DLL exports DllMainfollowed by DllGetClassObject. DllGetClassObject needs to perform a check if this class clsid is supported.

 

Inside a CoLib dll, DllGetClassObject performs this check by walking a structure called a ClassMap. This Map is an array of ClassItem structures, each items describing a class the DLL supports. If a match between the requested class clsid and a supported clsid in the ClassMap is made, a Class Factory Object (CFO) is created.

 

This CFO contains a reference to the matching ClassItem, such that each CFO is associated with a particular class. Thus, a particular CFO is a factory for a single class only.

 

The CFO method IClassFactory::CreateInstance is then invoked by the CoCreateInstance API. The factory creates its referenced object, and casts it as IUnknown. The IUnknown::QueryInterface method of this unknown object is then invoked, requesting the interface iid parameter of the original CoCreateInstanceinvocation. If the interface is supported, a reference to it is passed back to the caller. If not, the object is deleted and a fail code is returned.

 

Each ClassItem contains a reference to an InterfaceMap,which is an array of InterfaceItemstructures. Each item describes an interface supported by the object. This is how QueryInterfaceis able to determine what interfaces an object supports.

 

Briefly, that is how CoLib creates an object. The members of these class structures will be discussed in detail later on.

 

 

CLASS BASICS

 

Classes are defined in a structure called ClassItem. Each class defined in the project needs a ClassItem,which defines the requirements of the class. The fields of this structure are defined as so:

 

ClassItem STRUCT

m_clsid DWORD ; reference to the Class ID (clsid) or

; GUID of this class

m_Flags DWORD ; Control some basic object properties

; (See Object Flags)

m_pTypeLibInfo DWORD ; reference to a TypeLibInfo structure for

; this class

m_pIMap DWORD ; reference to an InterfaceMap for

; this class

m_pConstructor DWORD ; pointer to custom class constructor

; function, may be NULL

m_pDestructorDWORD ; pointer to custom class destructor

; function, may be NULL

m_pDataDWORD ; pointer to custom class data

; structure, may be NULL

m_ObjectSizeDWORD ; size of the custom ProjectData

; structure

ClassItem ENDS

 

 

This structure was redefined in CoLib version 1.1. Originally, m_ObjectSize defined the entire object size. This meant you had to custom define this object, not a simple task. It finally dawned on the author that only the custom data structure needs definition, as the other elements sizes may be determined either through SIZEOF at compile time, or counting at runtime.

 

Several interlocking structures are defined to provide all the information any class will need to define it's objects. All objects to be created through CoCreateInstance need have a ClassItem included in the ClassMap. Each project needs to define its custom ClassMap.

 

The ClassMap is an array of ClassItemstructures as so:

 

ClassMap:

ClassItem1 ClassItem { }

ClassItem1 ClassItem { }

...

ClassItemN ClassItem { }

END_CLASS_MAP

The END_CLASS_MAP macro is provided to flag the end of the Map list.   Classes also may also be instanced without a call to CoCreateInstance. If your class does not need to be instanced…

END_INTERFACE_MAP

The END_INTERFACE_MAP macro is provided to flag the end of the Map list.   Each object that may be served from the dll will need its particular InterfaceMap. Each InterfaceItem will need to…

ObjectData

  The ProjectData structure is custom to each class and must be defined by the…  

M_clsid

Class ID (clsid) for this class.

M_Flags

    AGGREGATABLE Object will allow itself to be…

M_pTypeLibInfo

Reference to the TypeLibInfo structure for this class.

M_pIMap

Reference to the InterfaceMap for this class.

M_pConstructor

Function pointer for the class creator function. Used to create any class-specific resources. May be NULL if no constructor is supplied.

M_pDestructor

Function pointer for the class deletion function. Used to clean up any class-specific resources. May be NULL if no destructor is supplied.

M_pData

Structure pointer for custom class information. It is entirely up to the specific class to determine how this parameter is used. May be NULL if no data is required.

M_ObjectSize

SIZEOF the specific class object structure. See ProjectObject.

 

 

InterfaceItem

InterfaceItem STRUCT

m_refiid DWORD 0

m_pVtbl DWORD 0

InterfaceItem ENDS

 

Contains parameters for an InterfaceMap item. Each interface of a class needs this definition.

M_refiid

refid for the GUID of this interface.

M_pVtbl

pointer to the implementation table for this interface.

 

 

ObjectData

ObjectDataSTRUCT

m_RefCountDWORD

m_pUnkOuterDWORD

m_lcidDWORD

m_ptiDWORD

m_pAggListDWORD

m_pClassItemDWORD

m_pEntry0DWORD

ObjectData

 

Contains basic instance information for an object. Each instance of a class needs this definition.

M_RefCount

reference count of the object

M_pUnkOuter

aggregating object's IUnknown

M_lcid

current LCID of this object

M_pti

object type library info pointer

M_pAggList

pointer to first aggregated object

M_pClassItem

reference to the ClassItem of this object

M_pEntry0

reference to first EntryItem entry (to index past the custom data area)

 

 

ObjectEntry

ObjectEntrySTRUCT

m_pVtblDWORD

m_pBaseDWORD

ObjectEntryENDS

 

Contains parameters for the TypeLibInfo structure to define a type library for a ClassItem class definition structure.

M_pVtbl

reference to the virtual table of functions for this interface

M_pBase

   

M_pIID_TYPELIB

refid for this type lib.

M_MajorVer

Major Version of type lib.

M_MinorVer

Minor Version of type lib.

 

 

 

APPENDIX C

DATA STRUCTURES IMPLEMENTED BY THE PROJECT

 

ClassMap

ClassMap:

ClassItem1 ClassItem { }

ClassItem2 ClassItem { }

...

ClassItemN ClassItem { }

END_CLASS_MAP

A ClassMap structure to define all classes supported by a particular dll. This array is particular to a given dll, and must be defined by the project employing the library. A ClassItem is used to define the ClassMap members, where the individual ClassItem structures are specified.

ClassItemN

An ClassItem structure for a particular class. Each class needs its ClassItem to be defined.

 

 

InterfaceMap

 

InterfaceMap EQU InterfaceItem1

InterfaceItem1 InterfaceItem{ }

InterfaceItem2 InterfaceItem{ }

...

InterfaceItemN InterfaceItem{ }

END_OF_INTERFACEMAP

 

 

A InterfaceMap structure to define all interfaces supported by a particular class. This array is particular to a given class, and each class must have an InterfaceMap defined by the project. An InterfaceItem is used to define the InterfaceMap elements, where the individual InterfaceItem structure is specified.

InterfaceMap

The InterfaceMap is a reference to the first element in the map array.

 

InterfaceItem

A InterfaceItem structure for a particular interface. Each interface in a class needs its InterfaceItem to be defined.

END_OF_INTERFACEMAP

   

M_DataItemN

   

ObjectData1

An instance of the ObjectData structure

ProjectData0

ProjectData is a holder for a particular class member data. It is defined in the project file.

ObjectEntryN

  APPENDIX D

GName

Textequate. Name to use for the GUID.
Will also define "p" & gName with a reference to gName.

 

reg

Optional parameter. Textequate. Text representation of the guid value. May be left blank if sgName is defined elsewhere in the project.

 

DeclareVARIANT

DeclareVARIANT MACRO varName, VarType, VarValue

 

Macro data function to define a variant data structure.

• Defines
• Also defined a named reference to the guid

Parameters

VarName

Variable name of the VARIANT being defined.

VarType

Variable type of the VARIANT being defined.

VarValue

  pObjectBase

PObject

reg Name of the register to return the cast. _offsetl

PObject

reg Name of the register to return the cast. _offsetl

ComPtrAssign PROC

lp:DWORD// reference to existing COM pointer Parameters pp

ComQIPtrAssign PROC

lp:DWORD// reference to existing COM pointer riid:DWORD// reference to existing COM pointer Parameters