Search
Module:
Directory

   Desktop Functions:

   Smart Device Functions:


Show Recent Changes
Subscribe (RSS)
Misc. Pages
Comments
FAQ
Helpful Tools
Playground
Suggested Reading
Website TODO List
Download Visual Studio Add-In

RegisterApplicationRestart (kernel32)
 
.
Summary
The application restart feature is very simple to use requiring only a single function call.

C# Signature:

[DllImport("kernel32.dll", SetLastError=true)]
static extern int RegisterApplicationRestart([MarshalAs(UnmanagedType.BStr) string commandLineArgs, int Flags);

VB Signature:

Declare Function RegisterApplicationRestart Lib "kernel32.dll" (commandLineArgs As String, Flags As Integer) As Integer

User-Defined Types:

None.

Notes:

commandLineArgs

A pointer to a Unicode string that specifies the command-line arguments for the application when it is restarted. The maximum size of the command line that you can specify is RESTART_MAX_CMD_LINE characters. Do not include the name of the executable in the command line; this function adds it for you.

If this parameter is NULL or an empty string, the previously registered command line is removed. If the argument contains spaces, use quotes around the argument.

Flags

This parameter can be 0 or one or more of the following values.

RESTART_NO_CRASH = 1 : Do not restart the process if it terminates due to an unhandled exception

RESTART_NO_HANG = 2 : Do not restart the process if it terminates due to the application not responding.

RESTART_NO_PATCH = 4 : Do not restart the process if it terminates due to the installation of an update.

RESTART_NO_REBOOT = 8 : Do not restart the process if the computer is restarted as the result of an update.

Tips & Tricks:

Your initial registration for restart must occur before the application encounters an unhandled exception or becomes unresponsive. You could then call this function from inside your recovery callback to update the command line.

For a Windows application that is being updated, the last opportunity to call this function is while processing the WM_QUERYENDSESSION message. For a console application that is being updated, the registration must occur before the installer tries to shutdown the application (you need to keep the registration current; you cannot call this function when handling the CTRL_C_EVENT notification).

If you register for restart and the application encounters an unhandled exception or is not responsive, the user is offered the opportunity to restart the application; the application is not automatically restarted without the user's consent. However, if the application is being updated and requires a restart, the application is restarted automatically.

To prevent cyclical restarts, the system will only restart the application if it has been running for a minimum of 60 seconds.

Note that for an application to be restarted when the update requires a computer restart, the installer must call the ExitWindowsEx function with the EWX_RESTARTAPPS flag set or the InitiateShutdown function with the SHUTDOWN_RESTARTAPPS flag set.

Sample Code:

Flags

private enum RestartFlags

{

      NONE = 0,
      RESTART_NO_CRASH = 1,
      RESTART_NO_HANG = 2,
      RESTART_NO_PATCH = 4,
      RESTART_NO_REBOOT = 8

}

[DllImport("kernel32.dll", CharSet = CharSet.Auto)]

private static extern uint RegisterApplicationRestart(string pwsCommandLine, RestartFlags dwFlags);

public bool RegisterApplicationForRestart()

{

      uint RegisterResult = RegisterApplicationRestart(APPLICATION_CRASHED, RestartFlags.NONE);
      return RegisterResult == 0;

}

Documentation

Please edit this page!

Do you have...

  • helpful tips or sample code to share for using this API in managed code?
  • corrections to the existing content?
  • variations of the signature you want to share?
  • additional languages you want to include?

Select "Edit This Page" on the right hand toolbar and edit it! Or add new pages containing supporting types needed for this API (structures, delegates, and more).

 
Access PInvoke.net directly from VS:
Terms of Use
Find References
Show Printable Version
Revisions