Expand Minimize

FwpmEngineOpen0 function

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 NTAPI FwpmEngineOpen0(
  _In_opt_  const wchar_t *serverName,
  _In_      UINT32 authnService,
  _In_opt_  SEC_WINNT_AUTH_IDENTITY_W *authIdentity,
  _In_opt_  const FWPM_SESSION0 *session,
  _Out_     HANDLE *engineHandle
);

Parameters

serverName [in, optional]

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.

authnService [in]

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.

authIdentity [in, optional]

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.

session [in, optional]

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.

engineHandle [out]

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

Version

Available starting with Windows Vista.

Header

Fwpmk.h (include Fwpmk.h)

IRQL

PASSIVE_LEVEL

See also

FwpmBfeStateGet0
FwpmBfeStateSubscribeChanges0
FwpmCalloutAdd0
FwpmCalloutDeleteById0
FwpmCalloutDeleteByKey0
FwpmEngineClose0
Other Windows Filtering Platform Functions

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft. All rights reserved.