Função FltCreateCommunicationPort (fltkernel.h)

Artigo
08/07/2023

FltCreateCommunicationPort cria uma porta de servidor de comunicação na qual um driver de minifiltro pode receber solicitações de conexão de aplicativos do modo de usuário.

Sintaxe

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

Ponteiro de filtro opaco para o chamador.

[out] ServerPort

Ponteiro para uma variável alocada pelo chamador que recebe um identificador de porta opaco para a porta do servidor de comunicação. O driver de minifiltro usa esse identificador para escutar solicitações de conexão de entrada de um aplicativo no modo de usuário.

[in] ObjectAttributes

Ponteiro para uma estrutura OBJECT_ATTRIBUTES que especifica os atributos da porta do servidor de comunicação. Essa estrutura deve ter sido inicializada por uma chamada anterior para InitializeObjectAttributes. Esse parâmetro é necessário e não pode ser NULL. Os membros dessa estrutura para um objeto de porta de comunicação incluem o seguinte.

Membro	Valor
Comprimentodo ULONG	InitializeObjectAttributes define esse membro como sizeof(OBJECT_ATTRIBUTES).
PUNICODE_STRING ObjectName	Ponteiro para uma estrutura de UNICODE_STRING que contém um nome exclusivo (por exemplo, L"\\MyFilterPort") para o objeto de porta.
PSECURITY_DESCRIPTOR SecurityDescriptor	Ponteiro para um descritor de segurança (SECURITY_DESCRIPTOR) a ser aplicado ao objeto de porta. Se necessário, um descritor de segurança padrão pode ser criado chamando FltBuildDefaultSecurityDescriptor.
AtributosULONG	Máscara de bits de sinalizadores especificando os atributos desejados para o identificador de porta. Esses sinalizadores devem incluir OBJ_KERNEL_HANDLE. Opcionalmente, o chamador pode definir o sinalizador OBJ_CASE_INSENSITIVE, que indica que o código de pesquisa de nome deve ignorar o caso de ObjectName em vez de executar uma pesquisa de correspondência exata.

[in, optional] ServerPortCookie

Ponteiro para informações de contexto definidas pelo driver de minifiltro. Essas informações podem ser usadas para distinguir entre várias portas de servidor de comunicação criadas pelo mesmo driver de minifiltro. O Gerenciador de Filtros passa esse ponteiro de contexto como um parâmetro para a rotina ConnectNotifyCallback . Esse parâmetro é opcional e pode ser NULL.

[in] ConnectNotifyCallback

Ponteiro para uma rotina de retorno de chamada fornecida pelo chamador. O Gerenciador de Filtros chama essa rotina sempre que um aplicativo de modo de usuário chama FilterConnectCommunicationPort para enviar uma solicitação de conexão para o driver de minifiltro. Esse parâmetro é necessário e não pode ser NULL. Essa rotina é chamada em IRQL = PASSIVE_LEVEL.

Essa rotina é declarada da seguinte maneira:

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 a nova porta do cliente estabelecida entre o aplicativo de modo de usuário e o driver de minifiltro no modo kernel.

O driver de minifiltro deve passar esse identificador como o parâmetro ClientPort para FltSendMessage ao enviar e responder a mensagens nesta porta do cliente. (Observe que isso não é o mesmo que o identificador ServerPort retornado por FltCreateCommunicationPort.)

O driver de minifiltro deve, eventualmente, fechar essa porta do cliente. A porta do cliente é fechada chamando FltCloseClientPort, geralmente da rotina DisconnectNotifyCallback do driver de minifiltro.

ServerPortCookie

Ponteiro para informações de contexto definidas pelo driver de minifiltro. Essas informações podem ser usadas para distinguir entre várias portas de servidor de comunicação criadas pelo mesmo driver de minifiltro. Quando a porta do servidor foi criada, o driver de minifiltro passou esse ponteiro de contexto como um parâmetro para FltCreateCommunicationPort.

Connectioncontext

Ponteiro de informações de contexto que o aplicativo de modo de usuário passou no parâmetro lpContext para FilterConnectCommunicationPort.

SizeOfContext

Tamanho, em bytes, do buffer para o qual ConnectionContext aponta.

ConnectionPortCookie

Ponteiro para informações que identificam exclusivamente essa porta do cliente. Essas informações são definidas pelo driver de minifiltro. O Gerenciador de Filtros passa esse ponteiro de contexto como um parâmetro para as rotinas DisconnectNotifyCallback e MessageNotifyCallback do driver de minifiltro.

[in] DisconnectNotifyCallback

Ponteiro para uma rotina de retorno de chamada fornecida pelo chamador a ser chamada sempre que a contagem de identificadores do modo de usuário para a porta do cliente atingir zero ou quando o driver de minifiltro estiver prestes a ser descarregado. Esse parâmetro é necessário e não pode ser NULL. Essa rotina é chamada em IRQL = PASSIVE_LEVEL.

Essa rotina é declarada da seguinte maneira:

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

ConnectionCookie

Ponteiro para informações que identificam exclusivamente essa porta do cliente. Essas informações são definidas pelo driver de minifiltro. Quando a porta do cliente foi criada, o driver de minifiltro retornou esse ponteiro de contexto no parâmetro ConnectionPortCookie de sua rotina ConnectNotifyCallback .

[in, optional] MessageNotifyCallback

Ponteiro para uma rotina de retorno de chamada fornecida pelo chamador. O Gerenciador de Filtros chama essa rotina, em IRQL = PASSIVE_LEVEL, sempre que um aplicativo no modo de usuário chama FilterSendMessage para enviar uma mensagem ao driver de minifiltro por meio da porta do cliente. Esse parâmetro é opcional e pode ser NULL. Se for NULL, qualquer solicitação feita no modo de usuário para enviar dados para a porta receberá um erro.

Essa rotina é declarada da seguinte maneira:

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

Ponteiro para um buffer alocado pelo chamador que contém a mensagem a ser enviada para o driver de minifiltro.

Observe que InputBuffer é um ponteiro para um buffer bruto do modo de usuário desbloqueado. Esse ponteiro é válido apenas no contexto do processo de modo de usuário e só deve ser acessado de dentro de um bloco try/, exceto .

O gerenciador de filtros chama ProbeForRead para validar esse ponteiro, mas não garante que o buffer esteja alinhado corretamente. Se o buffer contiver estruturas com requisitos de alinhamento, o driver de minifiltro será responsável por executar as verificações de alinhamento necessárias. Para fazer isso, o driver de minifiltro pode usar a macro IS_ALIGNED , conforme mostrado no driver de minifiltro de exemplo MiniSpy.

Esse parâmetro é opcional e pode ser NULL.

InputBufferLength

Tamanho, em bytes, do buffer para o qual InputBuffer aponta. Esse parâmetro será ignorado se InputBuffer for NULL.

OutputBuffer

Ponteiro para um buffer alocado pelo chamador que recebe a resposta (se houver) do driver de minifiltro.

Observe que OutputBuffer é um ponteiro para um buffer bruto do modo de usuário desbloqueado. Esse ponteiro é válido apenas no contexto do processo de modo de usuário e só deve ser acessado de dentro de um bloco try/, exceto .

O gerenciador de filtros chama ProbeForWrite para validar esse ponteiro, mas não garante que o buffer esteja alinhado corretamente. Se o buffer contiver estruturas com requisitos de alinhamento, o driver de minifiltro será responsável por executar as verificações de alinhamento necessárias. Para fazer isso, o driver de minifiltro pode usar a macro IS_ALIGNED , conforme mostrado no driver de minifiltro de exemplo MiniSpy.

Esse parâmetro é opcional e pode ser NULL.

OutputBufferLength

Tamanho, em bytes, do buffer para o qual OutputBuffer aponta. Esse parâmetro será ignorado se OutputBuffer for NULL.

ReturnOutputBufferLength

Ponteiro para uma variável alocada pelo chamador que recebe o número de bytes retornados no buffer para o qual OutputBuffer aponta.

[in] MaxConnections

Número máximo de conexões de cliente simultâneas a serem permitidas para esta porta do servidor. Esse parâmetro é necessário e deve ser maior que zero.

Retornar valor

FltCreateCommunicationPort retorna STATUS_SUCCESS ou um valor NTSTATUS apropriado, como um dos seguintes:

Código de retorno	Descrição
STATUS_FLT_DELETING_OBJECT	O Filtro especificado está sendo derrubado. Este é um código de erro.
STATUS_INSUFFICIENT_RESOURCES	FltCreateCommunicationPort encontrou uma falha de alocação de pool. Este é um código de erro.
STATUS_OBJECT_NAME_COLLISION	Já existe uma porta de comunicação do driver de minifiltro com o mesmo nome. Os nomes de porta devem ser exclusivos. Este é um código de erro.

Comentários

Um driver de minifiltro chama FltCreateCommunicationPort para criar um objeto de porta do servidor de comunicação.

Depois que a porta do servidor tiver sido criada, um aplicativo de modo de usuário poderá se conectar à porta chamando FilterConnectCommunicationPort. Quando conectado, o aplicativo de modo de usuário pode enviar e receber mensagens chamando funções de mensagens no modo de usuário, como FilterSendMessage, FilterGetMessage e FilterReplyMessage.

Os chamadores devem definir o sinalizador atributos OBJ_KERNEL_HANDLE para o parâmetro ObjectAttributes de FltCreateCommunicationPort. Definir esse sinalizador impede que o identificador de porta do servidor de comunicação do driver de minifiltro seja usado por um processo de modo de usuário em cujo contexto um chamador de FltCreateCommunicationPort possa estar em execução. Se esse sinalizador não estiver definido, FltCreateCommunicationPort retornará STATUS_INVALID_PARAMETER.

Qualquer porta de servidor criada por FltCreateCommunicationPort deverá eventualmente ser fechada chamando FltCloseCommunicationPort. Quando a porta do servidor é fechada, nenhuma nova conexão com a porta do servidor é permitida e todas as chamadas para FilterConnectCommunicationPort falham. No entanto, todas as conexões existentes permanecem abertas até que sejam fechadas pelo aplicativo de modo de usuário ou pelo driver de minifiltro ou até que o driver de minifiltro seja descarregado.