' ########################################################################################
' Microsoft Windows
' File: RestartManager.inc
' Contents: Header for RestartManager API
' Copyright (c) 2011 Jos? Roca
' Portions Copyright (c) Microsoft Corporation.
' All Rights Reserved.
' THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
' EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF
' MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE.
' ########################################################################################
#IF NOT %DEF(PBX_RestartManager_PBI)
#DEFINE PBX_RestartManager_PBI
%EQUATE `RESTARTMANAGER_INC = 1
#INCLUDE ONCE "Core/Windows.inc"
'// Macros and Types
'// RM_SESSION_KEY_LEN - size in bytes of binary session key
'#define RM_SESSION_KEY_LEN sizeof(GUID)
%EQUATE `RM_SESSION_KEY_LEN = 16
'// CCH_RM_SESSION_KEY - character count of text-encoded session key
%EQUATE `CCH_RM_SESSION_KEY = %RM_SESSION_KEY_LEN * 2
'// CCH_RM_MAX_APP_NAME - maximum character count of application friendly name
%EQUATE `CCH_RM_MAX_APP_NAME = 255
'// CCH_RM_MAX_SVC_NAME - maximum character count of service short name
%EQUATE `CCH_RM_MAX_SVC_NAME = 63
'// Uninitialized value for TS Session ID
%EQUATE `RM_INVALID_TS_SESSION = -1
'// Uninitialized value for Process ID
%EQUATE `RM_INVALID_PROCESS = -1
' enum RM_APP_TYPE
%EQUATE `RmUnknownApp = 0 ' // Application type cannot be classified in
 ' // known categories
%EQUATE `RmMainWindow = 1 ' // Application is a windows application that
 ' // displays a top-level window
%EQUATE `RmOtherWindow = 2 ' // Application is a windows app but does not
 ' // display a top-level window
%EQUATE `RmService = 3 ' // Application is an NT service
%EQUATE `RmExplorer = 4 ' // Application is Explorer
%EQUATE `RmConsole = 5 ' // Application is Console application
%EQUATE `RmCritical = 1000 ' // Application is critical system process
 ' // where a reboot is required to restart
' enum RM_SHUTDOWN_TYPE
%EQUATE `RmForceShutdown = &H1 ' // Force app shutdown
%EQUATE `RmShutdownOnlyRegistered = &H10 ' // Only shudown apps if all apps
 ' // registered for restart
' enum RM_APP_STATUS
%EQUATE `RmStatusUnknown = &H0 ' // Application in unknown state
 ' // or state not important
%EQUATE `RmStatusRunning = &H1 ' // Application is currently running
%EQUATE `RmStatusStopped = &H2 ' // Application stopped by Restart Manager
%EQUATE `RmStatusStoppedOther = &H4 ' // Application detected stopped
 ' // by outside action
%EQUATE `RmStatusRestarted = &H8 ' // Application restarted by Restart Manager
%EQUATE `RmStatusErrorOnStop = &H10 ' // An error occurred when stopping
 ' // this application
%EQUATE `RmStatusErrorOnRestart = &H20 ' // An error occurred when restarting
 ' // this application
%EQUATE `RmStatusShutdownMasked = &H40 ' // Shutdown action masked by filer
%EQUATE `RmStatusRestartMasked = &H80 ' // Restart action masked by filter
' enum RM_REBOOT_REASON
%EQUATE `RmRebootReasonNone = &H0 ' // Reboot not required
%EQUATE `RmRebootReasonPermissionDenied = &H1 ' // Current user does not have
 ' // permission to shut down
 ' // one or more detected processes
%EQUATE `RmRebootReasonSessionMismatch = &H2 ' // One or more processes are
 ' // running in another TS session.
%EQUATE `RmRebootReasonCriticalProcess = &H4 ' // A critical process has been
 ' // detected
%EQUATE `RmRebootReasonCriticalService = &H8 ' // A critical service has been
 ' // detected
%EQUATE `RmRebootReasonDetectedSelf = &H10 ' // The current process has been
 ' // detected
' // Size = 12 bytes
TYPE RM_UNIQUE_PROCESS DWORD
 dwProcessId AS DWORD ' DWORD // PID
 ProcessStartTime AS FILETIME ' FILETIME // Process creation time
END TYPE
' // Size = 668 bytes
TYPE RM_PROCESS_INFO DWORD
 Process AS RM_UNIQUE_PROCESS ' // Unique process identification
 strAppName AS WSTRINGZ * %CCH_RM_MAX_APP_NAME + 1 ' WCHAR // Application friendly name
 strServiceShortName AS WSTRINGZ * %CCH_RM_MAX_SVC_NAME + 1 ' WCHAR // Service short name,
 ' // if applicable
 ApplicationType AS LONG ' RM_APP_TYPE // Application type
 AppStatus AS DWORD ' ULONG // Bit mask of application status
 TSSessionId AS DWORD ' DWORD // Terminal Service session ID of
 ' // process (-1 if n/a)
 bRestartable AS LONG ' BOOL // Is application restartable?
END TYPE
' enum RM_FILTER_TRIGGER
%EQUATE `RmFilterTriggerInvalid = 0 ' // Invalid value
%EQUATE `RmFilterTriggerFile = 1 ' // Filter is triggered by EXE name
%EQUATE `RmFilterTriggerProcess = 2 ' // Filter is triggered by PID/create time
%EQUATE `RmFilterTriggerService = 3 ' // Filter is triggered by service short name
' enum _RM_FILTER_ACTION {
%EQUATE `RmInvalidFilterAction = 0 ' // Invalid value
%EQUATE `RmNoRestart = 1 ' // Prevent restart of application
%EQUATE `RmNoShutdown = 2 ' // Prevent shutdown and restart of
 ' // application
' // Size = 12 bytes
UNION RM_FILTER_INFO_UNION DWORD
 strFilename AS WSTRINGZ PTR ' LPWSTR // When RmFilterTrigger == RmFilterTriggerFile,
 ' // this contains the filename this filter applies to
 Process AS RM_UNIQUE_PROCESS ' // When RmFilterTrigger == RmFilterTriggerProcess,
 ' // this contains the process this filter applies to
 strServiceShortName AS WSTRINGZ PTR ' LPWSTR // When RmFilterTrigger == RmFilterTriggerService,
 ' // this contians the service name this filter applies to
END UNION
' // Size = 24 bytes
TYPE RM_FILTER_INFO DWORD
 FilterAction AS LONG ' RM_FILTER_ACTION // Filter action
 FilterTrigger AS LONG ' RM_FILTER_TRIGGER // Filter trigger
 cbNextOffset AS DWORD ' DWORD // Bytes to next structure
 RM_FILTER_INFO_UNION
END TYPE
'typedef void (*RM_WRITE_STATUS_CALLBACK)( __in UINT nPercentComplete );
'SUB RM_WRITE_STATUS_CALLBACK (BYVAL nPercentComplete AS DWORD)
'// Functions
'// Function: RmStartSession
'// Purpose: Begins a Restart Manager session as the Conductor
'// Error Codes:
'// ERROR_SEM_TIMEOUT
'// Failed to obtain semaphore lock in allotted time.
'// ERROR_BAD_ARGUMENTS
'// An invalid argument was supplied to the function.
'// ERROR_WRITE_FAULT
'// Read/write operation failed.
'// ERROR_OUTOFMEMORY
'// Could not allocate memory or instantiate class object.
DECLARE FUNCTION RmStartSession LIB "rstrtmgr.dll" ALIAS "RmStartSession" ( BYREF pSessionHandle AS QUAD , BYVAL dwSessionFlags AS QUAD , BYREF strSessionKey AS WSTRINGZ ) AS QUAD
'// Function: RmJoinSession
'// Purpose: Joins an existing Restart Manager session as a Subordinate
'// Error Codes:
'// ERROR_SEM_TIMEOUT
'// Failed to obtain semaphore lock in allotted time.
'// ERROR_BAD_ARGUMENTS
'// An invalid argument was supplied to the function.
'// ERROR_WRITE_FAULT
'// Read/write operation failed.
'// ERROR_OUTOFMEMORY
'// Could not allocate memory or instantiate class object.
DECLARE FUNCTION RmJoinSession LIB "rstrtmgr.dll" ALIAS "RmJoinSession" ( BYREF pSessionHandle AS QUAD , BYREF strSessionKey AS WSTRINGZ ) AS QUAD
'// Function: RmEndSession
'// Purpose: Terminates and cleans up an existing session.
'// Error Codes:
'// ERROR_SEM_TIMEOUT
'// Failed to obtain semaphore lock in allotted time.
'// ERROR_BAD_ARGUMENTS
'// An invalid argument was supplied to the function.
'// ERROR_WRITE_FAULT
'// Read/write operation failed.
'// ERROR_OUTOFMEMORY
'// Could not allocate memory or instantiate class object.
'// ERROR_INVALID_HANDLE
'// No session exists for the supplied handle.
DECLARE FUNCTION RmEndSession LIB "rstrtmgr.dll" ALIAS "RmEndSession" ( BYVAL dwSessionHandle AS QUAD ) AS QUAD
'// Function: RmRegisterResources
'// Purpose: Called if error is encountered. Installer
'// must pass in all files to be updated
'// that may prevent the install from completing. Processes
'// passed in array are forced to stop/start. Services short
'// names passed in array are stopped (along with dependencies
'// and restarted.
'// Error Codes:
'// ERROR_SEM_TIMEOUT
'// Failed to obtain semaphore lock in allotted time.
'// ERROR_BAD_ARGUMENTS
'// An invalid argument was supplied to the function.
'// ERROR_WRITE_FAULT
'// Read/write operation failed.
'// ERROR_OUTOFMEMORY
'// Could not allocate memory or instantiate class object.
'// ERROR_INVALID_HANDLE
'// No session exists for the supplied handle.
DECLARE FUNCTION RmRegisterResources LIB "rstrtmgr.dll" ALIAS "RmRegisterResources" ( BYVAL dwSessionHandle AS QUAD , BYVAL nFiles AS QUAD , BYREF rgsFileNames AS WSTRINGZ , BYVAL nApplications AS QUAD , BYREF rgApplications AS RM_UNIQUE_PROCESS , BYVAL nServices AS QUAD , OPTIONAL BYREF rgsServiceNames AS WSTRINGZ ) AS QUAD
'// Function: RmGetList
'// Purpose: Gets the list of applications affected by registered
'// resources and their current status.
'// Returns: An array of RM_PROCESS_INFO structs containing a list of
'// all applications affected by registered items, the number
'// of structs needed to retreive all application information,
'// the number of structs that were populated, and a series
'// of flags describing why a reboot will be necessary.
'// Error Codes:
'// ERROR_MORE_DATA
'// Buffer is not large enough for all information.
'// ERROR_CANCELLED
'// Operation was cancelled by user.
'// ERROR_SEM_TIMEOUT
'// Failed to obtain semaphore lock in allotted time.
'// ERROR_BAD_ARGUMENTS
'// An invalid argument was supplied to the function.
'// ERROR_WRITE_FAULT
'// Read/write operation failed.
'// ERROR_OUTOFMEMORY
'// Could not allocate memory or instantiate class object.
'// ERROR_INVALID_HANDLE
'// No session exists for the supplied handle.
DECLARE FUNCTION RmGetList LIB "rstrtmgr.dll" ALIAS "RmGetList" ( BYVAL dwSessionHandle AS QUAD , BYREF pnProcInfoNeeded AS QUAD , BYREF pnProcInfo AS QUAD , BYREF rgAffectedApps AS RM_PROCESS_INFO , BYREF lpdwRebootReasons AS QUAD ) AS QUAD
'// Function: RmShutdown
'// Purpose: Initiates application shutdown sequence.
'// Error Codes:
'// ERROR_FAIL_NOACTION_REBOOT
'// One or more of the affected applications requires a reboot
'// to be shut down.
'// ERROR_FAIL_SHUTDOWN
'// There was an error shuting down some application(s).
'// ERROR_CANCELLED
'// Operation was cancelled by user.
'// ERROR_SEM_TIMEOUT
'// Failed to obtain semaphore lock in allotted time.
'// ERROR_BAD_ARGUMENTS
'// An invalid argument was supplied to the function.
'// ERROR_WRITE_FAULT
'// Read/write operation failed.
'// ERROR_OUTOFMEMORY
'// Could not allocate memory or instantiate class object.
'// ERROR_INVALID_HANDLE
'// No session exists for the supplied handle.
DECLARE FUNCTION RmShutdown LIB "rstrtmgr.dll" ALIAS "RmShutdown" ( BYVAL dwSessionHandle AS QUAD , BYVAL lActionFlags AS QUAD , OPTIONAL BYVAL fnStatus AS QUAD ) AS QUAD
'// Function: RmRestart
'// Purpose: Applications automatically shutdown by RmShutdown()
'// and are registered for restart or are services are restarted.
'// Error Codes:
'// ERROR_FAIL_NOACTION_REBOOT
'// One or more of the affected applications requires a reboot
'// to be shut down.
'// ERROR_FAIL_SHUTDOWN
'// There was an error shuting down some application(s).
'// ERROR_CANCELLED
'// Operation was cancelled by user.
'// ERROR_SEM_TIMEOUT
'// Failed to obtain semaphore lock in allotted time.
'// ERROR_BAD_ARGUMENTS
'// An invalid argument was supplied to the function.
'// ERROR_WRITE_FAULT
'// Read/write operation failed.
'// ERROR_OUTOFMEMORY
'// Could not allocate memory or instantiate class object.
'// ERROR_INVALID_HANDLE
'// No session exists for the supplied handle.
DECLARE FUNCTION RmRestart LIB "rstrtmgr.dll" ALIAS "RmRestart" ( BYVAL dwSessionHandle AS QUAD , BYVAL dwRestartFlags AS QUAD , OPTIONAL BYVAL fnStatus AS QUAD ) AS QUAD
'// Function: RmCancelCurrentTask()
'// Purpose: Notifies Restart Manager to cancel the task it is performing
'// as soon as possible.
'// Error Codes:
'// ERROR_BAD_ARGUMENTS
'// An invalid argument was supplied to the function.
'// ERROR_OUTOFMEMORY
'// Could not allocate memory or instantiate class object.
'// ERROR_INVALID_HANDLE
'// No session exists for the supplied handle.
DECLARE FUNCTION RmCancelCurrentTask LIB "rstrtmgr.dll" ALIAS "RmCancelCurrentTask" ( BYVAL dwSessionHandle AS QUAD ) AS QUAD
'// Function: RmAddFilter()
'// Purpose: Adds a filter for process module (ie. executable name), process ID,
'// or service short name to prevent Restart Manager from performing
'// the specified action on the process(es) or service noted.
'// Error Codes:
'// ERROR_BAD_ARGUMENTS
'// An invalid argument was supplied to the function.
'// ERROR_INVALID_HANDLE
'// No session exists for the supplied handle.
DECLARE FUNCTION RmAddFilter LIB "rstrtmgr.dll" ALIAS "RmAddFilter" ( BYVAL dwSessionHandle AS QUAD , BYREF strModuleName AS WSTRINGZ , BYREF pProcess AS RM_UNIQUE_PROCESS , BYREF strServiceShortName AS WSTRINGZ , BYVAL FilterAction AS LONG ) AS QUAD
'// Function: RmRemoveFilter()
'// Purpose: Removes a previously added filter for process module
'// (ie. executable name), process ID, or service short name
'// enabling all Restart Manager actions on the process(es)
'// or service noted.
'// Error Codes:
'// ERROR_BAD_ARGUMENTS
'// An invalid argument was supplied to the function.
'// ERROR_INVALID_HANDLE
'// No session exists for the supplied handle.
DECLARE FUNCTION RmRemoveFilter LIB "rstrtmgr.dll" ALIAS "RmRemoveFilter" ( BYVAL dwSessionHandle AS QUAD , BYREF strModuleName AS WSTRINGZ , BYREF pProcess AS RM_UNIQUE_PROCESS , OPTIONAL BYREF strServiceShortName AS WSTRINGZ ) AS QUAD
'// Function: RmGetFilterList()
'// Purpose: Writes a set of currenly applied filters
'// to a caller-allocated buffer.
'// Error Codes:
'// ERROR_BAD_ARGUMENTS
'// An invalid argument was supplied to the function.
'// ERROR_INVALID_HANDLE
'// No session exists for the supplied handle.
DECLARE FUNCTION RmGetFilterList LIB "rstrtmgr.dll" ALIAS "RmGetFilterList" ( BYVAL dwSessionHandle AS QUAD , BYVAL pbFilterBuf AS BYTE PTR , BYVAL cbFilterBuf AS QUAD , BYREF cbFilterBufNeeded AS QUAD ) AS QUAD
#ENDIF
