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 #ifndef GNUNET_CONVERSATION_SERVICE_H
  29 #define GNUNET_CONVERSATION_SERVICE_H
  30
  31 #ifdef __cplusplus
  32 extern "C"
  33 {
  34 #if 0                           /* keep Emacsens' auto-indent happy */
  35 }
  36 #endif
  37 #endif
  38
  39 /**
  40  * Version of the conversation API.
  41  */
  42 #define GNUNET_CONVERSATION_VERSION 0x00000001
  43
  44
  45 enum GNUNET_CONVERSATION_RejectReason
  46 {
  47   GNUNET_CONVERSATION_REJECT_REASON_GENERIC = 0,
  48   GNUNET_CONVERSATION_REJECT_REASON_NOT_AVAILABLE,
  49   GNUNET_CONVERSATION_REJECT_REASON_NO_CLIENT,
  50   GNUNET_CONVERSATION_REJECT_REASON_ACTIVE_CALL,
  51   GNUNET_CONVERSATION_REJECT_REASON_NOT_WANTED,
  52   GNUNET_CONVERSATION_REJECT_REASON_NO_ANSWER
  53
  54 };
  55
  56
  57 enum GNUNET_CONVERSATION_NotificationType
  58 {
  59   GNUNET_CONVERSATION_NT_SERVICE_BLOCKED = 0,
  60   GNUNET_CONVERSATION_NT_NO_PEER,
  61   GNUNET_CONVERSATION_NT_NO_ANSWER,
  62   GNUNET_CONVERSATION_NT_AVAILABLE_AGAIN,
  63   GNUNET_CONVERSATION_NT_CALL_ACCEPTED,
  64   GNUNET_CONVERSATION_NT_CALL_TERMINATED
  65 };
  66
  67
  68 /**
  69  *
  70  */
  71 struct GNUNET_CONVERSATION_MissedCall
  72 {
  73   struct GNUNET_PeerIdentity peer;
  74   struct GNUNET_TIME_Absolute time;
  75 };
  76
  77
  78 struct GNUNET_CONVERSATION_MissedCallNotification
  79 {
  80   int number;
  81   struct GNUNET_CONVERSATION_MissedCall *calls;
  82 };
  83
  84 struct GNUNET_CONVERSATION_CallInformation;
  85
  86 struct GNUNET_CONVERSATION_Handle;
  87
  88
  89 /**
  90  * Method called whenever a call is incoming
  91  *
  92  * @param cls closure
  93  * @param handle to the conversation session
  94  * @param caller peer that calls you
  95  */
  96 typedef void (GNUNET_CONVERSATION_CallHandler) (void *cls,
  97                                                 struct GNUNET_CONVERSATION_Handle *handle,
  98                                                 const struct GNUNET_PeerIdentity *caller);
  99
 100
 101 /**
 102  * Method called whenever a call is rejected
 103  *
 104  * @param cls closure
 105  * @param handle to the conversation session
 106  * @param reason reason given for rejecting the call
 107  * @param peer peer that rejected your call
 108  */
 109 typedef void (GNUNET_CONVERSATION_RejectHandler) (void *cls,
 110                                                   struct GNUNET_CONVERSATION_Handle *handle,
 111                                                   enum GNUNET_CONVERSATION_RejectReason reason,
 112                                                   const struct GNUNET_PeerIdentity *peer);
 113
 114
 115 /**
 116  * Method called whenever a notification is there
 117  *
 118  * @param cls closure
 119  * @param handle to the conversation session
 120  * @param type the type of the notification
 121  * @param peer peer that the notification is about
 122  */
 123 typedef void (GNUNET_CONVERSATION_NotificationHandler) (void *cls,
 124                                                         struct GNUNET_CONVERSATION_Handle *handle,
 125                                                         enum GNUNET_CONVERSATION_NotificationType type,
 126                                                         const struct GNUNET_PeerIdentity *peer);
 127
 128
 129 /**
 130  * Method called whenever a notification for missed calls is there
 131  *
 132  * @param cls closure
 133  * @param handle to the conversation session
 134  * @param missed_calls a list of missed calls
 135  */
 136 typedef void (GNUNET_CONVERSATION_MissedCallHandler) (void *cls,
 137                                                       struct GNUNET_CONVERSATION_Handle *handle,
 138                                                       struct GNUNET_CONVERSATION_MissedCallNotification *missed_calls);
 139
 140
 141 /**
 142  * Connect to the VoIP service
 143  *
 144  * @param cfg configuration
 145  * @param cls NULL
 146  * @param call_handler the callback which is called when a call is incoming
 147  * @param reject_handler the callback which is called when a call is rejected
 148  * @param notification_handler the callback which is called when there is a notification
 149  * @param missed_call_handler the callback which is called when the service notifies the client about missed clients
 150  * @return handle to the connection to the conversation service
 151  */
 152 struct GNUNET_CONVERSATION_Handle *
 153 GNUNET_CONVERSATION_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
 154                              void *cls,
 155                              GNUNET_CONVERSATION_CallHandler call_handler,
 156                              GNUNET_CONVERSATION_RejectHandler reject_handler,
 157                              GNUNET_CONVERSATION_NotificationHandler notification_handler,
 158                              GNUNET_CONVERSATION_MissedCallHandler missed_call_handler);
 159
 160
 161 /**
 162  * Disconnect from the VoIP service
 163  *
 164  * @param handle handle to the VoIP connection
 165  */
 166 void
 167 GNUNET_CONVERSATION_disconnect (struct GNUNET_CONVERSATION_Handle *handle);
 168
 169
 170 /**
 171  * Establish a call
 172  *
 173  * @param handle handle to the VoIP connection
 174  * @param callee the peer (PeerIdentity or GNS name) to call
 175  * @param doGnsLookup 0 = no GNS lookup or 1  = GNS lookup
 176  */
 177 void
 178 GNUNET_CONVERSATION_call (struct GNUNET_CONVERSATION_Handle *handle,
 179                           const char *callee,
 180                           int doGnsLookup);
 181
 182
 183 /**
 184  * Terminate the active call
 185  *
 186  * @param handle handle to the VoIP connection
 187  */
 188 void
 189 GNUNET_CONVERSATION_hangup (struct GNUNET_CONVERSATION_Handle *handle);
 190
 191
 192 /**
 193  * Accept an incoming call
 194  *
 195  * @param handle handle to the VoIP connection
 196  */
 197 void
 198 GNUNET_CONVERSATION_accept (struct GNUNET_CONVERSATION_Handle *handle);
 199
 200
 201 /**
 202  * Reject an incoming call
 203  *
 204  * @param handle handle to the VoIP connection
 205  */
 206 void
 207 GNUNET_CONVERSATION_reject (struct GNUNET_CONVERSATION_Handle *handle);
 208
 209
 210
 211 ////////////////////////////////////////////////////////////////////
 212 ////////////////////////// NEW API /////////////////////////////////
 213 ////////////////////////////////////////////////////////////////////
 214
 215 /*
 216    NOTE: This API is deliberately deceptively simple; the idea
 217    is that advanced features (such as answering machines) will
 218    be done with a separate service (an answering machine service)
 219    with its own APIs; the speaker/microphone abstractions are
 220    used to facilitate plugging in custom logic for implementing
 221    such a service later by creating "software" versions of
 222    speakers and microphones that record to disk or play a file.
 223    Notifications about missed calls should similarly be done
 224    using a separate service; CONVERSATION is supposed to be just
 225    the "bare bones" voice service.
 226
 227    Meta data passing is supported so that advanced services
 228    can identify themselves appropriately.
 229
 230    As this is supposed to be a "secure" service, caller ID is of
 231    course provided as part of the basic implementation, as only the
 232    CONVERSATION service can know for sure who it is that we are
 233    talking to.x */
 234
 235
 236 #include "gnunet_identity_service.h"
 237 #include "gnunet_namestore_service.h"
 238
 239
 240 /**
 241  * A speaker is a device that can play or record audio data.
 242  */
 243 struct GNUNET_CONVERSATION_Speaker;
 244
 245
 246 /**
 247  * Create a speaker that corresponds to the speaker hardware
 248  * of our system.
 249  *
 250  * @param cfg configuration to use
 251  * @return NULL on error
 252  */
 253 struct GNUNET_CONVERSATION_Speaker *
 254 GNUNET_CONVERSATION_speaker_create_from_hardware (struct GNUNET_CONFIGURATION_Handle *cfg);
 255
 256
 257 /**
 258  * Destroy a speaker.
 259  *
 260  * @param speaker speaker to destroy
 261  */
 262 void
 263 GNUNET_CONVERSATION_speaker_destroy (struct GNUNET_CONVERSATION_Speaker *speaker);
 264
 265
 266 /**
 267  * A speaker is a device that can generate audio data.
 268  */
 269 struct GNUNET_CONVERSATION_Microphone;
 270
 271
 272 /**
 273  * Create a speaker that corresponds to the speaker hardware
 274  * of our system.
 275  *
 276  * @param cfg configuration to use
 277  * @return NULL on error
 278  */
 279 struct GNUNET_CONVERSATION_Microphone *
 280 GNUNET_CONVERSATION_microphone_create_from_hardware (struct GNUNET_CONFIGURATION_Handle *cfg);
 281
 282
 283 /**
 284  * Destroy a microphone.
 285  *
 286  * @param mic microphone to destroy
 287  */
 288 void
 289 GNUNET_CONVERSATION_microphone_destroy (struct GNUNET_CONVERSATION_Microphone *mic);
 290
 291
 292 /**
 293  * Information about the current status of a call.  Each call
 294  * progresses from ring over ready to terminated.  Steps may
 295  * be skipped.
 296  */
 297 enum GNUNET_CONVERSATION_EventCode
 298 {
 299   /**
 300    * The phone is ringing, caller ID is provided in the varargs as
 301    * a `const char *`.  The caller ID will be a GNS name.
 302    */
 303   GNUNET_CONVERSATION_EC_RING,
 304
 305   /**
 306    * We are ready to talk, metadata about the call may be supplied
 307    * as a `const char *` in the varargs.
 308    */
 309   GNUNET_CONVERSATION_EC_READY,
 310
 311   /**
 312    * The conversation was terminated, a reason may be supplied
 313    * as a `const char *` in the varargs.
 314    */
 315   GNUNET_CONVERSATION_EC_TERMINATED
 316
 317 };
 318
 319
 320 /**
 321  * Function called with an event emitted by a phone.
 322  *
 323  * @param cls closure
 324  * @param code type of the event on the phone
 325  * @param ... additional information, depends on @a code
 326  */
 327 typedef void (*GNUNET_CONVERSATION_EventHandler)(void *cls,
 328                                                  enum GNUNET_CONVERSATION_EventCode code,
 329                                                  ...);
 330
 331
 332 /**
 333  * A phone is a device that can ring to signal an incoming call and
 334  * that you can pick up to answer the call and hang up to terminate
 335  * the call.  You can also hang up a ringing phone immediately
 336  * (without picking it up) to stop it from ringing.  Phones have
 337  * caller ID.  You can ask the phone for its record and make that
 338  * record available (via GNS) to enable others to call you.
 339  * Multiple phones maybe connected to the same line (the line is
 340  * something rather internal to a phone and not obvious from it).
 341  * You can only have one conversation per phone at any time.
 342  */
 343 struct GNUNET_CONVERSATION_Phone;
 344
 345
 346 /**
 347  * Create a new phone.
 348  *
 349  * @param cfg configuration for the phone; specifies the phone service and
 350  *        which line the phone is to be connected to
 351  * @param event_handler how to notify the owner of the phone about events
 352  * @param event_handler_cls closure for @a event_handler
 353  */
 354 struct GNUNET_CONVERSATION_Phone *
 355 GNUNET_CONVERSATION_phone_create (const struct GNUNET_CONFIGURATION_Handle *cfg,
 356                                   GNUNET_CONVERSATION_EventHandler event_handler,
 357                                   void *event_handler_cls);
 358
 359
 360 /**
 361  * Fill in a namestore record with the contact information
 362  * for this phone.  Note that the filled in "data" value
 363  * is only valid until the phone is destroyed.
 364  *
 365  * @param phone phone to create a record for
 366  * @param rd namestore record to fill in
 367  */
 368 void
 369 GNUNET_CONVERSATION_phone_get_record (struct GNUNET_CONVERSATION_Phone *phone,
 370                                       struct GNUNET_NAMESTORE_RecordData *rd);
 371
 372
 373 /**
 374  * Picks up a (ringing) phone.  This will connect the speaker
 375  * to the microphone of the other party, and vice versa.
 376  *
 377  * @param phone phone to pick up
 378  * @param metadata meta data to give to the other user about the pick up event
 379  * @param speaker speaker to use
 380  * @param mic microphone to use
 381  */
 382 void
 383 GNUNET_CONVERSTATION_phone_pick_up (struct GNUNET_CONVERSATION_Phone *phone,
 384                                     const char *metadata,
 385                                     struct GNUNET_CONVERSATION_Speaker *speaker,
 386                                     struct GNUNET_CONVERSATION_Microphone *mic);
 387
 388
 389 /**
 390  * Hang up up a (possibly ringing) phone.  This will notify the other
 391  * party that we are no longer interested in talking with them.
 392  *
 393  * @param phone phone to pick up
 394  * @param reason text we give to the other party about why we terminated the conversation
 395  */
 396 void
 397 GNUNET_CONVERSTATION_phone_hang_up (struct GNUNET_CONVERSATION_Phone *phone,
 398                                     const char *reason);
 399
 400
 401 /**
 402  * Destroys a phone.
 403  *
 404  * @param phone phone to destroy
 405  */
 406 void
 407 GNUNET_CONVERSATION_phone_destroy (struct GNUNET_CONVERSATION_Phone *phone);
 408
 409
 410 /**
 411  * Handle for an outgoing call.
 412  */
 413 struct GNUNET_CONVERSATION_Call;
 414
 415
 416 /**
 417  * Call the phone of another user.
 418  *
 419  * @param cfg configuration to use, specifies our phone service
 420  * @param caller_id identity of the caller
 421  * @param callee GNS name of the callee (used to locate the callee's record)
 422  * @param speaker speaker to use (will be used automatically immediately once the
 423  *        #GNUNET_CONVERSATION_EC_READY event is generated); we will NOT generate
 424  *        a ring tone on the speaker
 425  * @param mic microphone to use (will be used automatically immediately once the
 426  *        #GNUNET_CONVERSATION_EC_READY event is generated)
 427  * @param event_handler how to notify the owner of the phone about events
 428  * @param event_handler_cls closure for @a event_handler
 429  */
 430 struct GNUNET_CONVERSATION_Call *
 431 GNUNET_CONVERSATION_call_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
 432                                 struct GNUNET_IDENTITY_Ego *caller_id,
 433                                 const char *callee,
 434                                 struct GNUNET_CONVERSATION_Speaker *speaker,
 435                                 struct GNUNET_CONVERSATION_Microphone *mic,
 436                                 GNUNET_CONVERSATION_EventHandler event_handler,
 437                                 void *event_handler_cls);
 438
 439
 440 /**
 441  * Terminate a call.  The call may be ringing or ready at this time.
 442  *
 443  * @param call call to terminate
 444  * @param reason if the call was active (ringing or ready) this will be the
 445  *        reason given to the other user for why we hung up
 446  */
 447 struct GNUNET_CONVERSATION_Call *
 448 GNUNET_CONVERSATION_call_stop (const struct GNUNET_CONVERSATION_Call *call,
 449                                const char *reason);
 450
 451
 452 #if 0                           /* keep Emacsens' auto-indent happy */
 453 {
 454 #endif
 455 #ifdef __cplusplus
 456 }
 457 #endif
 458
 459 #endif