src/conversation/conversation_api.c

   1 /*
   2   This file is part of GNUnet
   3   Copyright (C) 2013, 2014 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
  19 /**
  20  * @file conversation/conversation_api.c
  21  * @brief phone and caller API to the conversation service
  22  * @author Simon Dieterle
  23  * @author Andreas Fuchs
  24  * @author Christian Grothoff
  25  */
  26 #include "platform.h"
  27 #include "gnunet_conversation_service.h"
  28 #include "conversation.h"
  29
  30
  31 /**
  32  * Possible states of a caller.
  33  */
  34 enum CallerState
  35 {
  36   /**
  37    * The phone is ringing (user knows about incoming call).
  38    */
  39   CS_RINGING,
  40
  41   /**
  42    * The phone is in an active conversation.
  43    */
  44   CS_ACTIVE,
  45
  46   /**
  47    * We suspended the conversation.
  48    */
  49   CS_CALLEE_SUSPENDED,
  50
  51   /**
  52    * Caller suspended the conversation.
  53    */
  54   CS_CALLER_SUSPENDED,
  55
  56   /**
  57    * Both sides suspended the conversation.
  58    */
  59   CS_BOTH_SUSPENDED
  60 };
  61
  62
  63
  64 /**
  65  * A caller is the handle we have for an incoming call.
  66  */
  67 struct GNUNET_CONVERSATION_Caller
  68 {
  69
  70   /**
  71    * We keep all callers in a DLL.
  72    */
  73   struct GNUNET_CONVERSATION_Caller *next;
  74
  75   /**
  76    * We keep all callers in a DLL.
  77    */
  78   struct GNUNET_CONVERSATION_Caller *prev;
  79
  80   /**
  81    * Our phone.
  82    */
  83   struct GNUNET_CONVERSATION_Phone *phone;
  84
  85   /**
  86    * Function to call for phone events.
  87    */
  88   GNUNET_CONVERSATION_CallerEventHandler event_handler;
  89
  90   /**
  91    * Closure for @e event_handler
  92    */
  93   void *event_handler_cls;
  94
  95   /**
  96    * Speaker, or NULL if none is attached.
  97    */
  98   struct GNUNET_SPEAKER_Handle *speaker;
  99
 100   /**
 101    * Microphone, or NULL if none is attached.
 102    */
 103   struct GNUNET_MICROPHONE_Handle *mic;
 104
 105   /**
 106    * Identity of the person calling us.
 107    */
 108   struct GNUNET_CRYPTO_EcdsaPublicKey caller_id;
 109
 110   /**
 111    * Internal handle to identify the caller with the service.
 112    */
 113   uint32_t cid;
 114
 115   /**
 116    * State machine for the phone.
 117    */
 118   enum CallerState state;
 119
 120 };
 121
 122
 123 /**
 124  * Possible states of a phone.
 125  */
 126 enum PhoneState
 127 {
 128   /**
 129    * We still need to register the phone.
 130    */
 131   PS_REGISTER = 0,
 132
 133   /**
 134    * We are waiting for calls.
 135    */
 136   PS_READY
 137
 138 };
 139
 140
 141 /**
 142  * A phone is a device that can ring to signal an incoming call and
 143  * that you can pick up to answer the call and hang up to terminate
 144  * the call.  You can also hang up a ringing phone immediately
 145  * (without picking it up) to stop it from ringing.  Phones have
 146  * caller ID.  You can ask the phone for its record and make that
 147  * record available (via GNS) to enable others to call you.
 148  * Multiple phones maybe connected to the same line (the line is
 149  * something rather internal to a phone and not obvious from it).
 150  * You can only have one conversation per phone at any time.
 151  */
 152 struct GNUNET_CONVERSATION_Phone
 153 {
 154   /**
 155    * Our configuration.
 156    */
 157   const struct GNUNET_CONFIGURATION_Handle *cfg;
 158
 159   /**
 160    * We keep all callers in a DLL.
 161    */
 162   struct GNUNET_CONVERSATION_Caller *caller_head;
 163
 164   /**
 165    * We keep all callers in a DLL.
 166    */
 167   struct GNUNET_CONVERSATION_Caller *caller_tail;
 168
 169   /**
 170    * Function to call for phone events.
 171    */
 172   GNUNET_CONVERSATION_PhoneEventHandler event_handler;
 173
 174   /**
 175    * Closure for @e event_handler
 176    */
 177   void *event_handler_cls;
 178
 179   /**
 180    * Connection to NAMESTORE (for reverse lookup).
 181    */
 182   struct GNUNET_NAMESTORE_Handle *ns;
 183
 184   /**
 185    * Handle for transmitting to the CONVERSATION service.
 186    */
 187   struct GNUNET_MQ_Handle *mq;
 188
 189   /**
 190    * This phone's record.
 191    */
 192   struct GNUNET_CONVERSATION_PhoneRecord my_record;
 193
 194   /**
 195    * My GNS zone.
 196    */
 197   struct GNUNET_CRYPTO_EcdsaPrivateKey my_zone;
 198
 199   /**
 200    * State machine for the phone.
 201    */
 202   enum PhoneState state;
 203
 204 };
 205
 206
 207 /**
 208  * The phone got disconnected, reconnect to the service.
 209  *
 210  * @param phone phone to reconnect
 211  */
 212 static void
 213 reconnect_phone (struct GNUNET_CONVERSATION_Phone *phone);
 214
 215
 216 /**
 217  * Process recorded audio data.
 218  *
 219  * @param cls closure with the `struct GNUNET_CONVERSATION_Caller`
 220  * @param data_size number of bytes in @a data
 221  * @param data audio data to play
 222  */
 223 static void
 224 transmit_phone_audio (void *cls,
 225                       size_t data_size,
 226                       const void *data)
 227 {
 228   struct GNUNET_CONVERSATION_Caller *caller = cls;
 229   struct GNUNET_CONVERSATION_Phone *phone = caller->phone;
 230   struct GNUNET_MQ_Envelope *e;
 231   struct ClientAudioMessage *am;
 232
 233   e = GNUNET_MQ_msg_extra (am,
 234                            data_size,
 235                            GNUNET_MESSAGE_TYPE_CONVERSATION_CS_AUDIO);
 236   am->cid = caller->cid;
 237   GNUNET_memcpy (&am[1],
 238                  data,
 239                  data_size);
 240   GNUNET_MQ_send (phone->mq,
 241                   e);
 242 }
 243
 244
 245 /**
 246  * We received a `struct ClientPhoneRingMessage`
 247  *
 248  * @param cls the `struct GNUNET_CONVERSATION_Phone`
 249  * @param ring the message
 250  */
 251 static void
 252 handle_phone_ring (void *cls,
 253                    const struct ClientPhoneRingMessage *ring)
 254 {
 255   struct GNUNET_CONVERSATION_Phone *phone = cls;
 256   struct GNUNET_CONVERSATION_Caller *caller;
 257
 258   switch (phone->state)
 259   {
 260   case PS_REGISTER:
 261     GNUNET_assert (0);
 262     break;
 263   case PS_READY:
 264     caller = GNUNET_new (struct GNUNET_CONVERSATION_Caller);
 265     caller->phone = phone;
 266     GNUNET_CONTAINER_DLL_insert (phone->caller_head,
 267                                  phone->caller_tail,
 268                                  caller);
 269     caller->caller_id = ring->caller_id;
 270     caller->cid = ring->cid;
 271     caller->state = CS_RINGING;
 272     phone->event_handler (phone->event_handler_cls,
 273                           GNUNET_CONVERSATION_EC_PHONE_RING,
 274                           caller,
 275                           &caller->caller_id);
 276     break;
 277   }
 278 }
 279
 280
 281 /**
 282  * Find the record of the caller matching the @a cid
 283  *
 284  * @param phone phone to search
 285  * @param cid caller ID to search for (in NBO)
 286  * @return NULL if @a cid was not found
 287  */
 288 static struct GNUNET_CONVERSATION_Caller *
 289 find_caller (struct GNUNET_CONVERSATION_Phone *phone,
 290              uint32_t cid)
 291 {
 292   struct GNUNET_CONVERSATION_Caller *caller;
 293
 294   for (caller = phone->caller_head;NULL != caller;caller = caller->next)
 295     if (cid == caller->cid)
 296       return caller;
 297   return NULL;
 298 }
 299
 300
 301 /**
 302  * We received a `struct ClientPhoneHangupMessage`.
 303  *
 304  * @param cls the `struct GNUNET_CONVERSATION_Phone *`
 305  * @param msg the message
 306  */
 307 static void
 308 handle_phone_hangup (void *cls,
 309                      const struct ClientPhoneHangupMessage *hang)
 310 {
 311   struct GNUNET_CONVERSATION_Phone *phone = cls;
 312   struct GNUNET_CONVERSATION_Caller *caller;
 313
 314   caller = find_caller (phone,
 315                         hang->cid);
 316   if (NULL == caller)
 317   {
 318     GNUNET_log (GNUNET_ERROR_TYPE_DEBUG,
 319                 "Received HANG_UP message for unknown caller ID %u\n",
 320                 (unsigned int) hang->cid);
 321     return;
 322   }
 323
 324   GNUNET_log (GNUNET_ERROR_TYPE_DEBUG,
 325               "Received HANG_UP message, terminating call with `%s'\n",
 326               GNUNET_GNSRECORD_pkey_to_zkey (&caller->caller_id));
 327   switch (caller->state)
 328   {
 329   case CS_RINGING:
 330     phone->event_handler (phone->event_handler_cls,
 331                           GNUNET_CONVERSATION_EC_PHONE_HUNG_UP,
 332                           caller,
 333                           &caller->caller_id);
 334     break;
 335   case CS_ACTIVE:
 336     caller->speaker->disable_speaker (caller->speaker->cls);
 337     caller->mic->disable_microphone (caller->mic->cls);
 338     phone->event_handler (phone->event_handler_cls,
 339                           GNUNET_CONVERSATION_EC_PHONE_HUNG_UP,
 340                           caller,
 341                           &caller->caller_id);
 342     break;
 343   case CS_CALLEE_SUSPENDED:
 344   case CS_CALLER_SUSPENDED:
 345   case CS_BOTH_SUSPENDED:
 346     phone->event_handler (phone->event_handler_cls,
 347                           GNUNET_CONVERSATION_EC_PHONE_HUNG_UP,
 348                           caller,
 349                           &caller->caller_id);
 350     break;
 351   }
 352   GNUNET_CONTAINER_DLL_remove (phone->caller_head,
 353                                phone->caller_tail,
 354                                caller);
 355   GNUNET_free (caller);
 356 }
 357
 358
 359 /**
 360  * We received a `struct ClientPhoneSuspendMessage`.
 361  *
 362  * @param cls the `struct GNUNET_CONVERSATION_Phone`
 363  * @param suspend the message
 364  */
 365 static void
 366 handle_phone_suspend (void *cls,
 367                       const struct ClientPhoneSuspendMessage *suspend)
 368 {
 369   struct GNUNET_CONVERSATION_Phone *phone = cls;
 370   struct GNUNET_CONVERSATION_Caller *caller;
 371
 372   caller = find_caller (phone,
 373                         suspend->cid);
 374   if (NULL == caller)
 375     return;
 376   switch (caller->state)
 377   {
 378   case CS_RINGING:
 379     GNUNET_break_op (0);
 380     break;
 381   case CS_ACTIVE:
 382     caller->state = CS_CALLER_SUSPENDED;
 383     caller->speaker->disable_speaker (caller->speaker->cls);
 384     caller->mic->disable_microphone (caller->mic->cls);
 385     caller->event_handler (caller->event_handler_cls,
 386                            GNUNET_CONVERSATION_EC_CALLER_SUSPEND);
 387     break;
 388   case CS_CALLEE_SUSPENDED:
 389     caller->state = CS_BOTH_SUSPENDED;
 390     caller->event_handler (caller->event_handler_cls,
 391                            GNUNET_CONVERSATION_EC_CALLER_SUSPEND);
 392     break;
 393   case CS_CALLER_SUSPENDED:
 394   case CS_BOTH_SUSPENDED:
 395     GNUNET_break_op (0);
 396     break;
 397   }
 398 }
 399
 400
 401 /**
 402  * We received a `struct ClientPhoneResumeMessage`.
 403  *
 404  * @param cls the `struct GNUNET_CONVERSATION_Phone`
 405  * @param resume the message
 406  */
 407 static void
 408 handle_phone_resume (void *cls,
 409                      const struct ClientPhoneResumeMessage *resume)
 410 {
 411   struct GNUNET_CONVERSATION_Phone *phone = cls;
 412   struct GNUNET_CONVERSATION_Caller *caller;
 413
 414   caller = find_caller (phone,
 415                         resume->cid);
 416   if (NULL == caller)
 417     return;
 418   switch (caller->state)
 419   {
 420   case CS_RINGING:
 421     GNUNET_break_op (0);
 422     break;
 423   case CS_ACTIVE:
 424   case CS_CALLEE_SUSPENDED:
 425     GNUNET_break_op (0);
 426     break;
 427   case CS_CALLER_SUSPENDED:
 428     caller->state = CS_ACTIVE;
 429     caller->speaker->enable_speaker (caller->speaker->cls);
 430     caller->mic->enable_microphone (caller->mic->cls,
 431                                     &transmit_phone_audio,
 432                                     caller);
 433     caller->event_handler (caller->event_handler_cls,
 434                            GNUNET_CONVERSATION_EC_CALLER_RESUME);
 435     break;
 436   case CS_BOTH_SUSPENDED:
 437     caller->state = CS_CALLEE_SUSPENDED;
 438     caller->event_handler (caller->event_handler_cls,
 439                            GNUNET_CONVERSATION_EC_CALLER_RESUME);
 440     break;
 441   }
 442 }
 443
 444
 445 /**
 446  * We received a `struct ClientAudioMessage`, check it is well-formed.
 447  *
 448  * @param cls the `struct GNUNET_CONVERSATION_Phone`
 449  * @param am the message
 450  * @return #GNUNET_OK if @a am is well-formed
 451  */
 452 static int
 453 check_phone_audio (void *cls,
 454                    const struct ClientAudioMessage *am)
 455 {
 456   (void) cls;
 457   (void) am;
 458
 459   /* any variable-size payload is OK */
 460   return GNUNET_OK;
 461 }
 462
 463
 464 /**
 465  * We received a `struct ClientAudioMessage`
 466  *
 467  * @param cls the `struct GNUNET_CONVERSATION_Phone`
 468  * @param am the message
 469  */
 470 static void
 471 handle_phone_audio (void *cls,
 472                     const struct ClientAudioMessage *am)
 473 {
 474   struct GNUNET_CONVERSATION_Phone *phone = cls;
 475   struct GNUNET_CONVERSATION_Caller *caller;
 476
 477   caller = find_caller (phone,
 478                         am->cid);
 479   if (NULL == caller)
 480     return;
 481   switch (caller->state)
 482   {
 483   case CS_RINGING:
 484     GNUNET_break_op (0);
 485     break;
 486   case CS_ACTIVE:
 487     caller->speaker->play (caller->speaker->cls,
 488                            ntohs (am->header.size) - sizeof (struct ClientAudioMessage),
 489                            &am[1]);
 490     break;
 491   case CS_CALLEE_SUSPENDED:
 492   case CS_CALLER_SUSPENDED:
 493   case CS_BOTH_SUSPENDED:
 494     break;
 495   }
 496 }
 497
 498
 499 /**
 500  * We encountered an error talking with the conversation service.
 501  *
 502  * @param cls the `struct GNUNET_CONVERSATION_Phone`
 503  * @param error details about the error
 504  */
 505 static void
 506 phone_error_handler (void *cls,
 507                      enum GNUNET_MQ_Error error)
 508 {
 509   struct GNUNET_CONVERSATION_Phone *phone = cls;
 510
 511   (void) error;
 512   GNUNET_log (GNUNET_ERROR_TYPE_WARNING,
 513               _("Connection to conversation service lost, trying to reconnect\n"));
 514   reconnect_phone (phone);
 515 }
 516
 517
 518 /**
 519  * Clean up all callers of the given phone.
 520  *
 521  * @param phone phone to clean up callers for
 522  */
 523 static void
 524 clean_up_callers (struct GNUNET_CONVERSATION_Phone *phone)
 525 {
 526   struct GNUNET_CONVERSATION_Caller *caller;
 527
 528   while (NULL != (caller = phone->caller_head))
 529   {
 530     /* make sure mic/speaker are disabled *before* callback */
 531     if (CS_ACTIVE == caller->state)
 532     {
 533       caller->speaker->disable_speaker (caller->speaker->cls);
 534       caller->mic->disable_microphone (caller->mic->cls);
 535       caller->state = CS_CALLER_SUSPENDED;
 536     }
 537     phone->event_handler (phone->event_handler_cls,
 538                           GNUNET_CONVERSATION_EC_PHONE_HUNG_UP,
 539                           caller,
 540                           &caller->caller_id);
 541     GNUNET_CONVERSATION_caller_hang_up (caller);
 542   }
 543 }
 544
 545
 546 /**
 547  * The phone got disconnected, reconnect to the service.
 548  *
 549  * @param phone phone to reconnect
 550  */
 551 static void
 552 reconnect_phone (struct GNUNET_CONVERSATION_Phone *phone)
 553 {
 554   struct GNUNET_MQ_MessageHandler handlers[] = {
 555     GNUNET_MQ_hd_fixed_size (phone_ring,
 556                              GNUNET_MESSAGE_TYPE_CONVERSATION_CS_PHONE_RING,
 557                              struct ClientPhoneRingMessage,
 558                              phone),
 559     GNUNET_MQ_hd_fixed_size (phone_hangup,
 560                              GNUNET_MESSAGE_TYPE_CONVERSATION_CS_PHONE_HANG_UP,
 561                              struct ClientPhoneHangupMessage,
 562                              phone),
 563     GNUNET_MQ_hd_fixed_size (phone_suspend,
 564                              GNUNET_MESSAGE_TYPE_CONVERSATION_CS_PHONE_SUSPEND,
 565                              struct ClientPhoneSuspendMessage,
 566                              phone),
 567     GNUNET_MQ_hd_fixed_size (phone_resume,
 568                              GNUNET_MESSAGE_TYPE_CONVERSATION_CS_PHONE_RESUME,
 569                              struct ClientPhoneResumeMessage,
 570                              phone),
 571     GNUNET_MQ_hd_var_size (phone_audio,
 572                            GNUNET_MESSAGE_TYPE_CONVERSATION_CS_AUDIO,
 573                            struct ClientAudioMessage,
 574                            phone),
 575     GNUNET_MQ_handler_end ()
 576   };
 577   struct GNUNET_MQ_Envelope *e;
 578   struct ClientPhoneRegisterMessage *reg;
 579
 580   clean_up_callers (phone);
 581   if (NULL != phone->mq)
 582   {
 583     GNUNET_MQ_destroy (phone->mq);
 584     phone->mq = NULL;
 585   }
 586   phone->state = PS_REGISTER;
 587   phone->mq = GNUNET_CLIENT_connect (phone->cfg,
 588                                      "conversation",
 589                                      handlers,
 590                                      &phone_error_handler,
 591                                      phone);
 592   if (NULL == phone->mq)
 593     return;
 594   e = GNUNET_MQ_msg (reg,
 595                      GNUNET_MESSAGE_TYPE_CONVERSATION_CS_PHONE_REGISTER);
 596   reg->line_port = phone->my_record.line_port;
 597   GNUNET_MQ_send (phone->mq,
 598                   e);
 599   phone->state = PS_READY;
 600 }
 601
 602
 603 /**
 604  * Create a new phone.
 605  *
 606  * @param cfg configuration for the phone; specifies the phone service and
 607  *        which line the phone is to be connected to
 608  * @param ego ego to use for name resolution (when determining caller ID)
 609  * @param event_handler how to notify the owner of the phone about events
 610  * @param event_handler_cls closure for @a event_handler
 611  * @return NULL on error (no valid line configured)
 612  */
 613 struct GNUNET_CONVERSATION_Phone *
 614 GNUNET_CONVERSATION_phone_create (const struct GNUNET_CONFIGURATION_Handle *cfg,
 615                                   const struct GNUNET_IDENTITY_Ego *ego,
 616                                   GNUNET_CONVERSATION_PhoneEventHandler event_handler,
 617                                   void *event_handler_cls)
 618 {
 619   struct GNUNET_CONVERSATION_Phone *phone;
 620   char *line;
 621   struct GNUNET_HashCode line_port;
 622
 623   if (GNUNET_OK !=
 624       GNUNET_CONFIGURATION_get_value_string (cfg,
 625                                              "CONVERSATION",
 626                                              "LINE",
 627                                              &line))
 628   {
 629     GNUNET_log_config_missing (GNUNET_ERROR_TYPE_ERROR,
 630                                "CONVERSATION",
 631                                "LINE");
 632     return NULL;
 633   }
 634   GNUNET_CRYPTO_hash (line,
 635                       strlen (line),
 636                       &line_port);
 637   phone = GNUNET_new (struct GNUNET_CONVERSATION_Phone);
 638   if (GNUNET_OK !=
 639       GNUNET_CRYPTO_get_peer_identity (cfg,
 640                                        &phone->my_record.peer))
 641   {
 642     GNUNET_break (0);
 643     GNUNET_free (phone);
 644     return NULL;
 645   }
 646   phone->cfg = cfg;
 647   phone->my_zone = *GNUNET_IDENTITY_ego_get_private_key (ego);
 648   phone->event_handler = event_handler;
 649   phone->event_handler_cls = event_handler_cls;
 650   phone->ns = GNUNET_NAMESTORE_connect (cfg);
 651   phone->my_record.version = htonl (1);
 652   phone->my_record.reserved = htonl (0);
 653   phone->my_record.line_port = line_port;
 654   reconnect_phone (phone);
 655   if ( (NULL == phone->mq) ||
 656        (NULL == phone->ns) )
 657   {
 658     GNUNET_break (0);
 659     GNUNET_CONVERSATION_phone_destroy (phone);
 660     return NULL;
 661   }
 662   return phone;
 663 }
 664
 665
 666 /**
 667  * Fill in a namestore record with the contact information
 668  * for this phone.  Note that the filled in "data" value
 669  * is only valid until the phone is destroyed.
 670  *
 671  * @param phone phone to create a record for
 672  * @param rd namestore record to fill in
 673  */
 674 void
 675 GNUNET_CONVERSATION_phone_get_record (struct GNUNET_CONVERSATION_Phone *phone,
 676                                       struct GNUNET_GNSRECORD_Data *rd)
 677 {
 678   rd->data = &phone->my_record;
 679   rd->expiration_time = 0;
 680   rd->data_size = sizeof (struct GNUNET_CONVERSATION_PhoneRecord);
 681   rd->record_type = GNUNET_GNSRECORD_TYPE_PHONE;
 682   rd->flags = GNUNET_GNSRECORD_RF_NONE;
 683 }
 684
 685
 686 /**
 687  * Picks up a (ringing) phone.  This will connect the speaker
 688  * to the microphone of the other party, and vice versa.
 689  *
 690  * @param caller handle that identifies which caller should be answered
 691  * @param event_handler how to notify about events by the caller
 692  * @param event_handler_cls closure for @a event_handler
 693  * @param speaker speaker to use
 694  * @param mic microphone to use
 695  */
 696 void
 697 GNUNET_CONVERSATION_caller_pick_up (struct GNUNET_CONVERSATION_Caller *caller,
 698                                     GNUNET_CONVERSATION_CallerEventHandler event_handler,
 699                                     void *event_handler_cls,
 700                                     struct GNUNET_SPEAKER_Handle *speaker,
 701                                     struct GNUNET_MICROPHONE_Handle *mic)
 702 {
 703   struct GNUNET_CONVERSATION_Phone *phone = caller->phone;
 704   struct GNUNET_MQ_Envelope *e;
 705   struct ClientPhonePickupMessage *pick;
 706
 707   GNUNET_assert (CS_RINGING == caller->state);
 708   caller->speaker = speaker;
 709   caller->mic = mic;
 710   e = GNUNET_MQ_msg (pick,
 711                      GNUNET_MESSAGE_TYPE_CONVERSATION_CS_PHONE_PICK_UP);
 712   pick->cid = caller->cid;
 713   GNUNET_MQ_send (phone->mq,
 714                   e);
 715   caller->state = CS_ACTIVE;
 716   caller->event_handler = event_handler;
 717   caller->event_handler_cls = event_handler_cls;
 718   caller->speaker->enable_speaker (caller->speaker->cls);
 719   caller->mic->enable_microphone (caller->mic->cls,
 720                                   &transmit_phone_audio,
 721                                   caller);
 722 }
 723
 724
 725 /**
 726  * Hang up up a (possibly ringing) phone.  This will notify the other
 727  * party that we are no longer interested in talking with them.
 728  *
 729  * @param caller conversation to hang up on
 730  */
 731 void
 732 GNUNET_CONVERSATION_caller_hang_up (struct GNUNET_CONVERSATION_Caller *caller)
 733 {
 734   struct GNUNET_CONVERSATION_Phone *phone = caller->phone;
 735   struct GNUNET_MQ_Envelope *e;
 736   struct ClientPhoneHangupMessage *hang;
 737
 738   switch (caller->state)
 739   {
 740   case CS_ACTIVE:
 741     caller->speaker->disable_speaker (caller->speaker->cls);
 742     caller->mic->disable_microphone (caller->mic->cls);
 743     break;
 744   default:
 745     break;
 746   }
 747   GNUNET_CONTAINER_DLL_remove (phone->caller_head,
 748                                phone->caller_tail,
 749                                caller);
 750   e = GNUNET_MQ_msg (hang,
 751                      GNUNET_MESSAGE_TYPE_CONVERSATION_CS_PHONE_HANG_UP);
 752   hang->cid = caller->cid;
 753   GNUNET_MQ_send (phone->mq,
 754                   e);
 755   GNUNET_free (caller);
 756 }
 757
 758
 759 /**
 760  * Destroys a phone.
 761  *
 762  * @param phone phone to destroy
 763  */
 764 void
 765 GNUNET_CONVERSATION_phone_destroy (struct GNUNET_CONVERSATION_Phone *phone)
 766 {
 767   clean_up_callers (phone);
 768   if (NULL != phone->ns)
 769   {
 770     GNUNET_NAMESTORE_disconnect (phone->ns);
 771     phone->ns = NULL;
 772   }
 773   if (NULL != phone->mq)
 774   {
 775     GNUNET_MQ_destroy (phone->mq);
 776     phone->mq = NULL;
 777   }
 778   GNUNET_free (phone);
 779 }
 780
 781
 782 /**
 783  * Pause conversation of an active call.  This will disconnect the speaker
 784  * and the microphone.  The call can later be resumed with
 785  * #GNUNET_CONVERSATION_caller_resume.
 786  *
 787  * @param caller call to suspend
 788  */
 789 void
 790 GNUNET_CONVERSATION_caller_suspend (struct GNUNET_CONVERSATION_Caller *caller)
 791 {
 792   struct GNUNET_CONVERSATION_Phone *phone = caller->phone;
 793   struct GNUNET_MQ_Envelope *e;
 794   struct ClientPhoneSuspendMessage *suspend;
 795
 796   GNUNET_assert ( (CS_ACTIVE == caller->state) ||
 797                   (CS_CALLER_SUSPENDED == caller->state) );
 798   if (CS_ACTIVE == caller->state)
 799   {
 800     caller->speaker->disable_speaker (caller->speaker->cls);
 801     caller->mic->disable_microphone (caller->mic->cls);
 802   }
 803   caller->speaker = NULL;
 804   caller->mic = NULL;
 805   e = GNUNET_MQ_msg (suspend,
 806                      GNUNET_MESSAGE_TYPE_CONVERSATION_CS_PHONE_SUSPEND);
 807   suspend->cid = caller->cid;
 808   GNUNET_MQ_send (phone->mq,
 809                   e);
 810   if (CS_ACTIVE == caller->state)
 811     caller->state = CS_CALLEE_SUSPENDED;
 812   else
 813     caller->state = CS_BOTH_SUSPENDED;
 814 }
 815
 816
 817 /**
 818  * Resume suspended conversation of a phone.
 819  *
 820  * @param caller call to resume
 821  * @param speaker speaker to use
 822  * @param mic microphone to use
 823  */
 824 void
 825 GNUNET_CONVERSATION_caller_resume (struct GNUNET_CONVERSATION_Caller *caller,
 826                                    struct GNUNET_SPEAKER_Handle *speaker,
 827                                    struct GNUNET_MICROPHONE_Handle *mic)
 828 {
 829   struct GNUNET_CONVERSATION_Phone *phone = caller->phone;
 830   struct GNUNET_MQ_Envelope *e;
 831   struct ClientPhoneResumeMessage *resume;
 832
 833   GNUNET_assert ( (CS_CALLEE_SUSPENDED == caller->state) ||
 834                   (CS_BOTH_SUSPENDED == caller->state) );
 835   caller->speaker = speaker;
 836   caller->mic = mic;
 837   e = GNUNET_MQ_msg (resume,
 838                      GNUNET_MESSAGE_TYPE_CONVERSATION_CS_PHONE_RESUME);
 839   resume->cid = caller->cid;
 840   GNUNET_MQ_send (phone->mq,
 841                   e);
 842   if (CS_CALLEE_SUSPENDED == caller->state)
 843   {
 844     caller->state = CS_ACTIVE;
 845     caller->speaker->enable_speaker (caller->speaker->cls);
 846     caller->mic->enable_microphone (caller->mic->cls,
 847                                     &transmit_phone_audio,
 848                                     caller);
 849   }
 850   else
 851   {
 852     caller->state = CS_CALLER_SUSPENDED;
 853   }
 854 }
 855
 856 /* end of conversation_api.c */