Metodo IMarshal::MarshalInterface (objidl.h)

Articolo
08/25/2023

Effettua il marshalling di un puntatore di interfaccia.

Sintassi

HRESULT MarshalInterface(
  [in] IStream *pStm,
  [in] REFIID  riid,
  [in] void    *pv,
  [in] DWORD   dwDestContext,
  [in] void    *pvDestContext,
  [in] DWORD   mshlflags
);

Parametri

[in] pStm

Puntatore al flusso da usare durante il marshalling.

[in] riid

Riferimento all'identificatore dell'interfaccia di cui eseguire il marshalling. Questa interfaccia deve essere derivata dall'interfaccia IUnknown .

[in] pv

Puntatore al puntatore dell'interfaccia di cui effettuare il marshalling. Questo parametro può essere NULL se il chiamante non dispone di un puntatore all'interfaccia desiderata.

[in] dwDestContext

Contesto di destinazione in cui l'interfaccia specificata deve essere annullata. I valori possibili per dwDestContext provengono dall'enumerazione MSHCTX. Attualmente, unmarshaling può verificarsi in un altro apartment del processo corrente (MSHCTX_INPROC) o in un altro processo nello stesso computer del processo corrente (MSHCTX_LOCAL).

[in] pvDestContext

Questo parametro è riservato e deve essere 0.

[in] mshlflags

Indica se i dati da sottoporre a marshalling devono essere trasmessi al processo client, ovvero il caso tipico, o scritti in una tabella globale, in cui possono essere recuperati da più client. I valori possibili provengono dall'enumerazione MSHLFLAGS .

Valore restituito

Questo metodo può restituire il valore restituito standard E_FAIL, nonché i valori seguenti.

Codice restituito	Descrizione
S_OK	Il puntatore all'interfaccia è stato sottoposto correttamente a marshalling.
E_NOINTERFACE	L'interfaccia specificata non è supportata.
STG_E_MEDIUMFULL	Il flusso è pieno.

Commenti

Questo metodo viene chiamato indirettamente, in una chiamata a CoMarshalInterface, da qualsiasi codice nel processo del server sia responsabile del marshalling di un puntatore a un'interfaccia su un oggetto . Questo codice di marshalling è in genere uno stub generato da COM per una di diverse interfacce in grado di effettuare il marshalling di un puntatore a un'interfaccia implementata in un oggetto completamente diverso. Gli esempi includono le interfacce IClassFactory e IOleItemContainer . Ai fini della discussione, il codice responsabile del marshalling di un puntatore viene chiamato stub di marshalling.

Note ai chiamanti

In genere, anziché chiamare direttamente MarshalInterface , lo stub di marshalling deve chiamare invece la funzione CoMarshalInterface , che contiene una chiamata a questo metodo. Lo stub esegue questa chiamata al comando di un oggetto per scrivere i dati di marshalling in un flusso. Lo stub passa quindi i dati di marshalling al processo client o lo scrive in una tabella globale, in cui può essere annullata da più client. La chiamata dello stub a CoMarshalInterface è in genere preceduta da una chiamata a CoGetMarshalSizeMax per ottenere la dimensione massima del buffer di flusso in cui verranno scritti i dati di marshalling.

Questo metodo non viene chiamato in modo esplicito se si implementano interfacce COM esistenti o si definiscono interfacce personalizzate usando microsoft Interface Definition Language (MIDL). In entrambi i casi, lo stub generato da MIDL esegue automaticamente la chiamata.

Se non si usa MIDL per definire la propria interfaccia, lo stub di marshalling deve chiamare questo metodo, direttamente o indirettamente. L'implementazione dello stub deve chiamare MarshalInterface immediatamente dopo la chiamata precedente a IMarshal::GetMarshalSizeMax . Poiché il valore restituito da GetMarshalSizeMax è garantito che sia valido solo a condizione che lo stato interno dell'oggetto sottoposto a marshalling non cambi, un ritardo nella chiamata a MarshalInterface comporta il rischio che l'oggetto richieda un buffer di flusso più grande di quello indicato in origine.

Se il chiamante ha un puntatore all'interfaccia di cui eseguire il marshalling, deve, in termini di efficienza, usare il parametro pv per passare tale puntatore. In questo modo, un'implementazione che può usare tale puntatore per determinare il CLSID appropriato per il proxy non deve chiamare QueryInterface su se stesso. Se un chiamante non dispone di un puntatore all'interfaccia di cui eseguire il marshalling, può passare NULL.

Note per gli implementatori

L'implementazione di MarshalInterface deve scrivere nel flusso indipendentemente dai dati necessari per inizializzare il proxy sul lato ricevente. Tali dati includono un riferimento all'interfaccia di cui eseguire il marshalling, un valore MSHLFLAGS che specifica se i dati devono essere restituiti al processo client o scritti in una tabella globale e qualsiasi elemento necessario per connettersi all'oggetto, ad esempio una named pipe, un handle a una finestra o un puntatore a un canale RPC.

L'implementazione non deve presupporre che il flusso sia sufficientemente grande da contenere tutti i dati. Deve invece gestire correttamente un errore di STG_E_MEDIUMFULL. Subito prima dell'uscita, l'implementazione deve posizionare il puntatore seek nel flusso immediatamente dopo l'ultimo byte di dati scritto.

Se il parametro pv è NULL e l'implementazione richiede un puntatore a interfaccia, può chiamare QueryInterface sull'oggetto corrente per ottenerlo. Il parametro pv esiste semplicemente per migliorare l'efficienza.

Per garantire che l'implementazione di MarshalInterface continui a funzionare correttamente perché in futuro sono supportati nuovi contesti di destinazione, delegare il marshalling all'implementazione predefinita COM per tutti i valori dwDestContext che l'implementazione non gestisce. Per delegare il marshalling all'implementazione predefinita COM, chiamare la funzione helper CoGetStandardMarshal .

Usando l'enumerazione MSHLFLAGS , i chiamanti possono specificare se un puntatore di interfaccia deve essere sottoposto a marshalling a un singolo client o scritto in una tabella globale, in cui può essere scollegato da più client. È necessario assicurarsi che l'oggetto possa gestire le chiamate da più proxy che potrebbero essere creati dagli stessi dati di inizializzazione.

Requisiti


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	objidl.h (include ObjIdl.h)

Vedi anche

CoMarshalInterface

IMarshal

Condividi tramite