src/include/gnunet_conversation_service.h

   1 /*
   2   This file is part of GNUnet
   3   Copyright (C) 2013, 2014 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 Simon Dieterle
  23  * @author Andreas Fuchs
  24  * @author Christian Grothoff
  25  *
  26  * @file
  27  * API to the conversation service
  28  *
  29  * @defgroup conversation  Conversation service
  30  * One-to-one voice communication over CADET
  31  *
  32  * NOTE: This API is deliberately deceptively simple; the idea
  33  * is that advanced features (such as answering machines) will
  34  * be done with a separate service (an answering machine service)
  35  * with its own APIs; the speaker/microphone abstractions are
  36  * used to facilitate plugging in custom logic for implementing
  37  * such a service later by creating "software" versions of
  38  * speakers and microphones that record to disk or play a file.
  39  * Notifications about missed calls should similarly be done
  40  * using a separate service; CONVERSATION is supposed to be just
  41  * the "bare bones" voice service.
  42  *
  43  * As this is supposed to be a "secure" service, caller ID is of
  44  * course provided as part of the basic implementation, as only the
  45  * CONVERSATION service can know for sure who it is that we are
  46  * talking to.
  47  *
  48  * @{
  49  */
  50 #ifndef GNUNET_CONVERSATION_SERVICE_H
  51 #define GNUNET_CONVERSATION_SERVICE_H
  52
  53 #ifdef __cplusplus
  54 extern "C"
  55 {
  56 #if 0                           /* keep Emacsens' auto-indent happy */
  57 }
  58 #endif
  59 #endif
  60
  61 #include "gnunet_util_lib.h"
  62 #include "gnunet_identity_service.h"
  63 #include "gnunet_namestore_service.h"
  64 #include "gnunet_speaker_lib.h"
  65 #include "gnunet_microphone_lib.h"
  66
  67
  68 /**
  69  * Version of the conversation API.
  70  */
  71 #define GNUNET_CONVERSATION_VERSION 0x00000003
  72
  73 /**
  74  * Handle to identify a particular caller.  A caller is an entity that
  75  * initiate a call to a phone.  This struct identifies the caller to
  76  * the user operating the phone.  The entity that initiated the call
  77  * will have a `struct GNUNET_CONVERSATION_Call`.
  78  */
  79 struct GNUNET_CONVERSATION_Caller;
  80
  81
  82 GNUNET_NETWORK_STRUCT_BEGIN
  83
  84 /**
  85  * A phone record specifies which peer is hosting a given user and
  86  * may also specify the phone line that is used (typically zero).
  87  * The version is also right now always zero.
  88  */
  89 struct GNUNET_CONVERSATION_PhoneRecord
  90 {
  91
  92   /**
  93    * Version of the phone record, for now always zero.  We may
  94    * use other versions for anonymously hosted phone lines in
  95    * the future.
  96    */
  97   uint32_t version GNUNET_PACKED;
  98
  99   /**
 100    * Phone line to use at the peer.
 101    */
 102   uint32_t line GNUNET_PACKED;
 103
 104   /**
 105    * Identity of the peer hosting the phone service.
 106    */
 107   struct GNUNET_PeerIdentity peer;
 108
 109 };
 110
 111 GNUNET_NETWORK_STRUCT_END
 112
 113 /**
 114  * Information about active callers to a phone.
 115  */
 116 enum GNUNET_CONVERSATION_PhoneEventCode
 117 {
 118   /**
 119    * We are the callee and the phone is ringing.
 120    * We should accept the call or hang up.
 121    */
 122   GNUNET_CONVERSATION_EC_PHONE_RING,
 123
 124   /**
 125    * The conversation was terminated by the caller.
 126    * We must no longer use the caller's handle.
 127    */
 128   GNUNET_CONVERSATION_EC_PHONE_HUNG_UP
 129
 130 };
 131
 132
 133 /**
 134  * Function called with an event emitted by a phone.
 135  *
 136  * @param cls closure
 137  * @param code type of the event
 138  * @param caller handle for the caller
 139  * @param caller_id public key of the caller (in GNS)
 140  */
 141 typedef void
 142 (*GNUNET_CONVERSATION_PhoneEventHandler)(void *cls,
 143                                          enum GNUNET_CONVERSATION_PhoneEventCode code,
 144                                          struct GNUNET_CONVERSATION_Caller *caller,
 145                                          const struct GNUNET_CRYPTO_EcdsaPublicKey *caller_id);
 146
 147
 148 /**
 149  * Information about the current status of a call.  Each call
 150  * progresses from ring over ready to terminated.  Steps may
 151  * be skipped.
 152  */
 153 enum GNUNET_CONVERSATION_CallerEventCode
 154 {
 155
 156   /**
 157    * We are the callee and the caller suspended the call.  Note that
 158    * both sides can independently suspend and resume calls; a call is
 159    * only "working" of both sides are active.
 160    */
 161   GNUNET_CONVERSATION_EC_CALLER_SUSPEND,
 162
 163   /**
 164    * We are the callee and the caller resumed the call.  Note that
 165    * both sides can independently suspend and resume calls; a call is
 166    * only "working" of both sides are active.
 167    */
 168   GNUNET_CONVERSATION_EC_CALLER_RESUME
 169
 170 };
 171
 172
 173 /**
 174  * Function called with an event emitted by a caller.
 175  * These events are only generated after the phone is
 176  * picked up.
 177  *
 178  * @param cls closure
 179  * @param code type of the event for this caller
 180  */
 181 typedef void
 182 (*GNUNET_CONVERSATION_CallerEventHandler)(void *cls,
 183                                           enum GNUNET_CONVERSATION_CallerEventCode code);
 184
 185
 186 /**
 187  * A phone is a device that can ring to signal an incoming call and
 188  * that you can pick up to answer the call and hang up to terminate
 189  * the call.  You can also hang up a ringing phone immediately
 190  * (without picking it up) to stop it from ringing.  Phones have
 191  * caller ID.  You can ask the phone for its record and make that
 192  * record available (via GNS) to enable others to call you.
 193  * Multiple phones maybe connected to the same line (the line is
 194  * something rather internal to a phone and not obvious from it).
 195  * You can only have one conversation per phone at any time.
 196  */
 197 struct GNUNET_CONVERSATION_Phone;
 198
 199
 200 /**
 201  * Create a new phone.
 202  *
 203  * @param cfg configuration for the phone; specifies the phone service and
 204  *        which line the phone is to be connected to
 205  * @param ego ego to use for name resolution (when determining caller ID)
 206  * @param event_handler how to notify the owner of the phone about events
 207  * @param event_handler_cls closure for @a event_handler
 208  */
 209 struct GNUNET_CONVERSATION_Phone *
 210 GNUNET_CONVERSATION_phone_create (const struct GNUNET_CONFIGURATION_Handle *cfg,
 211                                   const struct GNUNET_IDENTITY_Ego *ego,
 212                                   GNUNET_CONVERSATION_PhoneEventHandler event_handler,
 213                                   void *event_handler_cls);
 214
 215
 216 /**
 217  * Fill in a namestore record with the contact information
 218  * for this phone.  Note that the filled in "data" value
 219  * is only valid until the phone is destroyed.
 220  *
 221  * @param phone phone to create a record for
 222  * @param rd namestore record to fill in
 223  */
 224 void
 225 GNUNET_CONVERSATION_phone_get_record (struct GNUNET_CONVERSATION_Phone *phone,
 226                                       struct GNUNET_GNSRECORD_Data *rd);
 227
 228
 229 /**
 230  * Picks up a (ringing) phone call.  This will connect the speaker
 231  * to the microphone of the other party, and vice versa.
 232  *
 233  * @param caller handle that identifies which caller should be answered
 234  * @param event_handler how to notify about events by the caller
 235  * @param event_handler_cls closure for @a event_handler
 236  * @param speaker speaker to use
 237  * @param mic microphone to use
 238  */
 239 void
 240 GNUNET_CONVERSATION_caller_pick_up (struct GNUNET_CONVERSATION_Caller *caller,
 241                                     GNUNET_CONVERSATION_CallerEventHandler event_handler,
 242                                     void *event_handler_cls,
 243                                     struct GNUNET_SPEAKER_Handle *speaker,
 244                                     struct GNUNET_MICROPHONE_Handle *mic);
 245
 246
 247 /**
 248  * Pause conversation of an active call.  This will disconnect the speaker
 249  * and the microphone.  The call can later be resumed with
 250  * #GNUNET_CONVERSATION_caller_resume.
 251  *
 252  * @param caller call to suspend
 253  */
 254 void
 255 GNUNET_CONVERSATION_caller_suspend (struct GNUNET_CONVERSATION_Caller *caller);
 256
 257
 258 /**
 259  * Resume suspended conversation of a phone.
 260  *
 261  * @param caller call to resume
 262  * @param speaker speaker to use
 263  * @param mic microphone to use
 264  */
 265 void
 266 GNUNET_CONVERSATION_caller_resume (struct GNUNET_CONVERSATION_Caller *caller,
 267                                    struct GNUNET_SPEAKER_Handle *speaker,
 268                                    struct GNUNET_MICROPHONE_Handle *mic);
 269
 270
 271 /**
 272  * Hang up up a (possibly ringing or paused) phone.  This will notify
 273  * the caller that we are no longer interested in talking with them.
 274  *
 275  * @param caller who should we hang up on
 276  */
 277 void
 278 GNUNET_CONVERSATION_caller_hang_up (struct GNUNET_CONVERSATION_Caller *caller);
 279
 280
 281 /**
 282  * Destroys a phone.
 283  *
 284  * @param phone phone to destroy
 285  */
 286 void
 287 GNUNET_CONVERSATION_phone_destroy (struct GNUNET_CONVERSATION_Phone *phone);
 288
 289
 290 /* *********************** CALL API ************************ */
 291
 292 /**
 293  * Handle for an outgoing call.
 294  */
 295 struct GNUNET_CONVERSATION_Call;
 296
 297
 298 /**
 299  * Information about the current status of a call.
 300  */
 301 enum GNUNET_CONVERSATION_CallEventCode
 302 {
 303
 304   /**
 305    * We are the caller and are now ringing the other party (GNS lookup
 306    * succeeded).
 307    */
 308   GNUNET_CONVERSATION_EC_CALL_RINGING,
 309
 310   /**
 311    * We are the caller and are now ready to talk as the callee picked up.
 312    */
 313   GNUNET_CONVERSATION_EC_CALL_PICKED_UP,
 314
 315   /**
 316    * We are the caller and failed to locate a phone record in GNS.
 317    * After this invocation, the respective call handle will be
 318    * automatically destroyed and the client must no longer call
 319    * #GNUNET_CONVERSATION_call_stop or any other function on the
 320    * call object.
 321    */
 322   GNUNET_CONVERSATION_EC_CALL_GNS_FAIL,
 323
 324   /**
 325    * We are the caller and the callee called
 326    * #GNUNET_CONVERSATION_caller_hang_up.  After this invocation, the
 327    * respective call handle will be automatically destroyed and the
 328    * client must no longer call #GNUNET_CONVERSATION_call_stop.
 329    */
 330   GNUNET_CONVERSATION_EC_CALL_HUNG_UP,
 331
 332   /**
 333    * We are the caller and the callee suspended the call.  Note that
 334    * both sides can independently suspend and resume calls; a call is
 335    * only "working" of both sides are active.
 336    */
 337   GNUNET_CONVERSATION_EC_CALL_SUSPENDED,
 338
 339   /**
 340    * We are the caller and the callee suspended the call.  Note that
 341    * both sides can independently suspend and resume calls; a call is
 342    * only "working" of both sides are active.
 343    */
 344   GNUNET_CONVERSATION_EC_CALL_RESUMED,
 345
 346   /**
 347    * We had an error handing the call, and are now restarting it
 348    * (back to lookup).  This happens, for example, if the peer
 349    * is restarted during a call.
 350    */
 351   GNUNET_CONVERSATION_EC_CALL_ERROR
 352
 353 };
 354
 355
 356 /**
 357  * Function called with an event emitted for a call.
 358  *
 359  * @param cls closure
 360  * @param code type of the event on the call
 361  */
 362 typedef void
 363 (*GNUNET_CONVERSATION_CallEventHandler)(void *cls,
 364                                         enum GNUNET_CONVERSATION_CallEventCode code);
 365
 366
 367 /**
 368  * Call the phone of another user.
 369  *
 370  * @param cfg configuration to use, specifies our phone service
 371  * @param caller_id identity of the caller
 372  * @param zone_id GNS zone to use to resolve @a callee
 373  * @param callee GNS name of the callee (used to locate the callee's record)
 374  * @param speaker speaker to use (will be used automatically immediately once the
 375  *        #GNUNET_CONVERSATION_EC_CALL_PICKED_UP event is generated); we will NOT generate
 376  *        a ring tone on the speaker
 377  * @param mic microphone to use (will be used automatically immediately once the
 378  *        #GNUNET_CONVERSATION_EC_CALL_PICKED_UP event is generated)
 379  * @param event_handler how to notify the owner of the phone about events
 380  * @param event_handler_cls closure for @a event_handler
 381  * @return handle for the call
 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                                 struct GNUNET_IDENTITY_Ego *zone_id,
 387                                 const char *callee,
 388                                 struct GNUNET_SPEAKER_Handle *speaker,
 389                                 struct GNUNET_MICROPHONE_Handle *mic,
 390                                 GNUNET_CONVERSATION_CallEventHandler event_handler,
 391                                 void *event_handler_cls);
 392
 393
 394 /**
 395  * Pause a call.  Temporarily suspends the use of speaker and
 396  * microphone.
 397  *
 398  * @param call call to pause
 399  */
 400 void
 401 GNUNET_CONVERSATION_call_suspend (struct GNUNET_CONVERSATION_Call *call);
 402
 403
 404 /**
 405  * Resumes a call after #GNUNET_CONVERSATION_call_suspend.
 406  *
 407  * @param call call to resume
 408  * @param speaker speaker to use
 409  * @param mic microphone to use
 410  */
 411 void
 412 GNUNET_CONVERSATION_call_resume (struct GNUNET_CONVERSATION_Call *call,
 413                                  struct GNUNET_SPEAKER_Handle *speaker,
 414                                  struct GNUNET_MICROPHONE_Handle *mic);
 415
 416
 417 /**
 418  * Terminate a call.  The call may be ringing or ready at this time.
 419  *
 420  * @param call call to terminate
 421  */
 422 void
 423 GNUNET_CONVERSATION_call_stop (struct GNUNET_CONVERSATION_Call *call);
 424
 425
 426 #if 0                           /* keep Emacsens' auto-indent happy */
 427 {
 428 #endif
 429 #ifdef __cplusplus
 430 }
 431 #endif
 432
 433 #endif
 434
 435 /** @} */  /* end of group */