FltCreateCommunicationPort
TOC
Collapse the table of content
Expand the table of content

FltCreateCommunicationPort function

FltCreateCommunicationPort creates a communication server port on which a minifilter driver can receive connection requests from user-mode applications.

Syntax


NTSTATUS FltCreateCommunicationPort(
  _In_     PFLT_FILTER            Filter,
  _Out_    PFLT_PORT              *ServerPort,
  _In_     POBJECT_ATTRIBUTES     ObjectAttributes,
  _In_opt_ PVOID                  ServerPortCookie,
  _In_     PFLT_CONNECT_NOTIFY    ConnectNotifyCallback,
  _In_     PFLT_DISCONNECT_NOTIFY DisconnectNotifyCallback,
  _In_opt_ PFLT_MESSAGE_NOTIFY    MessageNotifyCallback,
  _In_     LONG                   MaxConnections
);

Parameters

Filter [in]

Opaque filter pointer for the caller.

ServerPort [out]

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.

ObjectAttributes [in]

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.

MemberValue

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.

 

ServerPortCookie [in, optional]

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.

ConnectNotifyCallback [in]

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.

DisconnectNotifyCallback [in]

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.

MessageNotifyCallback [in, optional]

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.

MaxConnections [in]

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 codeDescription
STATUS_FLT_DELETING_OBJECT

The specified Filter is being torn down. This is an error code.

STATUS_INSUFFICIENT_RESOURCES

FltCreateCommunicationPort encountered a pool allocation failure. This is an error code.

STATUS_OBJECT_NAME_COLLISION

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

Target platform

Universal

Header

Fltkernel.h (include Fltkernel.h)

Library

FltMgr.lib

DLL

Fltmgr.sys

IRQL

PASSIVE_LEVEL

See also

FilterConnectCommunicationPort
FilterGetMessage
FilterSendMessage
FilterReplyMessage
FltBuildDefaultSecurityDescriptor
FltCloseClientPort
FltCloseCommunicationPort
FltFreeSecurityDescriptor
FltSendMessage
InitializeObjectAttributes
OBJECT_ATTRIBUTES
PFLT_FILTER_UNLOAD_CALLBACK
ProbeForRead
ProbeForWrite
SECURITY_DESCRIPTOR

 

 

Send comments about this topic to Microsoft

Show:
© 2016 Microsoft