more service documentation

2 files changed, 650 insertions, 2 deletions

diff --git a/docs/service/ModuleDD.txt b/docs/service/ModuleDD.txt
new file mode 100644
index 0000000..24df0d5
--- /dev/null
+++ b/docs/service/ModuleDD.txt
@@ -0,0 +1,646 @@
+
+
+                                  MODULE DD
+
+                              WINDOWS SERVICES
+
+                                Part 1: STORY
+
+
+
+What we have in this Module?
+
+    1. Windows Services Story
+    2. Service Control Manager (SCM)
+    3. Database of Installed Services
+    4. Automatically Starting Services
+    5. Starting Services on Demand
+    6. Stopping Services
+    7. Service Record List
+    8. SCM Handles
+    9. Service Programs
+   10. Service Entry Point
+   11. Service ServiceMain Function
+   12. Service Control Handler Function
+   13. Receiving Events in a Service
+
+
+                                 [INS: [INS:
+
+   IFRAME: [6]google_ads_frame
+
+   :INS] :INS]
+
+
+   [INS: [INS:
+
+   IFRAME: [7]google_ads_frame
+
+   :INS] :INS]
+
+   My Training Period: xx hours. Before you begin, read some
+   [8]instruction here.
+
+
+   Abilities:
+     * Able to understand the Windows services concepts.
+     * Able to understand the Service Control Manager (SCM).
+     * Able to use the Windows Task Manager and Services snap-in.
+     * Able to understand the security aspects of Windows services.
+
+Windows Services Story
+
+
+   There are two Windows service types:
+
+
+    1. Service application and
+    2. Driver service.
+
+
+   A service application conforms to the interface rules of the Service
+   Control Manager (SCM). It can be started:
+
+
+    1. Automatically at system boot.
+    2. By a user through the Services control panel applet or
+    3. By an application that uses the service functions.
+
+
+   Services can execute even when no user is logged on to the system. For
+   normal applications such as your word processor program, we need to
+   manually launch the program or automatically start it through the
+   program Startup setting. A driver service conforms to the device driver
+   protocols. It is similar to a service application, but it does not
+   interact with the SCM. For simplicity, here, the term service refers to
+   a service application. The following is the Services control panel that
+   can be launched through Services menu:
+
+
+   Start -> Programs -> Administrative Tools -> Services. To manage or
+   control any service, you can select the service -> right click your
+   mouse -> select Properties context menu.
+
+
+   You can also access the Services through the Control Panel: Start ->
+   Settings -> Control Panel. Notice at the bottom of the Services snap-in
+   there are Extended and Standard view. (Tenouk's Windows XP Pro)
+
+
+            Controlling Windows Services through Services snap-in
+
+
+   The following is a service property page for Windows Automatic Update
+   service.
+
+
+             Controlling Windows Services: Service property page
+
+
+   The running services (processes) can be seen through the Task Manager
+   as shown in the following figure.
+
+
+              Controlling Windows Services through Task Manager
+
+
+   The SCM maintains a database of installed services and driver services,
+   and provides a unified and secure means of controlling them. The
+   database includes information on how each service or driver service
+   should be started. It also enables system administrators to customize
+   security requirements for each service and thereby control access to
+   the service. The following types of programs use the functions provided
+   by the SCM.
+
+
+                                    Type
+
+                                 Description
+
+   Service program
+
+   A program that provides executable code for one or more services.
+   Service programs use functions that connect to the SCM and send status
+   information to the SCM.
+
+   Service configuration program
+
+   A program that queries or modifies the services database. Service
+   configuration programs use functions that open the database, install or
+   delete services in the database, and query or modify the configuration
+   and security parameters for installed services. Service configuration
+   programs manage both services and driver services.
+
+   Service control program
+
+   A program that starts and controls services and driver services.
+   Service control programs use functions that send requests to the SCM,
+   which carries out the request.
+
+
+                                   Table 1
+
+
+Service Control Manager
+
+
+   The SCM is started at system boot. It is a remote procedure call (RPC)
+   server, so that service configuration and service control programs can
+   manipulate services on remote machines. The service functions provide
+   an interface for the following tasks performed by the SCM:
+    1. Maintaining the database of installed services.
+    2. Starting services and driver services either upon system startup or
+       upon demand.
+    3. Enumerating installed services and driver services.
+    4. Maintaining status information for running services and driver
+       services.
+    5. Transmitting control requests to running services.
+    6. Locking and unlocking the service database.
+
+
+Database of Installed Services
+
+
+   The SCM maintains a database of installed services in the registry. The
+   database is used by the SCM and programs that add, modify, or configure
+   services. The following is the registry key for this database.
+
+     HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services
+
+   This key contains a subkey for each installed service and driver
+   service. The name of the subkey is the name of the service, as
+   specified by the CreateService() function when the service was
+   installed by a service configuration program. An initial copy of the
+   database is created when the system is installed. The database contains
+   entries for the device drivers required during system boot. The
+   database includes the following information about each installed
+   service and driver service:
+    1. The service type. This indicates whether the service executes in
+       its own process or shares a process with other services. For driver
+       services, this indicates whether the service is a kernel driver or
+       a file system driver.
+    2. The start type. This indicates whether the service or driver
+       service is started automatically at system startup (auto-start
+       service) or whether the SCM starts it when requested by a service
+       control program (demand-start service). The start type can also
+       indicate that the service or driver service is disabled, in which
+       case it cannot be started.
+    3. The error control level. This specifies the severity of the error
+       if the service or driver service fails to start during system
+       startup and determines the action that the startup program will
+       take.
+    4. The fully qualified path of the executable file. The filename
+       extension is .exe for services and .sys for driver services.
+    5. Optional dependency information used to determine the proper order
+       for starting services or driver services. For services, this
+       information can include a list of services that the SCM must start
+       before it can start the specified service, the name of a load
+       ordering group that the service is part of, and a tag identifier
+       that indicates the start order of the service in its load ordering
+       group. For driver services, this information includes a list of
+       drivers that must be started before the specified driver.
+    6. For services, an optional account name and password. The service
+       program runs in the context of this account. If no account is
+       specified, the service executes in the context of the LocalSystem
+       account.
+    7. For driver services, an optional driver object name (for example,
+       \FileSystem\Rdr or \Driver\Xns), used by the I/O system to load the
+       device driver. If no name is specified, the I/O system creates a
+       default name based on the driver service name.
+
+
+   Note:  This database is also known as the ServicesActive database or
+   the SCM database. You must use the functions provided by the SCM,
+   instead of modifying the database directly.
+
+
+Automatically Starting Services
+
+
+   During system boot, the SCM starts all auto-start services and the
+   services on which they depend (service dependency). For example, if an
+   auto-start service depends on another demand-start service, the
+   demand-start service is also started automatically. The load order is
+   determined by the following:
+
+
+    1. The order of groups in the load ordering group list,
+       ServiceGroupOrder, in the following [9]registry key:
+
+     HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control
+
+    2. The order of services within a group specified in the tags order
+       vector, GroupOrderList, in the following [10]registry key:
+
+     HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control
+
+    3. The dependencies listed for each service.
+
+
+   When the boot is complete, the system executes the boot verification
+   program specified by BootVerificationProgram value of the following
+   [11]registry key:
+
+     HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control
+
+   By default, this value is not set. The system simply reports that the
+   boot was successful after the first user has logged on. You can supply
+   a boot verification program that checks the system for problems and
+   reports the boot status to the SCM using the NotifyBootConfigStatus()
+   function. After a successful boot, the system saves a clone of the
+   database in the last-known-good (LKG) configuration. The system can
+   restore this copy of the database if changes made to the active
+   database cause the system reboot to fail. The following is the
+   [12]registry key for this database:
+
+     HKEY_LOCAL_MACHINE\SYSTEM\ControlSetXXX\Services
+
+   Where XXX is the value saved in the following [13]registry key value:
+
+     HKEY_LOCAL_MACHINE\System\Select\LastKnownGood.
+
+   If an auto-start service with a SERVICE_ERROR_CRITICAL error control
+   level fails to start, the SCM reboots the machine using the LKG
+   configuration. If the LKG configuration is already being used, the boot
+   fails.
+
+
+Starting Services on Demand
+
+
+   The user can start a service with the Services control panel utility.
+   The user can specify arguments for the service in the Start parameters
+   field. A service control program can start a service and specify its
+   arguments with the StartService() function. When the service is
+   started, the SCM performs the following steps:
+
+
+    1. Retrieve the account information stored in the database.
+    2. Log on the service account.
+    3. Create the service in the suspended state.
+    4. Assign the logon token to the process.
+    5. Allow the process to execute.
+
+
+   [INS: [INS:
+
+   IFRAME: [14]google_ads_frame
+
+   :INS] :INS]
+
+Stopping Services
+
+
+   The user can stop a service with the Services control panel utility. A
+   service control program can stop a service with the ControlService()
+   function, by sending a SERVICE_CONTROL_STOP request to the service
+   through the SCM. If the SCM receives a SERVICE_CONTROL_STOP request for
+   a service, it instructs the service to stop by forwarding the stop code
+   on to the service's ServiceMain() function. However, if the SCM
+   determines that other services that are running are dependent on the
+   specified service, it does not forward the stop request. Instead, it
+   returns the ERROR_DEPENDENT_SERVICES_RUNNING error code. To
+   programmatically stop a service with dependent services, you must first
+   enumerate and stop its dependent services.
+
+
+Service Record List
+
+
+   As each service entry is read from the database of installed services,
+   the SCM creates a service record for the service. A service record
+   includes:
+    1. Service name.
+    2. Start type (auto-start or demand-start).
+    3. Service status (see the SERVICE_STATUS structure)
+    4. Type.
+    5. Current state.
+    6. Acceptable control codes.
+    7. Exit code.
+    8. Wait hint.
+    9. Pointer to dependency list.
+
+
+   The user name and password of an account are specified at the time the
+   service is installed. The SCM stores the user name in the registry and
+   the password in a secure portion of the Local Security Authority (LSA).
+   The system administrator can create accounts with passwords that never
+   expire. Alternatively, the system administrator can create accounts
+   with passwords that expire and manage the accounts by changing the
+   passwords periodically. The SCM keeps two copies of a user account's
+   password, a current password and a backup password. The password
+   specified the first time the service is installed is stored as the
+   current password and the backup password is not initialized. When the
+   SCM attempts to run the service in the security context of the user
+   account, it uses the current password. If the current password is used
+   successfully, it is also saved as the backup password. If the password
+   is modified with the ChangeServiceConfig() function, or the Services
+   control panel utility, the new password is stored as the current
+   password and the previous password is stored as the backup password. If
+   the SCM attempts to start the service and the current password fails,
+   then it uses the backup password. If the backup password is used
+   successfully, it is saved as the current password. The SCM updates the
+   service status when a service sends it status notifications using the
+   SetServiceStatus() function. The SCM maintains the status of a driver
+   service by querying the I/O system, instead of receiving status
+   notifications, as it does from a service. A service can register
+   additional type information by calling the SetServiceBits() function.
+   The NetServerGetInfo() and NetServerEnum() functions obtain the
+   supported service types.
+
+
+SCM Handles
+
+
+   The SCM supports handle types to allow access to the following objects.
+    1. The database of installed services.
+    2. A service.
+    3. The database lock.
+
+
+   An SCManager object represents the database of installed services. It
+   is a container object that holds service objects. The OpenSCManager()
+   function returns a handle to an SCManager object on a specified
+   computer. This handle is used when installing, deleting, opening, and
+   enumerating services and when locking the services database. A service
+   object represents an installed service. The CreateService() and
+   OpenService() functions return handles to installed services. The
+   OpenSCManager(), CreateService(), and OpenService() functions can
+   request different types of access to SCManager and service objects. The
+   requested access is granted or denied depending on the access token of
+   the calling process and the security descriptor associated with the
+   SCManager or service object.
+
+   The CloseServiceHandle() function closes handles to SCManager and
+   service objects. When you no longer need these handles, be sure to
+   close them. A lock object is created during SCM initialization to
+   serialize access to the database of installed services. The SCM
+   acquires the lock before starting a service or driver service. Service
+   configuration programs use the LockServiceDatabase() function to
+   acquire the lock before reconfiguring a service and use the
+   UnlockServiceDatabase() function to release the lock.
+
+
+Service Programs
+
+
+   A service program contains executable code for one or more services. A
+   service created with the type SERVICE_WIN32_OWN_PROCESS only contains
+   the code for one service. A service created with the type
+   SERVICE_WIN32_SHARE_PROCESS contains code for more than one service,
+   enabling them to share code. A service can be configured to execute in
+   the context of a user account from either the built-in (local),
+   primary, or trusted domain. It can also be configured to run in a
+   special service user account. The following topics describe the
+   interface requirements of the SCM that a service program must include
+   and additional programming considerations. These sections do not apply
+   to driver services.
+    1. Service Entry Point.
+    2. Service ServiceMain() Function
+    3. Service Control Handler Function.
+
+
+Service Entry Point
+
+
+   Services are generally written as console applications. The entry point
+   of a console application is its main function. The main function
+   receives arguments from the ImagePath value from the registry key for
+   the service. When the SCM starts a service program, it waits for it to
+   call the StartServiceCtrlDispatcher() function. You can use the
+   following guidelines.
+    1. A service of type SERVICE_WIN32_OWN_PROCESS should call
+       StartServiceCtrlDispatcher() immediately, from its main thread. You
+       can perform any initialization after the service starts.
+    2. If the service type is SERVICE_WIN32_SHARE_PROCESS and there is
+       common initialization for all services in the program, you can
+       perform the initialization in the main thread before calling
+       StartServiceCtrlDispatcher(), as long as it takes less than 30
+       seconds. Otherwise, you must create another thread to do the common
+       initialization, while the main thread calls
+       StartServiceCtrlDispatcher(). You should still perform any
+       service-specific initialization after the service starts.
+
+
+   The StartServiceCtrlDispatcher() function takes a SERVICE_TABLE_ENTRY
+   structure for each service contained in the process. Each structure
+   specifies the service name and the entry point for the service. If
+   StartServiceCtrlDispatcher() succeeds, the calling thread does not
+   return until all running services in the process have terminated. The
+   SCM sends control requests to this thread through a named pipe. The
+   thread acts as a control dispatcher, performing the following tasks:
+
+   IFRAME: [15]google_ads_frame
+
+    1. Create a new thread to call the appropriate entry point when a new
+       service is started.
+    2. Call the appropriate handler function to handle service control
+       requests.
+
+
+Service ServiceMain Function
+
+
+   When a service control program requests that a new service run, the SCM
+   starts the service and sends a start request to the control dispatcher.
+   The control dispatcher creates a new thread to execute the
+   ServiceMain() function for the service. The ServiceMain() function
+   should perform the following tasks:
+
+
+    1. Call the RegisterServiceCtrlHandlerEx() function immediately to
+       register a HandlerEx() function to handle control requests for the
+       service. The return value of RegisterServiceCtrlHandlerEx() is a
+       service status handle that will be used in calls to notify the SCM
+       of the service status.
+    2. Perform initialization. If the execution time of the initialization
+       code is expected to be very short (less than one second),
+       initialization can be performed directly in ServiceMain().
+
+
+   If the initialization time is expected to be longer than one second,
+   call the SetServiceStatus() function, specifying the
+   SERVICE_START_PENDING service state and a wait hint in the
+   SERVICE_STATUS structure. As initialization continues, the service
+   should make additional calls to SetServiceStatus() to report progress.
+   Sending multiple SetServiceStatus() calls is useful for debugging
+   services.
+
+
+    3. When initialization is complete, call SetServiceStatus(),
+       specifying the SERVICE_RUNNING state in the SERVICE_STATUS
+       structure.
+    4. Perform the service tasks, or, if there are no pending tasks,
+       return. Any change in the state of the service warrants a call to
+       SetServiceStatus() to report new status information.
+    5. If an error occurs while the service is initializing or running,
+       the service should call SetServiceStatus(), specifying the
+       SERVICE_STOP_PENDING state in the SERVICE_STATUS structure, if
+       cleanup will be lengthy. Once cleanup is complete, call
+       SetServiceStatus() from the last thread to terminate, specifying
+       SERVICE_STOPPED in the SERVICE_STATUS structure. Be sure to set the
+       dwServiceSpecificExitCode and dwWin32ExitCode members of the
+       SERVICE_STATUS structure to identify the error.
+
+
+Service Control Handler Function
+
+
+   Each service has a control handler, the HandlerEx() function, that is
+   invoked by the control dispatcher when the service process receives a
+   control request from a service control program. Therefore, this
+   function executes in the context of the control dispatcher. Whenever
+   HandlerEx() is invoked, the service must call the SetServiceStatus()
+   function to report its status to the SCM. This must be done regardless
+   of whether the status changed. The service control program can send
+   control requests using the ControlService() function. All services must
+   accept and process the SERVICE_CONTROL_INTERROGATE control code. You
+   can enable or disable acceptance of the other control codes by calling
+   SetServiceStatus(). To receive the SERVICE_CONTROL_DEVICEEVENT control
+   code, you must call the RegisterDeviceNotification() function. Services
+   can also handle additional user-defined control codes.
+
+   The control handler must return within 30 seconds, or the SCM will
+   return an error. If a service needs to do lengthy processing when the
+   service is executing the control handler, it should create a secondary
+   thread to perform the lengthy processing, and then return. This
+   prevents the service from tying up the control dispatcher. For example,
+   when handling the stop request for a service that will take a long
+   time, create another thread to handle the stop process. The control
+   handler should simply call SetServiceStatus() with the
+   SERVICE_STOP_PENDING message and return.
+
+   When the user shuts down the system, all control handlers that have
+   called SetServiceStatus() with the SERVICE_ACCEPT_SHUTDOWN control code
+   receive the SERVICE_CONTROL_SHUTDOWN control code. They are notified in
+   the order that they appear in the database of installed services. By
+   default, a service has approximately 20 seconds to perform cleanup
+   tasks before the system shuts down. After this time expires, system
+   shutdown proceeds regardless of whether service shutdown is complete.
+   Note that if the system is left in the shutdown state (not restarted or
+   powered down), the service continues to run.
+
+   If the service needs more time to clean up, it sends STOP_PENDING
+   status messages, along with a wait hint, so the service controller
+   knows how long to wait before reporting to the system that service
+   shutdown is complete. However, there is a limit to how long the service
+   controller will wait, to prevent a service from stopping shutdown. To
+   change this time limit, modify the WaitToKillServiceTimeout value in
+   the following [16]registry key:
+
+     HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control
+
+   Note that during service shutdown, the SCM does not take dependencies
+   into consideration. The SCM enumerates the list of running services and
+   sends the SERVICE_CONTROL_SHUTDOWN command. Therefore, a service may
+   fail because another service it depends on has already stopped.
+   [INS: [INS:
+
+   IFRAME: [17]google_ads_frame
+
+   :INS] :INS]
+
+
+Receiving Events in a Service
+
+
+   A service that is a console application can register a console control
+   handler to receive notification when a user logs off. However, there is
+   no event sent when an interactive user logs on. To determine whether an
+   interactive user is logged on, verify that the process specified in the
+   following [18]key is running:
+
+     HKEY_LOCAL_MACHINE\SOFTWARE\
+
+          Microsoft\
+
+               Windows NT\
+
+                    CurrentVersion\
+
+                         Winlogon
+
+   This process is started when an interactive user logs onto a system.
+   Therefore, if this process is running, there is an interactive user
+   logged on. The system broadcasts device change events to all services.
+   These events can be received by a service in a window procedure or in
+   its service control handler. To specify which events your service
+   should receive, use the RegisterDeviceNotification() function.
+
+   Be sure to handle Plug and Play device events as quickly as possible.
+   Otherwise, the system may become unresponsive. If your event handler is
+   to perform an operation that may block execution (such as I/O), it is
+   best to start another thread to perform the operation asynchronously.
+   When a service calls RegisterDeviceNotification(), the service also
+   specifies either a window handle or a service status handle. If a
+   service specifies a window handle, the window procedure receives the
+   notification events. If a service specifies its service status handle,
+   its service control handler receives the notification events. Device
+   notification handles returned by RegisterDeviceNotification() must be
+   closed by calling the UnregisterDeviceNotification() function when they
+   are no longer needed.
+
+
+
+   Further reading and digging:
+
+
+    1. Structure, enum, union and typedef story can be found [19]C/C++
+       struct, enum, union & typedef.
+    2. For Multibytes, Unicode characters and Localization please refer to
+       [20]Locale, wide characters & Unicode (Story) and [21]Windows users
+       & groups programming tutorials (Implementation).
+    3. Windows data types are [22]Windows data types.
+    4. [23]Microsoft Visual C++, online MSDN.
+    5. [24]Check the best selling C / C++ and Windows books at Amazon.com.
+
+
+
+                                 [INS: [INS:
+
+   IFRAME: [25]google_ads_frame
+
+   :INS] :INS]
+
+    |< [26]Dynamic Link Library, DLL 4 | [27]Main | [28]Windows Services
+              Programming 2 >| [29]Site Index | [30]Download |
+     __________________________________________________________________
+
+   [31][comment.png] 2003-2009 © Tenouk. All rights reserved.
+
+   [32]web page hit counter
+
+References
+
+   1. http://www.tenouk.com/ModuleCC2.html
+   2. http://www.tenouk.com/cnwin32tutorials.html
+   3. http://www.tenouk.com/ModuleDD1.html
+   4. http://www.tenouk.com/Sitemap.html
+   5. http://www.tenouk.com/download.html
+   6. file://localhost/home/abaumann/ModuleDD_files/ads.html
+   7. file://localhost/home/abaumann/ModuleDD_files/ads_002.html
+   8. http://www.tenouk.com/visualcpluscompilerinstruction.html
+   9. http://www.tenouk.com/ModuleO.html
+  10. http://www.tenouk.com/ModuleO.html
+  11. http://www.tenouk.com/ModuleO.html
+  12. http://www.tenouk.com/ModuleO.html
+  13. http://www.tenouk.com/ModuleO.html
+  14. file://localhost/home/abaumann/ModuleDD_files/ads_003.html
+  15. file://localhost/home/abaumann/ModuleDD_files/ads_004.html
+  16. http://www.tenouk.com/ModuleO.html
+  17. file://localhost/home/abaumann/ModuleDD_files/ads_005.html
+  18. http://www.tenouk.com/ModuleO.html
+  19. http://www.tenouk.com/Module11.html
+  20. http://www.tenouk.com/ModuleG.html
+  21. http://www.tenouk.com/ModuleM.html
+  22. http://www.tenouk.com/ModuleC.html
+  23. http://msdn.microsoft.com/visualc/
+  24. http://www.tenouk.com/cplusbook.html
+  25. file://localhost/home/abaumann/ModuleDD_files/ads_006.html
+  26. http://www.tenouk.com/ModuleCC2.html
+  27. http://www.tenouk.com/cnwin32tutorials.html
+  28. http://www.tenouk.com/ModuleDD1.html
+  29. http://www.tenouk.com/Sitemap.html
+  30. http://www.tenouk.com/download.html
+  31. http://www.tenouk.com/comment.html
+  32. http://www.statcounter.com/
diff --git a/docs/service/README b/docs/service/README
index 704f704..de62560 100644
--- a/docs/service/README
+++ b/docs/service/README
@@ -12,8 +12,10 @@ The normal foreground mode in the console should also be possible
 and act on events:
 
 Good links:
-- http://www.codeproject.com/KB/winsdk/console_event_handling.aspx: how
-  to handle the events in foreground/console mode
+- console_event_handling.txt: how to handle the events in foreground/
+  console mode
 - the Sphynx searchd.cpp: especially service description, console events
 - POCO: on some design questions
 - Microsoft Knowledge Base: best source as always
+- ModuleDD.txt: good introduction to the history of Windows services
+  and how they work