nsis-simple-service-plugin

SimpleSC – NSIS plugin to manage Windows services: install, remove, start, stop, pause and restart services, query and change their configuration, logon account and failure actions. ANSI and Unicode builds.

★ 1 on GitHub

View on GitHub

Anyone may press Interesting, signed in or not. It helps others find this project.

Member rating

No ratings yet.

README

NSIS Simple Service Plugin (SimpleSC)

This plugin contains basic service functions like starting or stopping a service or checking the service status. It also contains advanced service functions, for example setting the service description, changing the logon account, granting or removing the service logon privilege.

Download

Download the latest version from the Releases page. Each release contains two packages:

Package	NSIS	Copy `SimpleSC.dll` to
`NSIS_Simple_Service_Plugin_<version>_ANSI.zip`	NSIS 2, NSIS 3 (ANSI installer)	`Plugins\x86-ansi` (NSIS 3) or `Plugins` (NSIS 2)
`NSIS_Simple_Service_Plugin_<version>_Unicode.zip`	NSIS 3 with `Unicode true`	`Plugins\x86-unicode`

Both packages provide the same functions. Earlier versions than 1.30 are not available.

Reference

nsis

SimpleSC::InstallService [name_of_service] [display_name] [service_type] [start_type] [binary_path] [dependencies] [account] [password]
SimpleSC::RemoveService [name_of_service]

SimpleSC::StartService [name_of_service] [arguments] [timeout]
SimpleSC::StopService [name_of_service] [wait_for_file_release] [timeout]
SimpleSC::PauseService [name_of_service] [timeout]
SimpleSC::ContinueService [name_of_service] [timeout]
SimpleSC::RestartService [name_of_service] [arguments] [timeout]
SimpleSC::ExistsService [name_of_service]

SimpleSC::GetServiceDisplayName [name_of_service]
SimpleSC::GetServiceName [display_name]
SimpleSC::GetServiceStatus [name_of_service]
SimpleSC::GetServiceDescription [name_of_service]
SimpleSC::GetServiceStartType [name_of_service]
SimpleSC::GetServiceBinaryPath [name_of_service]
SimpleSC::GetServiceLogon [name_of_service]
SimpleSC::GetServiceFailure [name_of_service]
SimpleSC::GetServiceFailureFlag [name_of_service]
SimpleSC::GetServiceDelayedAutoStartInfo [name_of_service]

SimpleSC::SetServiceDescription [name_of_service] [service_description]
SimpleSC::SetServiceStartType [name_of_service] [start_type]
SimpleSC::SetServiceBinaryPath [name_of_service] [binary_path]
SimpleSC::SetServiceLogon [name_of_service] [account] [password]
SimpleSC::SetServiceFailure [name_of_service] [reset_period] [reboot_message] [command] [action_type_1] [action_delay_1] [action_type_2] [action_delay_2] [action_type_3] [action_delay_3]
SimpleSC::SetServiceFailureFlag [name_of_service] [failure_actions_on_non_crash_failures]
SimpleSC::SetServiceDelayedAutoStartInfo [name_of_service] [delayed_autostart]

SimpleSC::GrantServiceLogonPrivilege [account]
SimpleSC::RemoveServiceLogonPrivilege [account]

SimpleSC::ServiceIsPaused [name_of_service]
SimpleSC::ServiceIsRunning [name_of_service]
SimpleSC::ServiceIsStopped [name_of_service]

SimpleSC::GetErrorMessage [error_code]

Parameters

name_of_service – The name of the service used for Start/Stop commands and all further commands

display_name – The name as shown in the service control manager applet in system control

service_type – One of the following codes

Value	Constant	Description
1	`SERVICE_KERNEL_DRIVER`	Driver service.
2	`SERVICE_FILE_SYSTEM_DRIVER`	File system driver service.
16	`SERVICE_WIN32_OWN_PROCESS`	Service that runs in its own process. (Should be used in most cases)
32	`SERVICE_WIN32_SHARE_PROCESS`	Service that shares a process with one or more other services.
256	`SERVICE_INTERACTIVE_PROCESS`	The service can interact with the desktop.

Note: If you specify either SERVICE_WIN32_OWN_PROCESS or SERVICE_WIN32_SHARE_PROCESS, and the service is running in the context of the LocalSystem account, you can also specify SERVICE_INTERACTIVE_PROCESS. Example: SERVICE_WIN32_OWN_PROCESS or SERVICE_INTERACTIVE_PROCESS – (16 or 256) = 272

Note: Services cannot directly interact with a user as of Windows Vista. Therefore, this technique should not be used in new code. See for more information: https://learn.microsoft.com/en-us/windows/win32/services/interactive-services

start_type – One of the following codes

Value	Constant	Description
0	`SERVICE_BOOT_START`	Driver boot stage start
1	`SERVICE_SYSTEM_START`	Driver scm stage start
2	`SERVICE_AUTO_START`	Service auto start (Should be used in most cases)
3	`SERVICE_DEMAND_START`	Driver/service manual start
4	`SERVICE_DISABLED`	Driver/service disabled

service_status – One of the following codes

Value	Constant
1	`SERVICE_STOPPED`
2	`SERVICE_START_PENDING`
3	`SERVICE_STOP_PENDING`
4	`SERVICE_RUNNING`
5	`SERVICE_CONTINUE_PENDING`
6	`SERVICE_PAUSE_PENDING`
7	`SERVICE_PAUSED`

binary_path – The path to the binary including all necessary parameters

dependencies – Needed services, controls which services have to be started before this one; use the forward slash / to add more than one service

account – The username/account which should be used

password – Password of the aforementioned account to be able to logon as a service. Note: If you do not specify account/password, the local system account will be used to run the service.

arguments – Arguments passed to the service main function. Note: Driver services do not receive these arguments.

reset_period – The time after which to reset the failure count to zero if there are no failures, in seconds. Specify 0 (INFINITE) to indicate that this value should never be reset

reboot_message – The message to be broadcast to server users before rebooting

command – The command line of the process to execute in response to the SC_ACTION_RUN_COMMAND service controller action. This process runs under the same account as the service

timeout – Timeout in seconds of the function

action_type_x – One of the following codes for the action to be performed

Value	Constant	Description
0	`SC_ACTION_NONE`	No action
1	`SC_ACTION_RESTART`	Restart the service
2	`SC_ACTION_REBOOT`	Reboot the computer (Note: The service user must have the `SE_SHUTDOWN_NAME` privilege)
3	`SC_ACTION_RUN_COMMAND`	Run a command

action_delay_x – The time to wait before performing the specified action, in milliseconds

failure_actions_on_non_crash_failures – This setting determines when failure actions are to be executed

Value	Description
0	The failure actions are executed only if the service terminates without reporting a status of `SERVICE_STOPPED`
1	The failure actions are executed if the status of a service is `SERVICE_STOPPED` but the exit code of the service is not 0

delayed_autostart – The delayed auto-start setting of an auto-start service

Value	Description
0	The service will be started during system boot.
1	The service will be started after other auto-start services are started plus a short delay

error_code – Error code of a function

service_description – The description as shown in the service control manager applet in system control

wait_for_file_release – Wait for file release after the service is stopped. This is useful if the binary file will be overwritten after stopping the service.

Value	Constant	Description
0	`NO_WAIT`	No wait for file release
1	`WAIT`	Wait for file release

Note: If SERVICE_WIN32_OWN_PROCESS is used this option should be set to WAIT. If SERVICE_WIN32_SHARE_PROCESS is used this option should only be set to WAIT if the last service in the process is stopped.

Examples

nsis

; Install a service - ServiceType own process - StartType automatic - NoDependencies - Logon as System Account
  SimpleSC::InstallService "MyService" "My Service Display Name" "16" "2" "C:\MyPath\MyService.exe" "" "" ""
  Pop $0 ; returns an errorcode (<>0) otherwise success (0)

; Install a service - ServiceType interact with desktop - StartType automatic - Dependencies on "Windows Time Service" (w32time) and "WWW Publishing Service" (w3svc) - Logon as System Account
  SimpleSC::InstallService "MyService" "My Service Display Name" "272" "2" "C:\MyPath\MyService.exe" "w32time/w3svc" "" ""
  Pop $0 ; returns an errorcode (<>0) otherwise success (0)

; Remove a service
  SimpleSC::RemoveService "MyService"
  Pop $0 ; returns an errorcode (<>0) otherwise success (0)

; Start a service
  SimpleSC::StartService "MyService" "" 30
  Pop $0 ; returns an errorcode (<>0) otherwise success (0)

; Start a service with two arguments "/param1=true" "/param2=1"
  SimpleSC::StartService "MyService" "/param1=true /param2=1" 30
  Pop $0 ; returns an errorcode (<>0) otherwise success (0)

; Start a service with two arguments "-p param1" "-param2"
  SimpleSC::StartService "MyService" '"-p param1" -param2' 30
  Pop $0 ; returns an errorcode (<>0) otherwise success (0)

; Stop a service and waits for file release
  SimpleSC::StopService "MyService" 1 30
  Pop $0 ; returns an errorcode (<>0) otherwise success (0)

; Stops two services and waits for file release after the last service is stopped
  SimpleSC::StopService "MyService1" 0 30
  Pop $0 ; returns an errorcode (<>0) otherwise success (0)
  SimpleSC::StopService "MyService2" 1 30
  Pop $0 ; returns an errorcode (<>0) otherwise success (0)

; Pause a service
  SimpleSC::PauseService "MyService" 30
  Pop $0 ; returns an errorcode (<>0) otherwise success (0)

; Continue a service
  SimpleSC::ContinueService "MyService" 30
  Pop $0 ; returns an errorcode (<>0) otherwise success (0)

; Restart a service
  SimpleSC::RestartService "MyService" "" 30
  Pop $0 ; returns an errorcode (<>0) otherwise success (0)

; Restart a service with two arguments "/param1=true" "/param2=1"
  SimpleSC::RestartService "MyService" "/param1=true /param2=1" 30
  Pop $0 ; returns an errorcode (<>0) otherwise success (0)

; Restart a service with two arguments "-p param1" "-param2"
  SimpleSC::RestartService "MyService" '"-p param1" -param2' 30
  Pop $0 ; returns an errorcode (<>0) otherwise success (0)

; Check if the service exists
  SimpleSC::ExistsService "MyService"
  Pop $0 ; returns an errorcode if the service doesn't exist (<>0)/service exists (0)

; Get the displayname of a service
  SimpleSC::GetServiceDisplayName "MyService"
  Pop $0 ; returns an errorcode (<>0) otherwise success (0)
  Pop $1 ; returns the displayname of the service

; Get the servicename of a service by the displayname
  SimpleSC::GetServiceName "MyService"
  Pop $0 ; returns an errorcode (<>0) otherwise success (0)
  Pop $1 ; returns the servicename of the service

; Get the current status of a service
  SimpleSC::GetServiceStatus "MyService"
  Pop $0 ; returns an errorcode (<>0) otherwise success (0)
  Pop $1 ; return the status of the service (See "service_status" in the parameters)

; Get the description of a service
  SimpleSC::GetServiceDescription "MyService"
  Pop $0 ; returns an errorcode (<>0) otherwise success (0)
  Pop $1 ; returns the description of the service

; Get the start type of the service
  SimpleSC::GetServiceStartType "MyService"
  Pop $0 ; returns an errorcode (<>0) otherwise success (0)
  Pop $1 ; returns the start type of the service (see "start_type" in the parameters)

; Get the binary path of a service
  SimpleSC::GetServiceBinaryPath "MyService"
  Pop $0 ; returns an errorcode (<>0) otherwise success (0)
  Pop $1 ; returns the binary path of the service

; Get the logon user of the service
  SimpleSC::GetServiceLogon "MyService"
  Pop $0 ; returns an errorcode (<>0) otherwise success (0)
  Pop $1 ; returns the logon username of the service

; Get the failure configuration of a service
  SimpleSC::GetServiceFailure "MyService"
  Pop $0 ; returns an errorcode (<>0) otherwise success (0)
  Pop $1 ; returns the reset period
  Pop $2 ; returns the reboot message
  Pop $3 ; returns the command
  Pop $4 ; returns the first action (See "action_type_x" in the parameters)
  Pop $5 ; returns the first action delay
  Pop $6 ; returns the second action (See "action_type_x" in the parameters)
  Pop $7 ; returns the second action delay
  Pop $8 ; returns the third action (See "action_type_x" in the parameters)
  Pop $9 ; returns the third action delay

; Get the failure flag configuration of a service
  SimpleSC::GetServiceFailureFlag "MyService"
  Pop $0 ; returns an errorcode (<>0) otherwise success (0)
  Pop $1 ; returns the service flag

; Get the delayed auto-start configuration of a service
  SimpleSC::GetServiceDelayedAutoStartInfo "MyService"
  Pop $0 ; returns an errorcode (<>0) otherwise success (0)
  Pop $1 ; returns the delayed auto-start configuration

; Set the description of a service
  SimpleSC::SetServiceDescription "MyService" "Sample Description"
  Pop $0 ; returns an errorcode (<>0) otherwise success (0)

; Set the starttype to automatic of a service
  SimpleSC::SetServiceStartType "MyService" "2"
  Pop $0 ; returns an errorcode (<>0) otherwise success (0)

; Sets the service binary path
  SimpleSC::SetServiceBinaryPath "MyService" "C:\MySoftware\MyService.exe"
  Pop $0 ; returns an errorcode (<>0) otherwise success (0)

; Sets the service logon to a user and grant the user the "SeServiceLogonPrivilege"
  SimpleSC::SetServiceLogon "MyService" "MyServiceUser" "MyServiceUserPassword"
  Pop $0 ; returns an errorcode (<>0) otherwise success (0)
  IntCmp $0 0 +1 Done Done ; If successful grant the service logon privilege to "MyServiceUser"
    ; Note: Every serviceuser must have the ServiceLogonPrivilege to start the service
    SimpleSC::GrantServiceLogonPrivilege "MyServiceUser"
    Pop $0 ; returns an errorcode (<>0) otherwise success (0)
  Done:

; Sets the service failure configuration - First action: Restart the service after one minute - Second action: Reboot the computer after five minutes
  SimpleSC::SetServiceFailure "MyService" "0" "" "" "1" "60000" "2" "300000" "0" "0"
  Pop $0 ; returns an errorcode (<>0) otherwise success (0)

; Sets the failure flag configuration of a service
  SimpleSC::SetServiceFailureFlag "MyService" "1"
  Pop $0 ; returns an errorcode (<>0) otherwise success (0)

; Sets the delayed auto-start configuration of a service
  SimpleSC::SetServiceDelayedAutoStartInfo "MyService" "1"
  Pop $0 ; returns an errorcode (<>0) otherwise success (0)

; Remove the "SeServiceLogonPrivilege" from a user
  SimpleSC::RemoveServiceLogonPrivilege "MyServiceUser"
  Pop $0 ; returns an errorcode (<>0) otherwise success (0)

; Check if the service is paused
  SimpleSC::ServiceIsPaused "MyService"
  Pop $0 ; returns an errorcode (<>0) otherwise success (0)
  Pop $1 ; returns 1 (service is paused) - returns 0 (service is not paused)

; Check if the service is running
  SimpleSC::ServiceIsRunning "MyService"
  Pop $0 ; returns an errorcode (<>0) otherwise success (0)
  Pop $1 ; returns 1 (service is running) - returns 0 (service is not running)

; Check if the service is stopped
  SimpleSC::ServiceIsStopped "MyService"
  Pop $0 ; returns an errorcode (<>0) otherwise success (0)
  Pop $1 ; returns 1 (service is stopped) - returns 0 (service is not stopped)

; Show the error message if a function fails
  SimpleSC::StopService "MyService" 1 30
  Pop $0 ; returns an errorcode (<>0) otherwise success (0)
  IntCmp $0 0 Done +1 +1
    Push $0
    SimpleSC::GetErrorMessage
    Pop $0
    MessageBox MB_OK|MB_ICONSTOP "Stopping fails - Reason: $0"
  Done:

Important Notes

Error codes are any non-zero value. For instance, if you attempt to start, stop, or query a service that does not exist, you may get the error code 1060.
The function SetServiceLogon only works if the service type is SERVICE_WIN32_OWN_PROCESS.
The functions GetServiceDescription, SetServiceDescription, GetServiceFailure and SetServiceFailure are only available on systems higher than Windows NT.
The functions GetServiceFailureFlag, SetServiceFailureFlag, GetServiceDelayedAutoStartInfo and SetServiceDelayedAutoStartInfo are only available on systems higher than Windows 2003.
If you change the logon of a service to a new user you have to grant him the Service Logon Privilege. Otherwise the service cannot be started by the user you have assigned.
The functions StartService, StopService, PauseService and ContinueService use a timeout of 30 seconds. This means the function must be executed within 30 seconds, otherwise the functions will return an error.

Building from Source

The ANSI and Unicode variants are separate code bases.

Variant	Folder	Project	Created with
ANSI	`src/ansi`	`SimpleSC.dpr`	Delphi 6
Unicode	`src/unicode`	`SimpleSC.dproj`	Delphi 10.3 Rio

Both variants build a 32-bit SimpleSC.dll.

License

SimpleSC is dual-licensed under the Mozilla Public License 1.1 or the GNU Lesser General Public License 2.1 or later. See License.txt for details.

Live chat for Free Pascal, Lazarus, Delphi and every Pascal programmer.

Nnsis-simple-service-plugin