FwpmEngineOpen0 - NtDoc
Native API online documentation, based on the System Informer
(formerly Process Hacker) phnt
headers
// fwpmk.h
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
);
View the official Windows Driver Kit DDI referenceNo description available.
The FwpmEngineOpen0 function opens a session to the filter engine.
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.
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 NTSTATUS codes | An error occurred. |
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.
FwpmEngineOpen0 is a specific version of FwpmEngineOpen. See WFP Version-Independent Names and Targeting Specific Versions of Windows for more information.