sipdialogp2t.h

MiniSip Client with DomainKeys Authentication, Sip, Audio communications, Echo Cancel

/*
 Copyright (C) 2004-2006 the Minisip Team
 
 This library is free software; you can redistribute it and/or
 modify it under the terms of the GNU Lesser General Public
 License as published by the Free Software Foundation; either
 version 2.1 of the License, or (at your option) any later version.
 
 This library is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 Lesser General Public License for more details.
 
 You should have received a copy of the GNU Lesser General Public
 License along with this library; if not, write to the Free Software
 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
 */

/* Copyright (C) 2004 
 *
 * Authors: Erik Eliasson <[e-mail]>
 *          Johan Bilien <[e-mail]>
*/


#ifndef SipDialogP2T_H
#define SipDialogP2T_H

#include<libminisip/libminisip_config.h>

#include<libmutil/StateMachine.h>

#include<libmnetutil/IPAddress.h>

#include<libmsip/SipTransaction.h>
#include<libmsip/SipResponse.h>
#include<libmsip/SipStack.h>

#include<libminisip/codecs/Codec.h>
#include<libminisip/p2t/RtcpReceiver.h>
#include<libminisip/p2t/RtcpSender.h>
#include<libminisip/p2t/GroupList.h>
#include<libminisip/p2t/GroupListUserElement.h>
#include<libminisip/p2t/GroupListClient.h>
#include<libminisip/p2t/P2T.h>
#include<libminisip/mediahandler/MediaHandler.h>
#include<libminisip/sip/SipSoftPhoneConfiguration.h>


/**
 * The main dialog for a P2T Session.
 * The <CODE>SipDialogP2T</CODE> dialog is mainly responsible for the Floor Control in a 
 * P2T Session.
 * 
 * <p><b>Floor Control:</b><br>
 * All participants in a P2T Session shall be informed when the floor is idle. A participant
 * who wishes to take the floor shall initiate a floor request by pressing the Push-2-Talk
 * button. If the user's request is granted, then the user is notified and all other users
 * should be notified that the floor has been taken and who has taken it. Only one
 * participant in a P2T Session can be granted the floor at one time. There exists four
 * different Floor Procedures:<br>
 * Floor Request Procedure, Floor Collision Procedure, Floor Release Procedure, and
 * Floor Revoke Procedure.
 *
 * <p><b>SipDialogP2T:</b><br>
 * The Floor Control is implemented in the <code>SipDialogP2T</code> dialog and uses five
 * different transactions: <code>RtcpTransactionGetFloor, RtcpTransactionReleaseFloor, 
 * RtcpTransactioinTakenFloor, RtcpTransactionGrantFloor, RtcpTransactionIdleFloor.</code>
 * 
 * <p><b>State Machine:</b><br>
 * The state machine implemented in <code>SipDialogP2T</code> is shown in the next three
 * figures (the illustration of the state machine is split up to avoid having a too crowded
 * figure). The notation for every transition is as follows: The upper part shows the
 * incoming command plus some additional conditions that have to be fullfilled and the 
 * lower part gives a short description about the action that takes place.
 * <p>
 *
 * <img src=material/SipDialogP2T-1.gif><br>
 * Figure 1 - The Floor Request, Floor Release and Floor Revoke Procedure
 * <p><p>
 *
 * <img src=material/SipDialogP2T-2.gif><br>
 * Figure 2 - The Floor Collision Procedure
 * <p><p>
 *
 * <img src=material/SipDialogP2T-3.gif><br>
 * Figure 3 - Terminating a P2T Session
 * <p><p>
 *
 * <b>Transitions:</b>
 * <table border="0" cellspacing="0" cellpadding="5">
 * <tr bgcolor="#999999">
 * <td><font color=white><b>&nbsp;<CODE>CommandString</CODE> Input:</b></font></td>
 * <td><font color=white><b>Action:</b></font></td>
 * <td><font color=white><b>Description:</b></font></td>
 * </tr>
 * 
 * <tr><td>&nbsp;p2tGetFloor</td><td>a0_idle_talkreq</td><td>
 * starts for every participating user a <code>RtcpTransactionGetFloor</code>
 * transaction that sends Floor REQUEST messages out.
 * </td></tr>
 * 
 * <tr bgcolor="#E6E6E6"><td>&nbsp;p2tRequestAnswered<br>
 * && allAnswered()=true <br> && checkStates(P2T::STATUS_GRANT)=true
 * </td><td>a1_talkreq_talk</td><td>
 * all other users has sent a Floor GRANT message back and thus the floor
 * is granted to the local user. Sends Floor TAKEN messages to all
 * participants.
 * </td></tr>
 *
 * <tr><td>&nbsp;p2tReleaseFloor</td><td>a2_talk_releasepend</td><td>
 * starts for every user a <code>RtcpTransactionReleaseFloor</code> that  
 * sends Floor RELEASE messages out.
 * </td></tr>
 *
 * <tr bgcolor="#E6E6E6"><td>&nbsp;p2tFloorReleased</td><td>a3_releasepend_idle</td><td>
 * all users have released the floor.
 * </td></tr>
 *
 * <tr><td>&nbsp;p2tREQUEST</td><td>a4_idle_listenreq</td><td>
 * Another user has sent a REQUEST message. Starts a 
 * <code>RtcpTransactionGrantFloor</code> transaction.
 * </td></tr>
 *
 * <tr bgcolor="#E6E6E6"><td>&nbsp;p2tSendRequest</td><td>a5_listenreq_listen</td><td>
 * A user that has requested the floor before has send a Floor
 * TAKEN message and the floor is granted to him.
 * </td></tr>
 *
 * <tr><td>&nbsp;p2tRELEASE</td><td>a6_listen_idle</td><td>
 * The user that had granted floor sent a Floor RELEASE message.
 * Starts a <code>RtcpTransactionIdleFloor</code> transaction.
 * </td></tr>
 *
 * <tr bgcolor="#E6E6E6"><td>&nbsp;p2tRequestAnswered <br>
 * && allAnswered()=true<br>
 * && checkStates(P2T::STATUS_GRANT)=false <br>
 * && highestPrio()=false</td><td>a7_talkreq_listenreq</td><td>
 * All users have answered the Floor REQUEST message, but not all
 * with a Floor GRANT message. There are collisions and one or more
 * of them have a higher priority. 
 * Starts for all collisioned users with higer priority a 
 * <code>RtcpTransactionGrantFloor</code> transaction.
 * </td></tr>
 *
 * <tr><td>&nbsp;p2tRequestAnswered <br>
 * && allAnswered()=true<br>
 * && checkStates(P2T::STATUS_GRANT)=false <br>
 * && highestPrio()=true <br>
 * && u</td><td>a8_talkreq_collision</td><td>
 * All users have answered the Floor REQUEST message, but there
 * are collisions and there are one or more users with the same
 * highest priority as the local user has. Starts the timerRESEND för
 * resending the Floor REQUEST message to the collisioned users.
 * </td></tr>
 *
 * <tr bgcolor="#E6E6E6"><td>&nbsp;p2tREQUEST</td><td>a9_collision_listenreq</td><td>
 * Another user was faster with resending the Floor REQUEST message after
 * the collision, thus I have to grant him the floor. Starts a <code>
 * RtcpTransactionGrantFloor</code> transaction for this user.
 * </td></tr>
 *
 * <tr><td>&nbsp;timerRESEND</td><td>a10_collision_resent_timer</td><td>
 * The timer for resending the Floor REQUEST message to all collisoned users
 * has expired. Starts a <code>RtcpTransactionGetFloor</code> transaction for 
 * all users that have collisioned.
 * </td></tr>
 *
 * <tr bgcolor="#E6E6E6"><td>&nbsp;p2tRequestAnswered</td><td>a11_resent_collision_collison</td><td>
 * The collisioned users have answered my resended Floor REQUEST message but there
 * are again collisions. Resets the timerGRANT for the next resending of the
 * Floor REQUEST message.
 * </td></tr>
 *
 * <tr><td>&nbsp;p2tRequestAnswered <br>
 * && allAnswered()=true <br>
 * && checkStates(P2T::STATUS_GRANT)=true</td><td>a12_resent_talk</td><td>
 * All users have granted my resended Floor REQUEST message. Sends Floor
 * TAKEN messages to all participants and the floor is granted to the
 * local user.
 * </td></tr>
 
 * <tr bgcolor="#E6E6E6"><td>&nbsp;p2tRequestAnswered <br>
 * && allAnswered()=false</td><td>a13_resent_resent</td><td>
 * The command p2tRequestAnswered informs SipDialogP2T that a user has answered the
 * request. But because not all users have done this, we are staying still in the
 * 'resent' state.
 * </td></tr>
 *
 * <tr><td>&nbsp;timerREVOKE</td><td>a14_listen_listen</td><td>
 * The timerREVOKE has expired the first or second time. It sends
 * a Floor REVOKE message as warning to the granted user, that the 
 * maximum floor time is reached. Resets the timerREVOKE.
 * </td></tr>
 * 
 * <tr bgcolor="#E6E6E6"><td>&nbsp;p2tRequestAnswered <br>
 * && allAnswered=false</td><td>a15_talkreq_talkreq</td><td>
 * Because not all users have answered we do nothing and are staying
 * still in the 'talkreq' state.
 * </td></tr>
 *
 * <tr><td>&nbsp;p2tFloorReleased <br>
 * && ...
 * </td><td>a16_releasepend_relaesepend</td><td>
 * Not all users have answered the Floor RELEASE message.
 * </td></tr>
 * 
 * <tr bgcolor="#E6E6E6"><td>&nbsp;timerREVOKE</td><td>a17_listen_idle_revoke</td><td>
 * The timerREVOKE expired the third time. A final Floor REVOKE message
 * is sent and the local user moves to the 'idle' state.
 * </td></tr>
 *
 * <tr><td>&nbsp;p2tREVOKE</td><td>a18_talk_talk_revoke</td><td>
 * A remote user sent a Floor REVOKE message. Inform the GUI about that.
 * </td></tr>
 *
 * <tr bgcolor="#E6E6E6"><td>&nbsp;p2tREQUEST</td><td>a19_listenreq_listenreq</td><td>
 * Another user sent a Floor REQUEST message. Starts a <code>
 * RtcpTransactionGrantFloor</code> transactiona also for this user. 
 * Because there is a collision and one of the collisioned user
 * will send a Floor TAKEN message.
 * </td></tr>
 * 
 * <tr><td>&nbsp;p2tTerminate</td><td>a80_idle_terminated</td><td>
 * terminates the P2T Session.
 * </td></tr>
 * 
 * <tr bgcolor="#E6E6E6"><td>&nbsp;p2tTerminate</td><td>a81_talkreq_terminated</td><td>
 * terminates the P2T Session.
 * </td></tr>
 * 
 * <tr><td>&nbsp;p2tTerminate</td><td>a82_listenreq_terminated</td><td>
 * terminates the P2T Session.
 * </td></tr>
 * 
 * <tr bgcolor="#E6E6E6"><td>&nbsp;p2tTerminate</td><td>a83_talk_terminated</td><td>
 * terminates the P2T Session.
 * </td></tr>
 * 
 * <tr><td>&nbsp;p2tTerminate</td><td>a84_collision_terminated</td><td>
 * terminates the P2T Session.
 * </td></tr>
 * 
 * <tr bgcolor="#E6E6E6"><td>&nbsp;p2tTerminate</td><td>a85_listen_terminated</td><td>
 * terminates the P2T Session.
 * </td></tr>
 * 
 * <tr><td>&nbsp;p2tTerminate</td><td>a86_releasepend_terminated</td><td>
 * terminates the P2T Session.
 * </td></tr>
 *