TN039: MFC/OLE-Automatisierungs-Implementierung

Hinweis
Im Folgenden technischen Hinweis ist nicht aktualisiert wurde, seitdem er erstmals in der Onlinedokumentation enthalten waren.Folglich können mehrere Prozeduren und Themen veraltet oder falsch.Die aktuellsten Informationen wird empfohlen, zum Thema Onlinedokumentations im Index finden.

Übersicht über OLE Schnittstelle IDispatch

Die Schnittstelle wird durch IDispatch bedeutet, welche Anwendungen Methoden und Eigenschaften verfügbar machen, dass andere Anwendungen, z. B. Visual Basic oder andere Sprachen, in denen Funktionen der Anwendung verwenden können.Die meisten wichtigen Teil dieser Schnittstelle ist die IDispatch::Invoke-Funktion.MFC verwendet "Dispatchzuordnungen", um IDispatch::Invoke zu implementieren.Die MFC-Implementierungs stellt die Dispatchzuordnung auf dem Layout der Form "oder" aus dem CCmdTarget abgeleitete Klassen, sodass sie die Eigenschaften des Objekts direkt bearbeiten kann, oder ruft Memberfunktionen innerhalb Ihres Objekts auf, um IDispatch::Invoke Anforderungen zu erfüllen.

In den meisten Fällen kooperiert ClassWizard und MFC verwendet, um die meisten Details der OLE-Automatisierung vom programmierer Anwendung auszublenden.Der Programmierer liegt der Schwerpunkt auf den tatsächlichen Funktionen, die in der Anwendung verfügbar zu machen und müssen sich nicht um die zugrunde liegende Klempnerarbeit bereitgestellt.

Es gibt jedoch Fälle, in denen es notwendig ist, zu verstehen, die MFC im Hintergrund ausgeführt wird.Dieser Hinweis wird, wie das Framework DISPID s in den Memberfunktionen und Eigenschaften zuweist.Kenntnisse des Algorithmus für das Zuweisen von MFC verwendet DISPID s ist nur erforderlich, wenn Sie die IDs kennen müssen, beispielsweise wenn Sie eine Typbibliothek" für die Objekte der Anwendung erstellen.

Zuweisung MFC DISPID

Obwohl der Endbenutzer der Automatisierung (ein Visual Basic-Benutzer, z. B.), die tatsächlichen Namen der Automatisierung aktivierten Eigenschaften und Methoden in ihrem Code (z. B. obj.ShowWindow) sieht, erhält die Implementierung von IDispatch::Invoke nicht die tatsächlichen Namen.Für gründe Optimierung empfängt es DISPID, das ein 32-Bit- "Magic Cookie" lautet, das die Methode oder die Eigenschaft beschreibt, auf die zugegriffen werden soll.Diese DISPID-Werte werden von der IDispatch Implementierung durch eine andere Methode zurückgegeben wird, aufgerufen IDispatch::GetIDsOfNames.Eine Automatisierung clientanwendung ruft GetIDsOfNames einmal für jeden Member oder für jede überschriebene Eigenschaft, die bestimmt und speichert sie an den Zugriff für spätere Aufrufe IDispatch::Invoke.Auf diese Weise stellt die teure Zeichenfolgen Discovery wird einmal pro Objekt verwenden, anstatt nur einmal pro IDispatch::Invoke Aufruf durchgeführt.

MFC bestimmt das DISPID für jede Methode und - Eigenschaft auf zwei Dinge:

• Der Abstand zwischen dem oberen Rand der Dispatchzuordnung relativ (1)

• Der Abstand der Dispatchzuordnung der meisten abgeleiteten Klasse den relativen Koordinaten (0)

DISPID wird in zwei Teilen.LOWORDDISPID enthält die erste Komponente, den Abstand zwischen dem oberen Rand der Dispatchzuordnung.HIWORD enthält den Abstand zwischen der meisten abgeleiteten Klasse.Beispiele:

class CDispPoint : public CCmdTarget
{
public:
    short m_x, m_y;
    ...
    DECLARE_DISPATCH_MAP()
    ...
};

class CDisp3DPoint : public CDispPoint
{
public:
    short m_z;
    ...
    DECLARE_DISPATCH_MAP()
    ...
};

BEGIN_DISPATCH_MAP(CDispPoint, CCmdTarget)
    DISP_PROPERTY(CDispPoint, "x", m_x, VT_I2)
    DISP_PROPERTY(CDispPoint, "y", m_y, VT_I2)
END_DISPATCH_MAP()

BEGIN_DISPATCH_MAP(CDisp3DPoint, CDispPoint)
    DISP_PROPERTY(CDisp3DPoint, "z", m_z, VT_I2)
END_DISPATCH_MAP()

Wie Sie sehen können, gibt es zwei Klassen, die OLE-Automatisierungs-Schnittstellen verfügbar machen.Eine dieser Klassen ist der anderen abgeleitet und nutzt somit die Funktionalität der Basisklasse, einschließlich des OLE-Automatisierungs-Teil ("X" und "y" Eigenschaften in diesem Fall).

MFC CDispPoint Klasse für DISPID generiert:

property X    (DISPID)0x00000001
property Y    (DISPID)0x00000002

Da die Eigenschaften nicht in einer Basisklasse ist immer DISPID (null HIWORD die relativen Abstände von der meisten abgeleiteten Klasse für CDispPoint ist null).

MFC CDisp3DPoint Klasse für DISPID generiert:

property Z    (DISPID)0x00000001
property X    (DISPID)0x00010001
property Y    (DISPID)0x00010002

Die Z-Eigenschaft ist DISPID mit Nullen HIWORD angegeben, wie sie in der Klasse, die die Eigenschaften verfügbar macht, CDisp3DPoint definiert ist.Da die X und Y werden in einer Basisklasse definiert ist 1 DISPIDHIWORD, da die Klasse, in der diese Eigenschaft definiert sind, in einem Abstand von einer Ableitung von der meisten abgeleiteten Klasse ist.

Hinweis
LOWORD wird immer durch die Position der Zuordnung bestimmt, auch wenn Einträge in der Zuordnung mit explizitem DISPID vorhanden sind (siehe nächsten Abschnitt zu Informationen über die _ID-Versionen der DISP_PROPERTY und DISP_FUNCTION Makros).

Erweiterte MFC-Dispatchzuordnungs-Funktionen

Es gibt einige zusätzliche Funktionen, die ClassWizard nicht mit dieser Version von Visual C++ unterstützt.ClassWizard unterstützt DISP_FUNCTION, DISP_PROPERTY und DISP_PROPERTY_EX, die eine Methode, eine Eigenschaft definieren und Membervariablen bzw. eine Funktionseigenschaft des festgelegten Members erzeugt abrufen.Diese Funktionen sind normalerweise alle, die benötigt werden, um die meisten Automatisierungsserver zu erstellen.

Die folgenden zusätzlichen Makros können verwendet werden, wenn die ClassWizard unterstützten Makros nicht angemessen sind: DISP_PROPERTY_NOTIFY und DISP_PROPERTY_PARAM.

Beschreibung DISP PROPERTY NOTIFY - Makro

DISP_PROPERTY_NOTIFY( 
   theClass, 
   pszName, 
   memberName, 
   pfnAfterSet, 
   vtPropType 
)

Hinweise

Parameter

• theClass
  Name der Klasse.

• pszName
  Externer Name der Eigenschaft.

• memberName
  Name der Membervariable, in der die Eigenschaft gespeichert wird.

• pfnAfterSet
  Name der Memberfunktion, die aufgerufen werden soll, wenn Eigenschaft geändert wird.

• vtPropType
  Ein Wert, der den Typ der Eigenschaft angibt.

Hinweise

Dieses Makro ist ähnlich wie DISP_PROPERTY, mit der Ausnahme, dass sie ein zusätzliches Argument akzeptiert.Das zusätzliche Argument, pfnAfterSet, sollte eine Memberfunktion sein, die nichts zurückgibt und keine Parameter annimmt, "Ungültiges OnPropertyNotify ()".Es wird aufgerufen, nachdem die Membervariable geändert wurde.

Beschreibung DISP PROPERTY PARAM - Makro

DISP_PROPERTY_PARAM( 
   theClass,
   pszName,
   pfnGet,
   pfnSet,
   vtPropType,
   vtsParams 
)

Hinweise

Parameter

• theClass
  Name der Klasse.

• pszName
  Externer Name der Eigenschaft.

• memberGet
  Name der Memberfunktion verwendet, um die Eigenschaft abgerufen werden soll.

• memberSet
  Name der Memberfunktion, mit dem die Eigenschaft festgelegt werden soll.

• vtPropType
  Ein Wert, der den Typ der Eigenschaft angibt.

• vtsParams
  Eine Zeichenfolge des Leerraums getrennt VTS_ für jeden Parameter.

Hinweise

DISP_PROPERTY_EX wie das gesamte Makro definiert dieses Makro eine Eigenschaft, die mit separatem zugegriffen wird, abrufen und des festgelegten Member Functions.Dieses Makro ermöglicht es Ihnen jedoch, um eine Parameterliste für die Eigenschaft anzugeben.Dies ist zum Implementieren von Eigenschaften, die auf andere Weise indiziert oder parametrisiert werden.Die Parameter werden immer zuerst platziert, gefolgt von den neuen Wert für die Eigenschaft.Beispiele:

DISP_PROPERTY_PARAM(CMyObject, "item", GetItem, SetItem, VT_DISPATCH,    VTS_I2 VTS_I2)

würden entsprechen und Funktionen des abzurufenden Members festgelegt:

LPDISPATCH CMyObject::GetItem(short row, short col)
void CMyObject::SetItem(short row, short col, LPDISPATCH newValue)

Beschreibungen - Makro

DISP_FUNCTION_ID( 
   theClass,
   pszName,
   dispid,
   pfnMember,
   vtRetVal,
   vtsParams 
)
DISP_PROPERTY_ID( 
   theClass,
   pszName,
   dispid,
   memberName,
   vtPropType 
)
DISP_PROPERTY_NOTIFY_ID( 
   theClass,
   pszName,
   dispid,
   memberName,
   pfnAfterSet,
   vtPropType 
)
DISP_PROPERTY_EX_ID( 
   theClass,
   pszName,
   dispid,
   pfnGet,
   pfnSet,
   vtPropType 
)
DISP_PROPERTY_PARAM_ID( 
   theClass,
   pszName,
   dispid,
   pfnGet,
   pfnSet,
   vtPropType,
   vtsParams 
)

Hinweise

Parameter

• theClass
  Name der Klasse.

• pszName
  Externer Name der Eigenschaft.

• dispid
  Das feste DISPIDs für die Eigenschaft oder Methode.

• pfnGet
  Name der Memberfunktion verwendet, um die Eigenschaft abgerufen werden soll.

• pfnSet
  Name der Memberfunktion, mit dem die Eigenschaft festgelegt werden soll.

• memberName
  Der Name der Membervariable der der Eigenschaft zugeordnet werden soll

• vtPropType
  Ein Wert, der den Typ der Eigenschaft angibt.

• vtsParams
  Eine Zeichenfolge des Leerraums getrennt VTS_ für jeden Parameter.

Hinweise

Diese Makros ermöglichen es Ihnen, DISPID, statt MFC, wird automatisch ein zuweisen, anzugeben.Diese erweiterten Macros haben dieselben Namen, mit der Ausnahme, dass ID wird an den Makronamen angefügt (z. B.DISP_PROPERTY_ID) und die ID wird durch den Parameter bestimmt, der direkt nach dem pszName-Parameter angegeben wird.Weitere Informationen finden Sie AFXDISP.H Informationen zu diesen Makros.Die _ID Einträge müssen am Ende der Dispatchzuordnung platziert werden.Sie wirken sich auf die automatische Generierung DISPID, genauso wie eine Nicht-_ID-Version des Makros wurde (das DISPID s werden durch Position bestimmt).Beispiele:

BEGIN_DISPATCH_MAP(CDisp3DPoint, CCmdTarget)
    DISP_PROPERTY(CDisp3DPoint, "y", m_y, VT_I2)
    DISP_PROPERTY(CDisp3DPoint, "z", m_z, VT_I2)
    DISP_PROPERTY_ID(CDisp3DPoint, "x", 0x00020003, m_x, VT_I2)
END_DISPATCH_MAP()

MFC generiert DISPID Klasse CDisp3DPoint wie folgt:

property X    (DISPID)0x00020003
property Y    (DISPID)0x00000002
property Z     (DISPID)0x00000001

Festes DISPID anzugeben ist hilfreich, um die Abwärtskompatibilität zu einer bereits vorhandenen Dispatchschnittstelle beizubehalten, oder zum Implementieren der definierte bestimmtes System die Methoden oder Eigenschaften (normalerweise durch negatives DISPID, wie die DISPID_NEWENUM-Auflistung).

Die IDispatch-Schnittstelle für ein COleClientItem abrufen

Viele Server unterstützen die Automatisierung innerhalb ihrer Dokumentobjekte zusammen mit der OLE-Server.Um auf diese Automatisierung Oberfläche zu erlangen, müssen die COleClientItem::m_lpObject-Membervariable direkt zugreifen.Im folgenden Code wird die IDispatch-Schnittstelle für ein Objekt ab, das von COleClientItem abgeleitet ist.Sie können den folgenden Code in die Anwendung einschließen, wenn Sie die notwendige Funktionalität finden:

LPDISPATCH CMyClientItem::GetIDispatch()
{
    ASSERT_VALID(this);
    ASSERT(m_lpObject != NULL);

    LPUNKNOWN lpUnk = m_lpObject;

    Run();    // must be running

    LPOLELINK lpOleLink = NULL;
    if (m_lpObject->QueryInterface(IID_IOleLink, 
        (LPVOID FAR*)&lpOleLink) == NOERROR)
    {
        ASSERT(lpOleLink != NULL);
        lpUnk = NULL;
        if (lpOleLink->GetBoundSource(&lpUnk) != NOERROR)
        {
            TRACE0("Warning: Link is not connected!\n");
            lpOleLink->Release();
            return NULL;
        }
        ASSERT(lpUnk != NULL);
    }

    LPDISPATCH lpDispatch = NULL;
    if (lpUnk->QueryInterface(IID_IDispatch, &lpDispatch) 
        != NOERROR)
    {
        TRACE0("Warning: does not support IDispatch!\n");
        return NULL;
    }

    ASSERT(lpDispatch != NULL);
    return lpDispatch;
}

Die Dispatchschnittstelle, die von dieser Funktion zurückgegeben wurde, kann dann direkt verwendet werden oder COleDispatchDriver für typsicheren Zugriff angefügt werden.Wenn Sie diese direkt verwenden, stellen Sie sicher, dass Sie den Release-Member wenn mit den Zeiger aufrufen (durch COleDispatchDriver Destruktor geschieht dies die Standardeinstellung).

Siehe auch

Weitere Ressourcen

Technische Hinweise durch Zahl

Technische Hinweise nach Kategorie