manager.h

Go to the documentation of this file.
00001 /*
00002  * manager.h
00003  *
00004  * OPAL system manager.
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: manager.h,v $
00028  * Revision 2.45.2.1  2006/12/08 06:27:20  csoutheren
00029  * Fix compilation problem caused by bad patch backports
00030  * Allow compilation with latest PWLib
00031  *
00032  * Revision 2.45  2005/11/30 13:35:26  csoutheren
00033  * Changed tags for Doxygen
00034  *
00035  * Revision 2.44  2005/11/24 20:31:54  dsandras
00036  * Added support for echo cancelation using Speex.
00037  * Added possibility to add a filter to an OpalMediaPatch for all patches of a connection.
00038  *
00039  * Revision 2.43  2005/10/08 19:26:38  dsandras
00040  * Added OnForwarded callback in case of call forwarding.
00041  *
00042  * Revision 2.42  2005/09/20 07:25:43  csoutheren
00043  * Allow userdata to be passed from SetupCall through to Call and Connection constructors
00044  *
00045  * Revision 2.41  2005/08/24 10:43:51  rjongbloed
00046  * Changed create video functions yet again so can return pointers that are not to be deleted.
00047  *
00048  * Revision 2.40  2005/08/23 12:45:09  rjongbloed
00049  * Fixed creation of video preview window and setting video grab/display initial frame size.
00050  *
00051  * Revision 2.39  2005/07/14 08:51:18  csoutheren
00052  * Removed CreateExternalRTPAddress - it's not needed because you can override GetMediaAddress
00053  * to do the same thing
00054  * Fixed problems with logic associated with media bypass
00055  *
00056  * Revision 2.38  2005/07/11 06:52:16  csoutheren
00057  * Added support for outgoing calls using external RTP
00058  *
00059  * Revision 2.37  2005/07/11 01:52:24  csoutheren
00060  * Extended AnsweringCall to work for SIP as well as H.323
00061  * Fixed problems with external RTP connection in H.323
00062  * Added call to OnClosedMediaStream
00063  *
00064  * Revision 2.36  2005/07/09 06:57:20  rjongbloed
00065  * Changed SetSTUNServer so returns the determined NAT type.
00066  *
00067  * Revision 2.35  2005/06/13 23:13:53  csoutheren
00068  * Fixed various typos thanks to Julien PUYDT
00069  *
00070  * Revision 2.34  2005/05/25 17:04:08  dsandras
00071  * Fixed ClearAllCalls when being executed synchronously. Fixes a crash on exit when a call is in progress. Thanks Robert!
00072  *
00073  * Revision 2.33  2005/04/10 20:46:56  dsandras
00074  * Added callback that is called when a connection is put on hold (locally or remotely).
00075  *
00076  * Revision 2.32  2005/01/31 07:37:09  csoutheren
00077  * Fixed problem with compiling under gcc 3.4
00078  * Thanks to Peter Robinson
00079  *
00080  * Revision 2.31  2004/12/21 08:24:31  dsandras
00081  * The dictionnary key is a PString, not an OpalGloballyUniqueID. Fixes problem when doing several calls at the same time.
00082  *
00083  * Revision 2.30  2004/08/18 13:02:48  rjongbloed
00084  * Changed to make calling OPalManager::OnClearedCall() in override optional.
00085  *
00086  * Revision 2.29  2004/08/14 07:56:29  rjongbloed
00087  * Major revision to utilise the PSafeCollection classes for the connections and calls.
00088  *
00089  * Revision 2.28  2004/07/14 13:26:14  rjongbloed
00090  * Fixed issues with the propagation of the "established" phase of a call. Now
00091  *   calling an OnEstablished() chain like OnAlerting() and OnConnected() to
00092  *   finally arrive at OnEstablishedCall() on OpalManager
00093  *
00094  * Revision 2.27  2004/07/11 12:42:10  rjongbloed
00095  * Added function on endpoints to get the list of all media formats any
00096  *   connection the endpoint may create can support.
00097  *
00098  * Revision 2.26  2004/07/04 12:50:50  rjongbloed
00099  * Added some access functions to manager lists
00100  *
00101  * Revision 2.25  2004/06/05 14:34:44  rjongbloed
00102  * Added functions to set the auto start video tx/rx flags.
00103  *
00104  * Revision 2.24  2004/05/24 13:40:12  rjongbloed
00105  * Added default values for silence suppression parameters.
00106  *
00107  * Revision 2.23  2004/05/15 12:53:03  rjongbloed
00108  * Added default username and display name to manager, for all endpoints.
00109  *
00110  * Revision 2.22  2004/04/18 07:09:12  rjongbloed
00111  * Added a couple more API functions to bring OPAL into line with similar functions in OpenH323.
00112  *
00113  * Revision 2.21  2004/03/11 06:54:27  csoutheren
00114  * Added ability to disable SIP or H.323 stacks
00115  *
00116  * Revision 2.20  2004/02/24 11:37:01  rjongbloed
00117  * More work on NAT support, manual external address translation and STUN
00118  *
00119  * Revision 2.19  2004/02/19 10:47:01  rjongbloed
00120  * Merged OpenH323 version 1.13.1 changes.
00121  *
00122  * Revision 2.18  2004/01/18 15:36:07  rjongbloed
00123  * Added stun support
00124  *
00125  * Revision 2.17  2003/03/17 10:26:59  robertj
00126  * Added video support.
00127  *
00128  * Revision 2.16  2003/03/06 03:57:47  robertj
00129  * IVR support (work in progress) requiring large changes everywhere.
00130  *
00131  * Revision 2.15  2002/11/10 11:33:17  robertj
00132  * Updated to OpenH323 v1.10.3
00133  *
00134  * Revision 2.14  2002/09/16 02:52:35  robertj
00135  * Added #define so can select if #pragma interface/implementation is used on
00136  *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
00137  *
00138  * Revision 2.13  2002/09/06 02:44:09  robertj
00139  * Added routing table system to route calls by regular expressions.
00140  *
00141  * Revision 2.12  2002/09/04 06:01:47  robertj
00142  * Updated to OpenH323 v1.9.6
00143  *
00144  * Revision 2.11  2002/07/01 04:56:31  robertj
00145  * Updated to OpenH323 v1.9.1
00146  *
00147  * Revision 2.10  2002/04/10 08:15:31  robertj
00148  * Added functions to set ports.
00149  *
00150  * Revision 2.9  2002/02/19 07:42:50  robertj
00151  * Restructured media bypass functions to fix problems with RFC2833.
00152  *
00153  * Revision 2.8  2002/02/11 07:38:55  robertj
00154  * Added media bypass for streams between compatible protocols.
00155  *
00156  * Revision 2.7  2002/01/22 05:04:58  robertj
00157  * Revamp of user input API triggered by RFC2833 support
00158  *
00159  * Revision 2.6  2001/12/07 08:56:19  robertj
00160  * Renamed RTP to be more general UDP port base, and TCP to be IP.
00161  *
00162  * Revision 2.5  2001/11/14 01:31:55  robertj
00163  * Corrected placement of adjusting media format list.
00164  *
00165  * Revision 2.4  2001/11/13 06:25:56  robertj
00166  * Changed SetUpConnection() so returns BOOL as returning
00167  *   pointer to connection is not useful.
00168  *
00169  * Revision 2.3  2001/08/23 05:51:17  robertj
00170  * Completed implementation of codec reordering.
00171  *
00172  * Revision 2.2  2001/08/17 08:23:59  robertj
00173  * Changed OnEstablished() to OnEstablishedCall() to be consistent.
00174  * Moved call end reasons enum from OpalConnection to global.
00175  *
00176  * Revision 2.1  2001/08/01 05:52:55  robertj
00177  * Moved media formats list from endpoint to connection.
00178  * Added function to adjust calls media formats list.
00179  *
00180  * Revision 2.0  2001/07/27 15:48:24  robertj
00181  * Conversion of OpenH323 to Open Phone Abstraction Library (OPAL)
00182  *
00183  */
00184 
00185 #ifndef __OPAL_MANAGER_H
00186 #define __OPAL_MANAGER_H
00187 
00188 #ifdef P_USE_PRAGMA
00189 #pragma interface
00190 #endif
00191 
00192 #include <opal/buildopts.h>
00193 
00194 #include <opal/call.h>
00195 #include <opal/guid.h>
00196 #include <codec/silencedetect.h>
00197 #include <codec/echocancel.h>
00198 
00199 #include <ptclib/pstun.h>
00200 #include <ptlib/videoio.h>
00201 
00202 class OpalEndPoint;
00203 class OpalMediaPatch;
00204 
00205 
00222 class OpalManager : public PObject
00223 {
00224     PCLASSINFO(OpalManager, PObject);
00225   public:
00230     OpalManager();
00231 
00236     ~OpalManager();
00238 
00248     void AttachEndPoint(
00249       OpalEndPoint * endpoint
00250     );
00251 
00255     void DetachEndPoint(
00256       OpalEndPoint * endpoint
00257     );
00258 
00261     OpalEndPoint * FindEndPoint(
00262       const PString & prefix
00263     );
00264 
00267     const PList<OpalEndPoint> & GetEndPoints() const { return endpoints; }
00269 
00291     virtual BOOL SetUpCall(
00292       const PString & partyA,       
00293       const PString & partyB,       
00294       PString & token,              
00295       void * userData = NULL        
00296     );
00297 
00306     virtual void OnEstablishedCall(
00307       OpalCall & call   
00308     );
00309 
00315     virtual BOOL HasCall(
00316       const PString & token  
00317     ) { return activeCalls.FindWithLock(token, PSafeReference) != NULL; }
00318 
00325     virtual BOOL IsCallEstablished(
00326       const PString & token  
00327     );
00328 
00337     PSafePtr<OpalCall> FindCallWithLock(
00338       const PString & token,  
00339       PSafetyMode mode = PSafeReadWrite
00340     ) { return activeCalls.FindWithLock(token, mode); }
00341 
00349     virtual BOOL ClearCall(
00350       const PString & token,    
00351       OpalConnection::CallEndReason reason = OpalConnection::EndedByLocalUser, 
00352       PSyncPoint * sync = NULL  
00353     );
00354 
00362     virtual BOOL ClearCallSynchronous(
00363       const PString & token,    
00364       OpalConnection::CallEndReason reason = OpalConnection::EndedByLocalUser 
00365     );
00366 
00372     virtual void ClearAllCalls(
00373       OpalConnection::CallEndReason reason = OpalConnection::EndedByLocalUser, 
00374       BOOL wait = TRUE   
00375     );
00376 
00390     virtual void OnClearedCall(
00391       OpalCall & call   
00392     );
00393 
00402     virtual OpalCall * CreateCall();
00403     virtual OpalCall * CreateCall(
00404       void * userData            
00405     );
00406 
00415     virtual void DestroyCall(
00416       OpalCall * call
00417     );
00418 
00422     PString GetNextCallToken();
00424 
00461     virtual BOOL MakeConnection(
00462       OpalCall & call,        
00463       const PString & party   
00464     );
00465     virtual BOOL MakeConnection(
00466       OpalCall & call,        
00467       const PString & party,  
00468       void * userData         
00469     );
00470 
00497     virtual BOOL OnIncomingConnection(
00498       OpalConnection & connection   
00499     );
00500 
00507     virtual PString OnRouteConnection(
00508       OpalConnection & connection  
00509     );
00510 
00527     virtual void OnAlerting(
00528       OpalConnection & connection   
00529     );
00530 
00531     virtual OpalConnection::AnswerCallResponse
00532        OnAnswerCall(OpalConnection & connection,
00533                      const PString & caller
00534     );
00535 
00547     virtual void OnConnected(
00548       OpalConnection & connection   
00549     );
00550 
00563     virtual void OnEstablished(
00564       OpalConnection & connection   
00565     );
00566 
00582     virtual void OnReleased(
00583       OpalConnection & connection   
00584     );
00585     
00592     virtual void OnHold(
00593       OpalConnection & connection   
00594     );
00595 
00600     virtual BOOL OnForwarded(
00601       OpalConnection & connection,  
00602       const PString & remoteParty         
00603     );
00605 
00617     virtual void AdjustMediaFormats(
00618       const OpalConnection & connection,  
00619       OpalMediaFormatList & mediaFormats  
00620     ) const;
00621 
00624     virtual BOOL IsMediaBypassPossible(
00625       const OpalConnection & source,      
00626       const OpalConnection & destination, 
00627       unsigned sessionID                  
00628     ) const;
00629 
00645     virtual BOOL OnOpenMediaStream(
00646       OpalConnection & connection,  
00647       OpalMediaStream & stream    
00648     );
00649 
00654     virtual void OnClosedMediaStream(
00655       const OpalMediaStream & stream     
00656     );
00657 
00662     virtual void AddVideoMediaFormats(
00663       OpalMediaFormatList & mediaFormats, 
00664       const OpalConnection * connection = NULL  
00665     ) const;
00666 
00669     virtual BOOL CreateVideoInputDevice(
00670       const OpalConnection & connection,    
00671       const OpalMediaFormat & mediaFormat,  
00672       PVideoInputDevice * & device,         
00673       BOOL & autoDelete                     
00674     );
00675 
00679     virtual BOOL CreateVideoOutputDevice(
00680       const OpalConnection & connection,    
00681       const OpalMediaFormat & mediaFormat,  
00682       BOOL preview,                         
00683       PVideoOutputDevice * & device,        
00684       BOOL & autoDelete                     
00685     );
00686 
00694     virtual OpalMediaPatch * CreateMediaPatch(
00695       OpalMediaStream & source         
00696     );
00697 
00702     virtual void DestroyMediaPatch(
00703       OpalMediaPatch * patch
00704     );
00705 
00713     virtual BOOL OnStartMediaPatch(
00714       const OpalMediaPatch & patch     
00715     );
00717 
00725     virtual void OnUserInputString(
00726       OpalConnection & connection,  
00727       const PString & value         
00728     );
00729 
00736     virtual void OnUserInputTone(
00737       OpalConnection & connection,  
00738       char tone,                    
00739       int duration                  
00740     );
00742 
00755     virtual OpalT120Protocol * CreateT120ProtocolHandler(
00756       const OpalConnection & connection  
00757     ) const;
00758 
00769     virtual OpalT38Protocol * CreateT38ProtocolHandler(
00770       const OpalConnection & connection  
00771     ) const;
00772 
00773     class RouteEntry : public PObject
00774     {
00775         PCLASSINFO(RouteEntry, PObject);
00776       public:
00777         RouteEntry(const PString & pat, const PString & dest);
00778         void PrintOn(ostream & strm) const;
00779         PString            pattern;
00780         PString            destination;
00781         PRegularExpression regex;
00782     };
00783     PLIST(RouteTable, RouteEntry);
00784 
00811     virtual BOOL AddRouteEntry(
00812       const PString & spec  
00813     );
00814 
00821     BOOL SetRouteTable(
00822       const PStringArray & specs  
00823     );
00824 
00829     void SetRouteTable(
00830       const RouteTable & table  
00831     );
00832 
00835     const RouteTable & GetRouteTable() const { return routeTable; }
00836 
00839     virtual PString ApplyRouteTable(
00840       const PString & proto,
00841       const PString & addr
00842     );
00844 
00849     const PString & GetDefaultUserName() const { return defaultUserName; }
00850 
00853     void SetDefaultUserName(
00854       const PString & name
00855     ) { defaultUserName = name; }
00856 
00859     const PString & GetDefaultDisplayName() const { return defaultDisplayName; }
00860 
00863     void SetDefaultDisplayName(
00864       const PString & name
00865     ) { defaultDisplayName = name; }
00866 
00869     BOOL CanAutoStartReceiveVideo() const { return autoStartReceiveVideo; }
00870 
00873     void SetAutoStartReceiveVideo(BOOL can) { autoStartReceiveVideo = can; }
00874 
00877     BOOL CanAutoStartTransmitVideo() const { return autoStartTransmitVideo; }
00878 
00881     void SetAutoStartTransmitVideo(BOOL can) { autoStartTransmitVideo = can; }
00882 
00889     virtual BOOL IsLocalAddress(
00890       const PIPSocket::Address & remoteAddress
00891     ) const;
00892 
00899     virtual BOOL TranslateIPAddress(
00900       PIPSocket::Address & localAddress,
00901       const PIPSocket::Address & remoteAddress
00902     );
00903 
00906     const PIPSocket::Address & GetTranslationAddress() const { return translationAddress; }
00907 
00910     void SetTranslationAddress(
00911       const PIPSocket::Address & address
00912     ) { translationAddress = address; }
00913 
00919     PSTUNClient * GetSTUN(
00920       const PIPSocket::Address & address = 0
00921     ) const;
00922 
00927     PSTUNClient::NatTypes SetSTUNServer(
00928       const PString & server
00929     );
00930 
00933     WORD GetTCPPortBase() const { return tcpPorts.base; }
00934 
00937     WORD GetTCPPortMax() const { return tcpPorts.max; }
00938 
00941     void SetTCPPorts(unsigned tcpBase, unsigned tcpMax);
00942 
00945     WORD GetNextTCPPort();
00946 
00949     WORD GetUDPPortBase() const { return udpPorts.base; }
00950 
00953     WORD GetUDPPortMax() const { return udpPorts.max; }
00954 
00957     void SetUDPPorts(unsigned udpBase, unsigned udpMax);
00958 
00961     WORD GetNextUDPPort();
00962 
00965     WORD GetRtpIpPortBase() const { return rtpIpPorts.base; }
00966 
00969     WORD GetRtpIpPortMax() const { return rtpIpPorts.max; }
00970 
00973     void SetRtpIpPorts(unsigned udpBase, unsigned udpMax);
00974 
00977     WORD GetRtpIpPortPair();
00978 
00981     BYTE GetRtpIpTypeofService() const { return rtpIpTypeofService; }
00982 
00985     void SetRtpIpTypeofService(unsigned tos) { rtpIpTypeofService = (BYTE)tos; }
00986 
00990     unsigned GetMinAudioJitterDelay() const { return minAudioJitterDelay; }
00991 
00995     unsigned GetMaxAudioJitterDelay() const { return maxAudioJitterDelay; }
00996 
00999     void SetAudioJitterDelay(
01000       unsigned minDelay,   
01001       unsigned maxDelay    
01002     );
01003 
01006     const PStringArray & GetMediaFormatOrder() const { return mediaFormatOrder; }
01007 
01010     void SetMediaFormatOrder(const PStringArray & order) { mediaFormatOrder = order; }
01011 
01014     const PStringArray & GetMediaFormatMask() const { return mediaFormatMask; }
01015 
01018     void SetMediaFormatMask(const PStringArray & mask) { mediaFormatMask = mask; }
01019 
01022     virtual void SetSilenceDetectParams(
01023       const OpalSilenceDetector::Params & params
01024     ) { silenceDetectParams = params; }
01025 
01028     const OpalSilenceDetector::Params & GetSilenceDetectParams() const { return silenceDetectParams; }
01029     
01032     virtual void SetEchoCancelParams(
01033       const OpalEchoCanceler::Params & params
01034     ) { echoCancelParams = params; }
01035 
01038     const OpalEchoCanceler::Params & GetEchoCancelParams() const { return echoCancelParams; }
01039 
01047     virtual BOOL SetVideoInputDevice(
01048       const PVideoDevice::OpenArgs & deviceArgs 
01049     );
01050 
01054     const PVideoDevice::OpenArgs & GetVideoInputDevice() const { return videoInputDevice; }
01055 
01063     virtual BOOL SetVideoPreviewDevice(
01064       const PVideoDevice::OpenArgs & deviceArgs 
01065     );
01066 
01070     const PVideoDevice::OpenArgs & GetVideoPreviewDevice() const { return videoPreviewDevice; }
01071 
01079     virtual BOOL SetVideoOutputDevice(
01080       const PVideoDevice::OpenArgs & deviceArgs 
01081     );
01082 
01086     const PVideoDevice::OpenArgs & GetVideoOutputDevice() const { return videoOutputDevice; }
01087 
01088     BOOL DetectInBandDTMFDisabled() const
01089       { return disableDetectInBandDTMF; }
01090 
01093     void DisableDetectInBandDTMF(
01094       BOOL mode 
01095     ) { disableDetectInBandDTMF = mode; } 
01096 
01099     const PTimeInterval & GetNoMediaTimeout() const { return noMediaTimeout; }
01100 
01103     BOOL SetNoMediaTimeout(
01104       const PTimeInterval & newInterval  
01105     );
01106 
01109     const PString & GetDefaultILSServer() const { return ilsServer; }
01110 
01113     void SetDefaultILSServer(
01114       const PString & server
01115     ) { ilsServer = server; }
01117 
01118     // needs to be public for gcc 3.4
01119     void GarbageCollection();
01120 
01121   protected:
01122     // Configuration variables
01123     PString       defaultUserName;
01124     PString       defaultDisplayName;
01125     BOOL          autoStartReceiveVideo;
01126     BOOL          autoStartTransmitVideo;
01127     BYTE          rtpIpTypeofService;
01128     unsigned      minAudioJitterDelay;
01129     unsigned      maxAudioJitterDelay;
01130     PStringArray  mediaFormatOrder;
01131     PStringArray  mediaFormatMask;
01132     BOOL          disableDetectInBandDTMF;
01133     PTimeInterval noMediaTimeout;
01134     PString       ilsServer;
01135 
01136     OpalSilenceDetector::Params silenceDetectParams;
01137     OpalEchoCanceler::Params echoCancelParams;
01138 
01139     PVideoDevice::OpenArgs videoInputDevice;
01140     PVideoDevice::OpenArgs videoPreviewDevice;
01141     PVideoDevice::OpenArgs videoOutputDevice;
01142 
01143     struct PortInfo {
01144       void Set(
01145         unsigned base,
01146         unsigned max,
01147         unsigned range,
01148         unsigned dflt
01149       );
01150       WORD GetNext(
01151         unsigned increment
01152       );
01153 
01154       PMutex mutex;
01155       WORD   base;
01156       WORD   max;
01157       WORD   current;
01158     } tcpPorts, udpPorts, rtpIpPorts;
01159 
01160     PIPSocket::Address translationAddress;
01161     PSTUNClient      * stun;
01162 
01163     RouteTable routeTable;
01164     PMutex     routeTableMutex;
01165 
01166     // Dynamic variables
01167     PMutex inUseFlag;
01168 
01169     PList<OpalEndPoint> endpoints;
01170 
01171     unsigned     lastCallTokenID;
01172 
01173     class CallDict : public PSafeDictionary<PString, OpalCall>
01174     {
01175       public:
01176         CallDict(OpalManager & mgr) : manager(mgr) { }
01177         virtual void DeleteObject(PObject * object) const;
01178         OpalManager & manager;
01179     } activeCalls;
01180 
01181     BOOL         clearingAllCalls;
01182     PSyncPoint   allCallsCleared;
01183     PThread    * garbageCollector;
01184     PSyncPoint   garbageCollectExit;
01185     PDECLARE_NOTIFIER(PThread, OpalManager, GarbageMain);
01186 
01187   friend OpalCall::OpalCall(OpalManager & mgr);
01188   friend void OpalCall::OnReleased(OpalConnection & connection);
01189 };
01190 
01191 
01192 PString  OpalGetVersion();
01193 unsigned OpalGetMajorVersion();
01194 unsigned OpalGetMinorVersion();
01195 unsigned OpalGetBuildNumber();
01196 
01197 
01198 #endif // __OPAL_MANAGER_H
01199 
01200 
01201 // End of File ///////////////////////////////////////////////////////////////

Generated on Fri Sep 28 13:16:49 2007 for OPAL by  doxygen 1.5.3