Función FltSendMessage (fltkernel.h)
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 necesario y no se puede 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 de minifiltro en modo kernel. Para obtener más información sobre el puntero de puerto de cliente, vea 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 necesario y no se puede null.
[in] SenderBufferLength
Tamaño, en bytes, del búfer al que SenderBuffer apunta. Consulte comentarios para obtener 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 se puede NULL.
[in, out] ReplyLength
Tamaño, en bytes, del búfer al que ReplyBuffer. Este parámetro es opcional, pero no debe ser 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 de 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. Establézcalo 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 aplicación han terminado el subproceso. |
| STATUS_TIMEOUT | El intervalo de tiempo de espera expira antes de que se pueda entregar el mensaje o antes de recibir una respuesta. Se trata de un código correcto. |
Observaciones
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 de tiempo de espera es distinto de cero y la aplicación llama a FilterGetMessage antes de que expire el intervalo de tiempo de espera de, se entrega el mensaje.
Si timeout es distinto de 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 tiempo de espera 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 de la siguiente manera:
Si timeout es distinto de cero y la aplicación llama a FilterReplyMessage antes de que expire el intervalo de tiempo de espera de , el controlador de minifiltro recibe la respuesta y FltSendMessage devuelve STATUS_SUCCESS.
Si tiempo de espera es distinto de cero y el controlador de minifiltro no recibe una respuesta antes de que expire el intervalo tiempo de espera, FltSendMessage devuelve STATUS_TIMEOUT. (Nota: STATUS_TIMEOUT es un código correcto).
Si tiempo de espera 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 al establecer 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, puede parecer obvio que el autor de la llamada de FilterReplyMessage establecería dwReplyBufferSize en sizeof(REPLY_STRUCT)y establecer 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 lugar de sizeof(FILTER_REPLY_HEADER) + sizeof(MY_STRUCT)sizeof(REPLY_STRUCT). Esto garantiza que se omita cualquier relleno adicional al final de la estructura REPLY_STRUCT.
Requisitos
| Requisito | Valor |
|---|---|
| cliente mínimo admitido | Paquete acumulativo de actualizaciones de Microsoft Windows 2000 1 para SP4, Windows XP SP2, Windows Server 2003 SP1 y sistemas operativos posteriores. |
| de la plataforma de destino de | Universal |
| encabezado de | fltkernel.h (incluya FltKernel.h) |
| biblioteca de | FltMgr.lib |
| DLL de | Fltmgr.sys |
| irQL | <= APC_LEVEL |