Contains process status information for a service. The ControlServiceEx, EnumServicesStatusEx, NotifyServiceStatusChange, and QueryServiceStatusEx functions use this structure.
Syntax
Members
The type of service. This member can be one of the following values.
Value
Meaning
SERVICE_FILE_SYSTEM_DRIVER 0x00000002
The service is a file system driver.
SERVICE_KERNEL_DRIVER 0x00000001
The service is a device driver.
SERVICE_WIN32_OWN_PROCESS 0x00000010
The service runs in its own process.
SERVICE_WIN32_SHARE_PROCESS 0x00000020
The service shares a process with other services.
В
If the service type is either SERVICE_WIN32_OWN_PROCESS or SERVICE_WIN32_SHARE_PROCESS, and the service is running in the context of the LocalSystem account, the following type may also be specified.
Value
Meaning
SERVICE_INTERACTIVE_PROCESS
The service can interact with the desktop.
The current state of the service. This member can be one of the following values.
Value
Meaning
SERVICE_CONTINUE_PENDING 0x00000005
The service is about to continue.
SERVICE_PAUSE_PENDING 0x00000006
The service is pausing.
SERVICE_PAUSED 0x00000007
The service is paused.
SERVICE_RUNNING 0x00000004
The service is running.
SERVICE_START_PENDING 0x00000002
The service is starting.
SERVICE_STOP_PENDING 0x00000003
The service is stopping.
SERVICE_STOPPED 0x00000001
The service has stopped.
The control codes the service accepts and processes in its handler function (see Handler and HandlerEx). A user interface process can control a service by specifying a control command in the ControlService or ControlServiceEx function. By default, all services accept the SERVICE_CONTROL_INTERROGATE value.
The following are the control codes.
Control code
Meaning
SERVICE_ACCEPT_NETBINDCHANGE 0x00000010
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 SERVICE_CONTROL_NETBINDADD, SERVICE_CONTROL_NETBINDREMOVE, SERVICE_CONTROL_NETBINDENABLE, and SERVICE_CONTROL_NETBINDDISABLE notifications.
SERVICE_ACCEPT_PARAMCHANGE 0x00000008
The service can reread its startup parameters without being stopped and restarted.
This control code allows the service to receive SERVICE_CONTROL_PARAMCHANGE notifications.
SERVICE_ACCEPT_PAUSE_CONTINUE 0x00000002
The service can be paused and continued.
This control code allows the service to receive SERVICE_CONTROL_PAUSE and SERVICE_CONTROL_CONTINUE notifications.
SERVICE_ACCEPT_PRESHUTDOWN 0x00000100
The service can perform preshutdown tasks.
This control code enables the service to receive SERVICE_CONTROL_PRESHUTDOWN notifications. Note that ControlService and ControlServiceEx cannot send this notification; only the system can send it.
Windows ServerВ 2003 and WindowsВ XP:В В This value is not supported.
SERVICE_ACCEPT_SHUTDOWN 0x00000004
The service is notified when system shutdown occurs.
This control code allows the service to receive SERVICE_CONTROL_SHUTDOWN notifications. Note that ControlService and ControlServiceEx cannot send this notification; only the system can send it.
SERVICE_ACCEPT_STOP 0x00000001
The service can be stopped.
This control code allows the service to receive SERVICE_CONTROL_STOP notifications.
This member can also contain the following extended control codes, which are supported only by HandlerEx. (Note that these control codes cannot be sent by ControlService or ControlServiceEx.)
Control code
Meaning
SERVICE_ACCEPT_HARDWAREPROFILECHANGE 0x00000020
The service is notified when the computer’s hardware profile has changed. This enables the system to send SERVICE_CONTROL_HARDWAREPROFILECHANGE notifications to the service.
SERVICE_ACCEPT_POWEREVENT 0x00000040
The service is notified when the computer’s power status has changed. This enables the system to send SERVICE_CONTROL_POWEREVENT notifications to the service.
SERVICE_ACCEPT_SESSIONCHANGE 0x00000080
The service is notified when the computer’s session status has changed. This enables the system to send SERVICE_CONTROL_SESSIONCHANGE notifications to the service.
The error code that 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 ERROR_SERVICE_SPECIFIC_ERROR to indicate that the dwServiceSpecificExitCode member contains the error code. The service should set this value to NO_ERROR when it is running and when it terminates normally.
The 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 dwWin32ExitCode member is set to ERROR_SERVICE_SPECIFIC_ERROR.
The check-point value that 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.
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 dwCurrentState. If the amount of time specified by dwWaitHint passes, and dwCheckPoint has not been incremented or dwCurrentState 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.
The process identifier of the service.
This member can be one of the following values.
Value
Meaning
0
The service is running in a process that is not a system process, or it is not running.
If the service is running in a process that is not a system process, dwProcessId is nonzero. If the service is not running, dwProcessId is zero.
Introduction to Windows Service Applications
Microsoft Windows services, formerly known as NT services, enable you to create long-running executable applications that run in their own Windows sessions. These services can be automatically started when the computer boots, can be paused and restarted, and do not show any user interface. These features make services ideal for use on a server or whenever you need long-running functionality that does not interfere with other users who are working on the same computer. You can also run services in the security context of a specific user account that is different from the logged-on user or the default computer account. For more information about services and Windows sessions, see the Windows SDK documentation.
You can easily create services by creating an application that is installed as a service. For example, suppose you want to monitor performance counter data and react to threshold values. You could write a Windows Service application that listens to the performance counter data, deploy the application, and begin collecting and analyzing data.
You create your service as a Microsoft Visual Studio project, defining code within it that controls what commands can be sent to the service and what actions should be taken when those commands are received. Commands that can be sent to a service include starting, pausing, resuming, and stopping the service; you can also execute custom commands.
After you create and build the application, you can install it by running the command-line utility InstallUtil.exe and passing the path to the service’s executable file. You can then use the Services Control Manager to start, stop, pause, resume, and configure your service. You can also accomplish many of these same tasks in the Services node in Server Explorer or by using the ServiceController class.
Service Applications vs. Other Visual Studio Applications
Service applications function differently from many other project types in several ways:
The compiled executable file that a service application project creates must be installed on the server before the project can function in a meaningful way. You cannot debug or run a service application by pressing F5 or F11; you cannot immediately run a service or step into its code. Instead, you must install and start your service, and then attach a debugger to the service’s process. For more information, see How to: Debug Windows Service Applications.
Unlike some types of projects, you must create installation components for service applications. The installation components install and register the service on the server and create an entry for your service with the Windows Services Control Manager. For more information, see How to: Add Installers to Your Service Application.
The Main method for your service application must issue the Run command for the services your project contains. The Run method loads the services into the Services Control Manager on the appropriate server. If you use the Windows Services project template, this method is written for you automatically. Note that loading a service is not the same thing as starting the service. See «Service Lifetime» below for more information.
Windows Service applications run in a different window station than the interactive station of the logged-on user. A window station is a secure object that contains a Clipboard, a set of global atoms, and a group of desktop objects. Because the station of the Windows service is not an interactive station, dialog boxes raised from within a Windows service application will not be seen and may cause your program to stop responding. Similarly, error messages should be logged in the Windows event log rather than raised in the user interface.
The Windows service classes supported by the .NET Framework do not support interaction with interactive stations, that is, the logged-on user. The .NET Framework also does not include classes that represent stations and desktops. If your Windows service must interact with other stations, you will need to access the unmanaged Windows API. For more information, see the Windows SDK documentation.
The interaction of the Windows service with the user or other stations must be carefully designed to include scenarios such as there being no logged on user, or the user having an unexpected set of desktop objects. In some cases, it may be more appropriate to write a Windows application that runs under the control of the user.
Windows service applications run in their own security context and are started before the user logs into the Windows computer on which they are installed. You should plan carefully what user account to run the service within; a service running under the system account has more permissions and privileges than a user account.
Service Lifetime
A service goes through several internal states in its lifetime. First, the service is installed onto the system on which it will run. This process executes the installers for the service project and loads the service into the Services Control Manager for that computer. The Services Control Manager is the central utility provided by Windows to administer services.
After the service has been loaded, it must be started. Starting the service allows it to begin functioning. You can start a service from the Services Control Manager, from Server Explorer, or from code by calling the Start method. The Start method passes processing to the application’s OnStart method and processes any code you have defined there.
A running service can exist in this state indefinitely until it is either stopped or paused or until the computer shuts down. A service can exist in one of three basic states: Running, Paused, or Stopped. The service can also report the state of a pending command: ContinuePending, PausePending, StartPending, or StopPending. These statuses indicate that a command has been issued, such as a command to pause a running service, but has not been carried out yet. You can query the Status to determine what state a service is in, or use the WaitForStatus to carry out an action when any of these states occurs.
You can pause, stop, or resume a service from the Services Control Manager, from Server Explorer, or by calling methods in code. Each of these actions can call an associated procedure in the service (OnStop, OnPause, or OnContinue), in which you can define additional processing to be performed when the service changes state.
Types of Services
There are two types of services you can create in Visual Studio using the .NET Framework. Services that are the only service in a process are assigned the type Win32OwnProcess. Services that share a process with another service are assigned the type Win32ShareProcess. You can retrieve the service type by querying the ServiceType property.
You might occasionally see other service types if you query existing services that were not created in Visual Studio. For more information on these, see the ServiceType.
Services and the ServiceController Component
The ServiceController component is used to connect to an installed service and manipulate its state; using a ServiceController component, you can start and stop a service, pause and continue its functioning, and send custom commands to a service. However, you do not need to use a ServiceController component when you create a service application. In fact, in most cases your ServiceController component should exist in a separate application from the Windows service application that defines your service.
For more information, see ServiceController.
Requirements
Services must be created in a Windows Service application project or another .NET Framework–enabled project that creates an .exe file when built and inherits from the ServiceBase class.
Projects containing Windows services must have installation components for the project and its services. This can be easily accomplished from the Properties window. For more information, see How to: Add Installers to Your Service Application.
