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