Funzione CoCreateFreeThreadedMarshaler (combaseapi.h)

Articolo
08/22/2023

Crea un oggetto aggregabile in grado di effettuare il marshalling dipendente dal contesto.

Sintassi

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

Parametri

[in] punkOuter

Puntatore al controllo IUnknown dell'oggetto di aggregazione.

[out] ppunkMarshal

Indirizzo della variabile del puntatore che riceve il puntatore dell'interfaccia al gestore di marshalling aggregabile.

Valore restituito

Questa funzione può restituire il valore restituito standard E_OUTOFMEMORY, nonché il valore seguente.

Codice restituito	Descrizione
S_OK	Il gestore di marshalling è stato creato.

Commenti

La funzione CoCreateFreeThreadedMarshaler consente a un oggetto di effettuare in modo efficiente il marshalling dei puntatori di interfaccia tra thread nello stesso processo. Se gli oggetti non supportano il marshalling interthread, non è necessario chiamare questa funzione. È destinato all'uso da parte di server DLL a thread libero a cui è necessario accedere direttamente da tutti i thread in un processo, anche i thread associati a appartamenti a thread singolo. Esegue il marshalling personalizzato del puntatore di memoria reale in altri appartamenti come "proxy" fittizio e quindi concede l'accesso diretto a tutti i chiamanti, anche se non sono a thread libero.

La funzione CoCreateFreeThreadedMarshaler esegue le attività seguenti:

Crea un oggetto marshaler a thread libero.
Aggrega questo gestore di marshalling all'oggetto specificato dal parametro punkOuter . Questo oggetto è in genere quello il cui puntatore di interfaccia deve essere sottoposto a marshalling.

L'implementazione dell'oggetto di aggregazione di IMarshal deve delegare le chiamate QueryInterface per IID_IMarshal all'interfaccia IUnknown del gestore di marshalling a thread libero. Al momento della ricezione di una chiamata, il gestore di marshalling a thread libero esegue le attività seguenti:

Controlla il contesto di destinazione specificato dal parametro dwDestContext della funzione CoMarshalInterface.
Se il contesto di destinazione è MSHCTX_INPROC, copia il puntatore dell'interfaccia nel flusso di marshalling.
Se il contesto di destinazione è qualsiasi altro valore, trova o crea un'istanza del marshalling predefinito (standard) di COM e delega il marshalling.

I valori per dwDestContext provengono dall'enumerazione MSHCTX . MSHCTX_INPROC indica che il puntatore di interfaccia deve essere sottoposto a marshalling tra thread diversi nello stesso processo. Poiché entrambi i thread hanno accesso allo stesso spazio indirizzi, il thread client può dereferenziare direttamente il puntatore anziché dover indirizzare le chiamate a un proxy. In tutti gli altri casi, è necessario un proxy, quindi CoCreateFreeThreadedMarshaler delega il processo di marshalling all'implementazione predefinita di COM.

È consigliabile prestare molta attenzione all'uso della funzione CoCreateFreeThreadedMarshaler . Ciò è dovuto al fatto che le prestazioni degli oggetti che aggregano il gestore di marshalling a thread libero vengono ottenute tramite una violazione calcolata delle regole di COM, con il rischio sempre presente di un comportamento indefinito a meno che l'oggetto non funzioni entro determinate restrizioni. Le restrizioni più importanti sono:

Un oggetto marshalling a thread libero non può contenere puntatori diretti alle interfacce su un oggetto che non aggrega il gestore di marshalling a thread libero come parte del relativo stato. Se l'oggetto deve usare riferimenti diretti agli oggetti aggregati a thread singolo ordinari, può interrompere la proprietà a thread singolo. Se l'oggetto usa riferimenti diretti agli oggetti aggregati multithreading ordinari, questi oggetti possono comportarsi in modi che non mostrano alcuna sensibilità alle esigenze dei client di aggregazione a thread singolo diretto. Ad esempio, questi oggetti possono ruotare nuovi thread e passare parametri ai thread che fanno riferimento a oggetti di aggregazione a thread singolo ordinari.
Un oggetto marshalling a thread libero non può contenere riferimenti a proxy a oggetti in altri appartamenti. I proxy sono sensibili al modello di threading e possono restituire RPC_E_WRONG_THREAD se viene chiamato dal client errato.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [app desktop \| App UWP]
Server minimo supportato	Windows 2000 Server [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	combaseapi.h (include Objbase.h)
Libreria	Ole32.lib
DLL	Ole32.dll

Vedi anche

CoGetInterfaceAndReleaseStream

CoMarshalInterThreadInterfaceInStream

Condividi tramite