connection.h

Go to the documentation of this file.
00001 /*
00002  * connection.h
00003  *
00004  * Telephony connection abstraction
00005  *
00006  * Open Phone Abstraction Library (OPAL)
00007  * Formally known as the Open H323 project.
00008  *
00009  * Copyright (c) 2001 Equivalence Pty. Ltd.
00010  *
00011  * The contents of this file are subject to the Mozilla Public License
00012  * Version 1.0 (the "License"); you may not use this file except in
00013  * compliance with the License. You may obtain a copy of the License at
00014  * http://www.mozilla.org/MPL/
00015  *
00016  * Software distributed under the License is distributed on an "AS IS"
00017  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
00018  * the License for the specific language governing rights and limitations
00019  * under the License.
00020  *
00021  * The Original Code is Open Phone Abstraction Library.
00022  *
00023  * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
00024  *
00025  * Contributor(s): ______________________________________.
00026  *
00027  * $Log: connection.h,v $
00028  * Revision 2.49.2.1  2006/02/06 04:38:37  csoutheren
00029  * Backported RTP payload mapping fixes from CVS head
00030  *
00031  * Revision 2.50  2006/02/02 07:02:56  csoutheren
00032  * Added RTP payload map to transcoders and connections to allow remote SIP endpoints
00033  * to change the payload type used for outgoing RTP.
00034  *
00035  * Revision 2.49  2006/01/09 12:19:06  csoutheren
00036  * Added member variables to capture incoming destination addresses
00037  *
00038  * Revision 2.48  2005/12/06 21:32:24  dsandras
00039  * Applied patch from Frederic Heem <frederic.heem _Atttt_ telsey.it> to fix
00040  * assert in PSyncPoint when OnReleased is called twice from different threads.
00041  * Thanks! (Patch #1374240)
00042  *
00043  * Revision 2.47  2005/11/30 13:35:26  csoutheren
00044  * Changed tags for Doxygen
00045  *
00046  * Revision 2.46  2005/11/24 20:31:54  dsandras
00047  * Added support for echo cancelation using Speex.
00048  * Added possibility to add a filter to an OpalMediaPatch for all patches of a connection.
00049  *
00050  * Revision 2.45  2005/10/04 12:57:18  rjongbloed
00051  * Removed CanOpenSourceMediaStream/CanOpenSinkMediaStream functions and
00052  *   now use overides on OpenSourceMediaStream/OpenSinkMediaStream
00053  *
00054  * Revision 2.44  2005/09/15 17:02:40  dsandras
00055  * Added the possibility for a connection to prevent the opening of a sink/source media stream.
00056  *
00057  * Revision 2.43  2005/08/24 10:43:51  rjongbloed
00058  * Changed create video functions yet again so can return pointers that are not to be deleted.
00059  *
00060  * Revision 2.42  2005/08/23 12:45:09  rjongbloed
00061  * Fixed creation of video preview window and setting video grab/display initial frame size.
00062  *
00063  * Revision 2.41  2005/08/04 17:21:01  dsandras
00064  * Added functions to close/remove the media streams of a connection.
00065  *
00066  * Revision 2.40  2005/07/14 08:51:17  csoutheren
00067  * Removed CreateExternalRTPAddress - it's not needed because you can override GetMediaAddress
00068  * to do the same thing
00069  * Fixed problems with logic associated with media bypass
00070  *
00071  * Revision 2.39  2005/07/11 06:52:15  csoutheren
00072  * Added support for outgoing calls using external RTP
00073  *
00074  * Revision 2.38  2005/07/11 01:52:23  csoutheren
00075  * Extended AnsweringCall to work for SIP as well as H.323
00076  * Fixed problems with external RTP connection in H.323
00077  * Added call to OnClosedMediaStream
00078  *
00079  * Revision 2.37  2005/04/11 11:12:00  dsandras
00080  * Fixed previous commit.
00081  *
00082  * Revision 2.36  2005/04/11 10:42:35  dsandras
00083  * Fixed previous commit.
00084  *
00085  * Revision 2.35  2005/04/10 20:43:39  dsandras
00086  * Added support for function allowing to put the OpalMediaStreams on pause.
00087  *
00088  * Revision 2.34  2005/04/10 20:42:33  dsandras
00089  * Added support for a function that returns the "best guess" callback URL.
00090  *
00091  * Revision 2.33  2005/04/10 20:41:29  dsandras
00092  * Added support for call hold.
00093  *
00094  * Revision 2.32  2005/04/10 20:40:20  dsandras
00095  * Added support for Blind Transfert.
00096  *
00097  * Revision 2.31  2005/01/16 11:28:05  csoutheren
00098  * Added GetIdentifier virtual function to OpalConnection, and changed H323
00099  * and SIP descendants to use this function. This allows an application to
00100  * obtain a GUID for any connection regardless of the protocol used
00101  *
00102  * Revision 2.30  2004/12/12 12:29:02  dsandras
00103  * Moved GetRemoteApplication () to OpalConnection so that it is usable for all types of connection.
00104  *
00105  * Revision 2.29  2004/08/14 07:56:29  rjongbloed
00106  * Major revision to utilise the PSafeCollection classes for the connections and calls.
00107  *
00108  * Revision 2.28  2004/05/17 13:24:18  rjongbloed
00109  * Added silence suppression.
00110  *
00111  * Revision 2.27  2004/05/01 10:00:51  rjongbloed
00112  * Fixed ClearCallSynchronous so now is actually signalled when call is destroyed.
00113  *
00114  * Revision 2.26  2004/04/26 04:33:05  rjongbloed
00115  * Move various call progress times from H.323 specific to general conenction.
00116  *
00117  * Revision 2.25  2004/04/18 13:31:28  rjongbloed
00118  * Added new end call value from OpenH323.
00119  *
00120  * Revision 2.24  2004/03/13 06:25:50  rjongbloed
00121  * Slight rearrangement of local party name and alias list to beter match common
00122  *   behaviour in ancestor.
00123  * Abstracted local party name for endpoint into ancestor from H.,323.
00124  *
00125  * Revision 2.23  2004/03/11 06:54:27  csoutheren
00126  * Added ability to disable SIP or H.323 stacks
00127  *
00128  * Revision 2.22  2004/02/24 11:28:45  rjongbloed
00129  * Normalised RTP session management across protocols
00130  *
00131  * Revision 2.21  2003/03/17 10:26:59  robertj
00132  * Added video support.
00133  *
00134  * Revision 2.20  2003/03/06 03:57:47  robertj
00135  * IVR support (work in progress) requiring large changes everywhere.
00136  *
00137  * Revision 2.19  2003/01/07 04:39:53  robertj
00138  * Updated to OpenH323 v1.11.2
00139  *
00140  * Revision 2.18  2002/11/10 11:33:17  robertj
00141  * Updated to OpenH323 v1.10.3
00142  *
00143  * Revision 2.17  2002/09/16 02:52:35  robertj
00144  * Added #define so can select if #pragma interface/implementation is used on
00145  *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
00146  *
00147  * Revision 2.16  2002/09/12 06:54:06  robertj
00148  * Added missing virtual to Release() function so can be overridden.
00149  *
00150  * Revision 2.15  2002/07/01 04:56:30  robertj
00151  * Updated to OpenH323 v1.9.1
00152  *
00153  * Revision 2.14  2002/04/10 03:08:42  robertj
00154  * Moved code for handling media bypass address resolution into ancestor as
00155  *   now done ths same way in both SIP and H.323.
00156  *
00157  * Revision 2.13  2002/04/09 00:16:46  robertj
00158  * Changed "callAnswered" to better description of "originating".
00159  *
00160  * Revision 2.12  2002/02/19 07:42:07  robertj
00161  * Added OpalRFC2833 as a OpalMediaFormat variable.
00162  * Restructured media bypass functions to fix problems with RFC2833.
00163  *
00164  * Revision 2.11  2002/02/11 09:32:12  robertj
00165  * Updated to openH323 v1.8.0
00166  *
00167  * Revision 2.10  2002/02/11 07:38:35  robertj
00168  * Added media bypass for streams between compatible protocols.
00169  *
00170  * Revision 2.9  2002/01/22 05:04:21  robertj
00171  * Revamp of user input API triggered by RFC2833 support
00172  *
00173  * Revision 2.8  2001/11/14 01:31:55  robertj
00174  * Corrected placement of adjusting media format list.
00175  *
00176  * Revision 2.7  2001/11/02 10:45:19  robertj
00177  * Updated to OpenH323 v1.7.3
00178  *
00179  * Revision 2.6  2001/10/15 04:29:14  robertj
00180  * Added delayed start of media patch threads.
00181  * Removed answerCall signal and replaced with state based functions.
00182  *
00183  * Revision 2.5  2001/10/03 05:56:15  robertj
00184  * Changes abndwidth management API.
00185  *
00186  * Revision 2.4  2001/08/22 10:20:09  robertj
00187  * Changed connection locking to use double mutex to guarantee that
00188  *   no threads can ever deadlock or access deleted connection.
00189  *
00190  * Revision 2.3  2001/08/17 08:22:23  robertj
00191  * Moved call end reasons enum from OpalConnection to global.
00192  *
00193  * Revision 2.2  2001/08/13 05:10:39  robertj
00194  * Updates from OpenH323 v1.6.0 release.
00195  *
00196  * Revision 2.1  2001/08/01 05:26:35  robertj
00197  * Moved media formats list from endpoint to connection.
00198  *
00199  * Revision 2.0  2001/07/27 15:48:24  robertj
00200  * Conversion of OpenH323 to Open Phone Abstraction Library (OPAL)
00201  *
00202  */
00203 
00204 #ifndef __OPAL_CONNECTION_H
00205 #define __OPAL_CONNECTION_H
00206 
00207 #ifdef P_USE_PRAGMA
00208 #pragma interface
00209 #endif
00210 
00211 #include <opal/buildopts.h>
00212 
00213 #include <opal/mediafmt.h>
00214 #include <opal/mediastrm.h>
00215 #include <opal/guid.h>
00216 #include <opal/transports.h>
00217 #include <ptclib/dtmf.h>
00218 #include <ptlib/safecoll.h>
00219 #include <rtp/rtp.h>
00220 
00221 class OpalEndPoint;
00222 class OpalCall;
00223 class OpalSilenceDetector;
00224 class OpalEchoCanceler;
00225 class OpalRFC2833Proto;
00226 class OpalRFC2833Info;
00227 class OpalT120Protocol;
00228 class OpalT38Protocol;
00229 
00230 
00248 class OpalConnection : public PSafeObject
00249 {
00250     PCLASSINFO(OpalConnection, PSafeObject);
00251   public:
00256     enum CallEndReason {
00257       EndedByLocalUser,         
00258       EndedByNoAccept,          
00259       EndedByAnswerDenied,      
00260       EndedByRemoteUser,        
00261       EndedByRefusal,           
00262       EndedByNoAnswer,          
00263       EndedByCallerAbort,       
00264       EndedByTransportFail,     
00265       EndedByConnectFail,       
00266       EndedByGatekeeper,        
00267       EndedByNoUser,            
00268       EndedByNoBandwidth,       
00269       EndedByCapabilityExchange,
00270       EndedByCallForwarded,     
00271       EndedBySecurityDenial,    
00272       EndedByLocalBusy,         
00273       EndedByLocalCongestion,   
00274       EndedByRemoteBusy,        
00275       EndedByRemoteCongestion,  
00276       EndedByUnreachable,       
00277       EndedByNoEndPoint,        
00278       EndedByHostOffline,       
00279       EndedByTemporaryFailure,  
00280       EndedByQ931Cause,         
00281       EndedByDurationLimit,     
00282       EndedByInvalidConferenceID, 
00283       NumCallEndReasons
00284     };
00285 
00286 #if PTRACING
00287     friend ostream & operator<<(ostream & o, CallEndReason reason);
00288 #endif
00289 
00290     enum AnswerCallResponse {
00291       AnswerCallNow,               
00292       AnswerCallDenied,            
00293       AnswerCallPending,           
00294       AnswerCallDeferred,          
00295       AnswerCallAlertWithMedia,    
00296       AnswerCallDeferredWithMedia, 
00297       NumAnswerCallResponses
00298     };
00299 #if PTRACING
00300     friend ostream & operator<<(ostream & o, AnswerCallResponse s);
00301 #endif
00302 
00303 
00308     OpalConnection(
00309       OpalCall & call,          
00310       OpalEndPoint & endpoint,  
00311       const PString & token     
00312     );
00313 
00316     ~OpalConnection();
00318 
00325     void PrintOn(
00326       ostream & strm    
00327     ) const;
00329 
00332     enum Phases {
00333       UninitialisedPhase,
00334       SetUpPhase,
00335       AlertingPhase,
00336       ConnectedPhase,
00337       EstablishedPhase,
00338       ReleasingPhase, // Note these must be the last two phases.
00339       ReleasedPhase,
00340       NumPhases
00341     };
00342 
00347     inline Phases GetPhase() const { return phase; }
00348 
00357     CallEndReason GetCallEndReason() const { return callEndReason; }
00358 
00363     virtual void SetCallEndReason(
00364       CallEndReason reason        
00365     );
00366 
00374     void ClearCall(
00375       CallEndReason reason = EndedByLocalUser 
00376     );
00377 
00380     virtual void ClearCallSynchronous(
00381       PSyncPoint * sync,
00382       CallEndReason reason = EndedByLocalUser  
00383     );
00384 
00388     virtual void TransferConnection(
00389       const PString & remoteParty,   
00390       const PString & callIdentity = PString::Empty()
00392     );
00393     
00396     virtual void HoldConnection();
00397 
00401     virtual void RetrieveConnection();
00402 
00405     virtual BOOL IsConnectionOnHold();
00407 
00431     virtual BOOL OnIncomingConnection();
00432 
00439     virtual BOOL SetUpConnection() = 0;
00440 
00456     virtual void OnAlerting();
00457 
00468     virtual BOOL SetAlerting(
00469       const PString & calleeName,   
00470       BOOL withMedia                
00471     ) = 0;
00472 
00489     virtual AnswerCallResponse OnAnswerCall(
00490       const PString & callerName        
00491     );
00492 
00503     virtual void AnsweringCall(
00504       AnswerCallResponse response 
00505     );
00506 
00517     virtual void OnConnected();
00518 
00523     virtual BOOL SetConnected() = 0;
00524 
00535     virtual void OnEstablished();
00536 
00545     virtual void Release(
00546       CallEndReason reason = EndedByLocalUser 
00547     );
00548 
00566     virtual void OnReleased();
00568 
00578     virtual PString GetDestinationAddress();
00579 
00589     virtual BOOL ForwardCall(
00590       const PString & forwardParty   
00591     );
00593 
00602     virtual OpalMediaFormatList GetMediaFormats() const = 0;
00603 
00612     virtual void AdjustMediaFormats(
00613       OpalMediaFormatList & mediaFormats  
00614     ) const;
00615     
00618     virtual BOOL OpenSourceMediaStream(
00619       const OpalMediaFormatList & mediaFormats, 
00620       unsigned sessionID                   
00621     );
00622 
00625     virtual OpalMediaStream * OpenSinkMediaStream(
00626       OpalMediaStream & source    
00627     );
00628 
00631     virtual void StartMediaStreams();
00632     
00635     virtual void CloseMediaStreams();
00636     
00639     virtual void RemoveMediaStreams();
00640     
00643     virtual void PauseMediaStreams(BOOL paused);
00644 
00659     virtual OpalMediaStream * CreateMediaStream(
00660       const OpalMediaFormat & mediaFormat, 
00661       unsigned sessionID,                  
00662       BOOL isSource                        
00663     );
00664 
00676     virtual BOOL OnOpenMediaStream(
00677       OpalMediaStream & stream    
00678     );
00679 
00684     virtual void OnClosedMediaStream(
00685       const OpalMediaStream & stream     
00686     );
00687     
00692     virtual void OnPatchMediaStream(
00693       BOOL isSource,
00694       OpalMediaPatch & patch    
00695     );
00696 
00702     OpalMediaStream * GetMediaStream(
00703       unsigned sessionId,  
00704       BOOL source          
00705     ) const;
00706 
00712     virtual BOOL IsMediaBypassPossible(
00713       unsigned sessionID                  
00714     ) const;
00715 
00718     struct MediaInformation {
00719       MediaInformation() { rfc2833 = RTP_DataFrame::IllegalPayloadType; }
00720 
00721       OpalTransportAddress data;           
00722       OpalTransportAddress control;        
00723       RTP_DataFrame::PayloadTypes rfc2833; 
00724     };
00725 
00734     virtual BOOL GetMediaInformation(
00735       unsigned sessionID,     
00736       MediaInformation & info 
00737     ) const;
00738 
00743     virtual void AddVideoMediaFormats(
00744       OpalMediaFormatList & mediaFormats  
00745     ) const;
00746 
00749     virtual BOOL CreateVideoInputDevice(
00750       const OpalMediaFormat & mediaFormat,  
00751       PVideoInputDevice * & device,         
00752       BOOL & autoDelete                     
00753     );
00754 
00758     virtual BOOL CreateVideoOutputDevice(
00759       const OpalMediaFormat & mediaFormat,  
00760       BOOL preview,                         
00761       PVideoOutputDevice * & device,        
00762       BOOL & autoDelete                     
00763     );
00765 
00771     virtual RTP_Session * GetSession(
00772       unsigned sessionID    
00773     ) const;
00774 
00789     virtual RTP_Session * UseSession(
00790       const OpalTransport & transport,  
00791       unsigned sessionID,               
00792       RTP_QOS * rtpqos = NULL           
00793     );
00794 
00799     virtual void ReleaseSession(
00800       unsigned sessionID    
00801     );
00802 
00807     virtual RTP_Session * CreateSession(
00808       const OpalTransport & transport,
00809       unsigned sessionID,
00810       RTP_QOS * rtpqos
00811     );
00813 
00818     unsigned GetBandwidthAvailable() const { return bandwidthAvailable; }
00819 
00824     virtual BOOL SetBandwidthAvailable(
00825       unsigned newBandwidth,    
00826       BOOL force = FALSE        
00827     );
00828 
00833     virtual unsigned GetBandwidthUsed() const;
00834 
00843     virtual BOOL SetBandwidthUsed(
00844       unsigned releasedBandwidth,   
00845       unsigned requiredBandwidth    
00846     );
00848 
00857     virtual BOOL SendUserInputString(
00858       const PString & value                   
00859     );
00860 
00877     virtual BOOL SendUserInputTone(
00878       char tone,        
00879       unsigned duration = 0  
00880     );
00881 
00888     virtual void OnUserInputString(
00889       const PString & value   
00890     );
00891 
00898     virtual void OnUserInputTone(
00899       char tone,
00900       unsigned duration
00901     );
00902 
00906     void SendUserInputHookFlash(
00907       unsigned duration = 500  
00908     ) { SendUserInputTone('!', duration); }
00909 
00912     virtual PString GetUserInput(
00913       unsigned timeout = 30   
00914     );
00915 
00920     virtual void SetUserInput(
00921       const PString & input     
00922     );
00923 
00926     virtual PString ReadUserInput(
00927       const char * terminators = "#\r\n", 
00928       unsigned lastDigitTimeout = 4,      
00929       unsigned firstDigitTimeout = 30     
00930     );
00931 
00938     virtual BOOL PromptUserInput(
00939       BOOL play   
00940     );
00942 
00957     virtual OpalT120Protocol * CreateT120ProtocolHandler();
00958 
00971     virtual OpalT38Protocol * CreateT38ProtocolHandler();
00972 
00974 
00979     OpalEndPoint & GetEndPoint() const { return endpoint; }
00980     
00983     OpalCall & GetCall() const { return ownerCall; }
00984 
00987     const PString & GetToken() const { return callToken; }
00988 
00991     BOOL IsOriginating() const { return originating; }
00992 
00995     PTime GetSetupUpTime() const { return setupTime; }
00996 
00999     PTime GetAlertingTime() const { return alertingTime; }
01000 
01003     PTime GetConnectionStartTime() const { return connectedTime; }
01004 
01007     PTime GetConnectionEndTime() const { return callEndTime; }
01008 
01011     const PString & GetLocalPartyName() const { return localPartyName; }
01012 
01015     virtual void SetLocalPartyName(const PString & name);
01016 
01019     const PString & GetDisplayName() const { return displayName; }
01020 
01023     void SetDisplayName(const PString & name) { displayName = name; }
01024 
01027     const PString & GetRemotePartyName() const { return remotePartyName; }
01028 
01031     const PString & GetRemoteApplication() const { return remoteApplication; }
01032     
01037     const PString & GetRemotePartyNumber() const { return remotePartyNumber; }
01038 
01041     const PString & GetRemotePartyAddress() const { return remotePartyAddress; }
01042 
01047     virtual const PString GetRemotePartyCallbackURL() const { return remotePartyAddress; }
01048 
01049 
01053     virtual const PString & GetCalledDestinationNumber() const { return calledDestinationNumber; }
01054 
01058     virtual const PString & GetCalledDestinationName() const { return calledDestinationName; }
01059 
01063     unsigned GetMinAudioJitterDelay() const { return minAudioJitterDelay; }
01064 
01068     unsigned GetMaxAudioJitterDelay() const { return maxAudioJitterDelay; }
01069 
01072     void SetAudioJitterDelay(
01073       unsigned minDelay,   
01074       unsigned maxDelay    
01075     );
01076 
01079     OpalSilenceDetector * GetSilenceDetector() const { return silenceDetector; }
01080     
01083     OpalEchoCanceler * GetEchoCanceler() const { return echoCanceler; }
01084 
01087     virtual const OpalGloballyUniqueID & GetIdentifier() const
01088     { return callIdentifier; }
01089 
01090     virtual OpalTransport & GetTransport() const
01091     { return *(OpalTransport *)NULL; }
01092 
01093     PDICTIONARY(MediaAddressesDict, POrdinalKey, OpalTransportAddress);
01094     MediaAddressesDict & GetMediaTransportAddresses()
01095     { return mediaTransportAddresses; }
01096 
01098 
01099     const RTP_DataFrame::PayloadMapType & GetRTPPayloadMap() const
01100     { return rtpPayloadMap; }
01101 
01102   protected:
01103     PDECLARE_NOTIFIER(OpalRFC2833Info, OpalConnection, OnUserInputInlineRFC2833);
01104     PDECLARE_NOTIFIER(RTP_DataFrame, OpalConnection, OnUserInputInBandDTMF);
01105     PDECLARE_NOTIFIER(PThread, OpalConnection, OnReleaseThreadMain);
01106 
01107   // Member variables
01108     OpalCall             & ownerCall;
01109     OpalEndPoint         & endpoint;
01110 
01111     Phases               phase;
01112     PString              callToken;
01113     OpalGloballyUniqueID callIdentifier;
01114     BOOL                 originating;
01115     PTime                setupTime;
01116     PTime                alertingTime;
01117     PTime                connectedTime;
01118     PTime                callEndTime;
01119     PString              localPartyName;
01120     PString              displayName;
01121     PString              remotePartyName;
01122     PString              remoteApplication;
01123     PString              remotePartyNumber;
01124     PString              remotePartyAddress;
01125     CallEndReason        callEndReason;
01126     PString              calledDestinationNumber;
01127     PString              calledDestinationName;
01128 
01129     PString               userInputString;
01130     PMutex                userInputMutex;
01131     PSyncPoint            userInputAvailable;
01132     BOOL                  detectInBandDTMF;
01133     OpalSilenceDetector * silenceDetector;
01134     OpalEchoCanceler  * echoCanceler;
01135     OpalRFC2833Proto    * rfc2833Handler;
01136     OpalT120Protocol    * t120handler;
01137     OpalT38Protocol     * t38handler;
01138 
01139 
01140     MediaAddressesDict  mediaTransportAddresses;
01141     OpalMediaStreamList mediaStreams;
01142     RTP_SessionManager  rtpSessions;
01143     unsigned            minAudioJitterDelay;
01144     unsigned            maxAudioJitterDelay;
01145     unsigned            bandwidthAvailable;
01146 
01147     RTP_DataFrame::PayloadMapType rtpPayloadMap;
01148 
01149     // The In-Band DTMF detector. This is used inside an audio filter which is
01150     // added to the audio channel.
01151     PDTMFDecoder        dtmfDecoder;
01152 
01156     void SetPhase(Phases phaseToSet);
01157 
01158 #if PTRACING
01159     friend ostream & operator<<(ostream & o, Phases p);
01160 #endif
01161 };
01162 
01163 
01164 #endif // __OPAL_CONNECTION_H
01165 
01166 
01167 // End of File ///////////////////////////////////////////////////////////////

Generated on Mon Jan 7 22:30:47 2008 for OPAL by  doxygen 1.4.6