Export (0) Print
Expand All
9 out of 16 rated this helpful - Rate this topic

RegisterApplicationRecoveryCallback function

Registers the active instance of an application for recovery.

Syntax


HRESULT WINAPI RegisterApplicationRecoveryCallback(
  _In_      APPLICATION_RECOVERY_CALLBACK pRecoveryCallback,
  _In_opt_  PVOID pvParameter,
  _In_      DWORD dwPingInterval,
  _In_      DWORD dwFlags
);

Parameters

pRecoveryCallback [in]

A pointer to the recovery callback function. For more information, see ApplicationRecoveryCallback.

pvParameter [in, optional]

A pointer to a variable to be passed to the callback function. Can be NULL.

dwPingInterval [in]

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.

dwFlags [in]

Reserved for future use. Set to zero.

Return value

This function returns S_OK on success or one of the following error codes.

Return codeDescription
E_FAIL

Internal error; the registration failed.

E_INVALIDARG

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

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Header

Winbase.h (include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

See also

ApplicationRecoveryCallback
ApplicationRecoveryInProgress
RegisterApplicationRestart
UnregisterApplicationRecoveryCallback

 

 

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.