X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_helper_lib.h;h=60b3ff6816f7c355f8e7cbe36f181c9b302355a7;hb=a67bd3630046d3a52195a13cbd4b4631c283d68d;hp=12a4d3fe18dd14cd2cf16ae84cd87a6647f79a86;hpb=89daff335a418fb67ce8ea4d3e1e128e96d19877;p=oweals%2Fgnunet.git

diff --git a/src/include/gnunet_helper_lib.h b/src/include/gnunet_helper_lib.h
index 12a4d3fe1..60b3ff681 100644
--- a/src/include/gnunet_helper_lib.h
+++ b/src/include/gnunet_helper_lib.h
@@ -1,6 +1,6 @@
 /*
      This file is part of GNUnet.
-     (C) 2011, 2012 Christian Grothoff
+     Copyright (C) 2011, 2012 Christian Grothoff
 
      GNUnet is free software; you can redistribute it and/or modify
      it under the terms of the GNU General Public License as published
@@ -14,22 +14,32 @@
 
      You should have received a copy of the GNU General Public License
      along with GNUnet; see the file COPYING.  If not, write to the
-     Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-     Boston, MA 02111-1307, USA.
+     Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+     Boston, MA 02110-1301, USA.
 */
 
 /**
- * @file include/gnunet_helper_lib.h
- * @brief API for dealing with (SUID) helper processes that communicate via GNUNET_MessageHeaders on stdin/stdout
  * @author Philipp Toelke
  * @author Christian Grothoff
+ *
+ * @file
+ * API for dealing with SUID helper processes
+ *
+ * @defgroup helper  Helper library
+ * Dealing with SUID helper processes.
+ *
+ * Provides an API for dealing with (SUID) helper processes
+ * that communicate via GNUNET_MessageHeaders on STDIN/STDOUT.
+ *
+ * @{
  */
 
 #ifndef GNUNET_HELPER_LIB_H
 #define GNUNET_HELPER_LIB_H
 
 #include "gnunet_scheduler_lib.h"
-#include "gnunet_server_lib.h"
+#include "gnunet_mst_lib.h"
+
 
 /**
  * The handle to a helper process.
@@ -43,7 +53,8 @@ struct GNUNET_HELPER_Handle;
  *
  * @param cls the closure from GNUNET_HELPER_start()
  */
-typedef void (*GNUNET_HELPER_ExceptionCallback) (void *cls);
+typedef void
+(*GNUNET_HELPER_ExceptionCallback) (void *cls);
 
 
 /**
@@ -51,6 +62,7 @@ typedef void (*GNUNET_HELPER_ExceptionCallback) (void *cls);
  * restarted when it dies except when it is stopped using GNUNET_HELPER_stop()
  * or when the exp_cb callback is not NULL.
  *
+ * @param with_control_pipe does the helper support the use of a control pipe for signalling?
  * @param binary_name name of the binary to run
  * @param binary_argv NULL-terminated list of arguments to give when starting the binary (this
  *                    argument must not be modified by the client for
@@ -62,29 +74,67 @@ typedef void (*GNUNET_HELPER_ExceptionCallback) (void *cls);
  * @return the new Handle, NULL on error
  */
 struct GNUNET_HELPER_Handle *
-GNUNET_HELPER_start (const char *binary_name,
+GNUNET_HELPER_start (int with_control_pipe,
+		     const char *binary_name,
 		     char *const binary_argv[],
-		     GNUNET_SERVER_MessageTokenizerCallback cb,
+		     GNUNET_MessageTokenizerCallback cb,
 		     GNUNET_HELPER_ExceptionCallback exp_cb,
 		     void *cb_cls);
 
 
 /**
- * Kills the helper, closes the pipe and frees the handle
+ * Sends termination signal to the helper process.  The helper process is not
+ * reaped; call GNUNET_HELPER_wait() for reaping the dead helper process.
+ *
+ * @param h the helper handle
+ * @param soft_kill if #GNUNET_YES, signals termination by closing the helper's
+ *          stdin; #GNUNET_NO to signal termination by sending SIGTERM to helper
+ * @return #GNUNET_OK on success; #GNUNET_SYSERR on error
+ */
+int
+GNUNET_HELPER_kill (struct GNUNET_HELPER_Handle *h, int soft_kill);
+
+
+/**
+ * Reap the helper process.  This call is blocking (!).  The helper process
+ * should either be sent a termination signal before or should be dead before
+ * calling this function
+ *
+ * @param h the helper handle
+ * @return #GNUNET_OK on success; #GNUNET_SYSERR on error
+ */
+int
+GNUNET_HELPER_wait (struct GNUNET_HELPER_Handle *h);
+
+
+/**
+ * Free's the resources occupied by the helper handle
+ *
+ * @param h the helper handle to free
+ */
+void
+GNUNET_HELPER_destroy (struct GNUNET_HELPER_Handle *h);
+
+
+/**
+ * Kills the helper, closes the pipe, frees the handle and calls wait() on the
+ * helper process
  *
  * @param h handle to helper to stop
+ * @param soft_kill if #GNUNET_YES, signals termination by closing the helper's
+ *          stdin; #GNUNET_NO to signal termination by sending SIGTERM to helper
  */
 void
-GNUNET_HELPER_stop (struct GNUNET_HELPER_Handle *h);
+GNUNET_HELPER_stop (struct GNUNET_HELPER_Handle *h, int soft_kill);
 
 
 /**
  * Continuation function.
- * 
+ *
  * @param cls closure
- * @param result GNUNET_OK on success,
- *               GNUNET_NO if helper process died
- *               GNUNET_SYSERR during GNUNET_HELPER_stop
+ * @param result #GNUNET_OK on success,
+ *               #GNUNET_NO if helper process died
+ *               #GNUNET_SYSERR during GNUNET_HELPER_destroy
  */
 typedef void (*GNUNET_HELPER_Continuation)(void *cls,
 					   int result);
@@ -102,14 +152,15 @@ struct GNUNET_HELPER_SendHandle;
  * @param h helper to send message to
  * @param msg message to send
  * @param can_drop can the message be dropped if there is already one in the queue?
- * @param cont continuation to run once the message is out
- * @param cont_cls closure for 'cont'
- * @return NULL if the message was dropped, 
- *         otherwise handle to cancel *cont* (actual transmission may
+ * @param cont continuation to run once the message is out (#GNUNET_OK on succees, #GNUNET_NO
+ *             if the helper process died, #GNUNET_SYSERR during #GNUNET_HELPER_destroy).
+ * @param cont_cls closure for @a cont
+ * @return NULL if the message was dropped,
+ *         otherwise handle to cancel @a cont (actual transmission may
  *         not be abortable)
  */
 struct GNUNET_HELPER_SendHandle *
-GNUNET_HELPER_send (struct GNUNET_HELPER_Handle *h, 
+GNUNET_HELPER_send (struct GNUNET_HELPER_Handle *h,
 		    const struct GNUNET_MessageHeader *msg,
 		    int can_drop,
 		    GNUNET_HELPER_Continuation cont,
@@ -117,13 +168,16 @@ GNUNET_HELPER_send (struct GNUNET_HELPER_Handle *h,
 
 
 /**
- * Cancel a 'send' operation.  If possible, transmitting the
- * message is also aborted, but at least 'cont' won't be
- * called.
+ * Cancel a #GNUNET_HELPER_send operation.  If possible, transmitting
+ * the message is also aborted, but at least 'cont' won't be called.
  *
  * @param sh operation to cancel
  */
 void
 GNUNET_HELPER_send_cancel (struct GNUNET_HELPER_SendHandle *sh);
 
-#endif /* end of include guard: GNUNET_HELPER_LIB_H */
+
+#endif
+/* end of include guard: GNUNET_HELPER_LIB_H */
+
+/** @} */  /* end of group */