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      SPDX-License-Identifier: AGPL3.0-or-later
  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 0x00000004
  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 one.  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    * Reserved. In v1. always zero.
 101    */
 102   uint32_t reserved GNUNET_PACKED;
 103
 104   /**
 105    * Identity of the peer hosting the phone service.
 106    */
 107   struct GNUNET_PeerIdentity peer;
 108
 109   /**
 110    * Phone line (CADET port) to connect to.
 111    */
 112   struct GNUNET_HashCode line_port;
 113
 114 };
 115
 116 GNUNET_NETWORK_STRUCT_END
 117
 118 /**
 119  * Information about active callers to a phone.
 120  */
 121 enum GNUNET_CONVERSATION_PhoneEventCode
 122 {
 123   /**
 124    * We are the callee and the phone is ringing.
 125    * We should accept the call or hang up.
 126    */
 127   GNUNET_CONVERSATION_EC_PHONE_RING,
 128
 129   /**
 130    * The conversation was terminated by the caller.
 131    * We must no longer use the caller's handle.
 132    */
 133   GNUNET_CONVERSATION_EC_PHONE_HUNG_UP
 134
 135 };
 136
 137
 138 /**
 139  * Function called with an event emitted by a phone.
 140  *
 141  * @param cls closure
 142  * @param code type of the event
 143  * @param caller handle for the caller
 144  * @param caller_id public key of the caller (in GNS)
 145  */
 146 typedef void
 147 (*GNUNET_CONVERSATION_PhoneEventHandler)(void *cls,
 148                                          enum GNUNET_CONVERSATION_PhoneEventCode code,
 149                                          struct GNUNET_CONVERSATION_Caller *caller,
 150                                          const struct GNUNET_CRYPTO_EcdsaPublicKey *caller_id);
 151
 152
 153 /**
 154  * Information about the current status of a call.  Each call
 155  * progresses from ring over ready to terminated.  Steps may
 156  * be skipped.
 157  */
 158 enum GNUNET_CONVERSATION_CallerEventCode
 159 {
 160
 161   /**
 162    * We are the callee and the caller suspended the call.  Note that
 163    * both sides can independently suspend and resume calls; a call is
 164    * only "working" of both sides are active.
 165    */
 166   GNUNET_CONVERSATION_EC_CALLER_SUSPEND,
 167
 168   /**
 169    * We are the callee and the caller resumed the call.  Note that
 170    * both sides can independently suspend and resume calls; a call is
 171    * only "working" of both sides are active.
 172    */
 173   GNUNET_CONVERSATION_EC_CALLER_RESUME
 174
 175 };
 176
 177
 178 /**
 179  * Function called with an event emitted by a caller.
 180  * These events are only generated after the phone is
 181  * picked up.
 182  *
 183  * @param cls closure
 184  * @param code type of the event for this caller
 185  */
 186 typedef void
 187 (*GNUNET_CONVERSATION_CallerEventHandler)(void *cls,
 188                                           enum GNUNET_CONVERSATION_CallerEventCode code);
 189
 190
 191 /**
 192  * A phone is a device that can ring to signal an incoming call and
 193  * that you can pick up to answer the call and hang up to terminate
 194  * the call.  You can also hang up a ringing phone immediately
 195  * (without picking it up) to stop it from ringing.  Phones have
 196  * caller ID.  You can ask the phone for its record and make that
 197  * record available (via GNS) to enable others to call you.
 198  * Multiple phones maybe connected to the same line (the line is
 199  * something rather internal to a phone and not obvious from it).
 200  * You can only have one conversation per phone at any time.
 201  */
 202 struct GNUNET_CONVERSATION_Phone;
 203
 204
 205 /**
 206  * Create a new phone.
 207  *
 208  * @param cfg configuration for the phone; specifies the phone service and
 209  *        which line the phone is to be connected to
 210  * @param ego ego to use for name resolution (when determining caller ID)
 211  * @param event_handler how to notify the owner of the phone about events
 212  * @param event_handler_cls closure for @a event_handler
 213  */
 214 struct GNUNET_CONVERSATION_Phone *
 215 GNUNET_CONVERSATION_phone_create (const struct GNUNET_CONFIGURATION_Handle *cfg,
 216                                   const struct GNUNET_IDENTITY_Ego *ego,
 217                                   GNUNET_CONVERSATION_PhoneEventHandler event_handler,
 218                                   void *event_handler_cls);
 219
 220
 221 /**
 222  * Fill in a namestore record with the contact information
 223  * for this phone.  Note that the filled in "data" value
 224  * is only valid until the phone is destroyed.
 225  *
 226  * @param phone phone to create a record for
 227  * @param rd namestore record to fill in
 228  */
 229 void
 230 GNUNET_CONVERSATION_phone_get_record (struct GNUNET_CONVERSATION_Phone *phone,
 231                                       struct GNUNET_GNSRECORD_Data *rd);
 232
 233
 234 /**
 235  * Picks up a (ringing) phone call.  This will connect the speaker
 236  * to the microphone of the other party, and vice versa.
 237  *
 238  * @param caller handle that identifies which caller should be answered
 239  * @param event_handler how to notify about events by the caller
 240  * @param event_handler_cls closure for @a event_handler
 241  * @param speaker speaker to use
 242  * @param mic microphone to use
 243  */
 244 void
 245 GNUNET_CONVERSATION_caller_pick_up (struct GNUNET_CONVERSATION_Caller *caller,
 246                                     GNUNET_CONVERSATION_CallerEventHandler event_handler,
 247                                     void *event_handler_cls,
 248                                     struct GNUNET_SPEAKER_Handle *speaker,
 249                                     struct GNUNET_MICROPHONE_Handle *mic);
 250
 251
 252 /**
 253  * Pause conversation of an active call.  This will disconnect the speaker
 254  * and the microphone.  The call can later be resumed with
 255  * #GNUNET_CONVERSATION_caller_resume.
 256  *
 257  * @param caller call to suspend
 258  */
 259 void
 260 GNUNET_CONVERSATION_caller_suspend (struct GNUNET_CONVERSATION_Caller *caller);
 261
 262
 263 /**
 264  * Resume suspended conversation of a phone.
 265  *
 266  * @param caller call to resume
 267  * @param speaker speaker to use
 268  * @param mic microphone to use
 269  */
 270 void
 271 GNUNET_CONVERSATION_caller_resume (struct GNUNET_CONVERSATION_Caller *caller,
 272                                    struct GNUNET_SPEAKER_Handle *speaker,
 273                                    struct GNUNET_MICROPHONE_Handle *mic);
 274
 275
 276 /**
 277  * Hang up up a (possibly ringing or paused) phone.  This will notify
 278  * the caller that we are no longer interested in talking with them.
 279  *
 280  * @param caller who should we hang up on
 281  */
 282 void
 283 GNUNET_CONVERSATION_caller_hang_up (struct GNUNET_CONVERSATION_Caller *caller);
 284
 285
 286 /**
 287  * Destroys a phone.
 288  *
 289  * @param phone phone to destroy
 290  */
 291 void
 292 GNUNET_CONVERSATION_phone_destroy (struct GNUNET_CONVERSATION_Phone *phone);
 293
 294
 295 /* *********************** CALL API ************************ */
 296
 297 /**
 298  * Handle for an outgoing call.
 299  */
 300 struct GNUNET_CONVERSATION_Call;
 301
 302
 303 /**
 304  * Information about the current status of a call.
 305  */
 306 enum GNUNET_CONVERSATION_CallEventCode
 307 {
 308
 309   /**
 310    * We are the caller and are now ringing the other party (GNS lookup
 311    * succeeded).
 312    */
 313   GNUNET_CONVERSATION_EC_CALL_RINGING,
 314
 315   /**
 316    * We are the caller and are now ready to talk as the callee picked up.
 317    */
 318   GNUNET_CONVERSATION_EC_CALL_PICKED_UP,
 319
 320   /**
 321    * We are the caller and failed to locate a phone record in GNS.
 322    * After this invocation, the respective call handle will be
 323    * automatically destroyed and the client must no longer call
 324    * #GNUNET_CONVERSATION_call_stop or any other function on the
 325    * call object.
 326    */
 327   GNUNET_CONVERSATION_EC_CALL_GNS_FAIL,
 328
 329   /**
 330    * We are the caller and the callee called
 331    * #GNUNET_CONVERSATION_caller_hang_up.  After this invocation, the
 332    * respective call handle will be automatically destroyed and the
 333    * client must no longer call #GNUNET_CONVERSATION_call_stop.
 334    */
 335   GNUNET_CONVERSATION_EC_CALL_HUNG_UP,
 336
 337   /**
 338    * We are the caller and the callee suspended the call.  Note that
 339    * both sides can independently suspend and resume calls; a call is
 340    * only "working" of both sides are active.
 341    */
 342   GNUNET_CONVERSATION_EC_CALL_SUSPENDED,
 343
 344   /**
 345    * We are the caller and the callee suspended the call.  Note that
 346    * both sides can independently suspend and resume calls; a call is
 347    * only "working" of both sides are active.
 348    */
 349   GNUNET_CONVERSATION_EC_CALL_RESUMED,
 350
 351   /**
 352    * We had an error handing the call, and are now restarting it
 353    * (back to lookup).  This happens, for example, if the peer
 354    * is restarted during a call.
 355    */
 356   GNUNET_CONVERSATION_EC_CALL_ERROR
 357
 358 };
 359
 360
 361 /**
 362  * Function called with an event emitted for a call.
 363  *
 364  * @param cls closure
 365  * @param code type of the event on the call
 366  */
 367 typedef void
 368 (*GNUNET_CONVERSATION_CallEventHandler)(void *cls,
 369                                         enum GNUNET_CONVERSATION_CallEventCode code);
 370
 371
 372 /**
 373  * Call the phone of another user.
 374  *
 375  * @param cfg configuration to use, specifies our phone service
 376  * @param caller_id identity of the caller
 377  * @param callee GNS name of the callee (used to locate the callee's record)
 378  * @param speaker speaker to use (will be used automatically immediately once the
 379  *        #GNUNET_CONVERSATION_EC_CALL_PICKED_UP event is generated); we will NOT generate
 380  *        a ring tone on the speaker
 381  * @param mic microphone to use (will be used automatically immediately once the
 382  *        #GNUNET_CONVERSATION_EC_CALL_PICKED_UP event is generated)
 383  * @param event_handler how to notify the owner of the phone about events
 384  * @param event_handler_cls closure for @a event_handler
 385  * @return handle for the call
 386  */
 387 struct GNUNET_CONVERSATION_Call *
 388 GNUNET_CONVERSATION_call_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
 389                                 struct GNUNET_IDENTITY_Ego *caller_id,
 390                                 const char *callee,
 391                                 struct GNUNET_SPEAKER_Handle *speaker,
 392                                 struct GNUNET_MICROPHONE_Handle *mic,
 393                                 GNUNET_CONVERSATION_CallEventHandler event_handler,
 394                                 void *event_handler_cls);
 395
 396
 397 /**
 398  * Pause a call.  Temporarily suspends the use of speaker and
 399  * microphone.
 400  *
 401  * @param call call to pause
 402  */
 403 void
 404 GNUNET_CONVERSATION_call_suspend (struct GNUNET_CONVERSATION_Call *call);
 405
 406
 407 /**
 408  * Resumes a call after #GNUNET_CONVERSATION_call_suspend.
 409  *
 410  * @param call call to resume
 411  * @param speaker speaker to use
 412  * @param mic microphone to use
 413  */
 414 void
 415 GNUNET_CONVERSATION_call_resume (struct GNUNET_CONVERSATION_Call *call,
 416                                  struct GNUNET_SPEAKER_Handle *speaker,
 417                                  struct GNUNET_MICROPHONE_Handle *mic);
 418
 419
 420 /**
 421  * Terminate a call.  The call may be ringing or ready at this time.
 422  *
 423  * @param call call to terminate
 424  */
 425 void
 426 GNUNET_CONVERSATION_call_stop (struct GNUNET_CONVERSATION_Call *call);
 427
 428
 429 #if 0                           /* keep Emacsens' auto-indent happy */
 430 {
 431 #endif
 432 #ifdef __cplusplus
 433 }
 434 #endif
 435
 436 #endif
 437
 438 /** @} */  /* end of group */