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
  97                                                 GNUNET_CONVERSATION_Handle *handle,
  98                                                 const struct GNUNET_PeerIdentity *caller);
  99
 100
 101 /**
 102  * Method called whenever a call is rejected
 103  *
 104  * @param cls closure
 105  * @param handle to the conversation session
 106  * @param reason reason given for rejecting the call
 107  * @param peer peer that rejected your call
 108  */
 109 typedef void (GNUNET_CONVERSATION_RejectHandler) (void *cls,
 110                                                   struct GNUNET_CONVERSATION_Handle *handle,
 111                                                   enum GNUNET_CONVERSATION_RejectReason reason,
 112                                                   const struct GNUNET_PeerIdentity *peer);
 113
 114
 115 /**
 116  * Method called whenever a notification is there
 117  *
 118  * @param cls closure
 119  * @param handle to the conversation session
 120  * @param type the type of the notification
 121  * @param peer peer that the notification is about
 122  */
 123 typedef void (GNUNET_CONVERSATION_NotificationHandler) (void *cls,
 124                                                         struct GNUNET_CONVERSATION_Handle *handle,
 125                                                         enum GNUNET_CONVERSATION_NotificationType type,
 126                                                         const struct GNUNET_PeerIdentity *peer);
 127
 128
 129 /**
 130  * Method called whenever a notification for missed calls is there
 131  *
 132  * @param cls closure
 133  * @param handle to the conversation session
 134  * @param missed_calls a list of missed calls
 135  */
 136 typedef void (GNUNET_CONVERSATION_MissedCallHandler) (void *cls,
 137                                                       struct GNUNET_CONVERSATION_Handle *handle,
 138                                                       struct GNUNET_CONVERSATION_MissedCallNotification *missed_calls);
 139
 140
 141 /**
 142  * Connect to the VoIP service
 143  *
 144  * @param cfg configuration
 145  * @param cls NULL
 146  * @param call_handler the callback which is called when a call is incoming
 147  * @param reject_handler the callback which is called when a call is rejected
 148  * @param notification_handler the callback which is called when there is a notification
 149  * @param missed_call_handler the callback which is called when the service notifies the client about missed clients
 150  * @return handle to the connection to the conversation service
 151  */
 152 struct GNUNET_CONVERSATION_Handle *
 153 GNUNET_CONVERSATION_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
 154                              void *cls,
 155                              GNUNET_CONVERSATION_CallHandler call_handler,
 156                              GNUNET_CONVERSATION_RejectHandler reject_handler,
 157                              GNUNET_CONVERSATION_NotificationHandler notification_handler,
 158                              GNUNET_CONVERSATION_MissedCallHandler missed_call_handler);
 159
 160
 161 /**
 162  * Disconnect from the VoIP service
 163  *
 164  * @param handle handle to the VoIP connection
 165  */
 166 void
 167 GNUNET_CONVERSATION_disconnect (struct GNUNET_CONVERSATION_Handle *handle);
 168
 169
 170 /**
 171  * Establish a call
 172  *
 173  * @param handle handle to the VoIP connection
 174  * @param callee the peer (PeerIdentity or GNS name) to call
 175  * @param doGnsLookup 0 = no GNS lookup or 1  = GNS lookup
 176  */
 177 void
 178 GNUNET_CONVERSATION_call (struct GNUNET_CONVERSATION_Handle *handle,
 179                           const char *callee,
 180                           int doGnsLookup);
 181
 182
 183 /**
 184  * Terminate the active call
 185  *
 186  * @param handle handle to the VoIP connection
 187  */
 188 void
 189 GNUNET_CONVERSATION_hangup (struct GNUNET_CONVERSATION_Handle *handle);
 190
 191
 192 /**
 193  * Accept an incoming call
 194  *
 195  * @param handle handle to the VoIP connection
 196  */
 197 void
 198 GNUNET_CONVERSATION_accept (struct GNUNET_CONVERSATION_Handle *handle);
 199
 200
 201 /**
 202  * Reject an incoming call
 203  *
 204  * @param handle handle to the VoIP connection
 205  */
 206 void
 207 GNUNET_CONVERSATION_reject (struct GNUNET_CONVERSATION_Handle *handle);
 208
 209
 210 #if 0                           /* keep Emacsens' auto-indent happy */
 211 {
 212 #endif
 213 #ifdef __cplusplus
 214 }
 215 #endif
 216
 217 #endif