NotifySecurityHealthChange function

The NotifySecurityHealthChange function registers to be notified for a change to network security health on a local computer.

Syntax

DWORD WINAPI NotifySecurityHealthChange(
   PHANDLE      pHandle,
   LPOVERLAPPED pOverLapped,
   PULONG       SecurityHealthFlags
);

Parameters

  • pHandle
    A pointer to a HANDLE variable if the function is to be called asynchronously.

    On input when used asynchronously, this parameter should point to a HANDLE variable that receives a file handle for use in a subsequent call to the GetOverlappedResult function. The NotifySecurityHealthChange function will fill in the handle to use when the call is made asynchronously.

    On successful output when used asynchronously, this parameter will point to the HANDLE that was used. If the function fails, this parameter will point to an invalid handle.

    Warning  if the function is successful, do not close this handle and do not associate it with a completion port.

     

    If the pHandle and pOverLapped parameters are NULL, then the function call is synchronous.

  • pOverLapped
    A pointer to an overlapped structure to use if the call is to be made asynchronously.

    On input when used asynchronously, this parameter should point to an initialized OVERLAPPED structure that notifies the caller of a change to network security health.

    If the pHandle and pOverLapped parameters are NULL, then the function call is synchronous.

  • SecurityHealthFlags
    A pointer to a ULONG that contains a set flags that describe a known state of health of TCP/IP with respect to security and denial of service.

    On input, the value pointed to by this parameter indicates the known state of network security health. On successful output for synchronous calls, the value pointed to by this parameter indicates the state of the security health flags on the local computer.

    The possible values for this flag are defined in the Iprtrmib.h header file.

    Value Meaning
    0

    No network security health problems.

    To get notification when a TCP SYN attack starts, the NotifySecurityHealthChange function should be called with the SecurityHealthFlags parameter pointed to a ULONG that contains zero. The call completes when a TCP SYN attack occurs.

    MIB_SECURITY_TCP_SYN_ATTACK 0x00000001

    A TCP SYN attack is underway.

    To get notification when the TCP SYN attack stops, the NotifySecurityHealthChange function should be called with the SecurityHealthFlags parameter pointed to a ULONG that contains MIB_SECURITY_TCP_SYN_ATTACK. The call completes when a TCP SYN attack ceases.

     

Return value

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Return code Description
ERROR_INVALID_PARAMETER

An invalid parameter was passed to the function. This error is returned if the SecurityHealthFlags parameter contained a pointer to memory that could not be written. This error is also returned if the pHandle or pOverLapped parameters were not NULL, but contained a pointer to memory that could not be written.

ERROR_OPEN_FAILED

An open request failed on the network device that monitors network security health.

Other

Use FormatMessage to obtain the message string for the returned error.

 

Remarks

The NotifySecurityHealthChange function is only supported on Windows Server 2003 with Service Pack 1 (SP1) and Windows Server 2003 with Service Pack 2 (SP2).

Note  The NotifySecurityHealthChange function is not supported on Windows Vista and Windows Server 2008.

 

The NotifySecurityHealthChange function is used to register for a change notification for network security health on a local computer. A change to security health will occur when a TCP SYN attack against the local computer takes place. A TCP SYN attack is one form of a denial of service attempt.

The NotifySecurityHealthChange function may be called in two ways:

  • Synchronous method
  • Asynchronous method

If the pHandle and pOverLapped parameters are NULL, then the NotifySecurityHealthChange function call is synchronous and will block until the security health has changed (the value pointed to by the SecurityHealthFlags parameter).

If the NotifySecurityHealthChange function is called synchronously, a notification will be sent on the next security health change until the application terminates.

If the pHandle and pOverLapped parameters are not NULL, then the NotifySecurityHealthChange function call is asynchronous and results are returned when the state of security health changes (the value pointed to by the SecurityHealthFlags parameter). In this case, the function registers for a notification. The parameter passed in the pOverLapped parameter must point to a valid OVERLAPPED structure. The caller can use the returned handle pointed to by the pHandle parameter with the OVERLAPPED structure to receive asynchronous notification of a security health changes using the GetOverlappedResult function. See the following topics for information about using the handle and OVERLAPPED structure to receive notifications:

Each call to the NotifySecurityHealthChange function will result in a single notification. So once the NotifySecurityHealthChange function returns, if further notification is required then the function must be called again.

When the NotifySecurityHealthChange function call is asynchronous, an application can deregister for security change notification (cancel the pending notification request) by calling the CancelSecurityHealthChangeNotify function with the notifyOverlapped parameter set to the value returned in pOverLapped parameter returned from the NotifySecurityHealthChange function.

If the NotifySecurityHealthChange function is called asynchronously, a notification will be sent on the next security health change until either the application cancels the notification by calling the CancelSecurityHealthChangeNotify function or the application terminates. If the application terminates, the system will automatically cancel the registration for the notification. It is still recommended that an application explicitly cancel any notification before it terminates.

Any registration for a security health notification does not persist across a system shut down or reboot.

Requirements

Minimum supported client

None supported

Minimum supported server

Windows Server 2003 with SP1 [desktop apps only]

End of server support

Windows Server 2003 with SP2

Header

Iphlpapi.h

Library

Iphlpapi.lib

DLL

Iphlpapi.dll

See also

CancelSecurityHealthChangeNotify

GetOverlappedResult

OVERLAPPED