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  2005/11/30 13:35:26  csoutheren
00029  * Changed tags for Doxygen
00030  *
00031  * Revision 2.44  2005/11/24 20:31:54  dsandras
00032  * Added support for echo cancelation using Speex.
00033  * Added possibility to add a filter to an OpalMediaPatch for all patches of a connection.
00034  *
00035  * Revision 2.43  2005/10/08 19:26:38  dsandras
00036  * Added OnForwarded callback in case of call forwarding.
00037  *
00038  * Revision 2.42  2005/09/20 07:25:43  csoutheren
00039  * Allow userdata to be passed from SetupCall through to Call and Connection constructors
00040  *
00041  * Revision 2.41  2005/08/24 10:43:51  rjongbloed
00042  * Changed create video functions yet again so can return pointers that are not to be deleted.
00043  *
00044  * Revision 2.40  2005/08/23 12:45:09  rjongbloed
00045  * Fixed creation of video preview window and setting video grab/display initial frame size.
00046  *
00047  * Revision 2.39  2005/07/14 08:51:18  csoutheren
00048  * Removed CreateExternalRTPAddress - it's not needed because you can override GetMediaAddress
00049  * to do the same thing
00050  * Fixed problems with logic associated with media bypass
00051  *
00052  * Revision 2.38  2005/07/11 06:52:16  csoutheren
00053  * Added support for outgoing calls using external RTP
00054  *
00055  * Revision 2.37  2005/07/11 01:52:24  csoutheren
00056  * Extended AnsweringCall to work for SIP as well as H.323
00057  * Fixed problems with external RTP connection in H.323
00058  * Added call to OnClosedMediaStream
00059  *
00060  * Revision 2.36  2005/07/09 06:57:20  rjongbloed
00061  * Changed SetSTUNServer so returns the determined NAT type.
00062  *
00063  * Revision 2.35  2005/06/13 23:13:53  csoutheren
00064  * Fixed various typos thanks to Julien PUYDT
00065  *
00066  * Revision 2.34  2005/05/25 17:04:08  dsandras
00067  * Fixed ClearAllCalls when being executed synchronously. Fixes a crash on exit when a call is in progress. Thanks Robert!
00068  *
00069  * Revision 2.33  2005/04/10 20:46:56  dsandras
00070  * Added callback that is called when a connection is put on hold (locally or remotely).
00071  *
00072  * Revision 2.32  2005/01/31 07:37:09  csoutheren
00073  * Fixed problem with compiling under gcc 3.4
00074  * Thanks to Peter Robinson
00075  *
00076  * Revision 2.31  2004/12/21 08:24:31  dsandras
00077  * The dictionnary key is a PString, not an OpalGloballyUniqueID. Fixes problem when doing several calls at the same time.
00078  *
00079  * Revision 2.30  2004/08/18 13:02:48  rjongbloed
00080  * Changed to make calling OPalManager::OnClearedCall() in override optional.
00081  *
00082  * Revision 2.29  2004/08/14 07:56:29  rjongbloed
00083  * Major revision to utilise the PSafeCollection classes for the connections and calls.
00084  *
00085  * Revision 2.28  2004/07/14 13:26:14  rjongbloed
00086  * Fixed issues with the propagation of the "established" phase of a call. Now
00087  *   calling an OnEstablished() chain like OnAlerting() and OnConnected() to
00088  *   finally arrive at OnEstablishedCall() on OpalManager
00089  *
00090  * Revision 2.27  2004/07/11 12:42:10  rjongbloed
00091  * Added function on endpoints to get the list of all media formats any
00092  *   connection the endpoint may create can support.
00093  *
00094  * Revision 2.26  2004/07/04 12:50:50  rjongbloed
00095  * Added some access functions to manager lists
00096  *
00097  * Revision 2.25  2004/06/05 14:34:44  rjongbloed
00098  * Added functions to set the auto start video tx/rx flags.
00099  *
00100  * Revision 2.24  2004/05/24 13:40:12  rjongbloed
00101  * Added default values for silence suppression parameters.
00102  *
00103  * Revision 2.23  2004/05/15 12:53:03  rjongbloed
00104  * Added default username and display name to manager, for all endpoints.
00105  *
00106  * Revision 2.22  2004/04/18 07:09:12  rjongbloed
00107  * Added a couple more API functions to bring OPAL into line with similar functions in OpenH323.
00108  *
00109  * Revision 2.21  2004/03/11 06:54:27  csoutheren
00110  * Added ability to disable SIP or H.323 stacks
00111  *
00112  * Revision 2.20  2004/02/24 11:37:01  rjongbloed
00113  * More work on NAT support, manual external address translation and STUN
00114  *
00115  * Revision 2.19  2004/02/19 10:47:01  rjongbloed
00116  * Merged OpenH323 version 1.13.1 changes.
00117  *
00118  * Revision 2.18  2004/01/18 15:36:07  rjongbloed
00119  * Added stun support
00120  *
00121  * Revision 2.17  2003/03/17 10:26:59  robertj
00122  * Added video support.
00123  *
00124  * Revision 2.16  2003/03/06 03:57:47  robertj
00125  * IVR support (work in progress) requiring large changes everywhere.
00126  *
00127  * Revision 2.15  2002/11/10 11:33:17  robertj
00128  * Updated to OpenH323 v1.10.3
00129  *
00130  * Revision 2.14  2002/09/16 02:52:35  robertj
00131  * Added #define so can select if #pragma interface/implementation is used on
00132  *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
00133  *
00134  * Revision 2.13  2002/09/06 02:44:09  robertj
00135  * Added routing table system to route calls by regular expressions.
00136  *
00137  * Revision 2.12  2002/09/04 06:01:47  robertj
00138  * Updated to OpenH323 v1.9.6
00139  *
00140  * Revision 2.11  2002/07/01 04:56:31  robertj
00141  * Updated to OpenH323 v1.9.1
00142  *
00143  * Revision 2.10  2002/04/10 08:15:31  robertj
00144  * Added functions to set ports.
00145  *
00146  * Revision 2.9  2002/02/19 07:42:50  robertj
00147  * Restructured media bypass functions to fix problems with RFC2833.
00148  *
00149  * Revision 2.8  2002/02/11 07:38:55  robertj
00150  * Added media bypass for streams between compatible protocols.
00151  *
00152  * Revision 2.7  2002/01/22 05:04:58  robertj
00153  * Revamp of user input API triggered by RFC2833 support
00154  *
00155  * Revision 2.6  2001/12/07 08:56:19  robertj
00156  * Renamed RTP to be more general UDP port base, and TCP to be IP.
00157  *
00158  * Revision 2.5  2001/11/14 01:31:55  robertj
00159  * Corrected placement of adjusting media format list.
00160  *
00161  * Revision 2.4  2001/11/13 06:25:56  robertj
00162  * Changed SetUpConnection() so returns BOOL as returning
00163  *   pointer to connection is not useful.
00164  *
00165  * Revision 2.3  2001/08/23 05:51:17  robertj
00166  * Completed implementation of codec reordering.
00167  *
00168  * Revision 2.2  2001/08/17 08:23:59  robertj
00169  * Changed OnEstablished() to OnEstablishedCall() to be consistent.
00170  * Moved call end reasons enum from OpalConnection to global.
00171  *
00172  * Revision 2.1  2001/08/01 05:52:55  robertj
00173  * Moved media formats list from endpoint to connection.
00174  * Added function to adjust calls media formats list.
00175  *
00176  * Revision 2.0  2001/07/27 15:48:24  robertj
00177  * Conversion of OpenH323 to Open Phone Abstraction Library (OPAL)
00178  *
00179  */
00180 
00181 #ifndef __OPAL_MANAGER_H
00182 #define __OPAL_MANAGER_H
00183 
00184 #ifdef P_USE_PRAGMA
00185 #pragma interface
00186 #endif
00187 
00188 #include <opal/buildopts.h>
00189 
00190 #include <opal/call.h>
00191 #include <opal/guid.h>
00192 #include <codec/silencedetect.h>
00193 #include <codec/echocancel.h>
00194 #include <ptclib/pstun.h>
00195 
00196 class OpalEndPoint;
00197 class OpalMediaPatch;
00198 
00199 
00216 class OpalManager : public PObject
00217 {
00218     PCLASSINFO(OpalManager, PObject);
00219   public:
00224     OpalManager();
00225 
00230     ~OpalManager();
00232 
00242     void AttachEndPoint(
00243       OpalEndPoint * endpoint
00244     );
00245 
00249     void DetachEndPoint(
00250       OpalEndPoint * endpoint
00251     );
00252 
00255     OpalEndPoint * FindEndPoint(
00256       const PString & prefix
00257     );
00258 
00261     const PList<OpalEndPoint> & GetEndPoints() const { return endpoints; }
00263 
00285     virtual BOOL SetUpCall(
00286       const PString & partyA,       
00287       const PString & partyB,       
00288       PString & token,              
00289       void * userData = NULL        
00290     );
00291 
00300     virtual void OnEstablishedCall(
00301       OpalCall & call   
00302     );
00303 
00309     virtual BOOL HasCall(
00310       const PString & token  
00311     ) { return activeCalls.FindWithLock(token, PSafeReference) != NULL; }
00312 
00319     virtual BOOL IsCallEstablished(
00320       const PString & token  
00321     );
00322 
00331     PSafePtr<OpalCall> FindCallWithLock(
00332       const PString & token,  
00333       PSafetyMode mode = PSafeReadWrite
00334     ) { return activeCalls.FindWithLock(token, mode); }
00335 
00343     virtual BOOL ClearCall(
00344       const PString & token,    
00345       OpalConnection::CallEndReason reason = OpalConnection::EndedByLocalUser, 
00346       PSyncPoint * sync = NULL  
00347     );
00348 
00356     virtual BOOL ClearCallSynchronous(
00357       const PString & token,    
00358       OpalConnection::CallEndReason reason = OpalConnection::EndedByLocalUser 
00359     );
00360 
00366     virtual void ClearAllCalls(
00367       OpalConnection::CallEndReason reason = OpalConnection::EndedByLocalUser, 
00368       BOOL wait = TRUE   
00369     );
00370 
00384     virtual void OnClearedCall(
00385       OpalCall & call   
00386     );
00387 
00396     virtual OpalCall * CreateCall();
00397     virtual OpalCall * CreateCall(
00398       void * userData            
00399     );
00400 
00409     virtual void DestroyCall(
00410       OpalCall * call
00411     );
00412 
00416     PString GetNextCallToken();
00418 
00455     virtual BOOL MakeConnection(
00456       OpalCall & call,        
00457       const PString & party   
00458     );
00459     virtual BOOL MakeConnection(
00460       OpalCall & call,        
00461       const PString & party,  
00462       void * userData         
00463     );
00464 
00491     virtual BOOL OnIncomingConnection(
00492       OpalConnection & connection   
00493     );
00494 
00501     virtual PString OnRouteConnection(
00502       OpalConnection & connection  
00503     );
00504 
00521     virtual void OnAlerting(
00522       OpalConnection & connection   
00523     );
00524 
00525     virtual OpalConnection::AnswerCallResponse
00526        OnAnswerCall(OpalConnection & connection,
00527                      const PString & caller
00528     );
00529 
00541     virtual void OnConnected(
00542       OpalConnection & connection   
00543     );
00544 
00557     virtual void OnEstablished(
00558       OpalConnection & connection   
00559     );
00560 
00576     virtual void OnReleased(
00577       OpalConnection & connection   
00578     );
00579     
00586     virtual void OnHold(
00587       OpalConnection & connection   
00588     );
00589 
00594     virtual BOOL OnForwarded(
00595       OpalConnection & connection,  
00596       const PString & remoteParty         
00597     );
00599 
00611     virtual void AdjustMediaFormats(
00612       const OpalConnection & connection,  
00613       OpalMediaFormatList & mediaFormats  
00614     ) const;
00615 
00618     virtual BOOL IsMediaBypassPossible(
00619       const OpalConnection & source,      
00620       const OpalConnection & destination, 
00621       unsigned sessionID                  
00622     ) const;
00623 
00639     virtual BOOL OnOpenMediaStream(
00640       OpalConnection & connection,  
00641       OpalMediaStream & stream    
00642     );
00643 
00648     virtual void OnClosedMediaStream(
00649       const OpalMediaStream & stream     
00650     );
00651 
00656     virtual void AddVideoMediaFormats(
00657       OpalMediaFormatList & mediaFormats, 
00658       const OpalConnection * connection = NULL  
00659     ) const;
00660 
00663     virtual BOOL CreateVideoInputDevice(
00664       const OpalConnection & connection,    
00665       const OpalMediaFormat & mediaFormat,  
00666       PVideoInputDevice * & device,         
00667       BOOL & autoDelete                     
00668     );
00669 
00673     virtual BOOL CreateVideoOutputDevice(
00674       const OpalConnection & connection,    
00675       const OpalMediaFormat & mediaFormat,  
00676       BOOL preview,                         
00677       PVideoOutputDevice * & device,        
00678       BOOL & autoDelete                     
00679     );
00680 
00688     virtual OpalMediaPatch * CreateMediaPatch(
00689       OpalMediaStream & source         
00690     );
00691 
00696     virtual void DestroyMediaPatch(
00697       OpalMediaPatch * patch
00698     );
00699 
00707     virtual BOOL OnStartMediaPatch(
00708       const OpalMediaPatch & patch     
00709     );
00711 
00719     virtual void OnUserInputString(
00720       OpalConnection & connection,  
00721       const PString & value         
00722     );
00723 
00730     virtual void OnUserInputTone(
00731       OpalConnection & connection,  
00732       char tone,                    
00733       int duration                  
00734     );
00736 
00749     virtual OpalT120Protocol * CreateT120ProtocolHandler(
00750       const OpalConnection & connection  
00751     ) const;
00752 
00763     virtual OpalT38Protocol * CreateT38ProtocolHandler(
00764       const OpalConnection & connection  
00765     ) const;
00766 
00767     class RouteEntry : public PObject
00768     {
00769         PCLASSINFO(RouteEntry, PObject);
00770       public:
00771         RouteEntry(const PString & pat, const PString & dest);
00772         void PrintOn(ostream & strm) const;
00773         PString            pattern;
00774         PString            destination;
00775         PRegularExpression regex;
00776     };
00777     PLIST(RouteTable, RouteEntry);
00778 
00805     virtual BOOL AddRouteEntry(
00806       const PString & spec  
00807     );
00808 
00815     BOOL SetRouteTable(
00816       const PStringArray & specs  
00817     );
00818 
00823     void SetRouteTable(
00824       const RouteTable & table  
00825     );
00826 
00829     const RouteTable & GetRouteTable() const { return routeTable; }
00830 
00833     virtual PString ApplyRouteTable(
00834       const PString & proto,
00835       const PString & addr
00836     );
00838 
00843     const PString & GetDefaultUserName() const { return defaultUserName; }
00844 
00847     void SetDefaultUserName(
00848       const PString & name
00849     ) { defaultUserName = name; }
00850 
00853     const PString & GetDefaultDisplayName() const { return defaultDisplayName; }
00854 
00857     void SetDefaultDisplayName(
00858       const PString & name
00859     ) { defaultDisplayName = name; }
00860 
00863     BOOL CanAutoStartReceiveVideo() const { return autoStartReceiveVideo; }
00864 
00867     void SetAutoStartReceiveVideo(BOOL can) { autoStartReceiveVideo = can; }
00868 
00871     BOOL CanAutoStartTransmitVideo() const { return autoStartTransmitVideo; }
00872 
00875     void SetAutoStartTransmitVideo(BOOL can) { autoStartTransmitVideo = can; }
00876 
00883     virtual BOOL IsLocalAddress(
00884       const PIPSocket::Address & remoteAddress
00885     ) const;
00886 
00893     virtual BOOL TranslateIPAddress(
00894       PIPSocket::Address & localAddress,
00895       const PIPSocket::Address & remoteAddress
00896     );
00897 
00900     const PIPSocket::Address & GetTranslationAddress() const { return translationAddress; }
00901 
00904     void SetTranslationAddress(
00905       const PIPSocket::Address & address
00906     ) { translationAddress = address; }
00907 
00913     PSTUNClient * GetSTUN(
00914       const PIPSocket::Address & address = 0
00915     ) const;
00916 
00921     PSTUNClient::NatTypes SetSTUNServer(
00922       const PString & server
00923     );
00924 
00927     WORD GetTCPPortBase() const { return tcpPorts.base; }
00928 
00931     WORD GetTCPPortMax() const { return tcpPorts.max; }
00932 
00935     void SetTCPPorts(unsigned tcpBase, unsigned tcpMax);
00936 
00939     WORD GetNextTCPPort();
00940 
00943     WORD GetUDPPortBase() const { return udpPorts.base; }
00944 
00947     WORD GetUDPPortMax() const { return udpPorts.max; }
00948 
00951     void SetUDPPorts(unsigned udpBase, unsigned udpMax);
00952 
00955     WORD GetNextUDPPort();
00956 
00959     WORD GetRtpIpPortBase() const { return rtpIpPorts.base; }
00960 
00963     WORD GetRtpIpPortMax() const { return rtpIpPorts.max; }
00964 
00967     void SetRtpIpPorts(unsigned udpBase, unsigned udpMax);
00968 
00971     WORD GetRtpIpPortPair();
00972 
00975     BYTE GetRtpIpTypeofService() const { return rtpIpTypeofService; }
00976 
00979     void SetRtpIpTypeofService(unsigned tos) { rtpIpTypeofService = (BYTE)tos; }
00980 
00984     unsigned GetMinAudioJitterDelay() const { return minAudioJitterDelay; }
00985 
00989     unsigned GetMaxAudioJitterDelay() const { return maxAudioJitterDelay; }
00990 
00993     void SetAudioJitterDelay(
00994       unsigned minDelay,   
00995       unsigned maxDelay    
00996     );
00997 
01000     const PStringArray & GetMediaFormatOrder() const { return mediaFormatOrder; }
01001 
01004     void SetMediaFormatOrder(const PStringArray & order) { mediaFormatOrder = order; }
01005 
01008     const PStringArray & GetMediaFormatMask() const { return mediaFormatMask; }
01009 
01012     void SetMediaFormatMask(const PStringArray & mask) { mediaFormatMask = mask; }
01013 
01016     virtual void SetSilenceDetectParams(
01017       const OpalSilenceDetector::Params & params
01018     ) { silenceDetectParams = params; }
01019 
01022     const OpalSilenceDetector::Params & GetSilenceDetectParams() const { return silenceDetectParams; }
01023     
01026     virtual void SetEchoCancelParams(
01027       const OpalEchoCanceler::Params & params
01028     ) { echoCancelParams = params; }
01029 
01032     const OpalEchoCanceler::Params & GetEchoCancelParams() const { return echoCancelParams; }
01033 
01041     virtual BOOL SetVideoInputDevice(
01042       const PVideoDevice::OpenArgs & deviceArgs 
01043     );
01044 
01048     const PVideoDevice::OpenArgs & GetVideoInputDevice() const { return videoInputDevice; }
01049 
01057     virtual BOOL SetVideoPreviewDevice(
01058       const PVideoDevice::OpenArgs & deviceArgs 
01059     );
01060 
01064     const PVideoDevice::OpenArgs & GetVideoPreviewDevice() const { return videoPreviewDevice; }
01065 
01073     virtual BOOL SetVideoOutputDevice(
01074       const PVideoDevice::OpenArgs & deviceArgs 
01075     );
01076 
01080     const PVideoDevice::OpenArgs & GetVideoOutputDevice() const { return videoOutputDevice; }
01081 
01082     BOOL DetectInBandDTMFDisabled() const
01083       { return disableDetectInBandDTMF; }
01084 
01087     void DisableDetectInBandDTMF(
01088       BOOL mode 
01089     ) { disableDetectInBandDTMF = mode; } 
01090 
01093     const PTimeInterval & GetNoMediaTimeout() const { return noMediaTimeout; }
01094 
01097     BOOL SetNoMediaTimeout(
01098       const PTimeInterval & newInterval  
01099     );
01100 
01103     const PString & GetDefaultILSServer() const { return ilsServer; }
01104 
01107     void SetDefaultILSServer(
01108       const PString & server
01109     ) { ilsServer = server; }
01111 
01112     // needs to be public for gcc 3.4
01113     void GarbageCollection();
01114 
01115   protected:
01116     // Configuration variables
01117     PString       defaultUserName;
01118     PString       defaultDisplayName;
01119     BOOL          autoStartReceiveVideo;
01120     BOOL          autoStartTransmitVideo;
01121     BYTE          rtpIpTypeofService;
01122     unsigned      minAudioJitterDelay;
01123     unsigned      maxAudioJitterDelay;
01124     PStringArray  mediaFormatOrder;
01125     PStringArray  mediaFormatMask;
01126     BOOL          disableDetectInBandDTMF;
01127     PTimeInterval noMediaTimeout;
01128     PString       ilsServer;
01129 
01130     OpalSilenceDetector::Params silenceDetectParams;
01131     OpalEchoCanceler::Params echoCancelParams;
01132 
01133     PVideoDevice::OpenArgs videoInputDevice;
01134     PVideoDevice::OpenArgs videoPreviewDevice;
01135     PVideoDevice::OpenArgs videoOutputDevice;
01136 
01137     struct PortInfo {
01138       void Set(
01139         unsigned base,
01140         unsigned max,
01141         unsigned range,
01142         unsigned dflt
01143       );
01144       WORD GetNext(
01145         unsigned increment
01146       );
01147 
01148       PMutex mutex;
01149       WORD   base;
01150       WORD   max;
01151       WORD   current;
01152     } tcpPorts, udpPorts, rtpIpPorts;
01153 
01154     PIPSocket::Address translationAddress;
01155     PSTUNClient      * stun;
01156 
01157     RouteTable routeTable;
01158     PMutex     routeTableMutex;
01159 
01160     // Dynamic variables
01161     PMutex inUseFlag;
01162 
01163     PList<OpalEndPoint> endpoints;
01164 
01165     unsigned     lastCallTokenID;
01166 
01167     class CallDict : public PSafeDictionary<PString, OpalCall>
01168     {
01169       public:
01170         CallDict(OpalManager & mgr) : manager(mgr) { }
01171         virtual void DeleteObject(PObject * object) const;
01172         OpalManager & manager;
01173     } activeCalls;
01174 
01175     BOOL         clearingAllCalls;
01176     PSyncPoint   allCallsCleared;
01177     PThread    * garbageCollector;
01178     PSyncPoint   garbageCollectExit;
01179     PDECLARE_NOTIFIER(PThread, OpalManager, GarbageMain);
01180 
01181   friend OpalCall::OpalCall(OpalManager & mgr);
01182   friend void OpalCall::OnReleased(OpalConnection & connection);
01183 };
01184 
01185 
01186 PString  OpalGetVersion();
01187 unsigned OpalGetMajorVersion();
01188 unsigned OpalGetMinorVersion();
01189 unsigned OpalGetBuildNumber();
01190 
01191 
01192 #endif // __OPAL_MANAGER_H
01193 
01194 
01195 // End of File ///////////////////////////////////////////////////////////////

Generated on Mon Sep 25 16:20:07 2006 for OPAL by  doxygen 1.4.7