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  * @author Christian Grothoff
  27  */
  28 #ifndef GNUNET_CONVERSATION_SERVICE_H
  29 #define GNUNET_CONVERSATION_SERVICE_H
  30
  31 #ifdef __cplusplus
  32 extern "C"
  33 {
  34 #if 0                           /* keep Emacsens' auto-indent happy */
  35 }
  36 #endif
  37 #endif
  38
  39 #include "gnunet_util_lib.h"
  40
  41 /**
  42  * Version of the conversation API.
  43  */
  44 #define GNUNET_CONVERSATION_VERSION 0x00000001
  45
  46
  47 enum GNUNET_CONVERSATION_RejectReason
  48 {
  49   GNUNET_CONVERSATION_REJECT_REASON_GENERIC = 0,
  50   GNUNET_CONVERSATION_REJECT_REASON_NOT_AVAILABLE,
  51   GNUNET_CONVERSATION_REJECT_REASON_NO_CLIENT,
  52   GNUNET_CONVERSATION_REJECT_REASON_ACTIVE_CALL,
  53   GNUNET_CONVERSATION_REJECT_REASON_NOT_WANTED,
  54   GNUNET_CONVERSATION_REJECT_REASON_NO_ANSWER
  55
  56 };
  57
  58
  59 enum GNUNET_CONVERSATION_NotificationType
  60 {
  61   GNUNET_CONVERSATION_NT_SERVICE_BLOCKED = 0,
  62   GNUNET_CONVERSATION_NT_NO_PEER,
  63   GNUNET_CONVERSATION_NT_NO_ANSWER,
  64   GNUNET_CONVERSATION_NT_AVAILABLE_AGAIN,
  65   GNUNET_CONVERSATION_NT_CALL_ACCEPTED,
  66   GNUNET_CONVERSATION_NT_CALL_TERMINATED
  67 };
  68
  69
  70 /**
  71  *
  72  */
  73 struct GNUNET_CONVERSATION_MissedCall
  74 {
  75   struct GNUNET_PeerIdentity peer;
  76   struct GNUNET_TIME_Absolute time;
  77 };
  78
  79
  80 struct GNUNET_CONVERSATION_MissedCallNotification
  81 {
  82   int number;
  83   struct GNUNET_CONVERSATION_MissedCall *calls;
  84 };
  85
  86 struct GNUNET_CONVERSATION_CallInformation;
  87
  88 struct GNUNET_CONVERSATION_Handle;
  89
  90
  91 /**
  92  * Method called whenever a call is incoming
  93  *
  94  * @param cls closure
  95  * @param handle to the conversation session
  96  * @param caller peer that calls you
  97  */
  98 typedef void (GNUNET_CONVERSATION_CallHandler) (void *cls,
  99                                                 struct GNUNET_CONVERSATION_Handle *handle,
 100                                                 const struct GNUNET_PeerIdentity *caller);
 101
 102
 103 /**
 104  * Method called whenever a call is rejected
 105  *
 106  * @param cls closure
 107  * @param handle to the conversation session
 108  * @param reason reason given for rejecting the call
 109  * @param peer peer that rejected your call
 110  */
 111 typedef void (GNUNET_CONVERSATION_RejectHandler) (void *cls,
 112                                                   struct GNUNET_CONVERSATION_Handle *handle,
 113                                                   enum GNUNET_CONVERSATION_RejectReason reason,
 114                                                   const struct GNUNET_PeerIdentity *peer);
 115
 116
 117 /**
 118  * Method called whenever a notification is there
 119  *
 120  * @param cls closure
 121  * @param handle to the conversation session
 122  * @param type the type of the notification
 123  * @param peer peer that the notification is about
 124  */
 125 typedef void (GNUNET_CONVERSATION_NotificationHandler) (void *cls,
 126                                                         struct GNUNET_CONVERSATION_Handle *handle,
 127                                                         enum GNUNET_CONVERSATION_NotificationType type,
 128                                                         const struct GNUNET_PeerIdentity *peer);
 129
 130
 131 /**
 132  * Method called whenever a notification for missed calls is there
 133  *
 134  * @param cls closure
 135  * @param handle to the conversation session
 136  * @param missed_calls a list of missed calls
 137  */
 138 typedef void (GNUNET_CONVERSATION_MissedCallHandler) (void *cls,
 139                                                       struct GNUNET_CONVERSATION_Handle *handle,
 140                                                       struct GNUNET_CONVERSATION_MissedCallNotification *missed_calls);
 141
 142
 143 /**
 144  * Connect to the VoIP service
 145  *
 146  * @param cfg configuration
 147  * @param cls NULL
 148  * @param call_handler the callback which is called when a call is incoming
 149  * @param reject_handler the callback which is called when a call is rejected
 150  * @param notification_handler the callback which is called when there is a notification
 151  * @param missed_call_handler the callback which is called when the service notifies the client about missed clients
 152  * @return handle to the connection to the conversation service
 153  */
 154 struct GNUNET_CONVERSATION_Handle *
 155 GNUNET_CONVERSATION_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
 156                              void *cls,
 157                              GNUNET_CONVERSATION_CallHandler call_handler,
 158                              GNUNET_CONVERSATION_RejectHandler reject_handler,
 159                              GNUNET_CONVERSATION_NotificationHandler notification_handler,
 160                              GNUNET_CONVERSATION_MissedCallHandler missed_call_handler);
 161
 162
 163 /**
 164  * Disconnect from the VoIP service
 165  *
 166  * @param handle handle to the VoIP connection
 167  */
 168 void
 169 GNUNET_CONVERSATION_disconnect (struct GNUNET_CONVERSATION_Handle *handle);
 170
 171
 172 /**
 173  * Establish a call
 174  *
 175  * @param handle handle to the VoIP connection
 176  * @param callee the peer (PeerIdentity or GNS name) to call
 177  * @param doGnsLookup 0 = no GNS lookup or 1  = GNS lookup
 178  */
 179 void
 180 GNUNET_CONVERSATION_call (struct GNUNET_CONVERSATION_Handle *handle,
 181                           const char *callee,
 182                           int doGnsLookup);
 183
 184
 185 /**
 186  * Terminate the active call
 187  *
 188  * @param handle handle to the VoIP connection
 189  */
 190 void
 191 GNUNET_CONVERSATION_hangup (struct GNUNET_CONVERSATION_Handle *handle);
 192
 193
 194 /**
 195  * Accept an incoming call
 196  *
 197  * @param handle handle to the VoIP connection
 198  */
 199 void
 200 GNUNET_CONVERSATION_accept (struct GNUNET_CONVERSATION_Handle *handle);
 201
 202
 203 /**
 204  * Reject an incoming call
 205  *
 206  * @param handle handle to the VoIP connection
 207  */
 208 void
 209 GNUNET_CONVERSATION_reject (struct GNUNET_CONVERSATION_Handle *handle);
 210
 211
 212
 213 ////////////////////////////////////////////////////////////////////
 214 ////////////////////////// NEW API /////////////////////////////////
 215 ////////////////////////////////////////////////////////////////////
 216
 217 /*
 218    NOTE: This API is deliberately deceptively simple; the idea
 219    is that advanced features (such as answering machines) will
 220    be done with a separate service (an answering machine service)
 221    with its own APIs; the speaker/microphone abstractions are
 222    used to facilitate plugging in custom logic for implementing
 223    such a service later by creating "software" versions of
 224    speakers and microphones that record to disk or play a file.
 225    Notifications about missed calls should similarly be done
 226    using a separate service; CONVERSATION is supposed to be just
 227    the "bare bones" voice service.
 228
 229    Meta data passing is supported so that advanced services
 230    can identify themselves appropriately.
 231
 232    As this is supposed to be a "secure" service, caller ID is of
 233    course provided as part of the basic implementation, as only the
 234    CONVERSATION service can know for sure who it is that we are
 235    talking to.x */
 236
 237
 238 #include "gnunet_util_lib.h"
 239 #include "gnunet_identity_service.h"
 240 #include "gnunet_namestore_service.h"
 241 #include "gnunet_speaker_lib.h"
 242 #include "gnunet_microphone_lib.h"
 243
 244
 245 /**
 246  * Information about the current status of a call.  Each call
 247  * progresses from ring over ready to terminated.  Steps may
 248  * be skipped.
 249  */
 250 enum GNUNET_CONVERSATION_EventCode
 251 {
 252   /**
 253    * The phone is ringing, caller ID is provided in the varargs as
 254    * a `const char *`.  The caller ID will be a GNS name.
 255    */
 256   GNUNET_CONVERSATION_EC_RING,
 257
 258   /**
 259    * We are ready to talk, metadata about the call may be supplied
 260    * as a `const char *` in the varargs.
 261    */
 262   GNUNET_CONVERSATION_EC_READY,
 263
 264   /**
 265    * The conversation was terminated, a reason may be supplied
 266    * as a `const char *` in the varargs.
 267    */
 268   GNUNET_CONVERSATION_EC_TERMINATED
 269
 270 };
 271
 272
 273 /**
 274  * Function called with an event emitted by a phone.
 275  *
 276  * @param cls closure
 277  * @param code type of the event on the phone
 278  * @param ... additional information, depends on @a code
 279  */
 280 typedef void (*GNUNET_CONVERSATION_EventHandler)(void *cls,
 281                                                  enum GNUNET_CONVERSATION_EventCode code,
 282                                                  ...);
 283
 284
 285 /**
 286  * A phone is a device that can ring to signal an incoming call and
 287  * that you can pick up to answer the call and hang up to terminate
 288  * the call.  You can also hang up a ringing phone immediately
 289  * (without picking it up) to stop it from ringing.  Phones have
 290  * caller ID.  You can ask the phone for its record and make that
 291  * record available (via GNS) to enable others to call you.
 292  * Multiple phones maybe connected to the same line (the line is
 293  * something rather internal to a phone and not obvious from it).
 294  * You can only have one conversation per phone at any time.
 295  */
 296 struct GNUNET_CONVERSATION_Phone;
 297
 298
 299 /**
 300  * Create a new phone.
 301  *
 302  * @param cfg configuration for the phone; specifies the phone service and
 303  *        which line the phone is to be connected to
 304  * @param event_handler how to notify the owner of the phone about events
 305  * @param event_handler_cls closure for @a event_handler
 306  */
 307 struct GNUNET_CONVERSATION_Phone *
 308 GNUNET_CONVERSATION_phone_create (const struct GNUNET_CONFIGURATION_Handle *cfg,
 309                                   GNUNET_CONVERSATION_EventHandler event_handler,
 310                                   void *event_handler_cls);
 311
 312
 313 /**
 314  * Fill in a namestore record with the contact information
 315  * for this phone.  Note that the filled in "data" value
 316  * is only valid until the phone is destroyed.
 317  *
 318  * @param phone phone to create a record for
 319  * @param rd namestore record to fill in
 320  */
 321 void
 322 GNUNET_CONVERSATION_phone_get_record (struct GNUNET_CONVERSATION_Phone *phone,
 323                                       struct GNUNET_NAMESTORE_RecordData *rd);
 324
 325
 326 /**
 327  * Picks up a (ringing) phone.  This will connect the speaker
 328  * to the microphone of the other party, and vice versa.
 329  *
 330  * @param phone phone to pick up
 331  * @param metadata meta data to give to the other user about the pick up event
 332  * @param speaker speaker to use
 333  * @param mic microphone to use
 334  */
 335 void
 336 GNUNET_CONVERSTATION_phone_pick_up (struct GNUNET_CONVERSATION_Phone *phone,
 337                                     const char *metadata,
 338                                     struct GNUNET_SPEAKER_Handle *speaker,
 339                                     struct GNUNET_MICROPHONE_Handle *mic);
 340
 341
 342 /**
 343  * Hang up up a (possibly ringing) phone.  This will notify the other
 344  * party that we are no longer interested in talking with them.
 345  *
 346  * @param phone phone to pick up
 347  * @param reason text we give to the other party about why we terminated the conversation
 348  */
 349 void
 350 GNUNET_CONVERSTATION_phone_hang_up (struct GNUNET_CONVERSATION_Phone *phone,
 351                                     const char *reason);
 352
 353
 354 /**
 355  * Destroys a phone.
 356  *
 357  * @param phone phone to destroy
 358  */
 359 void
 360 GNUNET_CONVERSATION_phone_destroy (struct GNUNET_CONVERSATION_Phone *phone);
 361
 362
 363 /**
 364  * Handle for an outgoing call.
 365  */
 366 struct GNUNET_CONVERSATION_Call;
 367
 368
 369 /**
 370  * Call the phone of another user.
 371  *
 372  * @param cfg configuration to use, specifies our phone service
 373  * @param caller_id identity of the caller
 374  * @param callee GNS name of the callee (used to locate the callee's record)
 375  * @param speaker speaker to use (will be used automatically immediately once the
 376  *        #GNUNET_CONVERSATION_EC_READY event is generated); we will NOT generate
 377  *        a ring tone on the speaker
 378  * @param mic microphone to use (will be used automatically immediately once the
 379  *        #GNUNET_CONVERSATION_EC_READY event is generated)
 380  * @param event_handler how to notify the owner of the phone about events
 381  * @param event_handler_cls closure for @a event_handler
 382  */
 383 struct GNUNET_CONVERSATION_Call *
 384 GNUNET_CONVERSATION_call_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
 385                                 struct GNUNET_IDENTITY_Ego *caller_id,
 386                                 const char *callee,
 387                                 struct GNUNET_SPEAKER_Handle *speaker,
 388                                 struct GNUNET_MICROPHONE_Handle *mic,
 389                                 GNUNET_CONVERSATION_EventHandler event_handler,
 390                                 void *event_handler_cls);
 391
 392
 393 /**
 394  * Terminate a call.  The call may be ringing or ready at this time.
 395  *
 396  * @param call call to terminate
 397  * @param reason if the call was active (ringing or ready) this will be the
 398  *        reason given to the other user for why we hung up
 399  */
 400 void
 401 GNUNET_CONVERSATION_call_stop (const struct GNUNET_CONVERSATION_Call *call,
 402                                const char *reason);
 403
 404
 405 #if 0                           /* keep Emacsens' auto-indent happy */
 406 {
 407 #endif
 408 #ifdef __cplusplus
 409 }
 410 #endif
 411
 412 #endif