connection.h

Go to the documentation of this file.

/*
 * connection.h
 *
 * Telephony connection abstraction
 *
 * Open Phone Abstraction Library (OPAL)
 * Formally known as the Open H323 project.
 *
 * Copyright (c) 2001 Equivalence Pty. Ltd.
 *
 * The contents of this file are subject to the Mozilla Public License
 * Version 1.0 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS"
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 * the License for the specific language governing rights and limitations
 * under the License.
 *
 * The Original Code is Open Phone Abstraction Library.
 *
 * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
 *
 * Contributor(s): Post Increment
 *     Portions of this code were written with the assistance of funding from
 *     US Joint Forces Command Joint Concept Development & Experimentation (J9)
 *     http://www.jfcom.mil/about/abt_j9.htm
 *
 * $Log: connection.h,v $
 * Revision 2.89  2007/08/24 07:47:46  csoutheren
 * Get access to called URL
 *
 * Revision 2.88  2007/08/13 16:19:08  csoutheren
 * Ensure CreateMediaStream is only called *once* for each stream in H.323 calls
 *
 * Revision 2.87  2007/07/26 00:38:56  csoutheren
 * Make transmission of RFC2833 independent of the media stream
 *
 * Revision 2.86  2007/06/29 06:59:56  rjongbloed
 * Major improvement to the "product info", normalising H.221 and User-Agent mechanisms.
 *
 * Revision 2.85  2007/06/28 12:08:26  rjongbloed
 * Simplified mutex strategy to avoid some wierd deadlocks. All locking of access
 *   to an OpalConnection must be via the PSafeObject locks.
 *
 * Revision 2.84  2007/05/23 11:10:45  dsandras
 * Added missing check for PDTMFDecoder presence in PWLIB.
 *
 * Revision 2.83  2007/05/15 07:26:38  csoutheren
 * Remove deprecated  interface to STUN server in H323Endpoint
 * Change UseNATForIncomingCall to IsRTPNATEnabled
 * Various cleanups of messy and unused code
 *
 * Revision 2.82  2007/05/15 05:24:50  csoutheren
 * Add UseNATForIncomingCall override so applications can optionally implement their own NAT activation strategy
 *
 * Revision 2.81  2007/05/07 14:13:51  csoutheren
 * Add call record capability
 *
 * Revision 2.80  2007/04/26 07:01:01  csoutheren
 * Add extra code to deal with getting media formats from connections early enough to do proper
 * gatewaying between calls. The SIP and H.323 code need to have the handing of the remote
 * and local formats standardized, but this will do for now
 *
 * Revision 2.79  2007/04/18 00:00:44  csoutheren
 * Add hooks for recording call audio
 *
 * Revision 2.78  2007/04/03 05:27:29  rjongbloed
 * Cleaned up somewhat confusing usage of the OnAnswerCall() virtual
 *   function. The name is innaccurate and exists as a legacy from the
 *   OpenH323 days. it now only indicates how alerting is done
 *   (with/without media) and does not actually answer the call.
 *
 * Revision 2.77  2007/03/13 00:32:16  csoutheren
 * Simple but messy changes to allow compile time removal of protocol
 * options such as H.450 and H.460
 * Fix MakeConnection overrides
 *
 * Revision 2.76  2007/03/01 05:51:03  rjongbloed
 * Fixed backward compatibility of OnIncomingConnection() virtual
 *   functions on various classes. If an old override returned FALSE
 *   then it will now abort the call as it used to.
 *
 * Revision 2.75  2007/03/01 05:05:20  csoutheren
 * Fixed problem with override of OnIncomingConnection
 *
 * Revision 2.74  2007/03/01 03:52:31  csoutheren
 * Use local jitter buffer values rather than getting direct from OpalManager
 * Allow OpalConnection string options to be set during incoming calls
 *
 * Revision 2.73  2007/02/23 01:01:35  csoutheren
 * Added abilty to set Q.931 codes through normal OpalConnection::CallEndReason
 *
 * Revision 2.72  2007/02/19 04:42:27  csoutheren
 * Added OnIncomingMediaChannels so incoming calls can optionally be handled in two stages
 *
 * Revision 2.71  2007/02/12 02:44:27  csoutheren
 * Start of support for ZRTP
 *
 *
 * Revision 2.70  2007/01/24 04:00:56  csoutheren
 * Arrrghh. Changing OnIncomingConnection turned out to have a lot of side-effects
 * Added some pure viritual functions to prevent old code from breaking silently
 * New OpalEndpoint and OpalConnection descendants will need to re-implement
 * OnIncomingConnection. Sorry :)
 *
 * Revision 2.69  2007/01/18 04:45:16  csoutheren
 * Messy, but simple change to add additional options argument to OpalConnection constructor
 * This allows the provision of non-trivial arguments for connections
 *
 * Revision 2.68  2006/12/18 03:18:41  csoutheren
 * Messy but simple fixes
 *   - Add access to SIP REGISTER timeout
 *   - Ensure OpalConnection options are correctly progagated
 *
 * Revision 2.67  2006/12/08 04:22:06  csoutheren
 * Applied 1589261 - new release cause for fxo endpoints
 * Thanks to Frederic Heem
 *
 * Revision 2.66  2006/11/20 03:37:12  csoutheren
 * Allow optional inclusion of RTP aggregation
 *
 * Revision 2.65  2006/11/11 12:23:18  hfriederich
 * Code reorganisation to improve RFC2833 handling for both SIP and H.323. Thanks Simon Zwahlen for the idea
 *
 * Revision 2.64  2006/10/28 16:40:28  dsandras
 * Fixed SIP reinvite without breaking H.323 calls.
 *
 * Revision 2.63  2006/10/10 07:18:18  csoutheren
 * Allow compilation with and without various options
 *
 * Revision 2.62  2006/09/28 07:42:17  csoutheren
 * Merge of useful SRTP implementation
 *
 * Revision 2.61  2006/08/29 08:47:43  rjongbloed
 * Added functions to get average audio signal level from audio streams in
 *   suitable connection types.
 *
 * Revision 2.60  2006/08/28 00:07:43  csoutheren
 * Applied 1545125 - SetPhase mutex protection and transition control
 * Thanks to Drazen Dimoti
 *
 * Revision 2.59  2006/08/17 23:09:03  rjongbloed
 * Added volume controls
 *
 * Revision 2.58  2006/08/10 05:10:30  csoutheren
 * Various H.323 stability patches merged in from DeimosPrePLuginBranch
 *
 * Revision 2.57  2006/08/03 04:57:12  csoutheren
 * Port additional NAT handling logic from OpenH323 and extend into OpalConnection class
 *
 * Revision 2.56.2.1  2006/08/09 12:49:21  csoutheren
 * Improve stablity under heavy H.323 load
 *
 * Revision 2.56  2006/06/27 13:07:37  csoutheren
 * Patch 1374533 - add h323 Progress handling
 * Thanks to Frederich Heem
 *
 * Revision 2.55  2006/06/09 04:22:24  csoutheren
 * Implemented mapping between SIP release codes and Q.931 codes as specified
 *  by RFC 3398
 *
 * Revision 2.54  2006/05/30 04:58:06  csoutheren
 * Added suport for SIP INFO message (untested as yet)
 * Fixed some issues with SIP state machine on answering calls
 * Fixed some formatting issues
 *
 * Revision 2.53  2006/04/20 16:52:22  hfriederich
 * Adding support for H.224/H.281
 *
 * Revision 2.52  2006/03/20 10:37:47  csoutheren
 * Applied patch #1453753 - added locking on media stream manipulation
 * Thanks to Dinis Rosario
 *
 * Revision 2.51  2006/02/22 10:40:09  csoutheren
 * Added patch #1374583 from Frederic Heem
 * Added additional H.323 virtual function
 *
 * Revision 2.50  2006/02/02 07:02:56  csoutheren
 * Added RTP payload map to transcoders and connections to allow remote SIP endpoints
 * to change the payload type used for outgoing RTP.
 *
 * Revision 2.49  2006/01/09 12:19:06  csoutheren
 * Added member variables to capture incoming destination addresses
 *
 * Revision 2.48  2005/12/06 21:32:24  dsandras
 * Applied patch from Frederic Heem <frederic.heem _Atttt_ telsey.it> to fix
 * assert in PSyncPoint when OnReleased is called twice from different threads.
 * Thanks! (Patch #1374240)
 *
 * Revision 2.47  2005/11/30 13:35:26  csoutheren
 * Changed tags for Doxygen
 *
 * Revision 2.46  2005/11/24 20:31:54  dsandras
 * Added support for echo cancelation using Speex.
 * Added possibility to add a filter to an OpalMediaPatch for all patches of a connection.
 *
 * Revision 2.45  2005/10/04 12:57:18  rjongbloed
 * Removed CanOpenSourceMediaStream/CanOpenSinkMediaStream functions and
 *   now use overides on OpenSourceMediaStream/OpenSinkMediaStream
 *
 * Revision 2.44  2005/09/15 17:02:40  dsandras
 * Added the possibility for a connection to prevent the opening of a sink/source media stream.
 *
 * Revision 2.43  2005/08/24 10:43:51  rjongbloed
 * Changed create video functions yet again so can return pointers that are not to be deleted.
 *
 * Revision 2.42  2005/08/23 12:45:09  rjongbloed
 * Fixed creation of video preview window and setting video grab/display initial frame size.
 *
 * Revision 2.41  2005/08/04 17:21:01  dsandras
 * Added functions to close/remove the media streams of a connection.
 *
 * Revision 2.40  2005/07/14 08:51:17  csoutheren
 * Removed CreateExternalRTPAddress - it's not needed because you can override GetMediaAddress
 * to do the same thing
 * Fixed problems with logic associated with media bypass
 *
 * Revision 2.39  2005/07/11 06:52:15  csoutheren
 * Added support for outgoing calls using external RTP
 *
 * Revision 2.38  2005/07/11 01:52:23  csoutheren
 * Extended AnsweringCall to work for SIP as well as H.323
 * Fixed problems with external RTP connection in H.323
 * Added call to OnClosedMediaStream
 *
 * Revision 2.37  2005/04/11 11:12:00  dsandras
 * Fixed previous commit.
 *
 * Revision 2.36  2005/04/11 10:42:35  dsandras
 * Fixed previous commit.
 *
 * Revision 2.35  2005/04/10 20:43:39  dsandras
 * Added support for function allowing to put the OpalMediaStreams on pause.
 *
 * Revision 2.34  2005/04/10 20:42:33  dsandras
 * Added support for a function that returns the "best guess" callback URL.
 *
 * Revision 2.33  2005/04/10 20:41:29  dsandras
 * Added support for call hold.
 *
 * Revision 2.32  2005/04/10 20:40:20  dsandras
 * Added support for Blind Transfert.
 *
 * Revision 2.31  2005/01/16 11:28:05  csoutheren
 * Added GetIdentifier virtual function to OpalConnection, and changed H323
 * and SIP descendants to use this function. This allows an application to
 * obtain a GUID for any connection regardless of the protocol used
 *
 * Revision 2.30  2004/12/12 12:29:02  dsandras
 * Moved GetRemoteApplication () to OpalConnection so that it is usable for all types of connection.
 *
 * Revision 2.29  2004/08/14 07:56:29  rjongbloed
 * Major revision to utilise the PSafeCollection classes for the connections and calls.
 *
 * Revision 2.28  2004/05/17 13:24:18  rjongbloed
 * Added silence suppression.
 *
 * Revision 2.27  2004/05/01 10:00:51  rjongbloed
 * Fixed ClearCallSynchronous so now is actually signalled when call is destroyed.
 *
 * Revision 2.26  2004/04/26 04:33:05  rjongbloed
 * Move various call progress times from H.323 specific to general conenction.
 *
 * Revision 2.25  2004/04/18 13:31:28  rjongbloed
 * Added new end call value from OpenH323.
 *
 * Revision 2.24  2004/03/13 06:25:50  rjongbloed
 * Slight rearrangement of local party name and alias list to beter match common
 *   behaviour in ancestor.
 * Abstracted local party name for endpoint into ancestor from H.,323.
 *
 * Revision 2.23  2004/03/11 06:54:27  csoutheren
 * Added ability to disable SIP or H.323 stacks
 *
 * Revision 2.22  2004/02/24 11:28:45  rjongbloed
 * Normalised RTP session management across protocols
 *
 * Revision 2.21  2003/03/17 10:26:59  robertj
 * Added video support.
 *
 * Revision 2.20  2003/03/06 03:57:47  robertj
 * IVR support (work in progress) requiring large changes everywhere.
 *
 * Revision 2.19  2003/01/07 04:39:53  robertj
 * Updated to OpenH323 v1.11.2
 *
 * Revision 2.18  2002/11/10 11:33:17  robertj
 * Updated to OpenH323 v1.10.3
 *
 * Revision 2.17  2002/09/16 02:52:35  robertj
 * Added #define so can select if #pragma interface/implementation is used on
 *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
 *
 * Revision 2.16  2002/09/12 06:54:06  robertj
 * Added missing virtual to Release() function so can be overridden.
 *
 * Revision 2.15  2002/07/01 04:56:30  robertj
 * Updated to OpenH323 v1.9.1
 *
 * Revision 2.14  2002/04/10 03:08:42  robertj
 * Moved code for handling media bypass address resolution into ancestor as
 *   now done ths same way in both SIP and H.323.
 *
 * Revision 2.13  2002/04/09 00:16:46  robertj
 * Changed "callAnswered" to better description of "originating".
 *
 * Revision 2.12  2002/02/19 07:42:07  robertj
 * Added OpalRFC2833 as a OpalMediaFormat variable.
 * Restructured media bypass functions to fix problems with RFC2833.
 *
 * Revision 2.11  2002/02/11 09:32:12  robertj
 * Updated to openH323 v1.8.0
 *
 * Revision 2.10  2002/02/11 07:38:35  robertj
 * Added media bypass for streams between compatible protocols.
 *
 * Revision 2.9  2002/01/22 05:04:21  robertj
 * Revamp of user input API triggered by RFC2833 support
 *
 * Revision 2.8  2001/11/14 01:31:55  robertj
 * Corrected placement of adjusting media format list.
 *
 * Revision 2.7  2001/11/02 10:45:19  robertj
 * Updated to OpenH323 v1.7.3
 *
 * Revision 2.6  2001/10/15 04:29:14  robertj
 * Added delayed start of media patch threads.
 * Removed answerCall signal and replaced with state based functions.
 *
 * Revision 2.5  2001/10/03 05:56:15  robertj
 * Changes abndwidth management API.
 *
 * Revision 2.4  2001/08/22 10:20:09  robertj
 * Changed connection locking to use double mutex to guarantee that
 *   no threads can ever deadlock or access deleted connection.
 *
 * Revision 2.3  2001/08/17 08:22:23  robertj
 * Moved call end reasons enum from OpalConnection to global.
 *
 * Revision 2.2  2001/08/13 05:10:39  robertj
 * Updates from OpenH323 v1.6.0 release.
 *
 * Revision 2.1  2001/08/01 05:26:35  robertj
 * Moved media formats list from endpoint to connection.
 *
 * Revision 2.0  2001/07/27 15:48:24  robertj
 * Conversion of OpenH323 to Open Phone Abstraction Library (OPAL)
 *
 */

#ifndef __OPAL_CONNECTION_H
#define __OPAL_CONNECTION_H

#ifdef P_USE_PRAGMA
#pragma interface
#endif

#include <opal/buildopts.h>

#include <opal/mediafmt.h>
#include <opal/mediastrm.h>
#include <opal/guid.h>
#include <opal/transports.h>
#include <ptclib/dtmf.h>
#include <ptlib/safecoll.h>
#include <rtp/rtp.h>

class OpalEndPoint;
class OpalCall;
class OpalSilenceDetector;
class OpalEchoCanceler;
class OpalRFC2833Proto;
class OpalRFC2833Info;
class OpalT120Protocol;
class OpalT38Protocol;
class OpalH224Handler;
class OpalH281Handler;


class OpalProductInfo
{
  public:
    OpalProductInfo();

    static OpalProductInfo & Default();

    PCaselessString AsString() const;

    PString vendor;
    PString name;
    PString version;
    BYTE    t35CountryCode;
    BYTE    t35Extension;
    WORD    manufacturerCode;
};


class OpalConnection : public PSafeObject
{
    PCLASSINFO(OpalConnection, PSafeObject);
  public:
    enum CallEndReason {
      EndedByLocalUser,         
      EndedByNoAccept,          
      EndedByAnswerDenied,      
      EndedByRemoteUser,        
      EndedByRefusal,           
      EndedByNoAnswer,          
      EndedByCallerAbort,       
      EndedByTransportFail,     
      EndedByConnectFail,       
      EndedByGatekeeper,        
      EndedByNoUser,            
      EndedByNoBandwidth,       
      EndedByCapabilityExchange,
      EndedByCallForwarded,     
      EndedBySecurityDenial,    
      EndedByLocalBusy,         
      EndedByLocalCongestion,   
      EndedByRemoteBusy,        
      EndedByRemoteCongestion,  
      EndedByUnreachable,       
      EndedByNoEndPoint,        
      EndedByHostOffline,       
      EndedByTemporaryFailure,  
      EndedByQ931Cause,         
      EndedByDurationLimit,     
      EndedByInvalidConferenceID, 
      EndedByNoDialTone,        
      EndedByNoRingBackTone,    
      EndedByOutOfService,      
      EndedByAcceptingCallWaiting, 
      NumCallEndReasons,

      EndedWithQ931Code = 0x100  
    };

#if PTRACING
    friend ostream & operator<<(ostream & o, CallEndReason reason);
#endif

    enum AnswerCallResponse {
      AnswerCallNow,               
      AnswerCallDenied,            
      AnswerCallPending,           
      AnswerCallDeferred,          
      AnswerCallAlertWithMedia,    
      AnswerCallDeferredWithMedia, 
      AnswerCallProgress,          
      AnswerCallNowAndReleaseCurrent, 
      NumAnswerCallResponses
    };
#if PTRACING
    friend ostream & operator<<(ostream & o, AnswerCallResponse s);
#endif

    enum Options {
      FastStartOptionDisable       = 0x0001,   // H.323 specific
      FastStartOptionEnable        = 0x0002,
      FastStartOptionMask          = 0x0003,

      H245TunnelingOptionDisable   = 0x0004,   // H.323 specific
      H245TunnelingOptionEnable    = 0x0008,
      H245TunnelingOptionMask      = 0x000c,

      H245inSetupOptionDisable     = 0x0010,   // H.323 specific
      H245inSetupOptionEnable      = 0x0020,
      H245inSetupOptionMask        = 0x0030,

      DetectInBandDTMFOptionDisable = 0x0040,  // SIP and H.323
      DetectInBandDTMFOptionEnable  = 0x0080,
      DetectInBandDTMFOptionMask    = 0x00c0,

      RTPAggregationDisable        = 0x0100,   // SIP and H.323
      RTPAggregationEnable         = 0x0200,
      RTPAggregationMask           = 0x0300,

      SendDTMFAsDefault            = 0x0000,   // SIP and H.323
      SendDTMFAsString             = 0x0400,
      SendDTMFAsTone               = 0x0800,
      SendDTMFAsRFC2833            = 0x0c00,
      SendDTMFMask                 = 0x0c00
    };

    class StringOptions : public PStringToString 
    {
    };

    OpalConnection(
      OpalCall & call,                         
      OpalEndPoint & endpoint,                 
      const PString & token,                   
      unsigned options = 0,                    
      OpalConnection::StringOptions * stringOptions = NULL     
    );  

    ~OpalConnection();

    void PrintOn(
      ostream & strm    
    ) const;

    enum Phases {
      UninitialisedPhase,
      SetUpPhase,
      AlertingPhase,
      ConnectedPhase,
      EstablishedPhase,
      ReleasingPhase, // Note these must be the last two phases.
      ReleasedPhase,
      NumPhases
    };

    inline Phases GetPhase() const { return phase; }

    CallEndReason GetCallEndReason() const { return callEndReason; }

    virtual void SetCallEndReason(
      CallEndReason reason        
    );

    void ClearCall(
      CallEndReason reason = EndedByLocalUser 
    );

    virtual void ClearCallSynchronous(
      PSyncPoint * sync,
      CallEndReason reason = EndedByLocalUser  
    );

    unsigned GetQ931Cause() const { return q931Cause; }

    void SetQ931Cause(unsigned v) { q931Cause = v; }

    virtual void TransferConnection(
      const PString & remoteParty,   
      const PString & callIdentity = PString::Empty()
    );
    
    virtual void HoldConnection();

    virtual void RetrieveConnection();

    virtual BOOL IsConnectionOnHold();

    virtual BOOL OnIncomingConnection(unsigned int options, OpalConnection::StringOptions * stringOptions);
    virtual BOOL OnIncomingConnection(unsigned int options);
    virtual BOOL OnIncomingConnection();

    virtual BOOL SetUpConnection() = 0;

    virtual BOOL OnSetUpConnection();

    
    virtual void OnAlerting();

    virtual BOOL SetAlerting(
      const PString & calleeName,   
      BOOL withMedia                
    ) = 0;

    virtual AnswerCallResponse OnAnswerCall(
      const PString & callerName        
    );

    virtual void AnsweringCall(
      AnswerCallResponse response 
    );

    virtual void OnConnected();

    virtual BOOL SetConnected() = 0;

    virtual void OnEstablished();

    virtual void Release(
      CallEndReason reason = EndedByLocalUser 
    );

    virtual void OnReleased();

    virtual PString GetDestinationAddress();

    virtual BOOL ForwardCall(
      const PString & forwardParty   
    );

    virtual OpalMediaFormatList GetMediaFormats() const = 0;

    virtual OpalMediaFormatList GetLocalMediaFormats();

    virtual void AdjustMediaFormats(
      OpalMediaFormatList & mediaFormats  
    ) const;
    
    virtual BOOL OpenSourceMediaStream(
      const OpalMediaFormatList & mediaFormats, 
      unsigned sessionID                   
    );

    virtual OpalMediaStream * OpenSinkMediaStream(
      OpalMediaStream & source    
    );

    virtual void StartMediaStreams();
    
    virtual void CloseMediaStreams();
    
    virtual void RemoveMediaStreams();
    
    virtual void PauseMediaStreams(BOOL paused);

    virtual OpalMediaStream * CreateMediaStream(
      const OpalMediaFormat & mediaFormat, 
      unsigned sessionID,                  
      BOOL isSource                        
    );

    virtual BOOL OnOpenMediaStream(
      OpalMediaStream & stream    
    );

    virtual void OnClosedMediaStream(
      const OpalMediaStream & stream     
    );
    
    virtual void OnPatchMediaStream(
      BOOL isSource,
      OpalMediaPatch & patch    
    );
        
    virtual void AttachRFC2833HandlerToPatch(BOOL isSource, OpalMediaPatch & patch);

    OpalMediaStream * GetMediaStream(
      unsigned sessionId,  
      BOOL source          
    ) const;

    BOOL RemoveMediaStream(
      OpalMediaStream * strm     // media stream to remove
    );

    virtual BOOL IsMediaBypassPossible(
      unsigned sessionID                  
    ) const;

    struct MediaInformation {
      MediaInformation() { 
        rfc2833  = RTP_DataFrame::IllegalPayloadType; 
#if OPAL_T38FAX
        ciscoNSE = RTP_DataFrame::IllegalPayloadType; 
#endif
      }

      OpalTransportAddress data;           
      OpalTransportAddress control;        
      RTP_DataFrame::PayloadTypes rfc2833; 
#if OPAL_T38FAX
      RTP_DataFrame::PayloadTypes ciscoNSE; 
#endif
    };

    virtual BOOL GetMediaInformation(
      unsigned sessionID,     
      MediaInformation & info 
    ) const;

#if OPAL_VIDEO

    virtual void AddVideoMediaFormats(
      OpalMediaFormatList & mediaFormats  
    ) const;

    virtual BOOL CreateVideoInputDevice(
      const OpalMediaFormat & mediaFormat,  
      PVideoInputDevice * & device,         
      BOOL & autoDelete                     
    );

    virtual BOOL CreateVideoOutputDevice(
      const OpalMediaFormat & mediaFormat,  
      BOOL preview,                         
      PVideoOutputDevice * & device,        
      BOOL & autoDelete                     
    );
#endif 

    virtual BOOL SetAudioVolume(
      BOOL source,                  
      unsigned percentage           
    );

    virtual unsigned GetAudioSignalLevel(
      BOOL source                   
    );

    virtual RTP_Session * GetSession(
      unsigned sessionID    
    ) const;

    virtual RTP_Session * UseSession(
      unsigned sessionID
    );
    virtual RTP_Session * UseSession(
      const OpalTransport & transport,  
      unsigned sessionID,               
      RTP_QOS * rtpqos = NULL           
    );

    virtual void ReleaseSession(
      unsigned sessionID,    
      BOOL clearAll = FALSE  
    );

    virtual RTP_Session * CreateSession(
      const OpalTransport & transport,
      unsigned sessionID,
      RTP_QOS * rtpqos
    );

    unsigned GetBandwidthAvailable() const { return bandwidthAvailable; }

    virtual BOOL SetBandwidthAvailable(
      unsigned newBandwidth,    
      BOOL force = FALSE        
    );

    virtual unsigned GetBandwidthUsed() const;

    virtual BOOL SetBandwidthUsed(
      unsigned releasedBandwidth,   
      unsigned requiredBandwidth    
    );

    enum SendUserInputModes {
      SendUserInputAsQ931,
      SendUserInputAsString,
      SendUserInputAsTone,
      SendUserInputAsInlineRFC2833,
      SendUserInputAsSeparateRFC2833,  // Not implemented
      SendUserInputAsProtocolDefault,
      NumSendUserInputModes
    };
#if PTRACING
    friend ostream & operator<<(ostream & o, SendUserInputModes m);
#endif

    virtual void SetSendUserInputMode(SendUserInputModes mode);

    virtual SendUserInputModes GetSendUserInputMode() const { return sendUserInputMode; }

    virtual SendUserInputModes GetRealSendUserInputMode() const { return GetSendUserInputMode(); }

    virtual BOOL SendUserInputString(
      const PString & value                   
    );

    virtual BOOL SendUserInputTone(
      char tone,        
      unsigned duration = 0  
    );

    virtual void OnUserInputString(
      const PString & value   
    );

    virtual void OnUserInputTone(
      char tone,
      unsigned duration
    );

    void SendUserInputHookFlash(
      unsigned duration = 500  
    ) { SendUserInputTone('!', duration); }

    virtual PString GetUserInput(
      unsigned timeout = 30   
    );

    virtual void SetUserInput(
      const PString & input     
    );

    virtual PString ReadUserInput(
      const char * terminators = "#\r\n", 
      unsigned lastDigitTimeout = 4,      
      unsigned firstDigitTimeout = 30     
    );

    virtual BOOL PromptUserInput(
      BOOL play   
    );

#if OPAL_T120DATA

    virtual OpalT120Protocol * CreateT120ProtocolHandler();
#endif

#if OPAL_T38FAX

    virtual OpalT38Protocol * CreateT38ProtocolHandler();
#endif

#if OPAL_H224
        
        virtual OpalH224Handler *CreateH224ProtocolHandler(unsigned sessionID);
        
        virtual OpalH281Handler *CreateH281ProtocolHandler(OpalH224Handler & h224Handler);
        
        OpalH224Handler * GetH224Handler() const { return  h224Handler; }
#endif


    OpalEndPoint & GetEndPoint() const { return endpoint; }
    
    OpalCall & GetCall() const { return ownerCall; }

    const PString & GetToken() const { return callToken; }

    BOOL IsOriginating() const { return originating; }

    PTime GetSetupUpTime() const { return setupTime; }

    PTime GetAlertingTime() const { return alertingTime; }

    PTime GetConnectionStartTime() const { return connectedTime; }

    PTime GetConnectionEndTime() const { return callEndTime; }

    const OpalProductInfo & GetProductInfo() const { return productInfo; }

    void SetProductInfo(
      const OpalProductInfo & info
    ) { productInfo = info; }

    const PString & GetLocalPartyName() const { return localPartyName; }

    virtual void SetLocalPartyName(const PString & name);

    const PString & GetDisplayName() const { return displayName; }

    void SetDisplayName(const PString & name) { displayName = name; }

    const PString & GetRemotePartyName() const { return remotePartyName; }

    PCaselessString GetRemoteApplication() const { return remoteProductInfo.AsString(); }

    const OpalProductInfo & GetRemoteProductInfo() const { return remoteProductInfo; }
    
    const PString & GetRemotePartyNumber() const { return remotePartyNumber; }

    const PString & GetRemotePartyAddress() const { return remotePartyAddress; }

    virtual const PString GetRemotePartyCallbackURL() const { return remotePartyAddress; }


    virtual const PString & GetCalledDestinationNumber() const { return calledDestinationNumber; }

    virtual const PString & GetCalledDestinationName() const { return calledDestinationName; }

    virtual const PString & GetCalledDestinationURL() const { return calledDestinationURL; }

    unsigned GetMinAudioJitterDelay() const { return minAudioJitterDelay; }

    unsigned GetMaxAudioJitterDelay() const { return maxAudioJitterDelay; }

    void SetAudioJitterDelay(
      unsigned minDelay,   
      unsigned maxDelay    
    );

    OpalSilenceDetector * GetSilenceDetector() const { return silenceDetector; }
    
    OpalEchoCanceler * GetEchoCanceler() const { return echoCanceler; }

    virtual const OpalGloballyUniqueID & GetIdentifier() const
    { return callIdentifier; }

    virtual OpalTransport & GetTransport() const
    { return *(OpalTransport *)NULL; }

    PDICTIONARY(MediaAddressesDict, POrdinalKey, OpalTransportAddress);
    MediaAddressesDict & GetMediaTransportAddresses()
    { return mediaTransportAddresses; }


    const RTP_DataFrame::PayloadMapType & GetRTPPayloadMap() const
    { return rtpPayloadMap; }

    BOOL RemoteIsNAT() const
    { return remoteIsNAT; }

    virtual void SetSecurityMode(const PString & v)
    { securityMode = v; }

    virtual PString GetSecurityMode() const 
    { return securityMode; }

    StringOptions * GetStringOptions() const
    { return stringOptions; }

    void SetStringOptions(StringOptions * options);

    virtual BOOL OnOpenIncomingMediaChannels();

    virtual void ApplyStringOptions();

    virtual void PreviewPeerMediaFormats(const OpalMediaFormatList & fmts);

    virtual void EnableRecording();
    virtual void DisableRecording();

    virtual BOOL IsRTPNATEnabled(const PIPSocket::Address & localAddr, 
                                 const PIPSocket::Address & peerAddr,
                                 const PIPSocket::Address & sigAddr,
                                                       BOOL incoming);

  protected:
    PDECLARE_NOTIFIER(OpalRFC2833Info, OpalConnection, OnUserInputInlineRFC2833);
    PDECLARE_NOTIFIER(OpalRFC2833Info, OpalConnection, OnUserInputInlineCiscoNSE);
#if P_DTMF
    PDECLARE_NOTIFIER(RTP_DataFrame, OpalConnection, OnUserInputInBandDTMF);
#endif
    PDECLARE_NOTIFIER(PThread, OpalConnection, OnReleaseThreadMain);
    PDECLARE_NOTIFIER(RTP_DataFrame, OpalConnection, OnRecordAudio);

  // Member variables
    OpalCall             & ownerCall;
    OpalEndPoint         & endpoint;

    PMutex               phaseMutex;
    Phases               phase;

    PString              callToken;
    OpalGloballyUniqueID callIdentifier;
    BOOL                 originating;
    PTime                setupTime;
    PTime                alertingTime;
    PTime                connectedTime;
    PTime                callEndTime;
    OpalProductInfo      productInfo;
    PString              localPartyName;
    PString              displayName;
    PString              remotePartyName;
    OpalProductInfo      remoteProductInfo;
    PString              remotePartyNumber;
    PString              remotePartyAddress;
    CallEndReason        callEndReason;
    PString              calledDestinationNumber;
    PString              calledDestinationName;
    PString              calledDestinationURL;
    BOOL                 remoteIsNAT;

    SendUserInputModes    sendUserInputMode;
    PString               userInputString;
    PSyncPoint            userInputAvailable;
    BOOL                  detectInBandDTMF;
    unsigned              q931Cause;

    OpalSilenceDetector * silenceDetector;
    OpalEchoCanceler    * echoCanceler;
    OpalRFC2833Proto    * rfc2833Handler;
#if OPAL_T120DATA
    OpalT120Protocol    * t120handler;
#endif
#if OPAL_T38FAX
    OpalT38Protocol     * t38handler;
    OpalRFC2833Proto    * ciscoNSEHandler;
#endif
#if OPAL_H224
    OpalH224Handler               * h224Handler;
#endif

    MediaAddressesDict  mediaTransportAddresses;
    OpalMediaStreamList mediaStreams;
    RTP_SessionManager  rtpSessions;
    unsigned            minAudioJitterDelay;
    unsigned            maxAudioJitterDelay;
    unsigned            bandwidthAvailable;

    RTP_DataFrame::PayloadMapType rtpPayloadMap;

    // The In-Band DTMF detector. This is used inside an audio filter which is
    // added to the audio channel.
#if P_DTMF
    PDTMFDecoder        dtmfDecoder;
#endif

    PString securityMode;

    void SetPhase(Phases phaseToSet);

#if PTRACING
    friend ostream & operator<<(ostream & o, Phases p);
#endif

    BOOL useRTPAggregation;

    StringOptions * stringOptions;
    PString recordAudioFilename;

    virtual OpalMediaStream * InternalCreateMediaStream(const OpalMediaFormat & mediaFormat, unsigned sessionID, BOOL isSource);
};

class RTP_UDP;

class OpalSecurityMode : public PObject
{
  PCLASSINFO(OpalSecurityMode, PObject);
  public:
    virtual RTP_UDP * CreateRTPSession(
      PHandleAggregator * _aggregator,   
      unsigned id,          
      BOOL remoteIsNAT      
    ) = 0;
    virtual BOOL Open() = 0;
};


#endif // __OPAL_CONNECTION_H


// End of File ///////////////////////////////////////////////////////////////

---