src/include/gnunet_conversation_service.h

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