Funzione FltCreateCommunicationPort (fltkernel.h)

Articolo
02/29/2024

FltCreateCommunicationPort crea una porta del server di comunicazione in cui un driver minifilter può ricevere richieste di connessione da applicazioni in modalità utente.

Sintassi

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
);

Parametri

[in] Filter

Puntatore di filtro opaco per il chiamante.

[out] ServerPort

Puntatore a una variabile allocata dal chiamante che riceve un handle di porta opaco per la porta del server di comunicazione. Il driver minifilter usa questo handle per ascoltare le richieste di connessione in ingresso da un'applicazione in modalità utente.

[in] ObjectAttributes

Puntatore a una struttura OBJECT_ATTRIBUTES che specifica gli attributi della porta del server di comunicazione. Questa struttura deve essere stata inizializzata da una chiamata precedente a InitializeObjectAttributes. Questo parametro è obbligatorio e non può essere NULL. I membri di questa struttura per un oggetto porta di comunicazione includono quanto segue.

Membro	Valore
LunghezzaULONG	InitializeObjectAttributes imposta questo membro su sizeof(OBJECT_ATTRIBUTES).
PUNICODE_STRING ObjectName	Puntatore a una struttura UNICODE_STRING contenente un nome univoco ,ad esempio L"\\MyFilterPort") per l'oggetto porta.
PSECURITY_DESCRIPTOR SecurityDescriptor	Puntatore a un descrittore di sicurezza (SECURITY_DESCRIPTOR) da applicare all'oggetto porta. Se necessario, è possibile creare un descrittore di sicurezza predefinito chiamando FltBuildDefaultSecurityDescriptor.
AttributiULONG	Maschera di flag che specificano gli attributi desiderati per l'handle della porta. Questi flag devono includere OBJ_KERNEL_HANDLE. Il chiamante può anche impostare facoltativamente il flag di OBJ_CASE_INSENSITIVE, che indica che il codice di ricerca dei nomi deve ignorare il caso di ObjectName anziché eseguire una ricerca di corrispondenza esatta.

[in, optional] ServerPortCookie

Puntatore alle informazioni sul contesto definite dal driver minifilter. Queste informazioni possono essere usate per distinguere tra più porte del server di comunicazione create dallo stesso driver minifilter. Gestione filtri passa questo puntatore di contesto come parametro alla routine ConnectNotifyCallback . Questo parametro è facoltativo e può essere NULL.

[in] ConnectNotifyCallback

Puntatore a una routine di callback fornita dal chiamante. Filter Manager chiama questa routine ogni volta che un'applicazione in modalità utente chiama FilterConnectCommunicationPort per inviare una richiesta di connessione al driver minifilter. Questo parametro è obbligatorio e non può essere NULL. Questa routine viene chiamata in IRQL = PASSIVE_LEVEL.

Questa routine viene dichiarata come segue:

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

ClientPort

Handle opaco per la nuova porta client stabilita tra l'applicazione in modalità utente e il driver minifilter in modalità kernel.

Il driver minifilter deve passare questo handle come parametro ClientPort a FltSendMessage durante l'invio e la risposta ai messaggi nella porta client. Si noti che questo non è lo stesso dell'handle ServerPort restituito da FltCreateCommunicationPort.

Il driver minifilter deve infine chiudere questa porta client. La porta client viene chiusa chiamando FltCloseClientPort, in genere dalla routine disconnessione del driver minifilterNotifyCallback .

ServerPortCookie

Puntatore alle informazioni sul contesto definite dal driver minifilter. Queste informazioni possono essere usate per distinguere tra più porte del server di comunicazione create dallo stesso driver minifilter. Quando è stata creata la porta del server, il driver minifilter ha passato questo puntatore di contesto come parametro a FltCreateCommunicationPort.

Connectioncontext

Puntatore alle informazioni di contesto passato dall'applicazione in modalità utente al parametro lpContext a FilterConnectCommunicationPort.

SizeOfContext

Dimensioni, in byte, del buffer a cui punta ConnectionContext .

ConnectionPortCookie

Puntatore alle informazioni che identificano in modo univoco questa porta client. Queste informazioni sono definite dal driver minifilter. Gestione filtri passa questo puntatore di contesto come parametro alle routine disconnessione del driver minifilterNotifyCallback e MessageNotifyCallback .

[in] DisconnectNotifyCallback

Puntatore a una routine di callback fornita dal chiamante da chiamare ogni volta che il conteggio dell'handle in modalità utente per la porta client raggiunge zero o quando il driver minifilter sta per essere scaricato. Questo parametro è obbligatorio e non può essere NULL. Questa routine viene chiamata in IRQL = PASSIVE_LEVEL.

Questa routine viene dichiarata come segue:

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

ConnectionCookie

Puntatore alle informazioni che identificano in modo univoco questa porta client. Queste informazioni sono definite dal driver minifilter. Quando è stata creata la porta client, il driver minifilter ha restituito questo puntatore di contesto nel parametro ConnectionPortCookie della routine ConnectNotifyCallback .

[in, optional] MessageNotifyCallback

Puntatore a una routine di callback fornita dal chiamante. Gestione filtri chiama questa routine, in IRQL = PASSIVE_LEVEL, ogni volta che un'applicazione in modalità utente chiama FilterSendMessage per inviare un messaggio al driver minifilter tramite la porta client. Questo parametro è facoltativo e può essere NULL. Se è NULL, qualsiasi richiesta effettuata dalla modalità utente per inviare dati alla porta riceverà un errore.

Questa routine viene dichiarata come segue:

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

Puntatore a un buffer allocato del chiamante contenente il messaggio da inviare al driver minifilter.

Si noti che InputBuffer è un puntatore a un buffer in modalità utente non elaborato. Questo puntatore è valido solo nel contesto del processo in modalità utente e deve essere accessibile solo dall'interno di un blocco di prova/.

La gestione filtri chiama ProbeForRead per convalidare questo puntatore, ma non garantisce che il buffer sia allineato correttamente. Se il buffer contiene strutture con requisiti di allineamento, il driver minifilter è responsabile dell'esecuzione di eventuali controlli di allineamento necessari. A tale scopo, il driver minifilter può usare la macro IS_ALIGNED , come illustrato nel driver minifilter di esempio MiniSpy.

Questo parametro è facoltativo e può essere NULL.

InputBufferLength

Dimensioni, in byte, del buffer a cui InputBuffer punta. Questo parametro viene ignorato se InputBuffer è NULL.

OutputBuffer

Puntatore a un buffer allocato dal chiamante che riceve la risposta (se presente) dal driver minifilter.

Si noti che OutputBuffer è un puntatore a un buffer in modalità utente non elaborato. Questo puntatore è valido solo nel contesto del processo in modalità utente e deve essere accessibile solo dall'interno di un blocco di prova/.

La gestione filtri chiama ProbeForWrite per convalidare questo puntatore, ma non garantisce che il buffer sia allineato correttamente. Se il buffer contiene strutture con requisiti di allineamento, il driver minifilter è responsabile dell'esecuzione di eventuali controlli di allineamento necessari. A tale scopo, il driver minifilter può usare la macro IS_ALIGNED , come illustrato nel driver minifilter di esempio MiniSpy.

Questo parametro è facoltativo e può essere NULL.

OutputBufferLength

Dimensioni, in byte, del buffer a cui fa riferimento OutputBuffer . Questo parametro viene ignorato se OutputBuffer è NULL.

ReturnOutputBufferLength

Puntatore a una variabile allocata dal chiamante che riceve il numero di byte restituiti nel buffer a cui OutputBuffer punta.

[in] MaxConnections

Numero massimo di connessioni client simultanee da consentire per questa porta server. Questo parametro è obbligatorio e deve essere maggiore di zero.

Valore restituito

FltCreateCommunicationPort restituisce STATUS_SUCCESS o un valore NTSTATUS appropriato, ad esempio uno dei seguenti:

Codice restituito	Descrizione
STATUS_FLT_DELETING_OBJECT	Il filtro specificato viene eliminato. Si tratta di un codice di errore.
STATUS_INSUFFICIENT_RESOURCES	FltCreateCommunicationPort ha rilevato un errore di allocazione del pool. Si tratta di un codice di errore.
STATUS_OBJECT_NAME_COLLISION	Esiste già una porta di comunicazione del driver minifilter con lo stesso nome. I nomi delle porte devono essere univoci. Si tratta di un codice di errore.

Commenti

Un driver minifilter chiama FltCreateCommunicationPort per creare un oggetto porta del server di comunicazione.

Dopo aver creato la porta server, un'applicazione in modalità utente può connettersi alla porta chiamando FilterConnectCommunicationPort. Quando è connessa, l'applicazione in modalità utente può inviare e ricevere messaggi chiamando funzioni di messaggistica in modalità utente, ad esempio FilterSendMessage, FilterGetMessage e FilterReplyMessage.

I chiamanti devono impostare il flag OBJ_KERNEL_HANDLE Attributes per il parametro ObjectAttributes di FltCreateCommunicationPort. L'impostazione di questo flag impedisce l'uso dell'handle di porta del server di comunicazione del driver minifilter da parte di un processo in modalità utente nel cui contesto potrebbe essere in esecuzione un chiamante di FltCreateCommunicationPort . Se questo flag non è impostato, FltCreateCommunicationPort restituisce STATUS_INVALID_PARAMETER.

Qualsiasi porta server creata da FltCreateCommunicationPort deve essere chiusa chiamando FltCloseCommunicationPort. Quando la porta del server viene chiusa, non sono consentite nuove connessioni alla porta del server e tutte le chiamate a FilterConnectCommunicationPort hanno esito negativo. Tuttavia, tutte le connessioni esistenti rimangono aperte fino a quando non vengono chiuse dall'applicazione in modalità utente o dal driver minifilter o fino a quando il driver minifilter non viene scaricato.

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Intestazione	fltkernel.h (include Fltkernel.h)
Libreria	FltMgr.lib
DLL	Fltmgr.sys
IRQL	PASSIVE_LEVEL