Función FltCreateCommunicationPort (fltkernel.h)

Artículo
07/16/2024

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

Sintaxis

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

Parámetros

Filter

[in] Puntero de filtro opaco para el autor de la llamada.

ServerPort

[out] 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 minifiltro usa este identificador para escuchar las solicitudes de conexión entrantes desde una aplicación en modo de usuario.

ObjectAttributes

[in] Puntero a una estructura 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 necesario y no puede ser NULL. Los miembros de esta estructura para un objeto de puerto de comunicación incluyen lo siguiente.

Miembro	Valor
longitud	InitializeObjectAttributes establece este miembro en `sizeof(OBJECT_ATTRIBUTES)`.
objectName	Puntero a una estructura de UNICODE_STRING que contiene un nombre único (por ejemplo, L"\MyFilterPort") para el objeto de puerto.
securityDescriptor de	Puntero a un descriptor de seguridad (SECURITY_DESCRIPTOR) que se aplicará al objeto de puerto. Si es necesario, se puede crear un descriptor de seguridad predeterminado llamando a FltBuildDefaultSecurityDescriptor.
atributos de	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 exacta de coincidencias.

ServerPortCookie

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

ConnectNotifyCallback

[in] Puntero a una rutina de devolución de llamada proporcionada por el autor de la llamada ConnectNotifyCallback. FltMgr 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 minifiltro. Este parámetro es necesario y no puede ser NULL.

DisconnectNotifyCallback

[in] Puntero a una rutina de devolución de llamada proporcionada por el autor de la llamada DisconnectNotifyCall back. FltMgr llama a esta rutina cada vez que el número de identificadores de modo de usuario del puerto de cliente alcanza cero o cuando el minifiltro está a punto de descargarse. Este parámetro es necesario y no puede ser NULL.

MessageNotifyCallback

[in, opcional] Puntero a una rutina de devolución de llamada proporcionada por el autor de la llamada MessageNotifyCallback. FltMgr llama a esta rutina cada vez que una aplicación en modo de usuario llama a FilterSendMessage para enviar un mensaje al 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 recibe un error.

MaxConnections

[in] 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 de filtro especificado se está descomponiéndose. Se trata de un código de error.
STATUS_INSUFFICIENT_RESOURCES	FltCreateCommunicationPort encontró un error de asignación de grupo. Se trata de un código de error.
STATUS_OBJECT_NAME_COLLISION	Ya existe un puerto de comunicación de minifiltro con el mismo nombre. Los nombres de puerto deben ser únicos. Se trata de un código de error.

Observaciones

Un 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 llamando 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, FilterGetMessagey FilterReplyMessage.

Los llamadores deben establecer la marca atributos de OBJ_KERNEL_HANDLE para el parámetro objectAttributes de de FltCreateCommunicationPort. Establecer esta marca impide que un proceso en modo de usuario use el controlador de puerto del servidor de comunicación de minifiltro en cuyo contexto puede estar ejecutándose un autor de llamada de FltCreateCommunicationPort. Si no se establece esta marca, FltCreateCommunicationPort devuelve STATUS_INVALID_PARAMETER.

Cualquier puerto de servidor que FltCreateCommunicationPort crea 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 minifiltro, o hasta que se descargue el minifiltro.

Para obtener más información, vea Comunicación entre el modo de usuario y los minifiltros.