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  * Meta data passing is supported so that advanced services
  41  * can identify themselves appropriately.
  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  * TODO:
  49  * - call waiting
  50  * - put on hold
  51  */
  52 #ifndef GNUNET_CONVERSATION_SERVICE_H
  53 #define GNUNET_CONVERSATION_SERVICE_H
  54
  55 #ifdef __cplusplus
  56 extern "C"
  57 {
  58 #if 0                           /* keep Emacsens' auto-indent happy */
  59 }
  60 #endif
  61 #endif
  62
  63 #include "gnunet_util_lib.h"
  64 #include "gnunet_identity_service.h"
  65 #include "gnunet_namestore_service.h"
  66 #include "gnunet_speaker_lib.h"
  67 #include "gnunet_microphone_lib.h"
  68
  69
  70 /**
  71  * Version of the conversation API.
  72  */
  73 #define GNUNET_CONVERSATION_VERSION 0x00000002
  74
  75
  76 /**
  77  * A phone record specifies which peer is hosting a given user and
  78  * may also specify the phone line that is used (typically zero).
  79  * The version is also right now always zero.
  80  */
  81 struct GNUNET_CONVERSATION_PhoneRecord
  82 {
  83
  84   /**
  85    * Version of the phone record, for now always zero.  We may
  86    * use other versions for anonymously hosted phone lines in
  87    * the future.
  88    */
  89   uint32_t version GNUNET_PACKED;
  90
  91   /**
  92    * Phone line to use at the peer.
  93    */
  94   uint32_t line GNUNET_PACKED;
  95
  96   /**
  97    * Identity of the peer hosting the phone service.
  98    */
  99   struct GNUNET_PeerIdentity peer;
 100
 101 };
 102
 103
 104 /**
 105  * Information about the current status of a call.  Each call
 106  * progresses from ring over ready to terminated.  Steps may
 107  * be skipped.
 108  */
 109 enum GNUNET_CONVERSATION_EventCode
 110 {
 111   /**
 112    * The phone is ringing, caller ID is provided in the varargs as
 113    * a `const char *`.  The caller ID will be a GNS name.
 114    */
 115   GNUNET_CONVERSATION_EC_RING,
 116
 117   /**
 118    * We are the caller and are now ringing the other party.
 119    * The varargs will be empty.
 120    */
 121   GNUNET_CONVERSATION_EC_RINGING,
 122
 123   /**
 124    * We are ready to talk, metadata about the call may be supplied
 125    * as a `const char *` in the varargs.
 126    */
 127   GNUNET_CONVERSATION_EC_READY,
 128
 129   /**
 130    * We failed to locate a phone record in GNS.  After this invocation,
 131    * the respective call handle will be automatically destroyed and the
 132    * client must no longer call #GNUNET_CONVERSATION_call_stop.
 133    */
 134   GNUNET_CONVERSATION_EC_GNS_FAIL,
 135
 136   /**
 137    * The phone is busy.  Varargs will be empty.   After this invocation,
 138    * the respective call handle will be automatically destroyed and the
 139    * client must no longer call #GNUNET_CONVERSATION_call_stop.
 140    */
 141   GNUNET_CONVERSATION_EC_BUSY,
 142
 143   /**
 144    * The conversation was terminated, a reason may be supplied as a
 145    * `const char *` in the varargs.  After this invocation, the
 146    * respective call handle will be automatically destroyed and the
 147    * client must no longer call #GNUNET_CONVERSATION_call_stop.
 148    */
 149   GNUNET_CONVERSATION_EC_TERMINATED
 150
 151 };
 152
 153
 154 /**
 155  * Function called with an event emitted by a phone.
 156  *
 157  * @param cls closure
 158  * @param code type of the event on the phone
 159  * @param ... additional information, depends on @a code
 160  */
 161 typedef void (*GNUNET_CONVERSATION_EventHandler)(void *cls,
 162                                                  enum GNUNET_CONVERSATION_EventCode code,
 163                                                  ...);
 164
 165
 166 /**
 167  * A phone is a device that can ring to signal an incoming call and
 168  * that you can pick up to answer the call and hang up to terminate
 169  * the call.  You can also hang up a ringing phone immediately
 170  * (without picking it up) to stop it from ringing.  Phones have
 171  * caller ID.  You can ask the phone for its record and make that
 172  * record available (via GNS) to enable others to call you.
 173  * Multiple phones maybe connected to the same line (the line is
 174  * something rather internal to a phone and not obvious from it).
 175  * You can only have one conversation per phone at any time.
 176  */
 177 struct GNUNET_CONVERSATION_Phone;
 178
 179
 180 /**
 181  * Create a new phone.
 182  *
 183  * @param cfg configuration for the phone; specifies the phone service and
 184  *        which line the phone is to be connected to
 185  * @param ego ego to use for name resolution (when determining caller ID)
 186  * @param event_handler how to notify the owner of the phone about events
 187  * @param event_handler_cls closure for @a event_handler
 188  */
 189 struct GNUNET_CONVERSATION_Phone *
 190 GNUNET_CONVERSATION_phone_create (const struct GNUNET_CONFIGURATION_Handle *cfg,
 191                                   const struct GNUNET_IDENTITY_Ego *ego,
 192                                   GNUNET_CONVERSATION_EventHandler event_handler,
 193                                   void *event_handler_cls);
 194
 195
 196 /**
 197  * Fill in a namestore record with the contact information
 198  * for this phone.  Note that the filled in "data" value
 199  * is only valid until the phone is destroyed.
 200  *
 201  * @param phone phone to create a record for
 202  * @param rd namestore record to fill in
 203  */
 204 void
 205 GNUNET_CONVERSATION_phone_get_record (struct GNUNET_CONVERSATION_Phone *phone,
 206                                       struct GNUNET_GNSRECORD_Data *rd);
 207
 208
 209 /**
 210  * Picks up a (ringing) phone.  This will connect the speaker
 211  * to the microphone of the other party, and vice versa.
 212  *
 213  * @param phone phone to pick up
 214  * @param metadata meta data to give to the other user about the pick up event
 215  * @param speaker speaker to use
 216  * @param mic microphone to use
 217  */
 218 void
 219 GNUNET_CONVERSATION_phone_pick_up (struct GNUNET_CONVERSATION_Phone *phone,
 220                                    const char *metadata,
 221                                    struct GNUNET_SPEAKER_Handle *speaker,
 222                                    struct GNUNET_MICROPHONE_Handle *mic);
 223
 224
 225 /**
 226  * Hang up up a (possibly ringing) phone.  This will notify the other
 227  * party that we are no longer interested in talking with them.
 228  *
 229  * @param phone phone to pick up
 230  * @param reason text we give to the other party about why we terminated the conversation
 231  */
 232 void
 233 GNUNET_CONVERSATION_phone_hang_up (struct GNUNET_CONVERSATION_Phone *phone,
 234                                    const char *reason);
 235
 236
 237 /**
 238  * Destroys a phone.
 239  *
 240  * @param phone phone to destroy
 241  */
 242 void
 243 GNUNET_CONVERSATION_phone_destroy (struct GNUNET_CONVERSATION_Phone *phone);
 244
 245
 246 /**
 247  * Handle for an outgoing call.
 248  */
 249 struct GNUNET_CONVERSATION_Call;
 250
 251
 252 /**
 253  * Call the phone of another user.
 254  *
 255  * @param cfg configuration to use, specifies our phone service
 256  * @param caller_id identity of the caller
 257  * @param callee GNS name of the callee (used to locate the callee's record)
 258  * @param speaker speaker to use (will be used automatically immediately once the
 259  *        #GNUNET_CONVERSATION_EC_READY event is generated); we will NOT generate
 260  *        a ring tone on the speaker
 261  * @param mic microphone to use (will be used automatically immediately once the
 262  *        #GNUNET_CONVERSATION_EC_READY event is generated)
 263  * @param event_handler how to notify the owner of the phone about events
 264  * @param event_handler_cls closure for @a event_handler
 265  */
 266 struct GNUNET_CONVERSATION_Call *
 267 GNUNET_CONVERSATION_call_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
 268                                 struct GNUNET_IDENTITY_Ego *caller_id,
 269                                 const char *callee,
 270                                 struct GNUNET_SPEAKER_Handle *speaker,
 271                                 struct GNUNET_MICROPHONE_Handle *mic,
 272                                 GNUNET_CONVERSATION_EventHandler event_handler,
 273                                 void *event_handler_cls);
 274
 275
 276 /**
 277  * Terminate a call.  The call may be ringing or ready at this time.
 278  *
 279  * @param call call to terminate
 280  * @param reason if the call was active (ringing or ready) this will be the
 281  *        reason given to the other user for why we hung up
 282  */
 283 void
 284 GNUNET_CONVERSATION_call_stop (struct GNUNET_CONVERSATION_Call *call,
 285                                const char *reason);
 286
 287
 288 #if 0                           /* keep Emacsens' auto-indent happy */
 289 {
 290 #endif
 291 #ifdef __cplusplus
 292 }
 293 #endif
 294
 295 #endif