Funzione FltCreateCommunicationPort (fltkernel.h)

Articolo
07/16/2024

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

Sintassi

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

Parametri

Filter

[in] Puntatore di filtro opaco per il chiamante.

ServerPort

[out] Puntatore a una variabile allocata dal chiamante che riceve un handle di porta opaco per la porta del server di comunicazione. Il minifiltro usa questo handle per restare in ascolto delle richieste di connessione in ingresso da un'applicazione in modalità utente.

ObjectAttributes

[in] 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
lunghezza	InitializeObjectAttributes imposta questo membro su `sizeof(OBJECT_ATTRIBUTES)`.
ObjectName	Puntatore a una struttura UNICODE_STRING contenente un nome univoco (ad esempio, L"\MyFilterPort") per l'oggetto porta.
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.
attributi	Maschera di bit di flag che specificano gli attributi desiderati per l'handle di 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 del nome deve ignorare il caso di ObjectName anziché eseguire una ricerca di corrispondenza esatta.

ServerPortCookie

[in, facoltativo] Puntatore alle informazioni di contesto definite dal minifiltro. Queste informazioni possono essere utilizzate per distinguere tra più porte server di comunicazione create dallo stesso minifiltro. FltMgr passa questo puntatore di contesto come parametro alla routine ConnectNotifyCallback . Questo parametro è facoltativo e può essere NULL.

ConnectNotifyCallback

[in] Puntatore a un chiamante fornito ConnectNotifyCallback routine di callback. FltMgr chiama questa routine ogni volta che un'applicazione in modalità utente chiama FilterConnectCommunicationPort per inviare una richiesta di connessione al minifiltro. Questo parametro è obbligatorio e non può essere NULL.

DisconnectNotifyCallback

[in] Puntatore a un chiamante fornito DisconnectNotifyCallback routine di callback. FltMgr chiama questa routine ogni volta che il numero di handle in modalità utente per la porta client raggiunge zero o quando il minifiltro sta per essere scaricato. Questo parametro è obbligatorio e non può essere NULL.

MessageNotifyCallback

[in, facoltativo] Puntatore a un chiamante fornito MessageNotifyCallback routine di callback. FltMgr chiama questa routine ogni volta che un'applicazione in modalità utente chiama FilterSendMessage per inviare un messaggio al minifiltro tramite la porta client. Questo parametro è facoltativo e può essere NULL. Se è NULL, qualsiasi richiesta effettuata dalla modalità utente per inviare dati alla porta riceve un errore.

MaxConnections

[in] Numero massimo di connessioni client simultanee consentite per questa porta del 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	L' di filtro specificato viene eliminato. Si tratta di un codice di errore.
STATUS_INSUFFICIENT_RESOURCES	FltCreateCommunicationPort rilevato un errore di allocazione del pool. Si tratta di un codice di errore.
STATUS_OBJECT_NAME_COLLISION	Esiste già una porta di comunicazione minifiltro con lo stesso nome. I nomi delle porte devono essere univoci. Si tratta di un codice di errore.

Osservazioni

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

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

I chiamanti devono impostare il flag attributi OBJ_KERNEL_HANDLE per il parametro ObjectAttributes di FltCreateCommunicationPort. L'impostazione di questo flag impedisce l'uso dell'handle di porta del server di comunicazione minifiltro 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 del server che FltCreateCommunicationPort crea 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 minifiltro o fino a quando il minifiltro non viene scaricato.

Per altre informazioni, vedere Comunicazione tra la modalità utente e i minifiltri.