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`.
`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 = (:STOP: | :PAUSE_CONTINUE: | :SHUTDOWN: | :PARAMCHANGE: | :NETBINDCHANGE: | :HARDWAREPROFILECHANGE: | :POWEREVENT: | :SESSIONCHANGE: | :PRESHUTDOWN: | :TIMECHANGE: | :TRIGGEREVENT:)`

A control in a ServiceControlsAccepted.

Symbol	Accepts control requests to
`: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

`ControlRequest = (:STOP: | :PAUSE: | :CONTINUE: | :INTERROGATE:)`

A control request for Service.control.

Symbol	Requests that the service
`:STOP:`	Stop
`:PAUSE:`	Pause
`:CONTINUE:`	Resume from the paused state
`:INTERROGATE:`	Report its current status

`ErrorControl = (:IGNORE: | :NORMAL: | :SEVERE: | :CRITICAL:)`

What Windows does when a service fails to start.

Symbol	Meaning
`: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 = (ManagerAccessMask | ManagerAccessRight | Iterable[ManagerAccessRight])`

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

`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 = (:STOPPED: | :START_PENDING: | :STOP_PENDING: | :RUNNING: | :CONTINUE_PENDING: | :PAUSE_PENDING: | :PAUSED: | :CREATED: | :DELETED: | :DELETE_PENDING:)`

A status change in a NotifyMask.

Symbol	Observes a change to
`: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 = (ServiceAccessMask | ServiceAccessRight | Iterable[ServiceAccessRight])`

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

`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 = (:STOPPED: | :START_PENDING: | :STOP_PENDING: | :RUNNING: | :CONTINUE_PENDING: | :PAUSE_PENDING: | :PAUSED:)`

The state of a service.

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

`ServiceTypeFlag = (:KERNEL_DRIVER: | :FILE_SYSTEM_DRIVER: | :WIN32_OWN_PROCESS: | :WIN32_SHARE_PROCESS: | :INTERACTIVE_PROCESS: | :DRIVER: | :WIN32:)`

A flag of a ServiceType.

Symbol	Meaning
`: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 = (:BOOT_START: | :SYSTEM_START: | :AUTO_START: | :DEMAND_START: | :DISABLED:)`

When a service starts.

Symbol	Meaning
`: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 = (:ACTIVE: | :INACTIVE: | :ALL:)`

Which services ScManager.enumerate_services includes.

Symbol	Includes
`:ACTIVE:`	Services that are not stopped
`:INACTIVE:`	Services that are stopped
`:ALL:`	Both

Functions

`open … -> ScManager`

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`

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`.