FilterConnectCommunicationPort function (fltuser.h)

Article
10/13/2021

FilterConnectCommunicationPort opens a new connection to a communication server port that is created by a file system minifilter.

Syntax

HRESULT FilterConnectCommunicationPort(
  [in]           LPCWSTR               lpPortName,
  [in]           DWORD                 dwOptions,
  [in, optional] LPCVOID               lpContext,
  [in]           WORD                  wSizeOfContext,
  [in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  [out]          HANDLE                *hPort
);

Parameters

[in] lpPortName

Pointer to a NULL-terminated wide-character string containing the fully qualified name of the communication server port (for example, L"\MyFilterPort").

[in] dwOptions

Connection options for the communication port. Prior to Windows 8.1, this value is set to 0.

Value	Meaning
FLT_PORT_FLAG_SYNC_HANDLE	The handle returned in hPort is for synchronous I/O. This flag is available starting with Windows 8.1.

[in, optional] lpContext

Pointer to caller-supplied context information to be passed to the kernel-mode minifilter's connect notification routine. (See the ConnectNotifyCallback parameter in the reference page for FltCreateCommunicationPort.) This parameter is optional and can be NULL.

[in] wSizeOfContext

Size, in bytes, of the structure that the lpContext parameter points to. If the value of lpContext is non-NULL, this parameter must be nonzero. If lpContext is NULL, this parameter must be zero.

[in, optional] lpSecurityAttributes

Pointer to a SECURITY_ATTRIBUTES structure that determines whether the returned handle can be inherited by child processes. For more information about the SECURITY_ATTRIBUTES structure, see the Microsoft Windows SDK documentation. This parameter is optional and can be NULL. If this parameter is NULL, the handle cannot be inherited.

[out] hPort

Pointer to a caller-allocated variable that receives a handle for the newly created connection port if the call to FilterConnectCommunicationPort succeeds; otherwise, it receives INVALID_HANDLE_VALUE.

Return value

FilterConnectCommunicationPort returns S_OK if successful. Otherwise, it returns an error value.

Remarks

FilterConnectCommunicationPort opens a connection to a minifilter's communication server port on behalf of a user-mode application. The application uses the resulting connection port handle to communicate with the minifilter.

After it successfully calls FilterConnectCommunicationPort, the application can send messages to the minifilter through the connection port by calling FilterSendMessage. It can also receive and reply to messages from the minifilter by calling FilterGetMessage and FilterReplyMessage, respectively. The connection port handle returned in the hPort parameter is passed as the first parameter to FilterSendMessage, FilterGetMessage, and FilterReplyMessage.

Any handle that is obtained from FilterConnectCommunicationPort must eventually be released by calling CloseHandle.

Requirements

Requirement	Value
Target Platform	Universal
Header	fltuser.h (include Fltuser.h)
Library	FltLib.lib
DLL	FltLib.dll