Metodo IMarshal::MarshalInterface (objidlbase.h)
Esegue il marshalling di un puntatore dell'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 da eseguire per il marshalling. Questa interfaccia deve essere derivata dall'interfaccia IUnknown .
[in] pv
Puntatore al puntatore dell'interfaccia da eseguire per 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 appartamento 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 eseguire per il marshalling devono essere trasmessi al processo client, ovvero il caso tipico o scritto in una tabella globale, in cui può essere recuperato 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 |
|---|---|
|
Il puntatore dell'interfaccia è stato eseguito correttamente il marshalling. |
|
L'interfaccia specificata non è supportata. |
|
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 in un oggetto. Questo codice di marshalling è in genere uno stub generato da COM per una di diverse interfacce che possono eseguire il marshalling di un puntatore a un'interfaccia implementata in un oggetto completamente diverso. Gli esempi includono le interfacce IClassFactory e IOleItemContainer . A scopo di discussione, il codice responsabile del marshalling di un puntatore viene chiamato stub di marshalling.
Note ai chiamanti
In genere, anziché chiamare direttamente MarshallalInterface , il marshalling stub deve invece chiamare 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 stub a CoMarshalInterface è normalmente preceduta da una chiamata a CoGetMarshalSizeMax per ottenere la dimensione massima del buffer di flusso in cui verranno scritti i dati di marshalling.Non si chiama in modo esplicito questo metodo se si implementano interfacce COM esistenti o si definiscono le proprie interfacce usando Microsoft Interface Definition Language (MIDL). In entrambi i casi, lo stub generato da MIDL effettua automaticamente la chiamata.
Se non si usa MIDL per definire la propria interfaccia, il marshalling stub deve chiamare questo metodo, direttamente o indirettamente. L'implementazione stub deve chiamare MarshallalInterface immediatamente dopo la chiamata precedente a IMarshal::GetMarshalSizeMax . Poiché il valore restituito da GetMarshalSizeMax è garantito essere valido solo a condizione che lo stato interno dell'oggetto in fase di marshalling non cambi, un ritardo nella chiamata a MarshallalInterface esegue il rischio che l'oggetto richieda un buffer di flusso più grande rispetto all'originale indicato.
Se il chiamante ha un puntatore all'interfaccia da eseguire per il marshalling, deve, in base all'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 da eseguire per il marshalling, può passare NULL.
Note per gli implementatori
L'implementazione di MarshallalInterface deve scrivere nel flusso qualsiasi dato necessario per inizializzare il proxy sul lato ricevente. Tali dati includono un riferimento all'interfaccia da eseguire per il marshalling, un valore MSHLFLAGS che specifica se i dati devono essere restituiti al processo client o scritti in una tabella globale e qualsiasi cosa sia necessaria per connettersi all'oggetto, ad esempio una pipe denominata, un handle a una finestra o un puntatore a un canale RPC.L'implementazione non deve presupporre che il flusso sia abbastanza grande per contenere tutti i dati. Invece, deve gestire correttamente un errore di STG_E_MEDIUMFULL. Prima di uscire, l'implementazione deve posizionare il puntatore di ricerca nel flusso immediatamente dopo l'ultimo byte di dati scritto.
Se il parametro pv è NULL e l'implementazione richiede un puntatore dell'interfaccia, può chiamare QueryInterface nell'oggetto corrente per ottenerlo. Il parametro pv esiste semplicemente per migliorare l'efficienza.
Per assicurarsi che l'implementazione di MarshallalInterface continui a funzionare correttamente perché i nuovi contesti di destinazione sono supportati in futuro, 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 dell'interfaccia deve essere eseguito il marshalling in un singolo client o scritto in una tabella globale, in cui può essere annullata da più client. È necessario assicurarsi che l'oggetto possa gestire le chiamate dai più proxy che potrebbero essere creati dagli stessi dati di inizializzazione.
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 | objidlbase.h (include ObjIdl.h) |