IMarshal::MarshalInterface-Methode (objidl.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 während des Marshallings verwendet werden soll.
[in] riid
Ein Verweis auf den Bezeichner der schnittstelle, die gemarshallt werden soll. Diese Schnittstelle muss von der IUnknown-Schnittstelle abgeleitet werden.
[in] pv
Ein Zeiger auf den Schnittstellenzeiger, der gemarshallt werden soll. Dieser Parameter kann NULL sein, wenn der Aufrufer keinen Zeiger auf die gewünschte Schnittstelle hat.
[in] dwDestContext
Der Zielkontext, in dem die angegebene Schnittstelle entmarshaliert 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) auftreten.
[in] pvDestContext
Dieser Parameter ist reserviert und muss 0 sein.
[in] mshlflags
Gibt an, ob die zu marshallende Daten zurück an den Clientprozess ü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 gemarshallt. |
|
Die angegebene Schnittstelle wird nicht unterstützt. |
|
Der Stream ist voll. |
Hinweise
Diese Methode wird indirekt aufgerufen, in einem Aufruf von CoMarshalInterface, durch den Code im Serverprozess, der für das Marshallen eines Zeigers auf eine Schnittstelle für ein Objekt verantwortlich ist. Dieser Marshallingcode ist in der Regel ein stub, der von COM für eine von mehreren Schnittstellen generiert wird, die einen Zeiger auf eine Schnittstelle marshallen kann, die in einem völlig anderen 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 Marshalling-Stub bezeichnet.
Hinweise für Anrufer
Anstatt MarshalInterface direkt aufzurufen, sollte Ihr Marshalling-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 Marshallingdaten in einen Stream zu schreiben. Der Stub übergibt dann entweder die Marshallingdaten zurück an den Clientprozess oder schreibt sie in eine globale Tabelle, wo sie von mehreren Clients aufgehoben werden können. Dem Aufruf des Stubs an CoMarshalInterface wird normalerweise ein Aufruf von CoGetMarshalSizeMax vorangestellt, um die maximale Größe des Streampuffers abzurufen, in den die Marshallingdaten geschrieben werden.Sie rufen diese Methode nicht explizit auf, wenn Sie vorhandene COM-Schnittstellen implementieren oder Eigene Schnittstellen mithilfe der Microsoft Interface Definition Language (MIDL) definieren. In beiden Fällen führt der von MIDL generierte Stub automatisch den Aufruf aus.
Wenn Sie midl nicht verwenden, um Ihre eigene Schnittstelle zu definieren, muss Ihr Marshalling-Stub diese Methode entweder direkt oder indirekt aufrufen. Ihre Stubimplementierung sollte MarshalInterface unmittelbar nach dem vorherigen Aufruf von IMarshal::GetMarshalSizeMax aufrufen. Da der von GetMarshalSizeMax zurückgegebene Wert garantiert nur gültig ist, solange sich der interne Zustand des gemarshallten Objekts nicht ändert, besteht bei einer Verzögerung beim Aufrufen von MarshalInterface das Risiko, dass das Objekt einen größeren Streampuffer 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 entsprechende CLSID für den Proxy zu bestimmen, nicht QueryInterface für sich selbst aufrufen. Wenn ein Aufrufer keinen Zeiger auf die zu marshallende Schnittstelle hat, kann er NULL übergeben.
Hinweise für Implementierer
Ihre Implementierung von MarshalInterface muss alle Daten in den Stream schreiben, die zum Initialisieren des Proxys auf der empfangenden Seite erforderlich sind. Diese 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 was für die Verbindung mit dem Objekt erforderlich ist, z. B. eine Named Pipe, ein Handle auf ein Fenster oder einen Zeiger auf einen RPC-Kanal.Ihre Implementierung sollte nicht davon ausgehen, dass der Stream groß genug ist, um alle Daten zu speichern. Stattdessen sollte ein STG_E_MEDIUMFULL Fehler ordnungsgemäß behandelt werden. Kurz vor dem Beenden sollte die Implementierung den Suchzeiger unmittelbar nach dem letzten byte geschriebenen Daten im Datenstrom positionieren.
Wenn der pv-Parameter NULL ist und Ihre Implementierung einen Schnittstellenzeiger benötigt, kann queryInterface für das aktuelle Objekt aufgerufen werden, um es abzurufen. Der pv-Parameter dient lediglich zur Verbesserung der Effizienz.
Um sicherzustellen, dass Ihre Implementierung von MarshalInterface weiterhin ordnungsgemäß funktioniert, da neue Zielkontexte in Zukunft unterstützt werden, delegieren Sie Marshalling an die COM-Standardimplementierung für alle dwDestContext-Werte , die ihre Implementierung nicht verarbeitet. Rufen Sie die Hilfsfunktion CoGetStandardMarshal auf, um Marshalling an die COM-Standardimplementierung zu delegieren.
Mithilfe der MSHLFLAGS-Aufzählung können Aufrufer angeben, ob ein Schnittstellenzeiger zurück an einen einzelnen Client gemarshallt 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 den gleichen Initialisierungsdaten erstellt werden.
Anforderungen
| 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 | objidl.h (include ObjIdl.h) |