FwpmEngineOpen0 function (fwpmk.h)

Article
10/21/2021

The FwpmEngineOpen0 function opens a session to the filter engine.

Note

FwpmEngineOpen0 is a specific version of FwpmEngineOpen. See WFP Version-Independent Names and Targeting Specific Versions of Windows for more information.

Syntax

NTSTATUS FwpmEngineOpen0(
  [in, optional] const wchar_t             *serverName,
  [in]           UINT32                    authnService,
  [in, optional] SEC_WINNT_AUTH_IDENTITY_W *authIdentity,
  [in, optional] const FWPM_SESSION0       *session,
  [out]          HANDLE                    *engineHandle
);

Parameters

[in, optional] serverName

A pointer to a NULL-terminated string that specifies the standard DNS name of the system on which the session to the filter engine is opened. Callout drivers must specify NULL for this parameter.

[in] authnService

The authentication service to use. For a list of valid choices for this parameter, see Authentication-Service Constants in the RPC section in the Microsoft Windows SDK documentation. Callout drivers must specify either RPC_C_AUTHN_WINNT or RPC_C_AUTHN_DEFAULT for this parameter.

[in, optional] authIdentity

A pointer to a SEC_WINNT_AUTH_IDENTITY_W structure that contains the authentication and authorization credentials for accessing the filter engine. This parameter is ignored when the FwpmEngineOpen0 function is called from a callout driver. Callout drivers should set this parameter to NULL.

[in, optional] session

A pointer to an FWPM_SESSION0 structure that defines session-specific parameters for the session being opened. This pointer is optional and can be NULL.

[out] engineHandle

A pointer to a variable that receives a handle for the open session to the filter engine.

Return value

The FwpmEngineOpen0 function returns one of the following NTSTATUS codes.

Return code	Description
STATUS_SUCCESS	A session to the filter engine was successfully opened. The variable pointed to by the engineHandle parameter contains a handle for the open session.
Other status codes	An error occurred.

Remarks

A callout driver calls the FwpmEngineOpen0 function to open a session to the filter engine. A handle to an open session to the filter engine is a required parameter to most of the Windows Filtering Platform management functions.

Callout drivers normally do not need to open a session to the filter engine because callout drivers typically do not call any of the Windows Filtering Platform management functions.

For a callout driver to successfully open a session to the filter engine, the filter engine must be currently running at the time that the callout driver calls the FwpmEngineOpen0 function. A callout driver can call the FwpmBfeStateGet0 function to obtain the current state of the filter engine. Before calling FwpmBfeStateGet0, the callout driver must call the FwpmBfeStateSubscribeChanges0 function to register a callback function that will be called whenever there is a change in the state of the filter engine.

After a callout driver has finished accessing the filter engine, it calls the FwpmEngineClose0 function to close the open session to the filter engine.

Requirements

Requirement	Value
Minimum supported client	Available starting with Windows Vista.
Target Platform	Universal
Header	fwpmk.h (include Fwpmk.h)
Library	Fwpkclnt.lib
IRQL	PASSIVE_LEVEL