CoCreateFreeThreadedMarshaler-Funktion (combaseapi.h)

  • Artikel

Erstellt ein aggregierbares Objekt, das kontextabhängiges Marshalling ermöglicht.

Syntax

HRESULT CoCreateFreeThreadedMarshaler(
  [in]  LPUNKNOWN punkOuter,
  [out] LPUNKNOWN *ppunkMarshal
);

Parameter

[in] punkOuter

Ein Zeiger auf das Aggregieren des Objekts, das IUnknown steuert.

[out] ppunkMarshal

Adresse der Zeigervariable, die den Schnittstellenzeiger auf den aggregierbaren Marshaller empfängt.

Rückgabewert

Diese Funktion kann den Standardrückgabewert E_OUTOFMEMORY sowie den folgenden Wert zurückgeben.

Rückgabecode BESCHREIBUNG
S_OK
 Der Marshaller wurde erstellt.

Hinweise

Die CoCreateFreeThreadedMarshaler-Funktion ermöglicht es einem Objekt, Schnittstellenzeiger zwischen Threads im selben Prozess effizient zu marshallen. Wenn Ihre Objekte interthread Marshaling nicht unterstützen, müssen Sie diese Funktion nicht aufrufen. Es ist für die Verwendung von Freethread-DLL-Servern vorgesehen, auf die von allen Threads in einem Prozess direkt zugegriffen werden muss, auch von den Threads, die Singlethread-Apartments zugeordnet sind. Es marshallt den echten Speicherzeiger als gefälschten "Proxy" in andere Wohnungen und ermöglicht dadurch direkten Zugriff auf alle Aufrufer, auch wenn sie nicht im Freethread enthalten sind.

Die CoCreateFreeThreadedMarshaler-Funktion führt die folgenden Aufgaben aus:

  1. Erstellt ein Freethread-Marshaller-Objekt.
  2. Aggregiert diesen Marshaller mit dem vom punkOuter-Parameter angegebenen Objekt. Dieses Objekt ist normalerweise das Objekt, dessen Schnittstellenzeiger gemarshallt werden sollen.
Die Implementierung von IMarshal des Aggregierensobjekts sollte QueryInterface-Aufrufe für IID_IMarshal an die IUnknown des Freethread-Marshallers delegieren. Nach dem Empfang eines Aufrufs führt der Freethread-Marshaller die folgenden Aufgaben aus:
  1. Überprüft den Zielkontext, der durch den dwDestContext-Parameter der CoMarshalInterface-Funktion angegeben wird.
  2. Wenn der Zielkontext MSHCTX_INPROC ist, kopiert den Schnittstellenzeiger in den Marshallingstream.
  3. Wenn der Zielkontext ein anderer Wert ist, sucht oder erstellt eine instance des Standard-Marshallers von COM und delegiert die Marshallingfunktion.
Werte für dwDestContext stammen aus der MSHCTX-Enumeration . MSHCTX_INPROC gibt an, dass der Schnittstellenzeiger zwischen verschiedenen Threads im selben Prozess gemarshallt werden soll. Da beide Threads Zugriff auf denselben Adressraum haben, kann der Clientthread den Zeiger direkt dereferenzieren, anstatt Aufrufe an einen Proxy weiterleiten zu müssen. In allen anderen Fällen ist ein Proxy erforderlich, sodass CoCreateFreeThreadedMarshaler den Marshallingauftrag an die Standardimplementierung von COM delegiert.

Bei der Verwendung der CoCreateFreeThreadedMarshaler-Funktion sollte große Sorgfalt walten. Dies liegt daran, dass die Leistung von Objekten, die den Freethread-Marshaller aggregieren, durch einen berechneten Verstoß gegen die Regeln von COM mit dem immer vorhandenen Risiko eines undefinierten Verhaltens abgerufen wird, es sei denn, das Objekt funktioniert innerhalb bestimmter Einschränkungen. Die wichtigsten Einschränkungen sind:

  • Ein Freethread-Marshaller-Objekt kann keine direkten Zeiger auf Schnittstellen in einem Objekt enthalten, das den Freethread-Marshaller nicht als Teil seines Zustands aggregiert. Wenn das Objekt direkte Verweise auf gewöhnliche Singlethread-Aggregatobjekte verwenden würde, kann die Singlethread-Eigenschaft unterbrochen werden. Wenn das Objekt direkte Verweise auf gewöhnliche Multithread-Aggregatobjekte verwenden würde, können sich diese Objekte auf eine Weise verhalten, die keine Empfindlichkeit gegenüber den Anforderungen direkter Singlethread-Aggregatclients zeigt. Beispielsweise können diese Objekte neue Threads drehen und Parameter an die Threads übergeben, die Verweise auf gewöhnliche Singlethread-Aggregatobjekte sind.
  • Ein Freethread-Marshallerobjekt kann keine Verweise auf Proxys auf Objekte in anderen Wohnungen enthalten. Proxys sind empfindlich auf das Threadingmodell und können RPC_E_WRONG_THREAD zurückgeben, wenn sie vom falschen Client aufgerufen 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 combaseapi.h (include Objbase.h)
Bibliothek Ole32.lib
DLL Ole32.dll

Weitere Informationen

CoGetInterfaceAndReleaseStream

CoMarshalInterThreadInterfaceInStream