src/include/gnunet_conversation_service.h

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