CComDispatchDriver

class CComDispatchDriver

CComDispatchDriver lets you retrieve or set an object's properties through an IDispatch pointer. For more information about adding properties to an object, see the ATL Tutorial.

#include <atlctl.h>

Class Members

See Also IDispatch in the Win32 SDK


CComDispatchDriver Class Members

Methods
CComDispatchDriverConstructor.
GetPropertyGets the value of a property exposed by an object.
PutPropertySets the value of a property exposed by an object.
ReleaseReleases the IDispatch pointer and sets it to NULL.
Operators
operator IDispatch*Converts a CComDispatchDriver object to an IDispatch pointer.
operator *Returns the dereferenced value of the data member p.
operator &Returns the address of the data member p.
operator ->Returns the data member p.
operator =Sets the data member p to the specified IDispatch interface pointer.
operator !Checks whether the data member p is NULL or not.
Data Members
pPointer to the IDispatch interface.

CComDispatchDriver Overview


Methods


CComDispatchDriver::CComDispatchDriver

CComDispatchDriver( );
CComDispatchDriver( IDispatch* lp );
CComDispatchDriver( IUnknown* lp );

Parameters

lp [in] Pointer to an IDispatch or IUnknown interface.

Remarks

The constructor. If there is no lp parameter, the constructor initializesthe data member p to NULL. If lp points to an IDispatch interface, the constructor sets p to that interface and calls AddRef. If lp points to an IUnknown interface, the constructor calls QueryInterface for the IDispatch interface and sets p to *IDispatch.

The destructor calls Release on p if necessary.

CComDispatchDriver Overview | Class Members


CComDispatchDriver::GetProperty

HRESULT GetProperty( DISPID dwDispID, VARIANT* var );
static HRESULT GetProperty( IDispatch* pDisp, DISPID dwDispID, VARIANT* var );

Return Value

One of the standard HRESULT values.

Parameters

dwDispID [in] The DISPID of the property to be retrieved. The DISPID can be obtained from IDispatch::GetIDsOfNames.

var [out] Pointer to where the property value is to be stored.

pDisp [in] Pointer to the IDispatch interface.

Remarks

Gets the value of the property identified by dwDispID. If you supply pDisp, that IDispatch pointer is used. If you do not, the IDispatch pointer contained in the data member p is used.

The following example shows a call to the static version of GetProperty. This code is used to implement IPersistStreamInitImpl::Save.

CComPtr<IDispatch> pDispatch;
const IID* piidOld = NULL;
for(int i = 0; pMap[i].pclsidPropPage != NULL; i++)
               // pMap is a pointer to an array of 
               // ATL_PROPMAP_ENTRY structures
{
   if (pMap[i].szDesc == NULL)
      continue;
   CComVariant var;
   if(pMap[i].piidDispatch != piidOld)
   {
      if(FAILED(ControlQueryInterface(*pMap[i].piidDispatch, 
                                      (void**)&pDispatch)))
      {
         ATLTRACE(_T("Failed to get a dispatch pointer for 
                  property #%i\n"), i);
         hr = E_FAIL;
         break;
      }
      piidOld = pMap[i].piidDispatch;
   }
   if (FAILED(CComDispatchDriver::GetProperty(pDispatch, 
                                     pMap[i].dispid, &var)))
   {
      ATLTRACE(_T("Invoked failed on DISPID %x\n"), pMap[i].dispid);
      hr = E_FAIL;
      break;
   }
   HRESULT hr = var.WriteToStream(pStm);
   if (FAILED(hr))
      break;
}

CComDispatchDriver Overview | Class Members

See Also CComDispatchDriver::PutProperty


CComDispatchDriver::PutProperty

HRESULT PutProperty( DISPID dwDispID, VARIANT* var );
static HRESULT PutProperty( IDispatch* pDisp, DISPID dwDispID, VARIANT* var );

Return Value

One of the standard HRESULT values.

Parameters

dwDispID [in] The DISPID of the property to be set. The DISPID can be obtained from IDispatch::GetIDsOfNames.

var [in] Pointer to the property value to be set.

pDisp [in] Pointer to the IDispatch interface.

Remarks

Sets the value of the property identified by dwDispID to the value in var. If you supply pDisp, that IDispatch pointer is used. If you do not, the IDispatch pointer contained in the data member p is used.

Here is an example using PutProperty:

VARIANT var;
HRESULT hRes;
OLECHAR *szMember = "ThisProperty"; 
VariantInit(&var) 
... 
hRes = pDisp->GetIDsOfNames(IID_NULL, szMember, 1, LOCALE_USER_DEFAULT, &dwDispID);
hRes = CComDispatchDriver::PutProperty(pDisp, dwDispID, &var); 

CComDispatchDriver Overview | Class Members

See Also CComDispatchDriver::GetProperty


CComDispatchDriver::Release

void Release( );

Remarks

Checks whether data member p points to an IDispatch interface and, if it does, releases the interface and sets p to NULL.

CComDispatchDriver Overview | Class Members


Operators


CComDispatchDriver::operator IDispatch*

operator IDispatch* ( ) ;

Remarks

Converts a CComDispatchDriver object to an IDispatch pointer by returning the data member p. Thus, if the CComDispatchDriver object is pDD, the following two statements are equivalent:

pMyDisp=(IDispatch*)(pDD) 
pMyDisp= pDD.p 

CComDispatchDriver Overview | Class Members


CComDispatchDriver::operator *

IDispatch& operator *( );

Remarks

Returns the dereferenced value of the IDispatch interface pointer stored in the data member p.

Note The operation will assert if p is NULL.

CComDispatchDriver Overview | Class Members


CComDispatchDriver::operator &

IDispatch** operator &( );

Remarks

Returns the address of the IDispatch interface pointer stored in the data member p. The operation will assert if p is non-NULL. This operator avoids memory leaks if you want to set p without releasing it first.

CComDispatchDriver Overview | Class Members


CComDispatchDriver::operator ->

IDispatch* operator ->( );

Remarks

Returns the IDispatch interface pointer stored in the data member p.

Note The operation will assert if p is NULL.

CComDispatchDriver Overview | Class Members


CComDispatchDriver::operator =

IDispatch* operator =( IDispatch* lp ) ;
IDispatch*
operator =( IUnknown* lp ) ;

Remarks

Sets the data member p to an IDispatch interface pointer or to a pointer to an IDispatch interface obtained through an IUnknown pointer.

If p already points to an IDispatch interface, that interface is first released.

For example, if the CComDispatch Driver object is pDD and an IDispatch pointer is pMyDisp, pDD=pMyDisp sets pDD.p to pMyDisp. If an IUnknown pointer is pMyUnk, pDD=pMyUnk sets pDD.p to point to the IDispatch queried for on pMyUnk, that is:
pMyUnk->QueryInterface(IID_IDispatch, (void**)pDD.p);

CComDispatchDriver Overview | Class Members


CComDispatchDriver::operator !

BOOL operator !( );

Remarks

Returns TRUE if the data member p is NULL; otherwise, FALSE.

CComDispatchDriver Overview | Class Members


Data Members


CComDispatchDriver::p

IDispatch* p;

Remarks

The pointer to the IDispatch interface. This data member can be set to an existing IDispatch interface with operator =.

CComDispatchDriver Overview | Class Members

See Also CComDispatchDriver::operator =