COleDispatchDriver-Klasse

Implementiert die Clientseite der OLE-Automatisierung.

Syntax

class COleDispatchDriver

Member

Öffentliche Konstruktoren

Öffentliche Methoden

Öffentliche Operatoren

Öffentliche Datenmember

Hinweise

COleDispatchDriver besitzt keine Basisklasse.

OLE-Verteilerschnittstellen bieten Zugriff auf die Methoden und Eigenschaften eines Objekts. Memberfunktionen von COleDispatchDriver Anfügen, Trennen, Erstellen und Freigeben einer Verteilerverbindung vom Typ IDispatch. Andere Memberfunktionen verwenden Variablenargumentlisten, um das Aufrufen IDispatch::Invokezu vereinfachen.

Diese Klasse kann direkt verwendet werden, wird jedoch in der Regel nur von Klassen verwendet, die vom Assistenten zum Hinzufügen von Kursen erstellt wurden. Wenn Sie neue C++-Klassen durch Importieren einer Typbibliothek erstellen, werden die neuen Klassen von COleDispatchDriver.

Weitere Informationen zur Verwendung COleDispatchDriverfinden Sie in den folgenden Artikeln:

• Automatisierungsclients

• Automatisierungsserver

Vererbungshierarchie

COleDispatchDriver

Anforderungen

Header: afxdisp.h

COleDispatchDriver::AttachDispatch

Rufen Sie die AttachDispatch -Memberfunktion auf, um dem IDispatch -Objekt einen COleDispatchDriver -Zeiger anzufügen. Weitere Informationen finden Sie unter Implementing the IDispatch Interface.

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

Parameter

lpDispatch
Zeiger auf ein IDispatch -OLE-Objekt, der an das COleDispatchDriver -Objekt angefügt werden soll.

bAutoRelease
Gibt an, ob die Verteilung freigegeben werden soll, wenn dieses Objekt den Gültigkeitsbereich verlässt.

Hinweise

Diese Funktion gibt alle IDispatch -Zeiger zurück, die dem COleDispatchDriver -Objekt bereits angefügt wurden.

Beispiel

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

Erstellt ein COleDispatchDriver-Objekt.

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

Parameter

lpDispatch
Zeiger auf ein IDispatch -OLE-Objekt, der an das COleDispatchDriver -Objekt angefügt werden soll.

bAutoRelease
Gibt an, ob die Verteilung freigegeben werden soll, wenn dieses Objekt den Gültigkeitsbereich verlässt.

dispatchSrc
Verweisen auf ein vorhandenes COleDispatchDriver Objekt.

Hinweise

Das Formular COleDispatchDriver( LPDISPATCH lpDispatch, BOOL bAutoRelease = TRUE ) verbindet die IDispatch-Schnittstelle .

Das Formular COleDispatchDriver( const COleDispatchDriver& dispatchSrc ) kopiert ein vorhandenes COleDispatchDriver Objekt und erhöht die Referenzanzahl.

Das Formular COleDispatchDriver( ) erstellt ein COleDispatchDriver Objekt, verbindet die IDispatch Schnittstelle jedoch nicht. Bevor Sie ohne Argumente verwenden COleDispatchDriver( ) , sollten Sie eine IDispatch Verbindung mit dieser herstellen, indem Sie entweder COleDispatchDriver::CreateDispatch oder COleDispatchDriver::AttachDispatch verwenden. Weitere Informationen finden Sie unter Implementing the IDispatch Interface.

Beispiel

Siehe dazu das Beispiel für COleDispatchDriver::CreateDispatch.

COleDispatchDriver::CreateDispatch

Erstellt ein IDispatch -Schnittstellenobjekt und fügt es zum COleDispatchDriver -Objekt hinzu.

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

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

Parameter

clsid
Die Klassen-ID, des zu erstellenden IDispatch -Verbindungsobjekts.

pError
Ein Zeiger auf ein OLE-Ausnahmeobjekt, das den Statuscode aufnimmt, der sich durch die Erstellung ergibt.

lpszProgID
Ein Zeiger auf den programmgesteuerten Bezeichner, z. B. „Excel.Document.5“, des Automatisierungsobjekts, für das das Dispatch-Objekt erstellt werden soll.

Rückgabewert

Bei Erfolg ein Wert ungleich 0 (null), andernfalls 0 (null).

Beispiel

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::D etachDispatch

Trennt die aktuelle IDispatch Verbindung von diesem Objekt.

LPDISPATCH DetachDispatch();

Rückgabewert

Ein Zeiger auf das zuvor angefügte OLE-Objekt IDispatch .

Hinweise

Dies IDispatch wird nicht freigegeben.

Weitere Informationen zum LPDISPATCH-Typ finden Sie unter Implementieren der IDispatch-Schnittstelle im Windows SDK.

Beispiel

LPDISPATCH CreateLPDispatch(LPCTSTR lpszProgId)
{
   COleDispatchDriver disp;

   disp.CreateDispatch(lpszProgId);

   return disp.DetachDispatch();
}

COleDispatchDriver::GetProperty

Ruft die durch dwDispID angegebene Objekteigenschaft ab.

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

Parameter

dwDispID
Identifiziert die abzurufende Eigenschaft.

vtProp
Gibt die abzurufende Eigenschaft an. Informationen zu den möglichen Werten finden Sie im Abschnitt „Anmerkungen“ für COleDispatchDriver::InvokeHelper.

pvProp
Adresse der Variablen, die den Eigenschaftswert erhält. Er muss mit dem durch vtProp angegebenen Typ übereinstimmen.

Beispiel

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

COleDispatchDriver::InvokeHelper

Ruft die durch dwDispID angegebene Objektmethode oder -eigenschaft im durch wFlags angegebenen Kontext auf.

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

Parameter

dwDispID
Bezeichnet die aufzurufende Methode oder Eigenschaft.

wFlags
Flags, die den Kontext des Aufrufs IDispatch::Invokebeschreiben. . Eine Liste der möglichen Werte finden Sie im wFlags-Parameter in IDispatch::Invoke im Windows SDK.

vtRet
Gibt den Typ des Rückgabewerts an. Mögliche Werte finden Sie im Abschnitt „Hinweise“.

pvRet
Die Adresse der Variablen, die den Eigenschaftswert oder Rückgabewert aufnimmt. Er muss mit dem von vtRet angegebenen Typ übereinstimmen.

pbParamInfo
Zeigen Sie auf eine mit Null beendete Zeichenfolge mit Bytes, die die Typen der Parameter nach pbParamInfo angibt.

...
Variable Liste der Parameter, von Typen, die in pbParamInfo angegeben sind.

Hinweise

Der PbParamInfo-Parameter gibt die Typen der Parameter an, die an die Methode oder Eigenschaft übergeben werden. Die variable Argumentliste wird in der Syntaxdeklaration durch ... dargestellt.

Mögliche Werte für das vtRet-Argument stammen aus der VARENUM-Aufzählung. Verfügbare mögliche Werte:

Das PbParamInfo-Argument ist eine durch Leerzeichen getrennte Liste mit VTS_ Konstanten. Einer oder mehrere dieser Werte, durch Leerzeichen (nicht Kommas) getrennt, gibt bzw. geben die Parameterliste der Funktion an. Die möglichen Werte sind beim Makro EVENT_CUSTOM aufgelistet.

Diese Funktion konvertiert die Parameter in VARIANTARG-Werte und ruft dann die IDispatch::Invoke-Methode auf. Bei einem Fehler des Aufrufs von Invoke löst diese Funktion eine Ausnahme aus. Wenn der von IDispatch::Invoke zurückgegebene SCODE (Statuscode) DISP_E_EXCEPTION ist, löst diese Funktion ein COleException-Objekt aus. Andernfalls wird eine COleDispatchException ausgelöst.

Weitere Informationen finden Sie unter VARIANTARG, Implementieren der IDispatch-Schnittstelle, IDispatch::Invoke und Struktur von COM-Fehlercodes im Windows SDK.

Beispiel

Siehe dazu das Beispiel für COleDispatchDriver::CreateDispatch.

COleDispatchDriver::m_bAutoRelease

Wenn TRUE, wird das COM-Objekt, auf das von m_lpDispatch zugegriffen wird, automatisch freigegeben, wenn ReleaseDispatch aufgerufen wird oder wenn dieses COleDispatchDriver Objekt zerstört wird.

BOOL m_bAutoRelease;

Hinweise

Standardmäßig m_bAutoRelease ist im Konstruktor auf TRUE festgelegt.

Weitere Informationen zum Freigeben von COM-Objekten finden Sie unter Implementieren von Referenzzählungen und IUnknown::Release im Windows SDK.

Beispiel

// 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

Der Zeiger auf die IDispatch an diese COleDispatchDriverSchnittstelle angefügte Schnittstelle.

LPDISPATCH m_lpDispatch;

Hinweise

Das m_lpDispatch Datenelement ist eine öffentliche Variable vom Typ LPDISPATCH.

Weitere Informationen finden Sie unter "IDispatch " im Windows SDK.

Beispiel

Sehen Sie sich das Beispiel für COleDispatchDriver::AttachDispatch an.

COleDispatchDriver::operator =

Kopiert den Quellwert in das COleDispatchDriver Objekt.

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

Parameter

dispatchSrc
Ein Zeiger auf ein vorhandenes COleDispatchDriver Objekt.

COleDispatchDriver::operator LPDISPATCH

Greift auf den zugrunde liegenden IDispatch Zeiger des COleDispatchDriver Objekts zu.

operator LPDISPATCH();

Beispiel

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

Gibt die IDispatch Verbindung frei. Weitere Informationen finden Sie unter Implementieren der IDispatch-Schnittstelle

void ReleaseDispatch();

Hinweise

Wenn die automatische Freigabe für diese Verbindung festgelegt wurde, ruft diese Funktion vor dem Freigeben der Schnittstelle auf IDispatch::Release .

Beispiel

Sehen Sie sich das Beispiel für COleDispatchDriver::AttachDispatch an.

COleDispatchDriver::SetProperty

Legt die durch dwDispID angegebene OLE-Objekteigenschaft fest.

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

Parameter

dwDispID
Gibt die festzulegende Eigenschaft an.

vtProp
Gibt den Typ der festzulegenden Eigenschaft an. Informationen zu den möglichen Werten finden Sie im Abschnitt „Anmerkungen“ für COleDispatchDriver::InvokeHelper.

...
Ein einzelner Parameter des typs, der von vtProp angegeben wird.

Beispiel

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

Siehe auch

MFC-Beispiel CALCDRIV
MFC-Beispiel ACDUAL
Hierarchiediagramm
CCmdTarget-Klasse