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
 *
 * $Revision: 23187 $
 * $Author: rjongbloed $
 * $Date: 2009-07-31 00:24:18 +0000 (Fri, 31 Jul 2009) $
 */

#ifndef OPAL_OPAL_CONNECTION_H
#define OPAL_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>
#include <im/t140.h>

class OpalEndPoint;
class OpalCall;
class OpalSilenceDetector;
class OpalEchoCanceler;
class OpalRFC2833Proto;
class OpalRFC2833Info;
class PURL;


#define OPAL_OPT_AUTO_START           "AutoStart"             
#define OPAL_OPT_CALL_IDENTIFIER      "Call-Identifier"       
#define OPAL_OPT_CALLING_PARTY_URL    "Calling-Party-URL"     
#define OPAL_OPT_CALLING_PARTY_NUMBER "Calling-Party-Number"  
#define OPAL_OPT_CALLING_PARTY_NAME   "Calling-Party-Name"    
#define OPAL_OPT_CALLING_PARTY_DOMAIN "Calling-Party-Domain"  
#define OPAL_OPT_CALLING_DISPLAY_NAME "Calling-Display-Name"  
#define OPAL_OPT_ORIGINATOR_ADDRESS   "Originator-Address"    
#define OPAL_OPT_INTERFACE            "Interface"             
#define OPAL_OPT_ENABLE_INBAND_DTMF   "EnableInbandDTMF"      
#define OPAL_OPT_ENABLE_INBAND_DTMF   "EnableInbandDTMF"      
#define OPAL_OPT_DETECT_INBAND_DTMF   "DetectInBandDTMF"      
#define OPAL_OPT_SEND_INBAND_DTMF     "SendInBandDTMF"        
#define OPAL_OPT_DTMF_MULT            "dtmfmult"
#define OPAL_OPT_DTMF_DIV             "dtmfdiv"
#define OPAL_OPT_DISABLE_JITTER       "Disable-Jitter"        
#define OPAL_OPT_MAX_JITTER           "Max-Jitter"            
#define OPAL_OPT_MIN_JITTER           "Min-Jitter"            
#define OPAL_OPT_RECORD_AUDIO         "Record-Audio"          
#define OPAL_OPT_ALERTING_TYPE        "Alerting-Type"         
#define OPAL_OPT_REMOVE_CODEC         "Remove-Codec"          


class OpalProductInfo
{
  public:
    OpalProductInfo();

    static OpalProductInfo & Default();

    PCaselessString AsString() const;

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


class OpalConnection : public PSafeObject
{
    PCLASSINFO(OpalConnection, PSafeObject);
  public:
    enum CallEndReasonCodes {
      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
    };

    struct CallEndReason {
      CallEndReason(
        CallEndReasonCodes reason = NumCallEndReasons,
        unsigned cause = 0
      ) : code(reason), q931(cause) { }

      operator CallEndReasonCodes() const { return code; }

      CallEndReasonCodes code:8; // Normalised OPAL code
      unsigned           q931:8; // PSTN Interworking code, actually Q.850
    };

#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 
    {
      public:
        // Make sure the key set in a StringOptions is caseless
        PBoolean SetAt(const char * key, const PString & data)
        {
          return PStringToString::SetAt(PCaselessString(key), data);
        }
        PBoolean SetAt(const PString & key, const PString & data)
        {
          return PStringToString::SetAt(PCaselessString(key), data);
        }
        PBoolean SetAt(const PCaselessString & key, const PString & data)
        {
          return PStringToString::SetAt(key, data);
        }

        void ExtractFromURL(
          PURL & url
        );
    };

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

    ~OpalConnection();

    void PrintOn(
      ostream & strm    
    ) const;

    virtual bool IsNetworkConnection() const = 0;

    enum Phases {
      UninitialisedPhase,   
      SetUpPhase,           
      ProceedingPhase,      
      AlertingPhase,        
      ConnectedPhase,       
      EstablishedPhase,     
      ForwardingPhase,      
      ReleasingPhase,       
      ReleasedPhase,        
      NumPhases             
    };

    inline Phases GetPhase() const { return phase; }

    void SetPhase(
      Phases phaseToSet  
    );

    CallEndReason GetCallEndReason() const { return callEndReason; }

    static PString GetCallEndReasonText(CallEndReason reason);
    PString GetCallEndReasonText() const { return GetCallEndReasonText(callEndReason); }

    static void SetCallEndReasonText(CallEndReasonCodes reasonCode, const PString & newText);

    virtual void SetCallEndReason(
      CallEndReason reason        
    );

    void ClearCall(
      CallEndReason reason = EndedByLocalUser 
    );

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

    unsigned GetQ931Cause() const { return callEndReason.q931; }

    void SetQ931Cause(unsigned v) { callEndReason.q931 = v; }

    virtual bool TransferConnection(
      const PString & remoteParty   
    );
    
    virtual bool HoldConnection();

    virtual bool RetrieveConnection();

    virtual PBoolean IsConnectionOnHold();

    virtual void OnHold(
      bool fromRemote,               
      bool onHold                    
    );

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

    virtual PBoolean SetUpConnection() = 0;

    virtual PBoolean OnSetUpConnection();

    
    virtual void OnProceeding();

    virtual void OnAlerting();

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

    virtual AnswerCallResponse OnAnswerCall(
      const PString & callerName        
    );

    virtual void AnsweringCall(
      AnswerCallResponse response 
    );

    virtual void OnConnected();

    virtual PBoolean SetConnected();

    virtual void OnEstablished();

    virtual void Release(
      CallEndReason reason = EndedByLocalUser 
    );

    virtual void OnReleased();

    virtual PString GetDestinationAddress();

    virtual PBoolean ForwardCall(
      const PString & forwardParty   
    );

    PSafePtr<OpalConnection> GetOtherPartyConnection() const;

    template <class cls> PSafePtr<cls> GetOtherPartyConnectionAs() const { return PSafePtrCast<OpalConnection, cls>(GetOtherPartyConnection()); }

    virtual OpalMediaFormatList GetMediaFormats() const;

    virtual OpalMediaFormatList GetLocalMediaFormats();

    virtual void AdjustMediaFormats(
      OpalMediaFormatList & mediaFormats  
    ) const;

    virtual unsigned GetNextSessionID(
      const OpalMediaType & mediaType,   
      bool isSource                      
    );

    virtual OpalMediaType::AutoStartMode GetAutoStart(
      const OpalMediaType & mediaType  
    ) const;

    virtual void AutoStartMediaStreams(
      bool force = false 
    );

#if OPAL_FAX

    virtual bool SwitchFaxMediaStreams(
      bool enableFax  
    );
#endif

    virtual OpalMediaStreamPtr OpenMediaStream(
      const OpalMediaFormat & mediaFormat, 
      unsigned sessionID,                  
      bool isSource                        
    );

    virtual bool CloseMediaStream(
      unsigned sessionId,  
      bool source          
    );

    virtual bool CloseMediaStream(
      OpalMediaStream & stream  
    );

    bool RemoveMediaStream(
      OpalMediaStream & strm     // media stream to remove
    );

    virtual void StartMediaStreams();
    
    virtual void CloseMediaStreams();
    
    virtual void PauseMediaStreams(PBoolean paused);

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

    OpalMediaStreamPtr GetMediaStream(
      const PString & streamID,  
      bool source                
    ) const;

    OpalMediaStreamPtr GetMediaStream(
      unsigned sessionId,  
      bool source          
    ) const;

    OpalMediaStreamPtr GetMediaStream(
      const OpalMediaType & mediaType,    
      bool source,                        
      OpalMediaStreamPtr previous = NULL  
    ) const;

    virtual PBoolean OnOpenMediaStream(
      OpalMediaStream & stream    
    );

    virtual void OnClosedMediaStream(
      const OpalMediaStream & stream     
    );
    
    virtual void OnPatchMediaStream(
      PBoolean isSource,
      OpalMediaPatch & patch    
    );
        
    virtual void OnMediaPatchStart(
      unsigned sessionId, 
          bool isSource
    );

    virtual void OnMediaPatchStop(
      unsigned sessionId, 
          bool isSource
    );

    PDECLARE_NOTIFIER(OpalMediaCommand, OpalConnection, OnMediaCommand);

    virtual void AttachRFC2833HandlerToPatch(PBoolean isSource, OpalMediaPatch & patch);

    virtual PBoolean IsMediaBypassPossible(
      unsigned sessionID                  
    ) const;

#if OPAL_VIDEO

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

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

    virtual PBoolean SetAudioVolume(
      PBoolean source,                  
      unsigned percentage           
    );

    virtual unsigned GetAudioSignalLevel(
      PBoolean source                   
    );

    unsigned GetBandwidthAvailable() const { return bandwidthAvailable; }

    virtual PBoolean SetBandwidthAvailable(
      unsigned newBandwidth,    
      PBoolean force = PFalse        
    );

    virtual unsigned GetBandwidthUsed() const;

    virtual PBoolean 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 PBoolean SendUserInputString(
      const PString & value                   
    );

    virtual PBoolean 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 PBoolean PromptUserInput(
      PBoolean play   
    );

    virtual bool GarbageCollection();

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

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

    PBoolean 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; }

    virtual PString GetPrefixName() const;

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

    virtual void SetLocalPartyName(const PString & name);

    virtual PString GetLocalPartyURL() const;

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

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

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

    void SetRemotePartyName(const PString & name) { remotePartyName = name; }

    const PString & GetRemotePartyNumber() const { return remotePartyNumber; }

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

    void SetRemotePartyAddress(const PString & addr) { remotePartyAddress = addr; }

    virtual PString GetRemotePartyURL() const;

    // Deprecated - backward compatibility only
    const PString GetRemotePartyCallbackURL() const { return GetRemotePartyURL(); }

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

    const OpalProductInfo & GetRemoteProductInfo() const { return remoteProductInfo; }


    const PString & GetCalledPartyName() const { return m_calledPartyName; }

    const PString & GetCalledPartyNumber() const { return m_calledPartyNumber; }

    virtual PString GetCalledPartyURL();

    /* Internal function to copy party names from "network" connection to
       "non-network" connection such as OpalPCSSConnection. This allows
       the non-network GetRemoteAddress() function and its ilk to return
       the intuitive value, i.e. the value from the OTHER connection.
     */
    void CopyPartyNames(const OpalConnection & other);


    virtual PString GetAlertingType() const;

    virtual bool SetAlertingType(const PString & info);


    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 PString GetIdentifier() const;

    virtual PINDEX GetMaxRtpPayloadSize() const;

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

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

#if OPAL_STATISTICS

    unsigned GetVideoUpdateRequestsSent() const { return m_VideoUpdateRequestsSent; }
#endif


    const StringOptions & GetStringOptions() const { return m_connStringOptions; }

    void SetStringOptions(
      const StringOptions & options,
      bool overwrite
    );

    virtual void ApplyStringOptions(OpalConnection::StringOptions & stringOptions);
    virtual void OnApplyStringOptions();

    virtual void PreviewPeerMediaFormats(const OpalMediaFormatList & fmts);

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

#if OPAL_HAS_IM

    virtual bool TransmitInternalIM(
      const OpalMediaFormat & format, 
      RTP_DataFrame & body
    );

    virtual void OnReceiveInternalIM(
      const OpalMediaFormat & format, 
      RTP_DataFrame & body
    );

    virtual bool TransmitExternalIM(
      const OpalMediaFormat & format, 
      RTP_DataFrame & body
    );

    virtual bool OnReceiveExternalIM(
      const OpalMediaFormat & format, 
      RTP_DataFrame & body
    );

#endif

  protected:
    void OnConnectedInternal();

    PDECLARE_NOTIFIER(PThread, OpalConnection, OnReleaseThreadMain);
    PDECLARE_NOTIFIER(RTP_DataFrame, OpalConnection, OnRecordAudio);
    PDECLARE_NOTIFIER(RTP_DataFrame, OpalConnection, OnRecordVideo);
    void OnStartRecording(OpalMediaPatch * patch);
    void OnStopRecording(OpalMediaPatch * patch);

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

  private:
    PMutex               phaseMutex;
    Phases               phase;

  protected:
    PString              callToken;
    PBoolean             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;
    bool                 synchronousOnRelease;
    PString              m_calledPartyNumber;
    PString              m_calledPartyName;

    SendUserInputModes    sendUserInputMode;
    PString               userInputString;
    PSyncPoint            userInputAvailable;

    OpalSilenceDetector * silenceDetector;
    OpalEchoCanceler    * echoCanceler;

    MediaAddressesDict         mediaTransportAddresses;
    PSafeList<OpalMediaStream> mediaStreams;

    unsigned            minAudioJitterDelay;
    unsigned            maxAudioJitterDelay;
    unsigned            bandwidthAvailable;

    // The In-Band DTMF detector. This is used inside an audio filter which is
    // added to the audio channel.
#if OPAL_PTLIB_DTMF
    PDTMFDecoder m_dtmfDecoder;
    bool         m_detectInBandDTMF;
    unsigned     m_dtmfScaleMultiplier;
    unsigned     m_dtmfScaleDivisor;
    PDECLARE_NOTIFIER(RTP_DataFrame, OpalConnection, OnDetectInBandDTMF);

    bool         m_sendInBandDTMF;
    bool         m_installedInBandDTMF;
    PDTMFEncoder m_inBandDTMF;
    PINDEX       m_emittedInBandDTMF;
    PMutex       m_inBandMutex;
    PDECLARE_NOTIFIER(RTP_DataFrame, OpalConnection, OnSendInBandDTMF);
#endif

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

    StringOptions m_connStringOptions;

    PString       m_recordingFilename;
    PNotifier     m_recordAudioNotifier;
    PNotifier     m_recordVideoNotifier;

#if OPAL_STATISTICS
    unsigned m_VideoUpdateRequestsSent;
#endif

    struct AutoStartInfo {
      unsigned preferredSessionId;  // preferred session ID (only used for originating)
      OpalMediaType::AutoStartMode autoStart;// Mode for this session when the call is started
    };

    class AutoStartMap : public std::map<OpalMediaType, AutoStartInfo>
    {
      public:
        AutoStartMap();
        void Initialise(const OpalConnection::StringOptions & stringOptions);
        OpalMediaType::AutoStartMode GetAutoStart(const OpalMediaType & mediaType) const;
        void SetAutoStart(const OpalMediaType & mediaType, OpalMediaType::AutoStartMode autoStart);

      protected:
        bool m_initialised;
        PMutex m_mutex;

    };
    AutoStartMap m_autoStartInfo;

  private:
    P_REMOVE_VIRTUAL(PBoolean, OnIncomingConnection(unsigned int), false);
    P_REMOVE_VIRTUAL(PBoolean, OnIncomingConnection(), false);
};

#endif // OPAL_OPAL_CONNECTION_H


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

---