System.Win32.Services

Documentation

type HandlerFunction = HANDLE -> ServiceControl -> IO Bool

A handler function is registered with the service dispatcher thread from a ServiceMainFunction. The first argument is a HANDLE returned from calling registerServiceCtrlHandler. The second argument represents the command this service has been directed to perform.

type ServiceMainFunction = String -> [String] -> HANDLE -> IO ()

The service dispatcher thread will call each function of this type that you provide. The first argument will be the name of the service. Any additional command-line parameters will appear in the second argument.

Each of these functions should call registerServiceCtrlHandler to register a function to handle incoming commands. It should then set the service's status to StartPending, and specify that no controls will be accepted. At this point the function may perform any other initialization steps before setting the service's status to Running. All of this should take no more than 100ms.

data ServiceAccept

The control codes the service accepts and processes in its handler function (See HandlerFunction). By default, all services accept the Interrogate value. To accept the DEVICEEVENT value, the service must register to receive device events by using the registerDeviceNotification function.

Constructors

AcceptNetBindChange

The service is a network component that can accept changes in its binding without being stopped and restarted. This control code allows the service to receive NetBindAdd, NetBindRemove, NetBindEnable, and NetBindDisable notifications.

AcceptParamChange

The service can reread its startup parameters without being stopped and restarted. This control code allows the service to receive ParamChange notifications.

AcceptPauseContinue

The service can be paused and continued. This control code allows the service to receive Pause and Continue notifications.

AcceptPreshutdown

MSDN documentation says that this function is not supported on Windows Server 2003 or Windows XP/2000. The support status on other versions is unknown to me.

The service can perform preshutdown tasks. This control code enables the service to receive Preshutdown notifications. Note that only the system can send it.

AcceptShutdown

The service is notified when system shutdown occurs. This control code allows the service to receive Shutdown notifications. Note that only the system can send it.

AcceptStop

The service can be stopped. This control code allows the service to receive Stop notifications.

Instances

Show ServiceAccept

Defined in System.Win32.Services.Accept

Methods

showsPrec :: Int -> ServiceAccept -> ShowS

show :: ServiceAccept -> String

showList :: [ServiceAccept] -> ShowS

data ServiceControl

A ServiceControl is used in Handler functions. All control codes are defined here, but some can only be used with a HandlerEx callback. Use convertSuccess to translate from a ServiceControl to a DWORD. Use convertAttempt to translate from a DWORD to a ServiceControl.

Constructors

Continue

Interrogate

NetBindAdd

NetBindDisable

NetBindEnable

NetBindRemove

ParamChange

Pause

PreShutdown

Shutdown

Stop

Instances

Show ServiceControl

Defined in System.Win32.Services.Control

Methods

showsPrec :: Int -> ServiceControl -> ShowS

show :: ServiceControl -> String

showList :: [ServiceControl] -> ShowS

data ServiceState

The current state of a service.

Constructors

ContinuePending

PausePending

Paused

Running

StartPending

StopPending

Stopped

Instances

Eq ServiceState

Defined in System.Win32.Services.State

Methods

(==) :: ServiceState -> ServiceState -> Bool

(/=) :: ServiceState -> ServiceState -> Bool

Show ServiceState

Defined in System.Win32.Services.State

Methods

showsPrec :: Int -> ServiceState -> ShowS

show :: ServiceState -> String

showList :: [ServiceState] -> ShowS

Storable ServiceState

State is stored as a DWORD value in memory. If an undocument value is encountered during a peek, there isn't any reasonable way to respond, so an ErrorCall exception will be thrown.

Defined in System.Win32.Services.State

Methods

sizeOf :: ServiceState -> Int

alignment :: ServiceState -> Int

peekElemOff :: Ptr ServiceState -> Int -> IO ServiceState

pokeElemOff :: Ptr ServiceState -> Int -> ServiceState -> IO ()

peekByteOff :: Ptr b -> Int -> IO ServiceState

pokeByteOff :: Ptr b -> Int -> ServiceState -> IO ()

peek :: Ptr ServiceState -> IO ServiceState

poke :: Ptr ServiceState -> ServiceState -> IO ()

data ServiceStatus

Contains status information for a service.

Constructors

ServiceStatus

Fields

• serviceType :: ServiceType

  The type of service. This binding only supports the Win32OwnProcess type.

• currentState :: ServiceState

  The current state of the service.

• controlsAccepted :: [ServiceAccept]

  See ServiceAccept for details on this field.

• win32ExitCode :: ErrCode

  The error code the service uses to report an error that occurs when it is starting or stopping. To return an error code specific to the service, the service must set this value to ServiceSpecificError to indicate that the serviceSpecificExitCode member contains the error code. The service should set this value to Success when it is running and on normal termination.

• serviceSpecificExitCode :: DWORD

  A service-specific error code that the service returns when an error occurs while the service is starting or stopping. This value is ignored unless the win32ExitCode member is set to ServiceSpecificError.

  This binding does not support service-specific error codes.

• checkPoint :: DWORD

  The check-point value the service increments periodically to report its progress during a lengthy start, stop, pause, or continue operation. For example, the service should increment this value as it completes each step of its initialization when it is starting up. The user interface program that invoked the operation on the service uses this value to track the progress of the service during a lengthy operation. This value is not valid and should be zero when the service does not have a start, stop, pause, or continue operation pending.

• waitHint :: DWORD

  The estimated time required for a pending start, stop, pause, or continue operation, in milliseconds. Before the specified amount of time has elapsed, the service should make its next call to the SetServiceStatus function with either an incremented dwCheckPoint value or a change in currentState. If the amount of time specified by waitHint passes, and checkPoint has not been incremented or currentState has not changed, the service control manager or service control program can assume that an error has occurred and the service should be stopped. However, if the service shares a process with other services, the service control manager cannot terminate the service application because it would have to terminate the other services sharing the process as well.

Instances

Show ServiceStatus

Defined in System.Win32.Services.Status

Methods

showsPrec :: Int -> ServiceStatus -> ShowS

show :: ServiceStatus -> String

showList :: [ServiceStatus] -> ShowS

Storable ServiceStatus

Defined in System.Win32.Services.Status

Methods

sizeOf :: ServiceStatus -> Int

alignment :: ServiceStatus -> Int

peekElemOff :: Ptr ServiceStatus -> Int -> IO ServiceStatus

pokeElemOff :: Ptr ServiceStatus -> Int -> ServiceStatus -> IO ()

peekByteOff :: Ptr b -> Int -> IO ServiceStatus

pokeByteOff :: Ptr b -> Int -> ServiceStatus -> IO ()

peek :: Ptr ServiceStatus -> IO ServiceStatus

poke :: Ptr ServiceStatus -> ServiceStatus -> IO ()

data ServiceType

Win32 defines many types of services, but this binding only supports Win32OwnProcess.

Constructors

FileSystemDriver

The service is a file system driver.

KernelDriver

The service is a device driver.

Win32OwnProcess

The service runs in its own process.

Win32ShareProcess

The service shares a process with other services.

ServiceInteractiveProcess

Do no write your own services of this type. Windows Vista and above prevent service processes from directly interacting with users.

A ServiceInteractiveProcess is either a Win32OwnProcess or a Win32ShareProcess running in the context of the LocalSystem account which is allowed to directly interact with users.

Instances

Show ServiceType

Defined in System.Win32.Services.Type

Methods

showsPrec :: Int -> ServiceType -> ShowS

show :: ServiceType -> String

showList :: [ServiceType] -> ShowS

Storable ServiceType

Defined in System.Win32.Services.Type

Methods

sizeOf :: ServiceType -> Int

alignment :: ServiceType -> Int

peekElemOff :: Ptr ServiceType -> Int -> IO ServiceType

pokeElemOff :: Ptr ServiceType -> Int -> ServiceType -> IO ()

peekByteOff :: Ptr b -> Int -> IO ServiceType

pokeByteOff :: Ptr b -> Int -> ServiceType -> IO ()

peek :: Ptr ServiceType -> IO ServiceType

poke :: Ptr ServiceType -> ServiceType -> IO ()

queryServiceStatus

Arguments

:: HANDLE

MSDN documentation: A handle to the service. This handle is returned by the OpenService or the CreateService function, and it must have the SERVICE_QUERY_STATUS access right. For more information, see Service Security and Access Rights.

-> IO ServiceStatus

This function will throw an Win32Exception when the internal Win32 call returnes an error condition. MSDN lists the following exceptions, but others might be thrown as well:

AccessDenied

The handle does not have the SERVICE_QUERY_STATUS access right.

InvalidHandle

The handle is invalid.

Retrieves the current status of the specified service.

setServiceStatus

Arguments

:: HANDLE

MSDN documentation: A handle to the status information structure for the current service. This handle is returned by the RegisterServiceCtrlHandlerEx function.

-> ServiceStatus

MSDN documentation: A pointer to the SERVICE_STATUS structure the contains the latest status information for the calling service.

-> IO ()

This function will throw an Win32Exception when the internal Win32 call returnes an error condition. MSDN lists the following exceptions, but others might be thrown as well:

InvalidData

The specified service status structure is invalid.

InvalidHandle

The specified handle is invalid.

Updates the service control manager's status information for the calling service.

startServiceCtrlDispatcher

Arguments

:: String

The name of the service. According to MSDN documentation this argument is unused in Win32OwnProcess type services, which is the only type supported by this binding. Even so, it is recommended that the name of the service be used.

MSDN description: The name of the service run by the calling thread. This is the service name that the service control program specified in the CreateService function when creating the service.

-> DWORD

waitHint

The estimated time required for a pending start, stop, pause, or continue operation, in milliseconds.

-> HandlerFunction

-> ServiceMainFunction

This is a callback function that will be called by the operating system whenever the service is started. It should perform service initialization including the registration of a handler function. MSDN documentation gives conflicting advice as to whether this function should return before the service has entered the stopped state. In the official example the service main function blocks until the service is ready to stop.

-> IO ()

This function will throw an Win32Exception when the internal Win32 call returnes an error condition. MSDN lists the following exceptions, but others might be thrown as well:

FailedServiceControllerConnect

This error is returned if the program is being run as a console application rather than as a service. If the program will be run as a console application for debugging purposes, structure it such that service-specific code is not called when this error is returned.

InvalidData

The specified dispatch table contains entries that are not in the proper format.

ServiceAlreadyRunning

The process has already called startServiceCtrlDispatcher. Each process can call startServiceCtrlDispatcher only one time.

Register a callback function to initialize the service, which will be called by the operating system immediately. startServiceCtrlDispatcher will block until the provided callback function returns.

MSDN documentation: Connects the main thread of a service process to the service control manager, which causes the thread to be the service control dispatcher thread for the calling process.