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    * Version of the phone record, for now always one.  We may
  93    * use other versions for anonymously hosted phone lines in
  94    * the future.
  95    */
  96   uint32_t version GNUNET_PACKED;
  97
  98   /**
  99    * Reserved. In v1. always zero.
 100    */
 101   uint32_t reserved GNUNET_PACKED;
 102
 103   /**
 104    * Identity of the peer hosting the phone service.
 105    */
 106   struct GNUNET_PeerIdentity peer;
 107
 108   /**
 109    * Phone line (CADET port) to connect to.
 110    */
 111   struct GNUNET_HashCode line_port;
 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  * Function called with an event emitted by a phone.
 137  *
 138  * @param cls closure
 139  * @param code type of the event
 140  * @param caller handle for the caller
 141  * @param caller_id public key of the caller (in GNS)
 142  */
 143 typedef void
 144 (*GNUNET_CONVERSATION_PhoneEventHandler)(void *cls,
 145                                          enum GNUNET_CONVERSATION_PhoneEventCode
 146                                          code,
 147                                          struct GNUNET_CONVERSATION_Caller *
 148                                          caller,
 149                                          const struct
 150                                          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    * We are the callee and the caller suspended the call.  Note that
 162    * both sides can independently suspend and resume calls; a call is
 163    * only "working" of both sides are active.
 164    */
 165   GNUNET_CONVERSATION_EC_CALLER_SUSPEND,
 166
 167   /**
 168    * We are the callee and the caller resumed the call.  Note that
 169    * both sides can independently suspend and resume calls; a call is
 170    * only "working" of both sides are active.
 171    */
 172   GNUNET_CONVERSATION_EC_CALLER_RESUME
 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
 187                                           GNUNET_CONVERSATION_CallerEventCode
 188                                           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
 218                                   event_handler,
 219                                   void *event_handler_cls);
 220
 221
 222 /**
 223  * Fill in a namestore record with the contact information
 224  * for this phone.  Note that the filled in "data" value
 225  * is only valid until the phone is destroyed.
 226  *
 227  * @param phone phone to create a record for
 228  * @param rd namestore record to fill in
 229  */
 230 void
 231 GNUNET_CONVERSATION_phone_get_record (struct GNUNET_CONVERSATION_Phone *phone,
 232                                       struct GNUNET_GNSRECORD_Data *rd);
 233
 234
 235 /**
 236  * Picks up a (ringing) phone call.  This will connect the speaker
 237  * to the microphone of the other party, and vice versa.
 238  *
 239  * @param caller handle that identifies which caller should be answered
 240  * @param event_handler how to notify about events by the caller
 241  * @param event_handler_cls closure for @a event_handler
 242  * @param speaker speaker to use
 243  * @param mic microphone to use
 244  */
 245 void
 246 GNUNET_CONVERSATION_caller_pick_up (struct GNUNET_CONVERSATION_Caller *caller,
 247                                     GNUNET_CONVERSATION_CallerEventHandler
 248                                     event_handler,
 249                                     void *event_handler_cls,
 250                                     struct GNUNET_SPEAKER_Handle *speaker,
 251                                     struct GNUNET_MICROPHONE_Handle *mic);
 252
 253
 254 /**
 255  * Pause conversation of an active call.  This will disconnect the speaker
 256  * and the microphone.  The call can later be resumed with
 257  * #GNUNET_CONVERSATION_caller_resume.
 258  *
 259  * @param caller call to suspend
 260  */
 261 void
 262 GNUNET_CONVERSATION_caller_suspend (struct GNUNET_CONVERSATION_Caller *caller);
 263
 264
 265 /**
 266  * Resume suspended conversation of a phone.
 267  *
 268  * @param caller call to resume
 269  * @param speaker speaker to use
 270  * @param mic microphone to use
 271  */
 272 void
 273 GNUNET_CONVERSATION_caller_resume (struct GNUNET_CONVERSATION_Caller *caller,
 274                                    struct GNUNET_SPEAKER_Handle *speaker,
 275                                    struct GNUNET_MICROPHONE_Handle *mic);
 276
 277
 278 /**
 279  * Hang up up a (possibly ringing or paused) phone.  This will notify
 280  * the caller that we are no longer interested in talking with them.
 281  *
 282  * @param caller who should we hang up on
 283  */
 284 void
 285 GNUNET_CONVERSATION_caller_hang_up (struct GNUNET_CONVERSATION_Caller *caller);
 286
 287
 288 /**
 289  * Destroys a phone.
 290  *
 291  * @param phone phone to destroy
 292  */
 293 void
 294 GNUNET_CONVERSATION_phone_destroy (struct GNUNET_CONVERSATION_Phone *phone);
 295
 296
 297 /* *********************** CALL API ************************ */
 298
 299 /**
 300  * Handle for an outgoing call.
 301  */
 302 struct GNUNET_CONVERSATION_Call;
 303
 304
 305 /**
 306  * Information about the current status of a call.
 307  */
 308 enum GNUNET_CONVERSATION_CallEventCode
 309 {
 310   /**
 311    * We are the caller and are now ringing the other party (GNS lookup
 312    * succeeded).
 313    */
 314   GNUNET_CONVERSATION_EC_CALL_RINGING,
 315
 316   /**
 317    * We are the caller and are now ready to talk as the callee picked up.
 318    */
 319   GNUNET_CONVERSATION_EC_CALL_PICKED_UP,
 320
 321   /**
 322    * We are the caller and failed to locate a phone record in GNS.
 323    * After this invocation, the respective call handle will be
 324    * automatically destroyed and the client must no longer call
 325    * #GNUNET_CONVERSATION_call_stop or any other function on the
 326    * call object.
 327    */
 328   GNUNET_CONVERSATION_EC_CALL_GNS_FAIL,
 329
 330   /**
 331    * We are the caller and the callee called
 332    * #GNUNET_CONVERSATION_caller_hang_up.  After this invocation, the
 333    * respective call handle will be automatically destroyed and the
 334    * client must no longer call #GNUNET_CONVERSATION_call_stop.
 335    */
 336   GNUNET_CONVERSATION_EC_CALL_HUNG_UP,
 337
 338   /**
 339    * We are the caller and the callee suspended the call.  Note that
 340    * both sides can independently suspend and resume calls; a call is
 341    * only "working" of both sides are active.
 342    */
 343   GNUNET_CONVERSATION_EC_CALL_SUSPENDED,
 344
 345   /**
 346    * We are the caller and the callee suspended the call.  Note that
 347    * both sides can independently suspend and resume calls; a call is
 348    * only "working" of both sides are active.
 349    */
 350   GNUNET_CONVERSATION_EC_CALL_RESUMED,
 351
 352   /**
 353    * We had an error handing the call, and are now restarting it
 354    * (back to lookup).  This happens, for example, if the peer
 355    * is restarted during a call.
 356    */
 357   GNUNET_CONVERSATION_EC_CALL_ERROR
 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
 370                                         code);
 371
 372
 373 /**
 374  * Call the phone of another user.
 375  *
 376  * @param cfg configuration to use, specifies our phone service
 377  * @param caller_id identity of the caller
 378  * @param callee GNS name of the callee (used to locate the callee's record)
 379  * @param speaker speaker to use (will be used automatically immediately once the
 380  *        #GNUNET_CONVERSATION_EC_CALL_PICKED_UP event is generated); we will NOT generate
 381  *        a ring tone on the speaker
 382  * @param mic microphone to use (will be used automatically immediately once the
 383  *        #GNUNET_CONVERSATION_EC_CALL_PICKED_UP event is generated)
 384  * @param event_handler how to notify the owner of the phone about events
 385  * @param event_handler_cls closure for @a event_handler
 386  * @return handle for the call
 387  */
 388 struct GNUNET_CONVERSATION_Call *
 389 GNUNET_CONVERSATION_call_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
 390                                 struct GNUNET_IDENTITY_Ego *caller_id,
 391                                 const char *callee,
 392                                 struct GNUNET_SPEAKER_Handle *speaker,
 393                                 struct GNUNET_MICROPHONE_Handle *mic,
 394                                 GNUNET_CONVERSATION_CallEventHandler
 395                                 event_handler,
 396                                 void *event_handler_cls);
 397
 398
 399 /**
 400  * Pause a call.  Temporarily suspends the use of speaker and
 401  * microphone.
 402  *
 403  * @param call call to pause
 404  */
 405 void
 406 GNUNET_CONVERSATION_call_suspend (struct GNUNET_CONVERSATION_Call *call);
 407
 408
 409 /**
 410  * Resumes a call after #GNUNET_CONVERSATION_call_suspend.
 411  *
 412  * @param call call to resume
 413  * @param speaker speaker to use
 414  * @param mic microphone to use
 415  */
 416 void
 417 GNUNET_CONVERSATION_call_resume (struct GNUNET_CONVERSATION_Call *call,
 418                                  struct GNUNET_SPEAKER_Handle *speaker,
 419                                  struct GNUNET_MICROPHONE_Handle *mic);
 420
 421
 422 /**
 423  * Terminate a call.  The call may be ringing or ready at this time.
 424  *
 425  * @param call call to terminate
 426  */
 427 void
 428 GNUNET_CONVERSATION_call_stop (struct GNUNET_CONVERSATION_Call *call);
 429
 430
 431 #if 0                           /* keep Emacsens' auto-indent happy */
 432 {
 433 #endif
 434 #ifdef __cplusplus
 435 }
 436 #endif
 437
 438 #endif
 439
 440 /** @} */  /* end of group */