winscm

Manages Windows services.

This API is VFS-aware: it operates through the VFS in scope for the current strand, so it works transparently under remote or elevated contexts. It is supported only on Windows targets; elsewhere every operation throws sys.UnsupportedError.

Types

Type	Description
ManagerAccessMask	Access rights for a ScManager handle.
NotifyMask	Service status changes to observe.
ScManager	An open handle to the Windows Service Control Manager.
Service	An open Windows service handle.
ServiceAccessMask	Access rights for a Service handle.
ServiceConfig	Immutable snapshot of a service's configuration.
ServiceControlsAccepted	Controls a running service accepts.
ServiceInfo	One entry in a service enumeration.
ServiceType	Windows service type flags.
Status	Snapshot of a service's current status.
AcceptedControl	A control in a ServiceControlsAccepted.
BinaryPathSpec	A service command line, given as a string, an executable path, or an iterable of arguments.
ControlRequest	A control request for Service.control.
ErrorControl	What Windows does when a service fails to start.
ManagerAccessMaskSpec	Manager rights, given as a ManagerAccessMask, one right, or an iterable of rights.
ManagerAccessRight	A right of a ManagerAccessMask: a manager-specific right, or a generic Windows AccessRight.
NotifyChange	A status change in a NotifyMask.
NotifyMaskSpec	Status changes, given as a NotifyMask, one change, or an iterable of changes.
ServiceAccessMaskSpec	Service rights, given as a ServiceAccessMask, one right, or an iterable of rights.
ServiceAccessRight	A right of a ServiceAccessMask: a service-specific right, or a generic Windows AccessRight.
ServiceState	The state of a service.
ServiceTypeFlag	A flag of a ServiceType.
ServiceTypeSpec	Service types, given as a ServiceType, one flag, or an iterable of flags.
StartType	When a service starts.
StateFilter	Which services ScManager.enumerate_services includes.

AcceptedControl

A control in a ServiceControlsAccepted.

Type	Description
:STOP:	Stop the service
:PAUSE_CONTINUE:	Pause or continue the service
:SHUTDOWN:	Prepare for system shutdown
:PARAMCHANGE:	Reload configuration parameters
:NETBINDCHANGE:	Handle a network binding change
:HARDWAREPROFILECHANGE:	Handle a hardware-profile change
:POWEREVENT:	Handle a power event
:SESSIONCHANGE:	Handle a terminal-services session change
:PRESHUTDOWN:	Prepare for system shutdown before other services
:TIMECHANGE:	Handle a system-time change
:TRIGGEREVENT:	Handle a service-trigger event

BinaryPathSpec = (Str | fs.Path | Iterable[Str | fs.Path])

A service command line, given as a string, an executable path, or an iterable of arguments.

ControlRequest

A control request for Service.control.

Type	Description
:STOP:	Stop
:PAUSE:	Pause
:CONTINUE:	Resume from the paused state
:INTERROGATE:	Report its current status

ErrorControl

What Windows does when a service fails to start.

Type	Description
:IGNORE:	Logs the error and continues startup
:NORMAL:	Logs the error, displays a message, and continues startup
:SEVERE:	Restarts with the last known-good configuration if possible
:CRITICAL:	Restarts with it; fails startup if that restart fails

ManagerAccessMaskSpec

@let ManagerAccessMaskSpec = $
  | ManagerAccessMask
  | ManagerAccessRight
  | Iterable[ManagerAccessRight]

Manager rights, given as a ManagerAccessMask, one right, or an iterable of rights.

ManagerAccessRight

@let ManagerAccessRight = $
  | :SC_MANAGER_CONNECT:
  | :SC_MANAGER_CREATE_SERVICE:
  | :SC_MANAGER_ENUMERATE_SERVICE:
  | :SC_MANAGER_LOCK:
  | :SC_MANAGER_QUERY_LOCK_STATUS:
  | :SC_MANAGER_MODIFY_BOOT_CONFIG:
  | :SC_MANAGER_ALL_ACCESS:
  | security.windows.AccessRight

A right of a ManagerAccessMask: a manager-specific right, or a generic Windows AccessRight.

Symbol	Meaning
:SC_MANAGER_CONNECT:	Connects to the Service Control Manager
:SC_MANAGER_CREATE_SERVICE:	Creates services
:SC_MANAGER_ENUMERATE_SERVICE:	Enumerates services
:SC_MANAGER_LOCK:	Locks the service database
:SC_MANAGER_QUERY_LOCK_STATUS:	Queries the service database lock status
:SC_MANAGER_MODIFY_BOOT_CONFIG:	Modifies boot configuration information
:SC_MANAGER_ALL_ACCESS:	All Service Control Manager-specific rights

NotifyChange

A status change in a NotifyMask.

Type	Description
:STOPPED:	The stopped state
:START_PENDING:	The start-pending state
:STOP_PENDING:	The stop-pending state
:RUNNING:	The running state
:CONTINUE_PENDING:	The continue-pending state
:PAUSE_PENDING:	The pause-pending state
:PAUSED:	The paused state
:CREATED:	Service creation
:DELETED:	Service deletion
:DELETE_PENDING:	A service becoming marked for deletion

NotifyMaskSpec = (NotifyMask | NotifyChange | Iterable[NotifyChange])

Status changes, given as a NotifyMask, one change, or an iterable of changes.

ServiceAccessMaskSpec

@let ServiceAccessMaskSpec = $
  | ServiceAccessMask
  | ServiceAccessRight
  | Iterable[ServiceAccessRight]

Service rights, given as a ServiceAccessMask, one right, or an iterable of rights.

ServiceAccessRight

@let ServiceAccessRight = $
  | :SERVICE_QUERY_CONFIG:
  | :SERVICE_CHANGE_CONFIG:
  | :SERVICE_QUERY_STATUS:
  | :SERVICE_ENUMERATE_DEPENDENTS:
  | :SERVICE_START:
  | :SERVICE_STOP:
  | :SERVICE_PAUSE_CONTINUE:
  | :SERVICE_INTERROGATE:
  | :SERVICE_USER_DEFINED_CONTROL:
  | :SERVICE_ALL_ACCESS:
  | security.windows.AccessRight

A right of a ServiceAccessMask: a service-specific right, or a generic Windows AccessRight.

Symbol	Meaning
:SERVICE_QUERY_CONFIG:	Queries the service configuration
:SERVICE_CHANGE_CONFIG:	Changes the service configuration
:SERVICE_QUERY_STATUS:	Queries the current service status
:SERVICE_ENUMERATE_DEPENDENTS:	Enumerates dependent services
:SERVICE_START:	Starts the service
:SERVICE_STOP:	Stops the service
:SERVICE_PAUSE_CONTINUE:	Pauses or resumes the service
:SERVICE_INTERROGATE:	Requests that the service report its status
:SERVICE_USER_DEFINED_CONTROL:	Sends user-defined control codes to the service
:SERVICE_ALL_ACCESS:	All service-specific rights

ServiceState

The state of a service.

Type	Description
:STOPPED:	Not running
:START_PENDING:	Starting
:STOP_PENDING:	Stopping
:RUNNING:	Running
:CONTINUE_PENDING:	Resuming from the paused state
:PAUSE_PENDING:	Pausing
:PAUSED:	Paused

ServiceTypeFlag

A flag of a ServiceType.

Type	Description
:KERNEL_DRIVER:	Kernel-mode device driver
:FILE_SYSTEM_DRIVER:	File-system driver
:WIN32_OWN_PROCESS:	Win32 service running in its own process
:WIN32_SHARE_PROCESS:	Win32 service sharing a process with other services
:INTERACTIVE_PROCESS:	Service that can interact with the desktop
:DRIVER:	Either kind of driver
:WIN32:	Either kind of Win32 service

ServiceTypeSpec = (ServiceType | ServiceTypeFlag | Iterable[ServiceTypeFlag])

Service types, given as a ServiceType, one flag, or an iterable of flags.

StartType

When a service starts.

Type	Description
:BOOT_START:	Starts during boot before the driver is ready
:SYSTEM_START:	Starts during kernel initialization
:AUTO_START:	Starts automatically during system startup
:DEMAND_START:	Starts when requested
:DISABLED:	Cannot be started

StateFilter

Which services ScManager.enumerate_services includes.

Type	Description
:ACTIVE:	Services that are not stopped
:INACTIVE:	Services that are stopped
:ALL:	Both

Functions

open … -> ScManager ^{overload 1 of 2}

Opens the local Service Control Manager.

Parameters

Name	Type	Description
:access?	ManagerAccessMaskSpec	Rights the returned handle requests. Defaults to :SC_MANAGER_CONNECT:.

Example

winscm.open access: :SC_MANAGER_ENUMERATE_SERVICE: do |manager|
  for info = manager.enumerate_services()
    echo $info.name

open[R] func … -> R ^{overload 2 of 2}

Opens the local Service Control Manager and calls func with it. The manager handle is closed when func returns.

Parameters

Name	Type	Description
:access?	ManagerAccessMaskSpec	Rights the returned handle requests. Defaults to :SC_MANAGER_CONNECT:.
func	((ScManager) -> R)	Called with the ScManager.