src/include/gnunet_client_lib.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2001-2013 GNUnet e.V.
   4
   5      GNUnet is free software; you can redistribute it and/or modify
   6      it under the terms of the GNU General Public License as published
   7      by the Free Software Foundation; either version 3, or (at your
   8      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      General Public License for more details.
  14
  15      You should have received a copy of the GNU General Public License
  16      along with GNUnet; see the file COPYING.  If not, write to the
  17      Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18      Boston, MA 02110-1301, USA.
  19 */
  20
  21 /**
  22  * @author Christian Grothoff
  23  *
  24  * @file
  25  * Functions related to accessing services
  26
  27  * @defgroup client  Client library
  28  * Generic client-side communication with services
  29  *
  30  * @see [Documentation](https://gnunet.org/ipc)
  31  *
  32  * @{
  33  */
  34
  35 #ifndef GNUNET_CLIENT_LIB_H
  36 #define GNUNET_CLIENT_LIB_H
  37
  38 #ifdef __cplusplus
  39 extern "C"
  40 {
  41 #if 0                           /* keep Emacsens' auto-indent happy */
  42 }
  43 #endif
  44 #endif
  45
  46 #include "gnunet_mq_lib.h"
  47
  48 /**
  49  * Opaque handle for a connection to a service.
  50  */
  51 struct GNUNET_CLIENT_Connection;
  52
  53
  54 /**
  55  * Create a message queue to connect to a GNUnet service.
  56  * If handlers are specfied, receive messages from the connection.
  57  *
  58  * @param connection the client connection
  59  * @param handlers handlers for receiving messages, can be NULL
  60  * @param error_handler error handler
  61  * @param error_handler_cls closure for the @a error_handler
  62  * @return the message queue, NULL on error
  63  */
  64 struct GNUNET_MQ_Handle *
  65 GNUNET_CLIENT_connecT (const struct GNUNET_CONFIGURATION_Handle *cfg,
  66                        const char *service_name,
  67                        const struct GNUNET_MQ_MessageHandler *handlers,
  68                        GNUNET_MQ_ErrorHandler error_handler,
  69                        void *error_handler_cls);
  70
  71
  72 /**
  73  * Create a message queue for a GNUNET_CLIENT_Connection.
  74  * If handlers are specfied, receive messages from the connection.
  75  *
  76  * @param connection the client connection, taken over and freed by the MQ
  77  * @param handlers handlers for receiving messages
  78  * @param error_handler error handler
  79  * @param error_handler_cls closure for the @a error_handler
  80  * @return the message queue
  81  * @deprecated use #GNUNET_CLIENT_connecT
  82  */
  83 struct GNUNET_MQ_Handle *
  84 GNUNET_MQ_queue_for_connection_client (struct GNUNET_CLIENT_Connection *connection,
  85                                        const struct GNUNET_MQ_MessageHandler *handlers,
  86                                        GNUNET_MQ_ErrorHandler error_handler,
  87                                        void *error_handler_cls);
  88
  89
  90 /**
  91  * Get a connection with a service.
  92  *
  93  * @param service_name name of the service
  94  * @param cfg configuration to use
  95  * @return NULL on error (service unknown to configuration)
  96  * @deprecated use #GNUNET_CLIENT_connect2
  97  */
  98 struct GNUNET_CLIENT_Connection *
  99 GNUNET_CLIENT_connect (const char *service_name,
 100                        const struct GNUNET_CONFIGURATION_Handle *cfg);
 101
 102
 103 /**
 104  * Destroy connection with the service.  This will automatically
 105  * cancel any pending "receive" request (however, the handler will
 106  * *NOT* be called, not even with a NULL message).  Any pending
 107  * transmission request will also be cancelled UNLESS the callback for
 108  * the transmission request has already been called, in which case the
 109  * transmission 'finish_pending_write' argument determines whether or
 110  * not the write is guaranteed to complete before the socket is fully
 111  * destroyed (unless, of course, there is an error with the server in
 112  * which case the message may still be lost).
 113  *
 114  * @param client handle to the service connection
 115  * @deprecated
 116  */
 117 void
 118 GNUNET_CLIENT_disconnect (struct GNUNET_CLIENT_Connection *client);
 119
 120
 121 /**
 122  * Type of a function to call when we receive a message
 123  * from the service.
 124  *
 125  * @param cls closure
 126  * @param msg message received, NULL on timeout or fatal error
 127  */
 128 typedef void
 129 (*GNUNET_CLIENT_MessageHandler) (void *cls,
 130                                  const struct GNUNET_MessageHeader *msg);
 131
 132
 133 /**
 134  * Read from the service.
 135  *
 136  * @param client connection to the service
 137  * @param handler function to call with the message
 138  * @param handler_cls closure for @a handler
 139  * @param timeout how long to wait until timing out
 140  * @deprecated
 141  */
 142 void
 143 GNUNET_CLIENT_receive (struct GNUNET_CLIENT_Connection *client,
 144                        GNUNET_CLIENT_MessageHandler handler,
 145                        void *handler_cls,
 146                        struct GNUNET_TIME_Relative timeout);
 147
 148
 149 /**
 150  * Transmit handle for client connections.
 151  */
 152 struct GNUNET_CLIENT_TransmitHandle;
 153
 154
 155 /**
 156  * Ask the client to call us once the specified number of bytes
 157  * are free in the transmission buffer.  Will never call the @a notify
 158  * callback in this task, but always first go into the scheduler.
 159  *
 160  * @param client connection to the service
 161  * @param size number of bytes to send
 162  * @param timeout after how long should we give up (and call
 163  *        @a notify with buf NULL and size 0)?
 164  * @param auto_retry if the connection to the service dies, should we
 165  *        automatically re-connect and retry (within the timeout period)
 166  *        or should we immediately fail in this case?  Pass #GNUNET_YES
 167  *        if the caller does not care about temporary connection errors,
 168  *        for example because the protocol is stateless
 169  * @param notify function to call
 170  * @param notify_cls closure for @a notify
 171  * @return NULL if someone else is already waiting to be notified
 172  *         non-NULL if the notify callback was queued (can be used to cancel
 173  *         using #GNUNET_CONNECTION_notify_transmit_ready_cancel)
 174  * @deprecated
 175  */
 176 struct GNUNET_CLIENT_TransmitHandle *
 177 GNUNET_CLIENT_notify_transmit_ready (struct GNUNET_CLIENT_Connection *client,
 178                                      size_t size,
 179                                      struct GNUNET_TIME_Relative timeout,
 180                                      int auto_retry,
 181                                      GNUNET_CONNECTION_TransmitReadyNotify notify,
 182                                      void *notify_cls);
 183
 184
 185 /**
 186  * Cancel a request for notification.
 187  *
 188  * @param th handle from the original request.
 189  * @deprecated
 190  */
 191 void
 192 GNUNET_CLIENT_notify_transmit_ready_cancel (struct GNUNET_CLIENT_TransmitHandle *th);
 193
 194
 195 /**
 196  * Convenience API that combines sending a request
 197  * to the service and waiting for a response.
 198  * If either operation times out, the callback
 199  * will be called with a "NULL" response (in which
 200  * case the connection should probably be destroyed).
 201  *
 202  * @param client connection to use
 203  * @param hdr message to transmit
 204  * @param timeout when to give up (for both transmission
 205  *         and for waiting for a response)
 206  * @param auto_retry if the connection to the service dies, should we
 207  *        automatically re-connect and retry (within the timeout period)
 208  *        or should we immediately fail in this case?  Pass #GNUNET_YES
 209  *        if the caller does not care about temporary connection errors,
 210  *        for example because the protocol is stateless
 211  * @param rn function to call with the response
 212  * @param rn_cls closure for @a rn
 213  * @return #GNUNET_OK on success, #GNUNET_SYSERR if a request
 214  *         is already pending
 215  * @deprecated
 216  */
 217 int
 218 GNUNET_CLIENT_transmit_and_get_response (struct GNUNET_CLIENT_Connection *client,
 219                                          const struct GNUNET_MessageHeader *hdr,
 220                                          struct GNUNET_TIME_Relative timeout,
 221                                          int auto_retry,
 222                                          GNUNET_CLIENT_MessageHandler rn,
 223                                          void *rn_cls);
 224
 225
 226 /**
 227  * Handle for a test to check if a service is running.
 228  */
 229 struct GNUNET_CLIENT_TestHandle;
 230
 231 /**
 232  * Function called with the result on the service test.
 233  *
 234  * @param cls closure
 235  * @param result #GNUNET_YES if the service is running,
 236  *               #GNUNET_NO if the service is not running
 237  *               #GNUNET_SYSERR if the configuration is invalid
 238  */
 239 typedef void
 240 (*GNUNET_CLIENT_TestResultCallback)(void *cls,
 241                                     int result);
 242
 243
 244 /**
 245  * Test if the service is running.  If we are given a UNIXPATH or a
 246  * local address, we do this NOT by trying to connect to the service,
 247  * but by trying to BIND to the same port.  If the BIND fails, we know
 248  * the service is running.
 249  *
 250  * @param service name of the service to wait for
 251  * @param cfg configuration to use
 252  * @param timeout how long to wait at most
 253  * @param cb function to call with the result
 254  * @param cb_cls closure for @a cb
 255  * @return handle to cancel the test
 256  * @deprecated
 257  */
 258 struct GNUNET_CLIENT_TestHandle *
 259 GNUNET_CLIENT_service_test (const char *service,
 260                             const struct GNUNET_CONFIGURATION_Handle *cfg,
 261                             struct GNUNET_TIME_Relative timeout,
 262                             GNUNET_CLIENT_TestResultCallback cb, void *cb_cls);
 263
 264
 265 /**
 266  * Abort testing for service.
 267  *
 268  * @param th test handle
 269  * @deprecated
 270  */
 271 void
 272 GNUNET_CLIENT_service_test_cancel (struct GNUNET_CLIENT_TestHandle *th);
 273
 274
 275 #if 0                           /* keep Emacsens' auto-indent happy */
 276 {
 277 #endif
 278 #ifdef __cplusplus
 279 }
 280 #endif
 281
 282 /* ifndef GNUNET_CLIENT_LIB_H */
 283 #endif
 284
 285 /** @} */ /* end of group client */
 286
 287 /* end of gnunet_client_lib.h */