FltCreateCommunicationPort function (fltkernel.h)
FltCreateCommunicationPort creates a communication server port on which a minifilter driver can receive connection requests from user-mode applications.
Syntax
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
);
Parameters
[in] Filter
Opaque filter pointer for the caller.
[out] ServerPort
Pointer to a caller-allocated variable that receives an opaque port handle for the communication server port. The minifilter driver uses this handle to listen for incoming connection requests from a user-mode application.
[in] ObjectAttributes
Pointer to an OBJECT_ATTRIBUTES structure that specifies the attributes of the communication server port. This structure must have been initialized by a previous call to InitializeObjectAttributes. This parameter is required and cannot be NULL. Members of this structure for a communication port object include the following.
| Member | Value |
|---|---|
| ULONG Length |
InitializeObjectAttributes sets this member to sizeof(OBJECT_ATTRIBUTES). |
| PUNICODE_STRING ObjectName | Pointer to a UNICODE_STRING structure containing a unique name (for example, L"\\MyFilterPort") for the port object. |
| PSECURITY_DESCRIPTOR SecurityDescriptor | Pointer to a security descriptor (SECURITY_DESCRIPTOR) to be applied to the port object. If needed, a default security descriptor can be created by calling FltBuildDefaultSecurityDescriptor. |
| ULONG Attributes | Bitmask of flags specifying the desired attributes for the port handle. These flags must include OBJ_KERNEL_HANDLE. The caller can also optionally set the OBJ_CASE_INSENSITIVE flag, which indicates that name-lookup code should ignore the case of ObjectName rather than performing an exact-match search. |
[in, optional] ServerPortCookie
Pointer to context information defined by the minifilter driver. This information can be used to distinguish among multiple communication server ports that are created by the same minifilter driver. The Filter Manager passes this context pointer as a parameter to the ConnectNotifyCallback routine. This parameter is optional and can be NULL.
[in] ConnectNotifyCallback
Pointer to a caller-supplied callback routine. The Filter Manager calls this routine whenever a user-mode application calls FilterConnectCommunicationPort to send a connection request to the minifilter driver. This parameter is required and cannot be NULL. This routine is called at IRQL = PASSIVE_LEVEL.
This routine is declared as follows:
typedef NTSTATUS
(*PFLT_CONNECT_NOTIFY) (
IN PFLT_PORT ClientPort,
IN PVOID ServerPortCookie,
IN PVOID ConnectionContext,
IN ULONG SizeOfContext,
OUT PVOID *ConnectionPortCookie
);
ClientPort
Opaque handle for the new client port that is established between the user-mode application and the kernel-mode minifilter driver.
The minifilter driver must pass this handle as the ClientPort parameter to FltSendMessage when sending and replying to messages on this client port. (Note that this is not the same as the ServerPort handle returned by FltCreateCommunicationPort.)
The minifilter driver must eventually close this client port. The client port is closed by calling FltCloseClientPort, usually from the minifilter driver's DisconnectNotifyCallback routine.
ServerPortCookie
Pointer to context information defined by the minifilter driver. This information can be used to distinguish among multiple communication server ports that are created by the same minifilter driver. When the server port was created, the minifilter driver passed this context pointer as a parameter to FltCreateCommunicationPort.
ConnectionContext
Context information pointer that the user-mode application passed in the lpContext parameter to FilterConnectCommunicationPort.
SizeOfContext
Size, in bytes, of the buffer that ConnectionContext points to.
ConnectionPortCookie
Pointer to information that uniquely identifies this client port. This information is defined by the minifilter driver. The Filter Manager passes this context pointer as a parameter to the minifilter driver's DisconnectNotifyCallback and MessageNotifyCallback routines.
[in] DisconnectNotifyCallback
Pointer to a caller-supplied callback routine to be called whenever the user-mode handle count for the client port reaches zero or when the minifilter driver is about to be unloaded. This parameter is required and cannot be NULL. This routine is called at IRQL = PASSIVE_LEVEL.
This routine is declared as follows:
typedef VOID
(*PFLT_DISCONNECT_NOTIFY) (
IN PVOID ConnectionCookie
);
ConnectionCookie
Pointer to information that uniquely identifies this client port. This information is defined by the minifilter driver. When the client port was created, the minifilter driver returned this context pointer in the ConnectionPortCookie parameter of its ConnectNotifyCallback routine.
[in, optional] MessageNotifyCallback
Pointer to a caller-supplied callback routine. The Filter Manager calls this routine, at IRQL = PASSIVE_LEVEL, whenever a user-mode application calls FilterSendMessage to send a message to the minifilter driver through the client port. This parameter is optional and can be NULL. If it is NULL, any request made from user mode to send data to the port will receive an error.
This routine is declared as follows:
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
Pointer to information that uniquely identifies this client port. This information is defined by the minifilter driver. When the client port was created, the minifilter driver returned this context pointer in the ConnectionPortCookie parameter of its ConnectNotifyCallback routine.
InputBuffer
Pointer to a caller-allocated buffer containing the message to be sent to the minifilter driver.
Note that InputBuffer is a pointer to a raw, unlocked user-mode buffer. This pointer is valid only in the context of the user-mode process and must only be accessed from within a try/except block.
The filter manager calls ProbeForRead to validate this pointer, but it does not ensure that the buffer is properly aligned. If the buffer contains structures that have alignment requirements, the minifilter driver is responsible for performing any necessary alignment checks. To do this, the minifilter driver can use the IS_ALIGNED macro as shown in the MiniSpy sample minifilter driver.
This parameter is optional and can be NULL.
InputBufferLength
Size, in bytes, of the buffer that InputBuffer points to. This parameter is ignored if InputBuffer is NULL.
OutputBuffer
Pointer to a caller-allocated buffer that receives the reply (if any) from the minifilter driver.
Note that OutputBuffer is a pointer to a raw, unlocked user-mode buffer. This pointer is valid only in the context of the user-mode process and must only be accessed from within a try/except block.
The filter manager calls ProbeForWrite to validate this pointer, but it does not ensure that the buffer is properly aligned. If the buffer contains structures that have alignment requirements, the minifilter driver is responsible for performing any necessary alignment checks. To do this, the minifilter driver can use the IS_ALIGNED macro as shown in the MiniSpy sample minifilter driver.
This parameter is optional and can be NULL.
OutputBufferLength
Size, in bytes, of the buffer that OutputBuffer points to. This parameter is ignored if OutputBuffer is NULL.
ReturnOutputBufferLength
Pointer to a caller-allocated variable that receives the number of bytes returned in the buffer that OutputBuffer points to.
[in] MaxConnections
Maximum number of simultaneous client connections to be allowed for this server port. This parameter is required and must be greater than zero.
Return value
FltCreateCommunicationPort returns STATUS_SUCCESS or an appropriate NTSTATUS value such as one of the following:
| Return code | Description |
|---|---|
|
The specified Filter is being torn down. This is an error code. |
|
FltCreateCommunicationPort encountered a pool allocation failure. This is an error code. |
|
A minifilter driver communication port with the same name already exists. Port names must be unique. This is an error code. |
Remarks
A minifilter driver calls FltCreateCommunicationPort to create a communication server port object.
After the server port has been created, a user-mode application can connect to the port by calling FilterConnectCommunicationPort. When connected, the user-mode application can send and receive messages by calling user-mode messaging functions such as FilterSendMessage, FilterGetMessage, and FilterReplyMessage.
Callers must set the OBJ_KERNEL_HANDLE Attributes flag for the ObjectAttributes parameter of FltCreateCommunicationPort. Setting this flag prevents the minifilter driver communication server port handle from being used by a user-mode process in whose context a caller of FltCreateCommunicationPort might be running. If this flag is not set, FltCreateCommunicationPort returns STATUS_INVALID_PARAMETER.
Any server port that is created by FltCreateCommunicationPort must eventually be closed by calling FltCloseCommunicationPort. When the server port is closed, no new connections to the server port are allowed, and all calls to FilterConnectCommunicationPort fail. However, any existing connections remain open until they are closed by the user-mode application or the minifilter driver, or until the minifilter driver is unloaded.
Requirements
| Requirement | Value |
|---|---|
| Target Platform | Universal |
| Header | fltkernel.h (include Fltkernel.h) |
| Library | FltMgr.lib |
| DLL | Fltmgr.sys |
| IRQL | PASSIVE_LEVEL |
See also
FilterConnectCommunicationPort
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for