1 out of 1 rated this helpful - Rate this topic

FwpmEngineOpen0 function

The FwpmEngineOpen0 function opens a session to the filter engine.

Syntax


DWORD WINAPI 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]

Type: const wchar_t*

This value must be NULL.

authnService [in]

Type: UINT32

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

authIdentity [in, optional]

Type: SEC_WINNT_AUTH_IDENTITY_W*

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.

session [in, optional]

Type: const FWPM_SESSION0*

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

engineHandle [out]

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.

C++


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

Minimum supported client	Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2008 [desktop apps only]
Header	Fwpmu.h
Library	Fwpuclnt.lib
DLL	Fwpuclnt.dll

Community Additions

ADD