From: Adam Dickmeiss <adam@indexdata.dk>
Date: Fri, 30 May 2008 12:44:24 +0000 (+0200)
Subject: Document Windows Service Control
X-Git-Tag: v3.0.30~25
X-Git-Url: http://sru.miketaylor.org.uk/?a=commitdiff_plain;h=50cffeb44b5c2b644a76359142063660b6b80f7a;p=yaz-moved-to-github.git

Document Windows Service Control
---

diff --git a/include/yaz/sc.h b/include/yaz/sc.h
index b0c1789..318f08a 100644
--- a/include/yaz/sc.h
+++ b/include/yaz/sc.h
@@ -25,26 +25,55 @@
  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
-/**
- * \file sc.h
- * \brief Header for Windows Service Control utility
+/** \file sc.h
+    \brief Header for Windows Service Control utility
+   
+    This is a simple wrapper for the Windows Service Control system. It
+    also operates on Unix in which case the user supplied main function
+    (sc_main) is is called immediately. See sc_test.c for an example.
  */
 
 #include <yaz/yconfig.h>
 
 YAZ_BEGIN_CDECL
 
+/** service control handle (opaque type) */
 typedef struct sc_s *yaz_sc_t;
 
+/** \brief creates service handle
+    \param service_name Service Name
+    \param display_name Display Name
+    \return service control handle
+
+    This function does not activate the service. Only creates handle.
+*/
 YAZ_EXPORT yaz_sc_t yaz_sc_create(const char *service_name,
                                   const char *display_name);
 
-YAZ_EXPORT void yaz_sc_running(yaz_sc_t s);
+/** \brief registers service controlled program
+    \param s service control handle
+    \param argc argc as given from main
+    \param argv argv as given from main
+    \param sc_main service main function
+    \param sc_stop service stop function
+    \return sc_main return value
 
+    sc_main is the main program of the application. It should initialize
+    the application.. Function yaz_sc_running MUST be called before
+    the application operates (after initialization)
+*/
 YAZ_EXPORT int yaz_sc_program(yaz_sc_t s, int argc, char **argv,
 	 		      int (*sc_main)(yaz_sc_t s, int argc, char **argv),
 			      void (*sc_stop)(yaz_sc_t s));
 
+/** \brief signals that sc_main applicatio starts running
+    \param s service control handle
+*/
+YAZ_EXPORT void yaz_sc_running(yaz_sc_t s);
+
+/** \brief frees service control handle
+    \param s service control handle
+*/    
 YAZ_EXPORT void yaz_sc_destroy(yaz_sc_t *s);
 
 YAZ_END_CDECL
diff --git a/src/sc_test.c b/src/sc_test.c
index 05810fc..3bab6b2 100644
--- a/src/sc_test.c
+++ b/src/sc_test.c
@@ -20,12 +20,20 @@
 #include <yaz/log.h>
 #include <yaz/sc.h>
 
+/** \brief handle that is used to stop that service should be stopped */
 HANDLE    default_stop_event = NULL;
+
+/** \brief stop handler which just signals "stop" */
 static void default_sc_stop(yaz_sc_t s)
 {
     SetEvent(default_stop_event);
 }
 
+/** \brief service control main
+    This does not read argc and argv.
+    Real applications would typically do that. It is very important that
+    yaz_sc_running is called before the application starts to operate .
+*/
 static int default_sc_main(yaz_sc_t s, int argc, char **argv)
 {
     default_stop_event = CreateEvent(
@@ -43,7 +51,7 @@ static int default_sc_main(yaz_sc_t s, int argc, char **argv)
     return 0;
 }
 
-
+/** \brief the system main function */
 int main(int argc, char **argv)
 {
     yaz_sc_t s = yaz_sc_create("yaz_sc_test", "YAZ Service Control Test");