Función FltCreateCommunicationPort (fltkernel.h)

Artículo
08/07/2023

FltCreateCommunicationPort crea un puerto de servidor de comunicación en el que un controlador de minifiltro puede recibir solicitudes de conexión de aplicaciones en modo de usuario.

Sintaxis

NTSTATUS FLTAPI FltCreateCommunicationPort(
  [in]           PFLT_FILTER            Filter,
  [out]          PFLT_PORT              *ServerPort,
  [in]           POBJECT_ATTRIBUTES     ObjectAttributes,
  [in, optional] PVOID                  ServerPortCookie,
  [in]           PFLT_CONNECT_NOTIFY    ConnectNotifyCallback,
  [in]           PFLT_DISCONNECT_NOTIFY DisconnectNotifyCallback,
  [in, optional] PFLT_MESSAGE_NOTIFY    MessageNotifyCallback,
  [in]           LONG                   MaxConnections
);

Parámetros

[in] Filter

Puntero de filtro opaco para el autor de la llamada.

[out] ServerPort

Puntero a una variable asignada por el autor de la llamada que recibe un identificador de puerto opaco para el puerto del servidor de comunicación. El controlador de minifiltro usa este identificador para escuchar las solicitudes de conexión entrantes desde una aplicación en modo de usuario.

[in] ObjectAttributes

Puntero a una estructura de OBJECT_ATTRIBUTES que especifica los atributos del puerto del servidor de comunicación. Esta estructura debe haberse inicializado mediante una llamada anterior a InitializeObjectAttributes. Este parámetro es obligatorio y no puede ser NULL. Los miembros de esta estructura para un objeto de puerto de comunicación incluyen lo siguiente.

Miembro	Valor
Longitud de ULONG	InitializeObjectAttributes establece este miembro en sizeof(OBJECT_ATTRIBUTES).
PUNICODE_STRING ObjectName	Puntero a una estructura de UNICODE_STRING que contiene un nombre único (por ejemplo, L"\\MyFilterPort") para el objeto de puerto.
PSECURITY_DESCRIPTOR SecurityDescriptor	Puntero a un descriptor de seguridad (SECURITY_DESCRIPTOR) que se va a aplicar al objeto de puerto. Si es necesario, se puede crear un descriptor de seguridad predeterminado llamando a FltBuildDefaultSecurityDescriptor.
Atributos de ULONG	Máscara de bits de marcas que especifican los atributos deseados para el identificador de puerto. Estas marcas deben incluir OBJ_KERNEL_HANDLE. El autor de la llamada también puede establecer opcionalmente la marca OBJ_CASE_INSENSITIVE, lo que indica que el código de búsqueda de nombres debe omitir el caso de ObjectName en lugar de realizar una búsqueda de coincidencia exacta.

[in, optional] ServerPortCookie

Puntero a la información de contexto definida por el controlador de minifiltro. Esta información se puede usar para distinguir entre varios puertos de servidor de comunicación creados por el mismo controlador de minifiltro. El Administrador de filtros pasa este puntero de contexto como parámetro a la rutina ConnectNotifyCallback . Este parámetro es opcional y puede ser NULL.

[in] ConnectNotifyCallback

Puntero a una rutina de devolución de llamada proporcionada por el autor de la llamada. El Administrador de filtros llama a esta rutina cada vez que una aplicación en modo de usuario llama a FilterConnectCommunicationPort para enviar una solicitud de conexión al controlador de minifiltro. Este parámetro es obligatorio y no puede ser NULL. Esta rutina se llama en IRQL = PASSIVE_LEVEL.

Esta rutina se declara de la siguiente manera:

typedef NTSTATUS
(*PFLT_CONNECT_NOTIFY) (
      IN PFLT_PORT ClientPort,
      IN PVOID ServerPortCookie,
      IN PVOID ConnectionContext,
      IN ULONG SizeOfContext,
      OUT PVOID *ConnectionPortCookie
      );

ClientPort

Identificador opaco para el nuevo puerto de cliente que se establece entre la aplicación en modo de usuario y el controlador minifiltro en modo kernel.

El controlador de minifiltro debe pasar este identificador como el parámetro ClientPort a FltSendMessage al enviar y responder a mensajes en este puerto de cliente. (Tenga en cuenta que esto no es lo mismo que el identificador ServerPort devuelto por FltCreateCommunicationPort).

El controlador de minifiltro debe cerrar finalmente este puerto de cliente. El puerto del cliente se cierra llamando a FltCloseClientPort, normalmente desde la rutina DisconnectNotifyCallback del controlador minifiltro.

ServerPortCookie

Puntero a la información de contexto definida por el controlador de minifiltro. Esta información se puede usar para distinguir entre varios puertos de servidor de comunicación creados por el mismo controlador de minifiltro. Cuando se creó el puerto del servidor, el controlador de minifiltro pasó este puntero de contexto como parámetro a FltCreateCommunicationPort.

ConnectionContext

Puntero de información de contexto que la aplicación en modo de usuario pasó en el parámetro lpContext a FilterConnectCommunicationPort.

SizeOfContext

Tamaño, en bytes, del búfer al que apunta ConnectionContext .

ConnectionPortCookie

Puntero a la información que identifica de forma única este puerto de cliente. Esta información se define mediante el controlador de minifiltro. El Administrador de filtros pasa este puntero de contexto como parámetro a las rutinas DisconnectNotifyCallback y MessageNotifyCallback del controlador de minifiltro.

[in] DisconnectNotifyCallback

Puntero a una rutina de devolución de llamada proporcionada por el autor de la llamada que se llamará cada vez que el número de identificadores del modo de usuario para el puerto de cliente alcance cero o cuando el controlador de minifiltro esté a punto de descargarse. Este parámetro es obligatorio y no puede ser NULL. Esta rutina se llama en IRQL = PASSIVE_LEVEL.

Esta rutina se declara de la siguiente manera:

typedef VOID
(*PFLT_DISCONNECT_NOTIFY) (
      IN PVOID ConnectionCookie
      );

ConnectionCookie

Puntero a la información que identifica de forma única este puerto de cliente. Esta información se define mediante el controlador de minifiltro. Cuando se creó el puerto de cliente, el controlador de minifiltro devolvió este puntero de contexto en el parámetro ConnectionPortCookie de su rutina ConnectNotifyCallback .

[in, optional] MessageNotifyCallback

Puntero a una rutina de devolución de llamada proporcionada por el autor de la llamada. El Administrador de filtros llama a esta rutina, en IRQL = PASSIVE_LEVEL, siempre que una aplicación en modo de usuario llama a FilterSendMessage para enviar un mensaje al controlador de minifiltro a través del puerto de cliente. Este parámetro es opcional y puede ser NULL. Si es NULL, cualquier solicitud realizada desde el modo de usuario para enviar datos al puerto recibirá un error.

Esta rutina se declara de la siguiente manera:

typedef NTSTATUS
(*PFLT_MESSAGE_NOTIFY) (
      IN PVOID PortCookie,
      IN PVOID InputBuffer OPTIONAL,
      IN ULONG InputBufferLength,
      OUT PVOID OutputBuffer OPTIONAL,
      IN ULONG OutputBufferLength,
      OUT PULONG ReturnOutputBufferLength
      );

PortCookie

InputBuffer

Puntero a un búfer asignado por el autor de la llamada que contiene el mensaje que se va a enviar al controlador de minifiltro.

Tenga en cuenta que InputBuffer es un puntero a un búfer en modo de usuario sin procesar. Este puntero solo es válido en el contexto del proceso en modo de usuario y solo se debe tener acceso desde dentro de un bloque try/.

El administrador de filtros llama a ProbeForRead para validar este puntero, pero no garantiza que el búfer esté correctamente alineado. Si el búfer contiene estructuras que tienen requisitos de alineación, el controlador de minifiltro es responsable de realizar las comprobaciones de alineación necesarias. Para ello, el controlador de minifiltro puede usar la macro de IS_ALIGNED , tal como se muestra en el controlador de minifiltro de ejemplo de MiniSpy.

Este parámetro es opcional y puede ser NULL.

InputBufferLength

Tamaño, en bytes, del búfer al que apunta InputBuffer . Este parámetro se omite si InputBuffer es NULL.

OutputBuffer

Puntero a un búfer asignado por el autor de la llamada que recibe la respuesta (si existe) del controlador de minifiltro.

Tenga en cuenta que OutputBuffer es un puntero a un búfer en modo de usuario sin procesar. Este puntero solo es válido en el contexto del proceso en modo de usuario y solo se debe tener acceso desde dentro de un bloque try/.

El administrador de filtros llama a ProbeForWrite para validar este puntero, pero no garantiza que el búfer esté correctamente alineado. Si el búfer contiene estructuras que tienen requisitos de alineación, el controlador de minifiltro es responsable de realizar las comprobaciones de alineación necesarias. Para ello, el controlador de minifiltro puede usar la macro de IS_ALIGNED , tal como se muestra en el controlador de minifiltro de ejemplo de MiniSpy.

Este parámetro es opcional y puede ser NULL.

OutputBufferLength

Tamaño, en bytes, del búfer al que apunta OutputBuffer . Este parámetro se omite si OutputBuffer es NULL.

ReturnOutputBufferLength

Puntero a una variable asignada por el autor de la llamada que recibe el número de bytes devueltos en el búfer al que apunta OutputBuffer .

[in] MaxConnections

Número máximo de conexiones de cliente simultáneas que se permitirán para este puerto de servidor. Este parámetro es necesario y debe ser mayor que cero.

Valor devuelto

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

Código devuelto	Descripción
STATUS_FLT_DELETING_OBJECT	El filtro especificado se está descomponendo. Se trata de un código de error.
STATUS_INSUFFICIENT_RESOURCES	FltCreateCommunicationPort encontró un error de asignación del grupo. Se trata de un código de error.
STATUS_OBJECT_NAME_COLLISION	Ya existe un puerto de comunicación del controlador de minifiltro con el mismo nombre. Los nombres de puerto deben ser únicos. Se trata de un código de error.

Comentarios

Un controlador de minifiltro llama a FltCreateCommunicationPort para crear un objeto de puerto del servidor de comunicación.

Una vez creado el puerto del servidor, una aplicación en modo de usuario puede conectarse al puerto mediante una llamada a FilterConnectCommunicationPort. Cuando se conecta, la aplicación en modo de usuario puede enviar y recibir mensajes llamando a funciones de mensajería en modo de usuario, como FilterSendMessage, FilterGetMessage y FilterReplyMessage.

Los autores de llamadas deben establecer la marca atributos de OBJ_KERNEL_HANDLE para el parámetro ObjectAttributes de FltCreateCommunicationPort. Al establecer esta marca, se impide que un proceso en modo de usuario use el controlador de comunicación del controlador minifiltro en cuyo contexto podría estar ejecutándose un autor de llamada de FltCreateCommunicationPort . Si no se establece esta marca, FltCreateCommunicationPort devuelve STATUS_INVALID_PARAMETER.

Cualquier puerto de servidor creado por FltCreateCommunicationPort debe cerrarse llamando a FltCloseCommunicationPort. Cuando se cierra el puerto del servidor, no se permiten nuevas conexiones al puerto del servidor y se producen errores en todas las llamadas a FilterConnectCommunicationPort . Sin embargo, las conexiones existentes permanecen abiertas hasta que se cierren mediante la aplicación en modo de usuario o el controlador de minifiltro, o hasta que se descargue el controlador de minifiltro.