RegisterApplicationRecoveryCallback function (winbase.h)
Registers the active instance of an application for recovery.
Syntax
HRESULT RegisterApplicationRecoveryCallback(
[in] APPLICATION_RECOVERY_CALLBACK pRecoveyCallback,
[in, optional] PVOID pvParameter,
[in] DWORD dwPingInterval,
[in] DWORD dwFlags
);
Parameters
[in] pRecoveyCallback
A pointer to the recovery callback function. For more information, see ApplicationRecoveryCallback.
[in, optional] pvParameter
A pointer to a variable to be passed to the callback function. Can be NULL.
[in] dwPingInterval
The recovery ping interval, in milliseconds. By default, the interval is 5 seconds (RECOVERY_DEFAULT_PING_INTERVAL). The maximum interval is 5 minutes. If you specify zero, the default interval is used.
You must call the ApplicationRecoveryInProgress function within the specified interval to indicate to ARR that you are still actively recovering; otherwise, WER terminates recovery. Typically, you perform recovery in a loop with each iteration lasting no longer than the ping interval. Each iteration performs a block of recovery work followed by a call to ApplicationRecoveryInProgress. Since you also use ApplicationRecoveryInProgress to determine if the user wants to cancel recovery, you should consider a smaller interval, so you do not perform a lot of work unnecessarily.
[in] dwFlags
Reserved for future use. Set to zero.
Return value
This function returns S_OK on success or one of the following error codes.
| Return code | Description |
|---|---|
|
Internal error; the registration failed. |
|
The ping interval cannot be more than five minutes. |
Remarks
If the application encounters an unhandled exception or becomes unresponsive, Windows Error Reporting (WER) calls the specified recovery callback. You should use the callback to save data and state information. You can use the information if you also call the RegisterApplicationRestart function to request that WER restart the application.
WER will not call your recovery callback if an installer wants to update a component of your application. To save data and state information in the update case, you should handle the WM_QUERYENDSESSION and WM_ENDSESSION messages. For details, see each message. The timeout for responding to these messages is five seconds. Most of the available recovery time is in the WM_CLOSE message for which you have 30 seconds.
A console application that can be updated uses the CTRL_C_EVENT notification to initiate recovery (for details, see the HandlerRoutine callback function). The timeout for the handler to complete is 30 seconds.
Applications should consider saving data and state information on a periodic bases to shorten the amount of time required for recovery.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows Vista [desktop apps only] |
| Minimum supported server | Windows Server 2008 [desktop apps only] |
| Target Platform | Windows |
| Header | winbase.h (include Windows.h) |
| Library | Kernel32.lib |
| DLL | Kernel32.dll |