winservice

package module
v0.0.0-...-7fc9b84 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 9, 2022 License: MIT Imports: 8 Imported by: 0

README

winservice Go Reference

The winservice package provides access to windows service management APIs.

Documentation

Overview

Package winservice provides windows service management functions.

Index

Constants

View Source
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
)
View Source
const (
	// PollingInterval is the service polling interval used by some winservice
	// functions.
	PollingInterval = time.Millisecond * 50
)

Variables

This section is empty.

Functions

func Delete

func Delete(ctx context.Context, name string) error

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 Exists

func Exists(name string) (bool, error)

Exists returns true if a service with the given name exists.

func Install

func Install(name string, options ...Option) error

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

func Instances(template string) ([]string, error)

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

func Restart(ctx context.Context, name string) error

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.

func Start

func Start(ctx context.Context, name string) error

Start issues a start command to a service and waits for it to start. It returns an error if it fails or the context is cancelled.

Start returns without error if the service is already started.

func Stop

func Stop(ctx context.Context, name string) error

Stop issues a stop command to a service and waits for it to stop. It returns an error if it fails or the context is cancelled.

Stop returns without error if the service is already stopped.

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.

func (Config) Apply

func (conf Config) Apply(c2 *Config)

Apply copies the values from conf to c2. It allows a configuration struct to be passed as an option.

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

type OpError struct {
	Op      string
	Service string
	Err     error
}

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.

func (OpError) Error

func (e OpError) Error() string

Error returns a string representation of the error.

func (OpError) Unwrap

func (e OpError) Unwrap() error

Unwrap returns the next error in the error chain.

type Option

type Option interface {
	Apply(conf *Config)
}

Option is a service configuration option.

func Account

func Account(account, password string) Option

Account returns a service configuration option for the given account credentials.

func Args

func Args(args ...string) Option

Args returns a service configuration option for a set of service arguments.

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 Path

type Path string

Path is a path to a windows service executable.

func (Path) Apply

func (p Path) Apply(conf *Config)

Apply applies the service path 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

func (Startup) Apply

func (s Startup) Apply(conf *Config)

Apply applies the service startup mode to conf.

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
	SharedProcess       Type = 0x00000020 // SERVICE_WIN32_SHARE_PROCESS
	IsolatedUserProcess Type = 0x00000050 // SERVICE_USER_OWN_PROCESS
	SharedUserProcess   Type = 0x00000060 // SERVICE_USER_SHARE_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

func (Type) Apply

func (t Type) Apply(conf *Config)

Apply applies the service type to conf. Its bits are OR'd with the current value of conf.Type.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL