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 |