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