Metodo IMarshal::GetMarshalSizeMax (objidl.h)

Articolo
02/29/2024

Recupera le dimensioni massime del buffer che saranno necessarie durante il marshalling.

Sintassi

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

Parametri

[in] riid

Riferimento all'identificatore dell'interfaccia di cui eseguire il marshalling.

[in] pv

Puntatore di interfaccia di cui effettuare il marshalling. Questo parametro può essere NULL.

[in] dwDestContext

Contesto di destinazione in cui l'interfaccia specificata deve essere annullata. I valori possibili provengono dall'enumerazione MSHCTX. 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 NULL.

[in] mshlflags

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

[out] pSize

Puntatore a una variabile che riceve le dimensioni massime del buffer.

Valore restituito

Questo metodo può restituire i valori restituiti standard E_FAIL e S_OK, nonché il valore seguente.

Codice restituito	Descrizione
E_NOINTERFACE	L'interfaccia specificata non è supportata.

Commenti

Questo metodo viene chiamato indirettamente, in una chiamata a CoGetMarshalSizeMax, 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.

Per creare un proxy per un oggetto, COM richiede due informazioni dall'oggetto originale: la quantità di dati da scrivere nel flusso di marshalling e il CLSID del proxy.

Lo stub di marshalling ottiene queste due informazioni con chiamate successive a CoGetMarshalSizeMax e CoMarshalInterface.

Note ai chiamanti

Lo stub di marshalling, tramite una chiamata a CoGetMarshalSizeMax, chiama l'implementazione dell'oggetto di questo metodo per preallocare il buffer del flusso che verrà passato a MarshalInterface.

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

Se non si usa MIDL per definire la propria interfaccia (vedere Definizione delle interfacce COM), lo stub di marshalling non deve chiamare GetMarshalSizeMax, anche se questa operazione è altamente consigliata. Un oggetto conosce meglio di uno stub di interfaccia quale sia la dimensione massima di un pacchetto di dati di marshalling. Pertanto, a meno che non si fornisca un flusso in crescita automatica che sia così efficiente che il sovraccarico dell'espansione sia insignificante, è consigliabile chiamare questo metodo anche quando si implementano le proprie interfacce.

Il valore restituito da questo metodo è garantito che sia valido solo se lo stato interno dell'oggetto sottoposto a marshalling non cambia. Pertanto, il marshalling effettivo deve essere eseguito immediatamente dopo la restituzione di questa funzione oppure lo stub rischia che l'oggetto, a causa di una modifica dello stato, richieda più memoria di quanto indicato in origine.

Note per gli implementatori

L'implementazione di MarshalInterface userà il buffer preallocato per scrivere i dati di marshalling nel flusso. Se il buffer è troppo piccolo, l'operazione di marshalling avrà esito negativo. Di conseguenza, il valore restituito da questo metodo deve essere una stima conservativa della quantità di dati che sarà necessario per effettuare il marshalling dell'interfaccia. La violazione di questo requisito deve essere considerata un errore irreversibile.

In una chiamata successiva a MarshalInterface, l'implementazione di IMarshal non può basarsi sul chiamante che ha effettivamente chiamato GetMarshalSizeMax in anticipo. Deve comunque essere prudente di STG_E_MEDIUMFULL errori restituiti dal flusso e essere pronti a gestirli normalmente.

Per garantire che l'implementazione di GetMarshalSizeMax continui a funzionare correttamente man mano che 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 riconosce. Per delegare il marshalling all'implementazione predefinita COM, chiamare la funzione CoGetStandardMarshal .

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

Vedi anche

CoGetMarshalSizeMax

IMarshal

Condividi tramite