src/include/gnunet_conversation_service.h

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