From 0ea877ed9a54a35539c8fbd1a742073e13f2988e Mon Sep 17 00:00:00 2001
From: Richard Quadling <rquadling@php.net>
Date: Mon, 8 Nov 2010 16:57:13 +0000
Subject: [PATCH] Don't automatically assume a service is ready to run. Allow a
 script to report back WIN32_SERVICE_START_PENDING before
 WIN32_SERVICE_RUNNING.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@305205 c90b9560-bf6c-de11-be94-00142212c4b1
---
 .../win32-start-service-ctrl-dispatcher.xml   | 22 ++++++++++++++-----
 1 file changed, 17 insertions(+), 5 deletions(-)

diff --git a/reference/win32service/functions/win32-start-service-ctrl-dispatcher.xml b/reference/win32service/functions/win32-start-service-ctrl-dispatcher.xml
index 86ce5339e3..ff43962646 100644
--- a/reference/win32service/functions/win32-start-service-ctrl-dispatcher.xml
+++ b/reference/win32service/functions/win32-start-service-ctrl-dispatcher.xml
@@ -21,11 +21,16 @@
    manager.
   </para>
   <para>
-   Once started, the service process should continue to check-in with the
-   service control manager so that it can determine if it should terminate.
-   This is achieved by periodically calling
-   <function>win32_get_last_control_message</function> and handling the return
-   code appropriately.
+   Once started, the service process should do 2 things. The first is to tell
+   the Service Control Manager that the service is running. This is achieved
+   by calling <function>win32_set_service_status</function> with the
+   <constant>WIN32_SERVICE_RUNNING<constant> constant. If you need to perform
+   some lengthy process before the service is actually running, then you can
+   use the <constant>WIN32_SERVICE_START_PENDING</constant> constant. The
+   second is to continue to check-in with the service control manager so that
+   it can determine if it should terminate. This is achieved by periodically
+   calling <function>win32_get_last_control_message</function> and handling the
+   return code appropriately.
   </para>
 
  </refsect1>
@@ -68,6 +73,12 @@ if (!win32_start_service_ctrl_dispatcher('dummyphp')) {
   die("I'm probably not running under the service control manager");
 }
 
+win32_set_service_status(WIN32_SERVICE_START_PENDING);
+
+// Some lengthy process to get this service up and running.
+
+win32_set_service_status(WIN32_SERVICE_RUNNING);
+
 while (WIN32_SERVICE_CONTROL_STOP != win32_get_last_control_message()) {
   # do some work here, trying not to take more than around 30 seconds
   # before coming back into the loop again
@@ -83,6 +94,7 @@ while (WIN32_SERVICE_CONTROL_STOP != win32_get_last_control_message()) {
   &reftitle.seealso;
   <para>
    <simplelist>
+    <member><function>win32_set_service_status</function></member>
     <member><function>win32_get_last_control_message</function></member>
     <member><link linkend="win32service.constants.errors">Win32 Error Codes</link></member>
    </simplelist>