FwpmEngineOpen0 function (fwpmu.h)

Article
09/23/2022

The FwpmEngineOpen0 function opens a session to the filter engine.

Syntax

DWORD 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

Type: const wchar_t*

This value must be NULL.

[in] authnService

Type: UINT32

Specifies the authentication service to use. Allowed services are RPC_C_AUTHN_WINNT and RPC_C_AUTHN_DEFAULT.

[in, optional] authIdentity

Type: SEC_WINNT_AUTH_IDENTITY_A*

The authentication and authorization credentials for accessing the filter engine. This pointer is optional and can be NULL. If this pointer is NULL, the calling thread's credentials are used.

[in, optional] session

Type: FWPM_SESSION0*

Session-specific parameters for the session being opened. This pointer is optional and can be NULL.

[out] engineHandle

Type: HANDLE*

Handle for the open session to the filter engine.

Return value

Type: DWORD

Return code/value	Description
ERROR_SUCCESS 0	The session was started successfully.
FWP_E_ALREADY_EXISTS 0x80320009	A session with the specified sessionKey is already opened.
*FWP_E_ error code** 0x80320001—0x80320039	A Windows Filtering Platform (WFP) specific error. See WFP Error Codes for details.
*RPC_ error code** 0x80010001—0x80010122	Failure to communicate with the remote or local firewall engine.

Remarks

A user application must call FwpmEngineOpen0 to obtain a handle for open session to the filter engine before adding or removing any filter objects. A handle for an open session to the filter engine is also required for most of the other Windows Filtering Platform management functions.

The session is automatically closed when the program ends. To explicitly close a session, call FwpmEngineClose0.

If session.flags is set to FWPM_SESSION_FLAG_DYNAMIC, any WFP objects added during the session are automatically deleted when the session ends. If the session is not dynamic, the caller needs to explicitly delete all WFP objects added during the session.

The caller needs FWPM_ACTRL_OPEN access to the filter engine. See Access Control for more information.

FwpmEngineOpen0 is intended for use in non-impersonated mode only.

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

Examples

The following C++ example uses FwpmEngineOpen0 to open a filter session.

// Open a session to the filter engine
        
HANDLE    engineHandle = NULL;
DWORD    result = ERROR_SUCCESS; 

printf("Opening the filter engine.\n");
        
result = FwpmEngineOpen0(
    NULL, 
    RPC_C_AUTHN_WINNT, 
    NULL,
    NULL, 
    &engineHandle );

if (result != ERROR_SUCCESS)
    printf("FwpmEngineOpen0 failed. Return value: %d.\n", result); 
else
    printf("Filter engine opened successfully.\n");

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2008 [desktop apps only]
Target Platform	Windows
Header	fwpmu.h
Library	Fwpuclnt.lib
DLL	Fwpuclnt.dll