IMarshal::GetMarshalSizeMax-Methode (objidl.h)

Artikel
08/25/2023

Ruft die maximale Größe des Puffers ab, die während des Marshallvorgangs benötigt wird.

Syntax

HRESULT GetMarshalSizeMax(
  [in]  REFIID riid,
  [in]  void   *pv,
  [in]  DWORD  dwDestContext,
  [in]  void   *pvDestContext,
  [in]  DWORD  mshlflags,
  [out] DWORD  *pSize
);

Parameter

[in] riid

Ein Verweis auf den Bezeichner der zu marshallden Schnittstelle.

[in] pv

Der zu marshallende Schnittstellenzeiger. Dieser Parameter kann NULL sein.

[in] dwDestContext

Der Zielkontext, in dem die angegebene Schnittstelle aufgehoben werden soll. Mögliche Werte stammen aus der Enumeration MSHCTX. Die Entkopplung kann 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 NULL 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, in der sie von mehreren Clients abgerufen werden können. Mögliche Werte stammen aus der MSHLFLAGS-Enumeration .

[out] pSize

Ein Zeiger auf eine Variable, die die maximale Größe des Puffers empfängt.

Rückgabewert

Diese Methode kann die Standardrückgabewerte E_FAIL und S_OK sowie den folgenden Wert zurückgeben.

Rückgabecode	Beschreibung
E_NOINTERFACE	Die angegebene Schnittstelle wird nicht unterstützt.

Hinweise

Diese Methode wird indirekt in einem Aufruf von CoGetMarshalSizeMax 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.

Um einen Proxy für ein Objekt zu erstellen, benötigt COM zwei Informationen aus dem ursprünglichen Objekt: die Menge an Daten, die in den Marshalldatenstrom geschrieben werden soll, und die CLSID des Proxys.

Der Marshallstub erhält diese beiden Informationen mit aufeinander folgenden Aufrufen von CoGetMarshalSizeMax und CoMarshalInterface.

Hinweise für Anrufer

Der Marshallstub ruft über einen Aufruf von CoGetMarshalSizeMax die Implementierung dieser Methode des Objekts auf, um den Streampuffer, der an MarshalInterface übergeben wird, vorab zuzuweisen.

Sie rufen diese Methode nicht explizit auf, wenn Sie vorhandene COM-Schnittstellen implementieren oder die Microsoft Interface Definition Language (MIDL) verwenden, um Ihre eigenen benutzerdefinierten Schnittstellen zu 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 (siehe Definieren von COM-Schnittstellen), muss Ihr Marshalling-Stub nicht GetMarshalSizeMax aufrufen, obwohl dies dringend empfohlen wird. Ein Objekt weiß besser als ein Schnittstellenstub, was die maximale Größe eines Marshalldatenpakets wahrscheinlich ist. Wenn Sie also nicht einen automatisch wachsenden Stream bereitstellen, der so effizient ist, dass der Aufwand der Erweiterung unbedeutend ist, sollten Sie diese Methode auch beim Implementieren eigener Schnittstellen aufrufen.

Der von dieser Methode zurückgegebene Wert ist nur gültig, solange sich der interne Zustand des zu marshallenden Objekts nicht ändert. Daher sollte das eigentliche Marshalling unmittelbar nach der Rückgabe dieser Funktion erfolgen, oder der Stub führt das Risiko aus, dass das Objekt aufgrund einer Änderung des Zustands möglicherweise mehr Arbeitsspeicher zum Marshallen benötigt als ursprünglich angegeben.

Hinweise zu Implementierern

Ihre Implementierung von MarshalInterface verwendet den vorab zugewiesenen Puffer, um Marshalldaten in den Stream zu schreiben. Wenn der Puffer zu klein ist, schlägt der Marshallvorgang fehl. Daher muss der von dieser Methode zurückgegebene Wert eine konservative Schätzung der Datenmenge sein, die zum Marshallen der Schnittstelle erforderlich ist. Die Verletzung dieser Anforderung sollte als schwerwiegender Fehler behandelt werden.

In einem nachfolgenden Aufruf von MarshalInterface kann sich Ihre IMarshal-Implementierung nicht darauf verlassen, dass der Aufrufer tatsächlich GetMarshalSizeMax zuvor aufgerufen hat. Es muss sich immer noch um STG_E_MEDIUMFULL Fehler kümmern, die vom Stream zurückgegeben werden, und darauf vorbereitet sein, sie ordnungsgemäß zu behandeln.

Um sicherzustellen, dass Ihre Implementierung von GetMarshalSizeMax weiterhin ordnungsgemäß funktioniert, wenn neue Zielkontexte in Zukunft unterstützt werden, delegieren Sie das Marshalling an die COM-Standardimplementierung für alle dwDestContext-Werte , die Ihre Implementierung nicht versteht. Um das Marshallen an die COM-Standardimplementierung zu delegieren, rufen Sie die Funktion CoGetStandardMarshal auf.

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	objidl.h

Weitere Informationen

CoGetMarshalSizeMax

IMarshal

Freigeben über