Método IMarshal::MarshalInterface (objidl.h)

Serializa un puntero de interfaz.

Sintaxis

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

Parámetros

[in] pStm

Puntero a la secuencia que se va a usar durante la serialización.

[in] riid

Referencia al identificador de la interfaz que se va a serializar. Esta interfaz debe derivarse de la interfaz IUnknown .

[in] pv

Puntero al puntero de interfaz que se va a serializar. Este parámetro puede ser NULL si el autor de la llamada no tiene un puntero a la interfaz deseada.

[in] dwDestContext

Contexto de destino donde se va a desmarcar la interfaz especificada. Los valores posibles para dwDestContext proceden de la enumeración MSHCTX. Actualmente, la anulación de la serialización puede producirse en otro apartamento del proceso actual (MSHCTX_INPROC) o en otro proceso que se encuentra en el mismo equipo que el proceso actual (MSHCTX_LOCAL).

[in] pvDestContext

Este parámetro está reservado y debe ser 0.

[in] mshlflags

Indica si los datos que se van a serializar se devuelven al proceso de cliente (el caso típico) o se escriben en una tabla global, donde varios clientes pueden recuperarlos. Los valores posibles proceden de la enumeración MSHLFLAGS .

Valor devuelto

Este método puede devolver el valor devuelto estándar E_FAIL, así como los siguientes valores.

Código devuelto	Descripción
S_OK	El puntero de interfaz se serializó correctamente.
E_NOINTERFACE	No se admite la interfaz especificada.
STG_E_MEDIUMFULL	La secuencia está llena.

Comentarios

Este método se denomina indirectamente, en una llamada a CoMarshalInterface, por cualquier código del proceso de servidor es responsable de serializar un puntero a una interfaz en un objeto. Este código de serialización suele ser un código auxiliar generado por COM para una de varias interfaces que pueden serializar un puntero a una interfaz implementada en un objeto completamente diferente. Entre los ejemplos se incluyen las interfaces IClassFactory e IOleItemContainer . Para fines de discusión, el código responsable de serializar un puntero se denomina código auxiliar de serialización.

Notas a los autores de llamadas

Normalmente, en lugar de llamar directamente a MarshalInterface , el código auxiliar de serialización debe llamar a la función CoMarshalInterface , que contiene una llamada a este método. El código auxiliar realiza esta llamada al comando de un objeto para escribir sus datos de serialización en una secuencia. A continuación, el código auxiliar pasa los datos de serialización al proceso de cliente o los escribe en una tabla global, donde varios clientes pueden desmarizarlos. La llamada del código auxiliar a CoMarshalInterface suele ir precedida de una llamada a CoGetMarshalSizeMax para obtener el tamaño máximo del búfer de secuencia en el que se escribirán los datos de serialización.

No llama explícitamente a este método si va a implementar interfaces COM existentes o definir sus propias interfaces mediante el lenguaje de definición de interfaz de Microsoft (MIDL). En cualquier caso, el código auxiliar generado por MIDL realiza automáticamente la llamada.

Si no usa MIDL para definir su propia interfaz, el código auxiliar de serialización debe llamar a este método, ya sea directa o indirectamente. La implementación del código auxiliar debe llamar a MarshalInterface inmediatamente después de su llamada anterior a IMarshal::GetMarshalSizeMax . Dado que se garantiza que el valor devuelto por GetMarshalSizeMax solo es válido siempre que el estado interno del objeto que se serialice no cambie, un retraso al llamar a MarshalInterface corre el riesgo de que el objeto requiera un búfer de flujo mayor que el indicado originalmente.

Si el autor de la llamada tiene un puntero a la interfaz que se va a serializar, debe, como cuestión de eficiencia, usar el parámetro pv para pasar ese puntero. De este modo, una implementación que puede usar este puntero para determinar el CLSID adecuado para el proxy no tiene que llamar a QueryInterface en sí mismo. Si un llamador no tiene un puntero a la interfaz que se va a serializar, puede pasar NULL.

Notas para los implementadores

La implementación de MarshalInterface debe escribir en el flujo los datos necesarios para inicializar el proxy en el lado receptor. Estos datos incluirían una referencia a la interfaz que se va a serializar, un valor MSHLFLAGS que especifica si los datos deben devolverse al proceso de cliente o escribirse en una tabla global, y lo que sea necesario para conectarse al objeto, como una canalización con nombre, un identificador a una ventana o un puntero a un canal RPC.

La implementación no debe suponer que la secuencia es lo suficientemente grande como para contener todos los datos. En su lugar, debe controlar correctamente un error de STG_E_MEDIUMFULL. Justo antes de salir, la implementación debe colocar el puntero de búsqueda en la secuencia inmediatamente después del último byte de datos escritos.

Si el parámetro pv es NULL y la implementación necesita un puntero de interfaz, puede llamar a QueryInterface en el objeto actual para obtenerlo. El parámetro pv existe simplemente para mejorar la eficiencia.

Para asegurarse de que la implementación de MarshalInterface sigue funcionando correctamente a medida que se admiten nuevos contextos de destino en el futuro, delegue las referencias a la implementación predeterminada de COM para todos los valores dwDestContext que la implementación no controla. Para delegar las referencias a la implementación predeterminada de COM, llame a la función auxiliar CoGetStandardMarshal .

Con la enumeración MSHLFLAGS , los autores de llamadas pueden especificar si un puntero de interfaz se va a serializar de nuevo en un solo cliente o escribir en una tabla global, donde varios clientes pueden anular la selección. Debe asegurarse de que el objeto puede controlar las llamadas desde los varios servidores proxy que se pueden crear a partir de los mismos datos de inicialización.

Requisitos

Cliente mínimo compatible	Windows 2000 Professional [aplicaciones de escritorio | Aplicaciones para UWP]
Servidor mínimo compatible	Windows 2000 Server [aplicaciones de escritorio | Aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	objidl.h (incluya ObjIdl.h)

Consulte también

CoMarshalInterface

IMarshal