Função FltCreateCommunicationPort (fltkernel.h)

Artigo
07/16/2024

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

Sintaxe

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] Ponteiro de filtro opaco para o chamador.

ServerPort

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

ObjectAttributes

[in] 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
de comprimento	InitializeObjectAttributes define esse membro como `sizeof(OBJECT_ATTRIBUTES)`.
ObjectName	Ponteiro para uma estrutura UNICODE_STRING que contém um nome exclusivo (por exemplo, L"\MyFilterPort") para o objeto de porta.
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.
atributos	Máscara de bits de sinalizadores especificando os atributos desejados para o identificador de porta. Esses sinalizadores devem incluir OBJ_KERNEL_HANDLE. O chamador também pode definir opcionalmente 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.

ServerPortCookie

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

ConnectNotifyCallback

[in] Ponteiro para um ConnectNotifyCallback fornecido pelo chamador rotina de retorno de chamada. fltMgr chama essa rotina sempre que um aplicativo de modo de usuário chama FilterConnectCommunicationPort para enviar uma solicitação de conexão para o minifiltro. Esse parâmetro é necessário e não pode ser NULL.

DisconnectNotifyCallback

[in] Ponteiro para uma rotina de retorno de chamada DisconnectNotifyCallback fornecida pelo chamador. FltMgr chama essa rotina sempre que a contagem de identificadores do modo de usuário para a porta do cliente atingir zero ou quando o minifiltro estiver prestes a ser descarregado. Esse parâmetro é necessário e não pode ser NULL.

MessageNotifyCallback

[in, opcional] Ponteiro para um messageNotifyCallback fornecido pelo chamador rotina de retorno de chamada. FltMgr chama essa rotina sempre que um aplicativo de modo de usuário chama FilterSendMessage para enviar uma mensagem ao 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.

MaxConnections

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

Valor de retorno

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

Código de retorno	Descrição
STATUS_FLT_DELETING_OBJECT	O de Filtro de 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 de minifiltro com o mesmo nome. Os nomes de porta devem ser exclusivos. Este é um código de erro.

Observações

Um 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, FilterGetMessagee 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 de minifiltro seja usado por um processo de modo de usuário em cujo contexto um chamador de FltCreateCommunicationPort pode estar em execução. Se esse sinalizador não estiver definido, FltCreateCommunicationPort retornará STATUS_INVALID_PARAMETER.

Qualquer porta de servidor que fltCreateCommunicationPort cria deve 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 falha. No entanto, todas as conexões existentes permanecem abertas até que sejam fechadas pelo aplicativo de modo de usuário ou pelo minifiltro ou até que o minifiltro seja descarregado.

Para obter mais informações, consulte Comunicação entre o modo de usuário e os minifiltros.