src/include/gnunet_conversation_service.h

   1 /*
   2   This file is part of GNUnet
   3   (C) 2013 Christian Grothoff (and other contributing authors)
   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., 59 Temple Place - Suite 330,
  18   Boston, MA 02111-1307, USA.
  19  */
  20
  21 /**
  22  * @file include/gnunet_conversation_service.h
  23  * @brief API to the conversation service
  24  * @author Simon Dieterle
  25  * @author Andreas Fuchs
  26  */
  27 #ifndef GNUNET_CONVERSATION_SERVICE_H
  28 #define GNUNET_CONVERSATION_SERVICE_H
  29
  30 #ifdef __cplusplus
  31 extern "C"
  32 {
  33 #if 0                           /* keep Emacsens' auto-indent happy */
  34 }
  35 #endif
  36 #endif
  37
  38 /**
  39  * Version of the conversation API.
  40  */
  41 #define GNUNET_CONVERSATION_VERSION 0x00000001
  42
  43
  44 enum GNUNET_CONVERSATION_RejectReason
  45 {
  46   GNUNET_CONVERSATION_REJECT_REASON_GENERIC = 0,
  47   GNUNET_CONVERSATION_REJECT_REASON_NOT_AVAILABLE,
  48   GNUNET_CONVERSATION_REJECT_REASON_NO_CLIENT,
  49   GNUNET_CONVERSATION_REJECT_REASON_ACTIVE_CALL,
  50   GNUNET_CONVERSATION_REJECT_REASON_NOT_WANTED,
  51   GNUNET_CONVERSATION_REJECT_REASON_NO_ANSWER
  52
  53 };
  54
  55
  56 enum GNUNET_CONVERSATION_NotificationType
  57 {
  58   GNUNET_CONVERSATION_NT_SERVICE_BLOCKED = 0,
  59   GNUNET_CONVERSATION_NT_NO_PEER,
  60   GNUNET_CONVERSATION_NT_NO_ANSWER,
  61   GNUNET_CONVERSATION_NT_AVAILABLE_AGAIN,
  62   GNUNET_CONVERSATION_NT_CALL_ACCEPTED,
  63   GNUNET_CONVERSATION_NT_CALL_TERMINATED
  64 };
  65
  66
  67 /**
  68  *
  69  */
  70 struct GNUNET_CONVERSATION_MissedCall
  71 {
  72   struct GNUNET_PeerIdentity peer;
  73   struct GNUNET_TIME_Absolute time;
  74 };
  75
  76
  77 struct GNUNET_CONVERSATION_MissedCallNotification
  78 {
  79   int number;
  80   struct GNUNET_CONVERSATION_MissedCall *calls;
  81 };
  82
  83 struct GNUNET_CONVERSATION_CallInformation;
  84
  85 struct GNUNET_CONVERSATION_Handle;
  86
  87
  88 /**
  89  * Method called whenever a call is incoming
  90  *
  91  * @param cls closure
  92  * @param handle to the conversation session
  93  * @param caller peer that calls you
  94  */
  95 typedef void (GNUNET_CONVERSATION_CallHandler) (void *cls,
  96                                                 struct GNUNET_CONVERSATION_Handle *handle,
  97                                                 const struct GNUNET_PeerIdentity *caller);
  98
  99
 100 /**
 101  * Method called whenever a call is rejected
 102  *
 103  * @param cls closure
 104  * @param handle to the conversation session
 105  * @param reason reason given for rejecting the call
 106  * @param peer peer that rejected your call
 107  */
 108 typedef void (GNUNET_CONVERSATION_RejectHandler) (void *cls,
 109                                                   struct GNUNET_CONVERSATION_Handle *handle,
 110                                                   enum GNUNET_CONVERSATION_RejectReason reason,
 111                                                   const struct GNUNET_PeerIdentity *peer);
 112
 113
 114 /**
 115  * Method called whenever a notification is there
 116  *
 117  * @param cls closure
 118  * @param handle to the conversation session
 119  * @param type the type of the notification
 120  * @param peer peer that the notification is about
 121  */
 122 typedef void (GNUNET_CONVERSATION_NotificationHandler) (void *cls,
 123                                                         struct GNUNET_CONVERSATION_Handle *handle,
 124                                                         enum GNUNET_CONVERSATION_NotificationType type,
 125                                                         const struct GNUNET_PeerIdentity *peer);
 126
 127
 128 /**
 129  * Method called whenever a notification for missed calls is there
 130  *
 131  * @param cls closure
 132  * @param handle to the conversation session
 133  * @param missed_calls a list of missed calls
 134  */
 135 typedef void (GNUNET_CONVERSATION_MissedCallHandler) (void *cls,
 136                                                       struct GNUNET_CONVERSATION_Handle *handle,
 137                                                       struct GNUNET_CONVERSATION_MissedCallNotification *missed_calls);
 138
 139
 140 /**
 141  * Connect to the VoIP service
 142  *
 143  * @param cfg configuration
 144  * @param cls NULL
 145  * @param call_handler the callback which is called when a call is incoming
 146  * @param reject_handler the callback which is called when a call is rejected
 147  * @param notification_handler the callback which is called when there is a notification
 148  * @param missed_call_handler the callback which is called when the service notifies the client about missed clients
 149  * @return handle to the connection to the conversation service
 150  */
 151 struct GNUNET_CONVERSATION_Handle *
 152 GNUNET_CONVERSATION_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
 153                              void *cls,
 154                              GNUNET_CONVERSATION_CallHandler call_handler,
 155                              GNUNET_CONVERSATION_RejectHandler reject_handler,
 156                              GNUNET_CONVERSATION_NotificationHandler notification_handler,
 157                              GNUNET_CONVERSATION_MissedCallHandler missed_call_handler);
 158
 159
 160 /**
 161  * Disconnect from the VoIP service
 162  *
 163  * @param handle handle to the VoIP connection
 164  */
 165 void
 166 GNUNET_CONVERSATION_disconnect (struct GNUNET_CONVERSATION_Handle *handle);
 167
 168
 169 /**
 170  * Establish a call
 171  *
 172  * @param handle handle to the VoIP connection
 173  * @param callee the peer (PeerIdentity or GNS name) to call
 174  * @param doGnsLookup 0 = no GNS lookup or 1  = GNS lookup
 175  */
 176 void
 177 GNUNET_CONVERSATION_call (struct GNUNET_CONVERSATION_Handle *handle,
 178                           const char *callee,
 179                           int doGnsLookup);
 180
 181
 182 /**
 183  * Terminate the active call
 184  *
 185  * @param handle handle to the VoIP connection
 186  */
 187 void
 188 GNUNET_CONVERSATION_hangup (struct GNUNET_CONVERSATION_Handle *handle);
 189
 190
 191 /**
 192  * Accept an incoming call
 193  *
 194  * @param handle handle to the VoIP connection
 195  */
 196 void
 197 GNUNET_CONVERSATION_accept (struct GNUNET_CONVERSATION_Handle *handle);
 198
 199
 200 /**
 201  * Reject an incoming call
 202  *
 203  * @param handle handle to the VoIP connection
 204  */
 205 void
 206 GNUNET_CONVERSATION_reject (struct GNUNET_CONVERSATION_Handle *handle);
 207
 208
 209 #if 0                           /* keep Emacsens' auto-indent happy */
 210 {
 211 #endif
 212 #ifdef __cplusplus
 213 }
 214 #endif
 215
 216 #endif