Documentation ¶
Overview ¶
Package winservice provides windows service management functions.
Index ¶
- Constants
- func Delete(ctx context.Context, name string) error
- func Exists(name string) (bool, error)
- func Install(name string, options ...Option) error
- func Instances(template string) ([]string, error)
- func Restart(ctx context.Context, name string) error
- func Start(ctx context.Context, name string) error
- func Stop(ctx context.Context, name string) error
- type Config
- type Description
- type DisplayName
- type Importance
- type OpError
- type Option
- type OptionFunc
- type Path
- type Startup
- type Type
Constants ¶
const ( // ErrAccessDenied is returned when the calling process has insufficient // permissions. ErrAccessDenied = syscall.ERROR_ACCESS_DENIED // ERROR_ACCESS_DENIED // ErrInvalidHandle is returned when an invalid service handle has // been provided to a system call. ErrInvalidHandle = syscall.Errno(0x00000006) // ERROR_INVALID_HANDLE // ErrInvalidParameter is returned when an invalid argument has been // provided to a system call. ErrInvalidParameter = syscall.Errno(0x00000057) // ERROR_INVALID_PARAMETER // ErrDependentServicesRunning is returned when a service cannot be // stopped because it has other services depending on it. ErrDependentServicesRunning = syscall.Errno(0x0000041B) // ERROR_DEPENDENT_SERVICES_RUNNING // ErrInvalidServiceControl is returned when an invalid service control // code has been sent. ErrInvalidServiceControl = syscall.Errno(0x0000041C) // ERROR_INVALID_SERVICE_CONTROL // ErrServiceRequestTimeout is returned when a service does not respond // to a control code within the windows service manager's timeout. ErrServiceRequestTimeout = syscall.Errno(0x0000041D) // ERROR_SERVICE_REQUEST_TIMEOUT // ErrServiceDoesNotExist is returned when a requested service does not // exist. ErrServiceDoesNotExist = syscall.Errno(0x00000424) // ERROR_SERVICE_DOES_NOT_EXIST // ErrServiceCannotAcceptControl is returned when a service is not in a // condition to accept a particular control code. ErrServiceCannotAcceptControl = syscall.Errno(0x00000425) // ERROR_SERVICE_CANNOT_ACCEPT_CTRL // ErrServiceNotActive is returned when a service is not running. ErrServiceNotActive = syscall.Errno(0x00000426) // ERROR_SERVICE_NOT_ACTIVE // ErrServiceMarkedForDeletion is returned when a service has already been // deleted but its removal is incomplete until the next restart. ErrServiceMarkedForDeletion = syscall.Errno(0x00000430) // ERROR_SERVICE_MARKED_FOR_DELETE // ErrShutdownInProgress is returned when an action cannot be taken on a // service because the system is shutting down. ErrShutdownInProgress = syscall.Errno(0x0000045B) // ERROR_SHUTDOWN_IN_PROGRESS )
const ( // PollingInterval is the service polling interval used by some winservice // functions. PollingInterval = time.Millisecond * 50 )
Variables ¶
This section is empty.
Functions ¶
func Delete ¶
Delete removes a service and waits for it to dissolve. It returns an error if it fails or the context is cancelled.
Delete will attempt to stop the service first if it is running.
Delete returns without error if the service doesn't exist. If the service has already been marked for deletion it returns an OpError that wraps ErrServiceMarkedForDeletion.
func Install ¶
Install installs a service with the given name and options.
NOTE: This function signature is subject to change in future revisions.
TODO: Consider making name an option instead of a required parameter.
func Instances ¶
Instances returns the names of per-user instances for the given service template name.
TODO: Use lower level system calls that don't require elevated rights.
FIXME: Right now this returns all services that are prefixed with the service template name and an underscore. In addition, we should verify that the services returned actually have the correct service type flags.
func Restart ¶
Restart issues a stop command to a service if it is running and waits for it to stop, then issues a start command and waits for it to start. It returns an error if either command fails or the context is cancelled.
If the service is not already running this is equivalent to calling Start.
Types ¶
type Config ¶
type Config struct { Path string Args []string Type Type Startup Startup Importance Importance Account string Password string // Write Only DisplayName string Description string }
Config holds configuration for a service.
NOTE: This structure is subject to change in future revisions.
type Description ¶
type Description string
Description is the description of a windows service.
func (Description) Apply ¶
func (d Description) Apply(conf *Config)
Apply applies the description to conf.
type DisplayName ¶
type DisplayName string
DisplayName is the user-friendly name of a windows service.
func (DisplayName) Apply ¶
func (dn DisplayName) Apply(conf *Config)
Apply applies the display name to conf.
type Importance ¶
type Importance uint32
Importance is the importance of a windows service to the operating system. It determines the action taken when a service fails to start.
const ( // Ignored services will be ignored if they fail to start. Ignored Importance = 0x00000000 // SERVICE_ERROR_IGNORE // Logged services will have startup failures logged. Logged Importance = 0x00000001 // SERVICE_ERROR_NORMAL // Essential services cause the operating system to revert to a last known // good configuration when the service fails to start, if possible. // // If the system is already is a last known good configuration it boots // normally. Essential Importance = 0x00000002 // SERVICE_ERROR_SEVERE // Critical services cause the operating system to revert to a last known // good configuration when the service fails to start, if possible. // // If the system is already is a last known good configuration the system // halts. Critical Importance = 0x00000003 // SERVICE_ERROR_CRITICAL )
Windows service startup types.
https://docs.microsoft.com/en-us/windows/desktop/api/winsvc/nf-winsvc-createservicew
func (Importance) Apply ¶
func (i Importance) Apply(conf *Config)
Apply applies the service importance to conf.
type OpError ¶
OpError is the error type usually returned by functions in the winservice package. It describes the operation and service the error relates to.
TODO: Consider use of pointer receivers as used in the standard library.
type Option ¶
type Option interface {
Apply(conf *Config)
}
Option is a service configuration option.
type OptionFunc ¶
type OptionFunc func(conf *Config)
OptionFunc is a service configuration function.
func (OptionFunc) Apply ¶
func (f OptionFunc) Apply(conf *Config)
Apply applies the configuration option to conf.
type Startup ¶
type Startup uint32
Startup is a windows service startup mode.
const ( // BootStart services are driver services started by the system loader. BootStart Startup = 0x00000000 // SERVICE_BOOT_START // SystemStart services are driver services started by IoInitSystem. SystemStart Startup = 0x00000001 // SERVICE_SYSTEM_START // AutoStart services are started automatically when the system starts. AutoStart Startup = 0x00000002 // SERVICE_AUTO_START // DemandStart services are started upon request. DemandStart Startup = 0x00000003 // SERVICE_DEMAND_START // Disabled services cannot be started. Disabled Startup = 0x00000004 // SERVICE_DISABLED )
Windows service startup modes.
https://docs.microsoft.com/en-us/windows/desktop/api/winsvc/nf-winsvc-createservicew
type Type ¶
type Type uint32
Type is a windows service type.
const ( KernelDriver Type = 0x00000001 // SERVICE_KERNEL_DRIVER FileSystemDriver Type = 0x00000002 // SERVICE_FILE_SYSTEM_DRIVER Adapter Type = 0x00000004 // SERVICE_ADAPTER RecognizerDriver Type = 0x00000008 // SERVICE_RECOGNIZER_DRIVER IsolatedProcess Type = 0x00000010 // SERVICE_WIN32_OWN_PROCESS IsolatedUserProcess Type = 0x00000050 // SERVICE_USER_OWN_PROCESS )
Windows service types.
https://docs.microsoft.com/en-us/windows/desktop/api/winsvc/nf-winsvc-createservicew https://docs.microsoft.com/en-us/windows/win32/api/winsvc/ns-winsvc-service_status