IMarshal::MarshalInterface-Methode (objidlbase.h)
Marshallt einen Schnittstellenzeiger.
Syntax
HRESULT MarshalInterface(
[in] IStream *pStm,
[in] REFIID riid,
[in] void *pv,
[in] DWORD dwDestContext,
[in] void *pvDestContext,
[in] DWORD mshlflags
);
Parameter
[in] pStm
Ein Zeiger auf den Stream, der beim Marshallen verwendet werden soll.
[in] riid
Ein Verweis auf den Bezeichner der zu marshallden Schnittstelle. Diese Schnittstelle muss von der IUnknown-Schnittstelle abgeleitet werden.
[in] pv
Ein Zeiger auf den Schnittstellenzeiger, der gemarst werden soll. Dieser Parameter kann NULL sein, wenn der Aufrufer keinen Zeiger auf die gewünschte Schnittstelle aufweist.
[in] dwDestContext
Der Zielkontext, in dem die angegebene Schnittstelle aufgehoben werden soll. Mögliche Werte für dwDestContext stammen aus der Enumeration MSHCTX. Derzeit kann die Entkopplung entweder in einer anderen Wohnung des aktuellen Prozesses (MSHCTX_INPROC) oder in einem anderen Prozess auf demselben Computer wie der aktuelle Prozess (MSHCTX_LOCAL) erfolgen.
[in] pvDestContext
Dieser Parameter ist reserviert und muss 0 sein.
[in] mshlflags
Gibt an, ob die zu marshallende Daten zurück an den Clientprozess (der typische Fall) übertragen oder in eine globale Tabelle geschrieben werden sollen, wo sie von mehreren Clients abgerufen werden können. Mögliche Werte stammen aus der MSHLFLAGS-Enumeration .
Rückgabewert
Diese Methode kann den Standardrückgabewert E_FAIL sowie die folgenden Werte zurückgeben.
| Rückgabecode | BESCHREIBUNG |
|---|---|
|
Der Schnittstellenzeiger wurde erfolgreich gemarst. |
|
Die angegebene Schnittstelle wird nicht unterstützt. |
|
Der Stream ist voll. |
Hinweise
Diese Methode wird indirekt in einem Aufruf von CoMarshalInterface aufgerufen, unabhängig davon, welcher Code im Serverprozess für das Marshallen eines Zeigers auf eine Schnittstelle für ein Objekt verantwortlich ist. Bei diesem Marshallingcode handelt es sich in der Regel um einen von COM generierten Stub für eine von mehreren Schnittstellen, die einen Zeiger auf eine Schnittstelle marshallen können, die für ein völlig anderes Objekt implementiert ist. Beispiele hierfür sind die Schnittstellen IClassFactory und IOleItemContainer . Zu Diskussionszwecken wird der Code, der für das Marshallen eines Zeigers verantwortlich ist, als Marshallstub bezeichnet.
Hinweise für Anrufer
Anstatt MarshalInterface direkt aufzurufen, sollte Ihr Marshall-Stub in der Regel die CoMarshalInterface-Funktion aufrufen, die einen Aufruf dieser Methode enthält. Der Stub führt diesen Aufruf aus, um ein Objekt zu befehlen, um seine Marshalldaten in einen Stream zu schreiben. Der Stub übergibt dann entweder die Marshalldaten zurück an den Clientprozess oder schreibt sie in eine globale Tabelle, in der sie von mehreren Clients aufgehoben werden können. Dem Aufruf von CoMarshalInterface des Stubs wird normalerweise ein Aufruf von CoGetMarshalSizeMax vorangestellt, um die maximale Größe des Datenstrompuffers abzurufen, in den die Marshalldaten geschrieben werden.Sie rufen diese Methode nicht explizit auf, wenn Sie vorhandene COM-Schnittstellen implementieren oder Ihre eigenen Schnittstellen mithilfe der Microsoft Interface Definition Language (MIDL) definieren. In beiden Fällen führt der von MIDL generierte Stub den Aufruf automatisch aus.
Wenn Sie MIDL nicht verwenden, um Ihre eigene Schnittstelle zu definieren, muss Ihr Marshall-Stub diese Methode direkt oder indirekt aufrufen. Ihre Stubimplementierung sollte MarshalInterface unmittelbar nach dem vorherigen Aufruf von IMarshal::GetMarshalSizeMax aufrufen. Da der von GetMarshalSizeMax zurückgegebene Wert nur solange gültig ist, wie sich der interne Zustand des zu marshallenden Objekts nicht ändert, besteht bei einer Verzögerung beim Aufrufen von MarshalInterface das Risiko, dass das Objekt einen größeren Datenstrompuffer als ursprünglich angegeben benötigt.
Wenn der Aufrufer über einen Zeiger auf die zu marshallende Schnittstelle verfügt, sollte er aus Effizienzgründen den pv-Parameter verwenden, um diesen Zeiger zu übergeben. Auf diese Weise muss eine Implementierung, die einen solchen Zeiger verwenden kann, um die geeignete CLSID für den Proxy zu bestimmen, nicht QueryInterface selbst aufrufen. Wenn ein Aufrufer keinen Zeiger auf die zu marshallende Schnittstelle hat, kann er NULL übergeben.
Hinweise zu Implementierern
Ihre Implementierung von MarshalInterface muss alle Daten in den Stream schreiben, die zum Initialisieren des Proxys auf der empfangenden Seite erforderlich sind. Solche Daten umfassen einen Verweis auf die zu marshallende Schnittstelle, einen MSHLFLAGS-Wert , der angibt, ob die Daten an den Clientprozess zurückgegeben oder in eine globale Tabelle geschrieben werden sollen, und alles, was für die Verbindung mit dem Objekt erforderlich ist, z. B. eine benannte Pipe, ein Handle in ein Fenster oder ein Zeiger auf einen RPC-Kanal.Ihre Implementierung sollte nicht davon ausgehen, dass der Stream groß genug ist, um alle Daten aufzunehmen. Stattdessen sollte ein STG_E_MEDIUMFULL Fehler ordnungsgemäß behandelt werden. Kurz vor dem Beenden sollte Ihre Implementierung den Suchzeiger unmittelbar nach dem letzten Byte der geschriebenen Daten im Stream positionieren.
Wenn der pv-Parameter NULL ist und Ihre Implementierung einen Schnittstellenzeiger benötigt, kann queryInterface für das aktuelle Objekt aufgerufen werden, um ihn abzurufen. Der pv-Parameter dient lediglich der Effizienzsteigerung.
Um sicherzustellen, dass Ihre Implementierung von MarshalInterface weiterhin ordnungsgemäß funktioniert, während neue Zielkontexte in Zukunft unterstützt werden, delegieren Sie das Marshallen an die COM-Standardimplementierung für alle dwDestContext-Werte , die Ihre Implementierung nicht verarbeitet. Um das Marshallen an die COM-Standardimplementierung zu delegieren, rufen Sie die Hilfsfunktion CoGetStandardMarshal auf.
Mit der MSHLFLAGS-Enumeration können Aufrufer angeben, ob ein Schnittstellenzeiger zurück an einen einzelnen Client gemarst oder in eine globale Tabelle geschrieben werden soll, wo er von mehreren Clients aufgehoben werden kann. Sie müssen sicherstellen, dass Ihr Objekt Aufrufe von mehreren Proxys verarbeiten kann, die möglicherweise aus denselben Initialisierungsdaten erstellt werden.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows 2000 Professional [Desktop-Apps | UWP-Apps] |
| Unterstützte Mindestversion (Server) | Windows 2000 Server [Desktop-Apps | UWP-Apps] |
| Zielplattform | Windows |
| Kopfzeile | objidlbase.h (include ObjIdl.h) |