src/include/gnunet_helper_lib.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2011, 2012 Christian Grothoff
   4
   5      GNUnet is free software: you can redistribute it and/or modify it
   6      under the terms of the GNU Affero General Public License as published
   7      by the Free Software Foundation, either version 3 of the License,
   8      or (at your option) any later version.
   9
  10      GNUnet is distributed in the hope that it will be useful, but
  11      WITHOUT ANY WARRANTY; without even the implied warranty of
  12      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13      Affero General Public License for more details.
  14
  15      You should have received a copy of the GNU Affero General Public License
  16      along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17 */
  18
  19 /**
  20  * @author Philipp Toelke
  21  * @author Christian Grothoff
  22  *
  23  * @file
  24  * API for dealing with SUID helper processes
  25  *
  26  * @defgroup helper  Helper library
  27  * Dealing with SUID helper processes.
  28  *
  29  * Provides an API for dealing with (SUID) helper processes
  30  * that communicate via GNUNET_MessageHeaders on STDIN/STDOUT.
  31  *
  32  * @{
  33  */
  34
  35 #ifndef GNUNET_HELPER_LIB_H
  36 #define GNUNET_HELPER_LIB_H
  37
  38 #include "gnunet_scheduler_lib.h"
  39 #include "gnunet_mst_lib.h"
  40
  41
  42 /**
  43  * The handle to a helper process.
  44  */
  45 struct GNUNET_HELPER_Handle;
  46
  47
  48 /**
  49  * Callback that will be called when the helper process dies. This is not called
  50  * when the helper process is stoped using GNUNET_HELPER_stop()
  51  *
  52  * @param cls the closure from GNUNET_HELPER_start()
  53  */
  54 typedef void
  55 (*GNUNET_HELPER_ExceptionCallback) (void *cls);
  56
  57
  58 /**
  59  * Starts a helper and begins reading from it. The helper process is
  60  * restarted when it dies except when it is stopped using GNUNET_HELPER_stop()
  61  * or when the exp_cb callback is not NULL.
  62  *
  63  * @param with_control_pipe does the helper support the use of a control pipe for signalling?
  64  * @param binary_name name of the binary to run
  65  * @param binary_argv NULL-terminated list of arguments to give when starting the binary (this
  66  *                    argument must not be modified by the client for
  67  *                     the lifetime of the helper handle)
  68  * @param cb function to call if we get messages from the helper
  69  * @param exp_cb the exception callback to call. Set this to NULL if the helper
  70  *          process has to be restarted automatically when it dies/crashes
  71  * @param cb_cls closure for the above callbacks
  72  * @return the new Handle, NULL on error
  73  */
  74 struct GNUNET_HELPER_Handle *
  75 GNUNET_HELPER_start (int with_control_pipe,
  76                      const char *binary_name,
  77                      char *const binary_argv[],
  78                      GNUNET_MessageTokenizerCallback cb,
  79                      GNUNET_HELPER_ExceptionCallback exp_cb,
  80                      void *cb_cls);
  81
  82
  83 /**
  84  * Sends termination signal to the helper process.  The helper process is not
  85  * reaped; call GNUNET_HELPER_wait() for reaping the dead helper process.
  86  *
  87  * @param h the helper handle
  88  * @param soft_kill if #GNUNET_YES, signals termination by closing the helper's
  89  *          stdin; #GNUNET_NO to signal termination by sending SIGTERM to helper
  90  * @return #GNUNET_OK on success; #GNUNET_SYSERR on error
  91  */
  92 int
  93 GNUNET_HELPER_kill (struct GNUNET_HELPER_Handle *h, int soft_kill);
  94
  95
  96 /**
  97  * Reap the helper process.  This call is blocking (!).  The helper process
  98  * should either be sent a termination signal before or should be dead before
  99  * calling this function
 100  *
 101  * @param h the helper handle
 102  * @return #GNUNET_OK on success; #GNUNET_SYSERR on error
 103  */
 104 int
 105 GNUNET_HELPER_wait (struct GNUNET_HELPER_Handle *h);
 106
 107
 108 /**
 109  * Free's the resources occupied by the helper handle
 110  *
 111  * @param h the helper handle to free
 112  */
 113 void
 114 GNUNET_HELPER_destroy (struct GNUNET_HELPER_Handle *h);
 115
 116
 117 /**
 118  * Kills the helper, closes the pipe, frees the handle and calls wait() on the
 119  * helper process
 120  *
 121  * @param h handle to helper to stop
 122  * @param soft_kill if #GNUNET_YES, signals termination by closing the helper's
 123  *          stdin; #GNUNET_NO to signal termination by sending SIGTERM to helper
 124  */
 125 void
 126 GNUNET_HELPER_stop (struct GNUNET_HELPER_Handle *h, int soft_kill);
 127
 128
 129 /**
 130  * Continuation function.
 131  *
 132  * @param cls closure
 133  * @param result #GNUNET_OK on success,
 134  *               #GNUNET_NO if helper process died
 135  *               #GNUNET_SYSERR during GNUNET_HELPER_destroy
 136  */
 137 typedef void (*GNUNET_HELPER_Continuation)(void *cls,
 138                                            int result);
 139
 140
 141 /**
 142  * Handle to cancel 'send'
 143  */
 144 struct GNUNET_HELPER_SendHandle;
 145
 146
 147 /**
 148  * Send an message to the helper.
 149  *
 150  * @param h helper to send message to
 151  * @param msg message to send
 152  * @param can_drop can the message be dropped if there is already one in the queue?
 153  * @param cont continuation to run once the message is out (#GNUNET_OK on succees, #GNUNET_NO
 154  *             if the helper process died, #GNUNET_SYSERR during #GNUNET_HELPER_destroy).
 155  * @param cont_cls closure for @a cont
 156  * @return NULL if the message was dropped,
 157  *         otherwise handle to cancel @a cont (actual transmission may
 158  *         not be abortable)
 159  */
 160 struct GNUNET_HELPER_SendHandle *
 161 GNUNET_HELPER_send (struct GNUNET_HELPER_Handle *h,
 162                     const struct GNUNET_MessageHeader *msg,
 163                     int can_drop,
 164                     GNUNET_HELPER_Continuation cont,
 165                     void *cont_cls);
 166
 167
 168 /**
 169  * Cancel a #GNUNET_HELPER_send operation.  If possible, transmitting
 170  * the message is also aborted, but at least 'cont' won't be called.
 171  *
 172  * @param sh operation to cancel
 173  */
 174 void
 175 GNUNET_HELPER_send_cancel (struct GNUNET_HELPER_SendHandle *sh);
 176
 177
 178 #endif
 179 /* end of include guard: GNUNET_HELPER_LIB_H */
 180
 181 /** @} */  /* end of group */