Compartir a través de

Función FltSendMessage (fltkernel.h)

  • Artículo

FltSendMessage envía un mensaje a una aplicación en modo de usuario en espera en nombre de un controlador de minifiltro o una instancia de controlador de minifiltro.

Sintaxis

NTSTATUS FLTAPI FltSendMessage(
  [in]            PFLT_FILTER    Filter,
  [in]            PFLT_PORT      *ClientPort,
  [in]            PVOID          SenderBuffer,
  [in]            ULONG          SenderBufferLength,
  [out, optional] PVOID          ReplyBuffer,
  [in, out]       PULONG         ReplyLength,
  [in, optional]  PLARGE_INTEGER Timeout
);

Parámetros

[in] Filter

Puntero de filtro opaco para el autor de la llamada. Este parámetro es obligatorio y no puede ser NULL.

[in] ClientPort

Puntero a una variable que contiene el puntero de puerto de cliente opaco para el puerto de conexión entre la aplicación en modo de usuario y el controlador minifiltro en modo kernel. Para obtener más información sobre el puntero de puerto de cliente, consulte la descripción del parámetro ConnectNotifyCallback en la entrada de referencia de FltCreateCommunicationPort.

[in] SenderBuffer

Puntero a un búfer asignado por el autor de la llamada que contiene el mensaje que se va a enviar a la aplicación en modo de usuario. Este parámetro es obligatorio y no puede ser NULL.

[in] SenderBufferLength

Tamaño, en bytes, del búfer al que apunta SenderBuffer . Consulte Comentarios para más información.

[out, optional] ReplyBuffer

Puntero a un búfer asignado por el autor de la llamada que recibe la respuesta, si existe, de la aplicación. Este parámetro es opcional y puede ser NULL.

[in, out] ReplyLength

Tamaño, en bytes, del búfer al que apunta ReplyBuffer . Este parámetro es opcional, pero debe ser distinto de NULL cuando ReplyBuffer no es NULL.

[in, optional] Timeout

Puntero a un valor de tiempo de espera que especifica el tiempo total absoluto o relativo, en unidades de 100 nanosegundos, para los que el autor de la llamada puede colocarse en un estado de espera hasta que la aplicación en modo usuario reciba el mensaje y hasta que reciba una respuesta (si se espera).

Un valor positivo especifica una hora absoluta, relativa al 1 de enero de 1601. Un valor negativo especifica un intervalo relativo a la hora actual. Se establece en NULL si el autor de la llamada puede colocarse en un estado de espera indefinidamente.

Valor devuelto

FltSendMessage devuelve STATUS_SUCCESS o un valor NTSTATUS adecuado, como uno de los siguientes:

Código devuelto Descripción
STATUS_INSUFFICIENT_RESOURCES FltSendMessage encontró un error de asignación de grupo. Se trata de un código de error.
STATUS_PORT_DISCONNECTED El puerto de comunicación se ha desconectado. Se trata de un código de error.
STATUS_THREAD_IS_TERMINATING La espera se interrumpió porque un usuario o una aplicación han terminado el subproceso.
STATUS_TIMEOUT El intervalo de tiempo de espera expiró antes de que se pudiera entregar el mensaje o antes de recibir una respuesta. Se trata de un código correcto.

Comentarios

FltSendMessage envía un mensaje a una aplicación en modo de usuario en nombre de un controlador de minifiltro o una instancia de controlador de minifiltro.

Si la aplicación llama a FilterGetMessage para obtener el mensaje antes de que el controlador de minifiltro llame a FltSendMessage para enviarlo, el mensaje se entrega inmediatamente. Este suele ser el caso cuando la aplicación llama a FilterGetMessage desde dentro de un bucle de mensajes.

De lo contrario, si no se ha llamado a una aplicación para obtener un mensaje, el controlador de minifiltro se coloca en un estado de espera como se indica a continuación:

  • Si Timeout no es cero y la aplicación llama a FilterGetMessage antes de que expire el intervalo de tiempo de espera, se entrega el mensaje.

  • Si Timeout no es cero y la aplicación no llama a FilterGetMessage antes de que expire el intervalo de tiempo de espera, el mensaje no se entrega y FltSendMessage devuelve STATUS_TIMEOUT. (Nota: STATUS_TIMEOUT es un código correcto).

  • Si Timeout es cero, el controlador de minifiltro se coloca en un estado de espera indefinidamente. Cuando la aplicación llama a FilterGetMessage, se entrega el mensaje.

Una vez entregado el mensaje, si ReplyBuffer es NULL, FltSendMessage devuelve STATUS_SUCCESS.

De lo contrario, si ReplyBuffer no es NULL, el controlador de minifiltro se coloca en un estado de espera como se indica a continuación:

  • Si Timeout es distinto de cero y la aplicación llama a FilterReplyMessage antes de que expire el intervalo de tiempo de espera, el controlador de minifiltro recibe la respuesta y FltSendMessage devuelve STATUS_SUCCESS.

  • Si Timeout es distinto de cero y el controlador de minifiltro no recibe una respuesta antes de que expire el intervalo de tiempo de espera, FltSendMessage devuelve STATUS_TIMEOUT. (Nota: STATUS_TIMEOUT es un código correcto).

  • Si Timeout es cero cuando el controlador de minifiltro está esperando la respuesta, el controlador de minifiltro se coloca en un estado de espera indefinidamente. Cuando la aplicación llama a FilterReplyMessage, el controlador de minifiltro recibe la respuesta y FltSendMessage devuelve STATUS_SUCCESS.

Nota

 Debido a los requisitos de relleno de estructura (específicos del sistema), se requiere precisión cuando se establece el tamaño de los búferes asociados a FltSendMessage y FilterReplyMessage. Por ejemplo, supongamos que los datos se deben enviar a través de FilterReplyMessage a un minifiltro. El componente en modo de usuario puede declarar la siguiente estructura para hacerlo:

typedef struct _REPLY_STRUCT
{
    FILTER_REPLY_HEADER Header;
    MY_STRUCT Data;  // The structure to be sent to the minifilter
} REPLY_STRUCT, *PREPLY_STRUCT;

Dada esta estructura, podría parecer obvio que el autor de la llamada de FilterReplyMessageestablecería dwReplyBufferSizesizeof(REPLY_STRUCT)en y establecería el parámetro ReplyLength de FltSendMessage en el mismo valor. Sin embargo, debido al relleno de estructuras idiosincrónicas, sizeof(REPLY_STRUCT) puede ser mayor que sizeof(FILTER_REPLY_HEADER) + sizeof(MY_STRUCT). Si este es el caso, FltSendMessage devuelve STATUS_BUFFER_OVERFLOW.

Por lo tanto, se recomienda llamar a FilterReplyMessage y FltSendMessage (aprovechando el ejemplo anterior) estableciendo dwReplyBufferSize y ReplyLength en sizeof(FILTER_REPLY_HEADER) + sizeof(MY_STRUCT) en lugar de sizeof(REPLY_STRUCT). Esto garantiza que se omita cualquier relleno adicional al final de la estructura de REPLY_STRUCT.

Requisitos

Requisito Value
Cliente mínimo compatible Paquete acumulativo de actualizaciones de Microsoft Windows 2000 1 para SP4, Windows XP SP2, Windows Server 2003 SP1 y sistemas operativos posteriores.
Plataforma de destino Universal
Encabezado fltkernel.h (incluya FltKernel.h)
Library FltMgr.lib
Archivo DLL Fltmgr.sys
IRQL <= APC_LEVEL

Consulte también

FilterGetMessage

FilterReplyMessage

FilterSendMessage

FltCreateCommunicationPort