COleDispatchDriver Class

Implements the client side of OLE automation.

Syntax

class COleDispatchDriver

Members

Public Constructors

Name	Description
COleDispatchDriver::COleDispatchDriver	Constructs a COleDispatchDriver object.

Public Methods

Name	Description
COleDispatchDriver::AttachDispatch	Attaches an IDispatch connection to the COleDispatchDriver object.
COleDispatchDriver::CreateDispatch	Creates an IDispatch connection and attaches it to the COleDispatchDriver object.
COleDispatchDriver::DetachDispatch	Detaches an IDispatch connection, without releasing it.
COleDispatchDriver::GetProperty	Gets an automation property.
COleDispatchDriver::InvokeHelper	Helper for calling automation methods.
COleDispatchDriver::ReleaseDispatch	Releases an IDispatch connection.
COleDispatchDriver::SetProperty	Sets an automation property.

Public Operators

Name	Description
COleDispatchDriver::operator =	Copies the source value into the COleDispatchDriver object.
COleDispatchDriver::operator LPDISPATCH	Accesses the underlying IDispatch pointer.

Public Data Members

Name	Description
COleDispatchDriver::m_bAutoRelease	Specifies whether to release the IDispatch during ReleaseDispatch or object destruction.
COleDispatchDriver::m_lpDispatch	Indicates the pointer to the IDispatch interface attached to this COleDispatchDriver.

Remarks

COleDispatchDriver does not have a base class.

OLE dispatch interfaces provide access to an object's methods and properties. Member functions of COleDispatchDriver attach, detach, create, and release a dispatch connection of type IDispatch. Other member functions use variable argument lists to simplify calling IDispatch::Invoke.

This class can be used directly, but it is generally used only by classes created by the Add Class wizard. When you create new C++ classes by importing a type library, the new classes are derived from COleDispatchDriver.

For more information on using COleDispatchDriver, see the following articles:

• Automation Clients

• Automation Servers

Inheritance Hierarchy

COleDispatchDriver

Requirements

Header: afxdisp.h

COleDispatchDriver::AttachDispatch

Call the AttachDispatch member function to attach an IDispatch pointer to the COleDispatchDriver object. For more information, see Implementing the IDispatch Interface.

void AttachDispatch(
    LPDISPATCH lpDispatch,
    BOOL bAutoRelease = TRUE);

Parameters

lpDispatch
Pointer to an OLE IDispatch object to be attached to the COleDispatchDriver object.

bAutoRelease
Specifies whether the dispatch is to be released when this object goes out of scope.

Remarks

This function releases any IDispatch pointer that is already attached to the COleDispatchDriver object.

Example

void COleContainerView::OnAttachDispatch()
{
   CLSID clsidWMP;
   LPDISPATCH pWMPDispatch = NULL;
   COleDispatchDriver oddWMP;

   try
   {
      AfxCheckError(::CLSIDFromProgID(_T("WMPlayer.OCX"), &clsidWMP));

      AfxCheckError(::CoCreateInstance(clsidWMP, NULL, CLSCTX_INPROC_SERVER,
         IID_IDispatch, (LPVOID*)& pWMPDispatch));

      oddWMP.AttachDispatch(pWMPDispatch, TRUE);
      pWMPDispatch = NULL; // our COleDispatchDriver now owns the interface

      CString strUIMode;
      oddWMP.GetProperty(23, VT_BSTR, (void*)& strUIMode);
      TRACE(_T("WMP uiMode is %s.\n"), strUIMode);
   }
   catch (COleException* pe)
   {
      pe->ReportError();
      pe->Delete();
   }
   catch (CMemoryException* pe)
   {
      pe->ReportError();
      pe->Delete();
   }

   // cleanup
   if (NULL != pWMPDispatch)
   {
      pWMPDispatch->Release();
   }

   // COleDispatchDriver automatically releases the dispatch interface when
   // it goes out of scope if m_bAutoRelease is TRUE.
}

COleDispatchDriver::COleDispatchDriver

Constructs a COleDispatchDriver object.

COleDispatchDriver();
COleDispatchDriver(LPDISPATCH lpDispatch, BOOL bAutoRelease = TRUE);
COleDispatchDriver(const COleDispatchDriver& dispatchSrc);

Parameters

lpDispatch
Pointer to an OLE IDispatch object to be attached to the COleDispatchDriver object.

bAutoRelease
Specifies whether the dispatch is to be released when this object goes out of scope.

dispatchSrc
Reference to an existing COleDispatchDriver object.

Remarks

The form COleDispatchDriver( LPDISPATCH lpDispatch, BOOL bAutoRelease = TRUE ) connects the IDispatch interface.

The form COleDispatchDriver( const COleDispatchDriver& dispatchSrc ) copies an existing COleDispatchDriver object and increments the reference count.

The form COleDispatchDriver( ) creates a COleDispatchDriver object but does not connect the IDispatch interface. Before using COleDispatchDriver( ) without arguments, you should connect an IDispatch to it using either COleDispatchDriver::CreateDispatch or COleDispatchDriver::AttachDispatch. For more information, see Implementing the IDispatch Interface.

Example

See the example for COleDispatchDriver::CreateDispatch.

COleDispatchDriver::CreateDispatch

Creates an IDispatch interface object and attaches it to the COleDispatchDriver object.

BOOL CreateDispatch(
    REFCLSID clsid,
    COleException* pError = NULL);

BOOL CreateDispatch(
    LPCTSTR lpszProgID,
    COleException* pError = NULL);

Parameters

clsid
Class ID of the IDispatch connection object to be created.

pError
Pointer to an OLE exception object, which will hold the status code resulting from the creation.

lpszProgID
Pointer to the programmatic identifier, such as "Excel.Document.5", of the automation object for which the dispatch object is to be created.

Return Value

Nonzero on success; otherwise 0.

Example

void COleContainerView::OnCreateDispatch()
{
   COleDispatchDriver disp;
   COleException* pe = new COleException;

   try
   {
      // Create instance of Microsoft System Information Control 
      // by using ProgID.
      if (disp.CreateDispatch(_T("WMPlayer.OCX"), pe))
      {
         //Get uiMode.     
         CString strUIMode;
         disp.InvokeHelper(23, DISPATCH_PROPERTYGET, VT_BSTR,
            (void*)& strUIMode, NULL);

         CString strMsg;
         strMsg.Format(_T("WMP uiMode is %s."), strUIMode);
         AfxMessageBox(strMsg);
      }
      else
      {
         throw pe;
      }
   }
   //Catch control-specific exceptions.
   catch (COleDispatchException* pe)
   {
      CString cStr;

      if (!pe->m_strSource.IsEmpty())
         cStr = pe->m_strSource + _T(" - ");
      if (!pe->m_strDescription.IsEmpty())
         cStr += pe->m_strDescription;
      else
         cStr += _T("unknown error");

      AfxMessageBox(cStr, MB_OK,
         (pe->m_strHelpFile.IsEmpty()) ? 0 : pe->m_dwHelpContext);

      pe->Delete();
   }
   //Catch all MFC exceptions, including COleExceptions.
   // OS exceptions will not be caught.
   catch (CException* pe)
   {
      TRACE(_T("%s(%d): OLE Execption caught: SCODE = %x"),
         __FILE__, __LINE__, COleException::Process(pe));
      pe->Delete();
   }

   pe->Delete();
}

COleDispatchDriver::DetachDispatch

Detaches the current IDispatch connection from this object.

LPDISPATCH DetachDispatch();

Return Value

A pointer to the previously attached OLE IDispatch object.

Remarks

The IDispatch is not released.

For more information about the LPDISPATCH type, see Implementing the IDispatch Interface in the Windows SDK.

Example

LPDISPATCH CreateLPDispatch(LPCTSTR lpszProgId)
{
   COleDispatchDriver disp;

   disp.CreateDispatch(lpszProgId);

   return disp.DetachDispatch();
}

COleDispatchDriver::GetProperty

Gets the object property specified by dwDispID.

void GetProperty(
    DISPID dwDispID,
    VARTYPE vtProp,
    void* pvProp) const;

Parameters

dwDispID
Identifies the property to be retrieved.

vtProp
Specifies the property to be retrieved. For possible values, see the Remarks section for COleDispatchDriver::InvokeHelper.

pvProp
Address of the variable that will receive the property value. It must match the type specified by vtProp.

Example

CString IMyComObject::GetString(DISPID dispid)
{
   CString result;
   GetProperty(dispid, VT_BSTR, (void*)& result);
   return result;
}

COleDispatchDriver::InvokeHelper

Calls the object method or property specified by dwDispID, in the context specified by wFlags.

void AFX_CDECL InvokeHelper(
    DISPID dwDispID,
    WORD wFlags,
    VARTYPE vtRet,
    void* pvRet,
    const BYTE* pbParamInfo, ...);

Parameters

dwDispID
Identifies the method or property to be invoked.

wFlags
Flags describing the context of the call to IDispatch::Invoke. . For a list of possible values, see the wFlags parameter in IDispatch::Invoke in the Windows SDK.

vtRet
Specifies the type of the return value. For possible values, see the Remarks section.

pvRet
Address of the variable that will receive the property value or return value. It must match the type specified by vtRet.

pbParamInfo
Pointer to a null-terminated string of bytes specifying the types of the parameters following pbParamInfo.

...
Variable list of parameters, of types specified in pbParamInfo.

Remarks

The pbParamInfo parameter specifies the types of the parameters passed to the method or property. The variable list of arguments is represented by ... in the syntax declaration.

Possible values for the vtRet argument are taken from the VARENUM enumeration. Possible values are as follows:

Symbol	Return Type
VT_EMPTY	void
VT_I2	short
VT_I4	long
VT_R4	float
VT_R8	double
VT_CY	CY
VT_DATE	DATE
VT_BSTR	BSTR
VT_DISPATCH	LPDISPATCH
VT_ERROR	SCODE
VT_BOOL	BOOL
VT_VARIANT	VARIANT
VT_UNKNOWN	LPUNKNOWN

The pbParamInfo argument is a space-separated list of VTS_ constants. One or more of these values, separated by spaces (not commas), specifies the function's parameter list. Possible values are listed with the EVENT_CUSTOM macro.

This function converts the parameters to VARIANTARG values, then invokes the IDispatch::Invoke method. If the call to Invoke fails, this function will throw an exception. If the SCODE (status code) returned by IDispatch::Invoke is DISP_E_EXCEPTION, this function throws a COleException object; otherwise it throws a COleDispatchException.

For more information, see VARIANTARG, Implementing the IDispatch Interface, IDispatch::Invoke, and Structure of COM Error Codes in the Windows SDK.

Example

See the example for COleDispatchDriver::CreateDispatch.

COleDispatchDriver::m_bAutoRelease

If TRUE, the COM object accessed by m_lpDispatch will be automatically released when ReleaseDispatch is called or when this COleDispatchDriver object is destroyed.

BOOL m_bAutoRelease;

Remarks

By default, m_bAutoRelease is set to TRUE in the constructor.

For more information on releasing COM objects, see Implementing Reference Counting and IUnknown::Release in the Windows SDK.

Example

// Clean up by forcing Release to be called
// on COleDispatchDriver object and delete
if (bError)
{
   pDisp->m_bAutoRelease = TRUE;
   delete pDisp;
   pDisp = NULL;
}

COleDispatchDriver::m_lpDispatch

The pointer to the IDispatch interface attached to this COleDispatchDriver.

LPDISPATCH m_lpDispatch;

Remarks

The m_lpDispatch data member is a public variable of type LPDISPATCH.

For more information, see IDispatch in the Windows SDK.

Example

See the example for COleDispatchDriver::AttachDispatch.

COleDispatchDriver::operator =

Copies the source value into the COleDispatchDriver object.

const COleDispatchDriver& operator=(const COleDispatchDriver& dispatchSrc);

Parameters

dispatchSrc
A pointer to an existing COleDispatchDriver object.

COleDispatchDriver::operator LPDISPATCH

Accesses the underlying IDispatch pointer of the COleDispatchDriver object.

operator LPDISPATCH();

Example

COleDispatchDriver disp;
if (disp.CreateDispatch(_T("WMPlayer.OCX")))
{
   IDispatch* pDispatch = disp; //COleDispatchDriver::operator
                                //LPDISPATCH is called here
   IUnknown* pUnkn = NULL;
   HRESULT hr = pDispatch->QueryInterface(IID_IUnknown, (void**)& pUnkn);
   if (SUCCEEDED(hr))
   {
      //Do something...
      pUnkn->Release();
   }
}

COleDispatchDriver::ReleaseDispatch

Releases the IDispatch connection. For more information, see Implementing the IDispatch Interface

void ReleaseDispatch();

Remarks

If auto release has been set for this connection, this function calls IDispatch::Release before releasing the interface.

Example

See the example for COleDispatchDriver::AttachDispatch.

COleDispatchDriver::SetProperty

Sets the OLE object property specified by dwDispID.

void AFX_CDECL SetProperty(
    DISPID dwDispID,
    VARTYPE vtProp, ...);

Parameters

dwDispID
Identifies the property to be set.

vtProp
Specifies the type of the property to be set. For possible values, see the Remarks section for COleDispatchDriver::InvokeHelper.

...
A single parameter of the type specified by vtProp.

Example

void IMyComObject::SetString(DISPID dispid, LPCTSTR propVal)
{
   SetProperty(dispid, VT_BSTR, propVal);
}

See also

MFC Sample CALCDRIV
MFC Sample ACDUAL
Hierarchy Chart
CCmdTarget Class