DumontEXE 0.0.1
Public Member Functions
cmcApi Class Reference

Commence COM Interface. More...

#include <cmcApi.h>

Inheritance diagram for cmcApi:

List of all members.

Public Member Functions

virtual ULONG AddRef (void)
 Server AddRef call.
 cmcApi (const cmcApi &copy)
 Copy Constructor.
 cmcApi (const QString &objectName, IDispatch *dispatch, cmcApplication *application, QObject *parent=NULL)
 Primary Constructor.
virtual QString GetServerString (DISPID dispid, const QString &req, WORD wFlags=DISPATCH_PROPERTYGET, HRESULT *hr=NULL)
virtual HRESULT QueryInterface (REFIID riid, void __RPC_FAR *__RPC_FAR *ppvObject)
 Server QueryInterface Call.
virtual ULONG Release (void)
 Server Release call.
virtual ~cmcApi ()
 Primary Destructor.

Detailed Description

Commence COM Interface.

This is the primary object used to interface to anything within the Commence executable. This interface occurs through the COM API. All of the calls are marshalled through the Invoke() method after the parameters have been initialized and whatnot. Included is a series of convenience functions such as GetServerLong(), GetServerBool(), GetServerString() and so on.

Let me make a note here on reference counting - a fun subject! When you call a COM invoke function on a server, and that server returns to you a new IDispatch pointer, that IDispatch pointer usually points to another server object. When the server fetched for you that new server object, it incremented the reference count on that new server object. You asked for a pointer to an object, the server manufactured it for you, and before it returned it to you it incremented it reference count so that the object the pointer was pointing to wouldn't inadvertently get destroyed before you got your hands on it.

Therefore, you now have an IDispatch pointer that is properly reference counted. Before you can throw that pointer away, you *must* release it. If you do not, then the server will still think there is a reference counted pointer hanging around somewhere.

In this Dumont project, we wrap these pointers inside of our Commence objects, since that's what the objects are for - interfacing to Commence. Our wrappers take care of all the messy interface details. However, when we construct a new wrapper, we pass along this IDispatch pointer we received earlier. According to policy, when we pass that pointer along to another function or wrapper, we must increment its reference count, since, there are now two objects that are holding a copy of that pointer. This is no problem because when our server wrapper gets created, with a reference to this dispatch pointer, it increments the reference count on that IDispatch pointer. And when our wrapper object gets destroyed, it decrements the reference count. All is good.

Until...

...we forget that we still have that initial IDispatch pointer we received from our initial invoke request on the server. As long as we remember to release the reference count on that pointer then everything is ok.

So, check out the code on the cmcApplication::database() routine for instance. You will see that first a IDispatch pointer is obtained from Invoke (AddRef(), that's one). Then we pass that interface pointer along to our new object wrapper (AddRef() again, that's two). Now, since we're done with the first IDispatch pointer we need to release it before we terminate this routine, otherwise we'll have that dangling pointer lying around that we don't want. The object that we created, still has a reference counted pointer to the object, and once eventually that object gets destroyed (sometime later), then the final count on that reference counted IDispatch pointer will be freed and the server will (probably) release that object from memory.

This is a very important concept to understand for vbScript, since it opens and releases objects constantly. Dumont is tailored very carefully to insure that objects that are referenced by some other part of the system are not inadvertently destroyed before vbScript is through with it.

Definition at line 93 of file cmcApi.h.


Constructor & Destructor Documentation

cmcApi ( const cmcApi copy)

Copy Constructor.

Definition at line 31 of file cmcApi.cpp.

cmcApi ( const QString &  objectName,
IDispatch *  dispatch,
cmcApplication application,
QObject *  parent = NULL 
)

Primary Constructor.

This constructor is used by any one of the super classes. It requires a pointer to the dispatch interface, and also requires a reference to the application object itself.

Definition at line 36 of file cmcApi.cpp.

virtual ~cmcApi ( ) [inline, virtual]

Primary Destructor.

This destructor handles cleanup of the object.

Definition at line 121 of file cmcApi.h.


Member Function Documentation

virtual ULONG AddRef ( void  ) [inline, virtual]

Server AddRef call.

This makes the call to the server AddRef.

Definition at line 153 of file cmcApi.h.

QString GetServerString ( DISPID  dispid,
const QString &  req,
WORD  wFlags = DISPATCH_PROPERTYGET,
HRESULT *  hr = NULL 
) [virtual]

Todo:
Make this code report these errors via the err object.

Definition at line 356 of file cmcApi.cpp.

virtual HRESULT QueryInterface ( REFIID  riid,
void __RPC_FAR *__RPC_FAR *  ppvObject 
) [inline, virtual]

Server QueryInterface Call.

This makes the call to the server QueryInterface.

Definition at line 134 of file cmcApi.h.

virtual ULONG Release ( void  ) [inline, virtual]

Server Release call.

This makes the call to the server Release.

Definition at line 167 of file cmcApi.h.


The documentation for this class was generated from the following files:
 All Classes Namespaces Functions Variables Enumerations Enumerator Properties




~ ~ ~ ~ ~ ~
Source Code without Comments is like a Cranberry Garland
without the berries. Comment your Code!
 
Commence Database User Support Group Forum
http://newsgroup.showoff-db.org/
~ ~ ~ ~ ~ ~
Author: Mark Petryk
Lorimark Solutions, LLC
mark@lorimarksolutions.com