endpoint.h

Go to the documentation of this file.
00001 /*
00002  * endpoint.h
00003  *
00004  * Telephony endpoint 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: endpoint.h,v $
00028  * Revision 2.29  2005/11/30 13:35:26  csoutheren
00029  * Changed tags for Doxygen
00030  *
00031  * Revision 2.28  2005/10/08 19:26:37  dsandras
00032  * Added OnForwarded callback in case of call forwarding.
00033  *
00034  * Revision 2.27  2005/08/24 10:43:51  rjongbloed
00035  * Changed create video functions yet again so can return pointers that are not to be deleted.
00036  *
00037  * Revision 2.26  2005/08/23 12:45:09  rjongbloed
00038  * Fixed creation of video preview window and setting video grab/display initial frame size.
00039  *
00040  * Revision 2.25  2005/07/14 08:51:18  csoutheren
00041  * Removed CreateExternalRTPAddress - it's not needed because you can override GetMediaAddress
00042  * to do the same thing
00043  * Fixed problems with logic associated with media bypass
00044  *
00045  * Revision 2.24  2005/07/11 06:52:16  csoutheren
00046  * Added support for outgoing calls using external RTP
00047  *
00048  * Revision 2.23  2005/07/11 01:52:23  csoutheren
00049  * Extended AnsweringCall to work for SIP as well as H.323
00050  * Fixed problems with external RTP connection in H.323
00051  * Added call to OnClosedMediaStream
00052  *
00053  * Revision 2.22  2005/04/10 20:45:22  dsandras
00054  * Added callback that is called when a connection is put on hold (locally or remotely).
00055  *
00056  * Revision 2.21  2004/08/14 07:56:29  rjongbloed
00057  * Major revision to utilise the PSafeCollection classes for the connections and calls.
00058  *
00059  * Revision 2.20  2004/07/11 12:42:10  rjongbloed
00060  * Added function on endpoints to get the list of all media formats any
00061  *   connection the endpoint may create can support.
00062  *
00063  * Revision 2.19  2004/04/26 06:30:32  rjongbloed
00064  * Added ability to specify more than one defualt listener for an endpoint,
00065  *   required by SIP which listens on both UDP and TCP.
00066  *
00067  * Revision 2.18  2004/03/13 06:25:52  rjongbloed
00068  * Slight rearrangement of local party name and alias list to beter match common
00069  *   behaviour in ancestor.
00070  * Abstracted local party name for endpoint into ancestor from H.,323.
00071  *
00072  * Revision 2.17  2004/03/11 06:54:27  csoutheren
00073  * Added ability to disable SIP or H.323 stacks
00074  *
00075  * Revision 2.16  2004/02/19 10:46:44  rjongbloed
00076  * Merged OpenH323 version 1.13.1 changes.
00077  *
00078  * Revision 2.15  2003/03/17 10:26:59  robertj
00079  * Added video support.
00080  *
00081  * Revision 2.14  2003/03/06 03:57:47  robertj
00082  * IVR support (work in progress) requiring large changes everywhere.
00083  *
00084  * Revision 2.13  2002/11/10 11:33:17  robertj
00085  * Updated to OpenH323 v1.10.3
00086  *
00087  * Revision 2.12  2002/09/16 02:52:35  robertj
00088  * Added #define so can select if #pragma interface/implementation is used on
00089  *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
00090  *
00091  * Revision 2.11  2002/07/04 07:41:47  robertj
00092  * Fixed memory/thread leak of transports.
00093  *
00094  * Revision 2.10  2002/07/01 04:56:30  robertj
00095  * Updated to OpenH323 v1.9.1
00096  *
00097  * Revision 2.9  2002/04/05 10:36:53  robertj
00098  * Rearranged OnRelease to remove the connection from endpoints connection
00099  *   list at the end of the release phase rather than the beginning.
00100  *
00101  * Revision 2.8  2002/01/22 05:04:40  robertj
00102  * Revamp of user input API triggered by RFC2833 support
00103  *
00104  * Revision 2.7  2001/11/14 01:31:55  robertj
00105  * Corrected placement of adjusting media format list.
00106  *
00107  * Revision 2.6  2001/11/13 06:25:56  robertj
00108  * Changed SetUpConnection() so returns BOOL as returning
00109  *   pointer to connection is not useful.
00110  *
00111  * Revision 2.5  2001/08/23 05:51:17  robertj
00112  * Completed implementation of codec reordering.
00113  *
00114  * Revision 2.4  2001/08/22 10:20:09  robertj
00115  * Changed connection locking to use double mutex to guarantee that
00116  *   no threads can ever deadlock or access deleted connection.
00117  *
00118  * Revision 2.3  2001/08/17 08:22:23  robertj
00119  * Moved call end reasons enum from OpalConnection to global.
00120  *
00121  * Revision 2.2  2001/08/01 05:26:35  robertj
00122  * Moved media formats list from endpoint to connection.
00123  *
00124  * Revision 2.1  2001/07/30 07:22:25  robertj
00125  * Abstracted listener management from H.323 to OpalEndPoint class.
00126  *
00127  * Revision 2.0  2001/07/27 15:48:24  robertj
00128  * Conversion of OpenH323 to Open Phone Abstraction Library (OPAL)
00129  *
00130  */
00131 
00132 #ifndef __OPAL_ENDPOINT_H
00133 #define __OPAL_ENDPOINT_H
00134 
00135 #ifdef P_USE_PRAGMA
00136 #pragma interface
00137 #endif
00138 
00139 #include <opal/buildopts.h>
00140 
00141 #include <opal/manager.h>
00142 #include <opal/mediafmt.h>
00143 #include <opal/transports.h>
00144 
00145 
00146 class OpalCall;
00147 class OpalMediaStream;
00148 
00149 
00169 class OpalEndPoint : public PObject
00170 {
00171     PCLASSINFO(OpalEndPoint, PObject);
00172   public:
00173     enum Attributes {
00174       CanTerminateCall = 1,
00175       HasLineInterface = 2
00176     };
00177 
00182     OpalEndPoint(
00183       OpalManager & manager,          
00184       const PCaselessString & prefix, 
00185       unsigned attributes             
00186     );
00187 
00190     ~OpalEndPoint();
00192 
00199     void PrintOn(
00200       ostream & strm    
00201     ) const;
00203 
00213     BOOL StartListeners(
00214       const PStringArray & interfaces 
00215     );
00216 
00224     BOOL StartListener(
00225       const OpalTransportAddress & iface 
00226     );
00227 
00233     BOOL StartListener(
00234       OpalListener * listener 
00235     );
00236 
00241     virtual PStringArray GetDefaultListeners() const;
00242 
00246     BOOL RemoveListener(
00247       OpalListener * listener 
00248     );
00249 
00252     OpalTransportAddressArray GetInterfaceAddresses(
00253       BOOL excludeLocalHost = TRUE,       
00254       OpalTransport * associatedTransport = NULL
00256     );
00257 
00262     PDECLARE_NOTIFIER(PThread, OpalEndPoint, ListenerCallback);
00263 
00272     virtual BOOL NewIncomingConnection(
00273       OpalTransport * transport  
00274     );
00276 
00308     virtual BOOL MakeConnection(
00309       OpalCall & call,        
00310       const PString & party,  
00311       void * userData         
00312     ) = 0;
00313 
00335     virtual BOOL OnIncomingConnection(
00336       OpalConnection & connection   
00337     );
00338 
00354     virtual void OnAlerting(
00355       OpalConnection & connection   
00356     );
00357 
00374     virtual OpalConnection::AnswerCallResponse OnAnswerCall(
00375       OpalConnection & connection,    
00376        const PString & caller         
00377     );
00378 
00389     virtual void OnConnected(
00390       OpalConnection & connection   
00391     );
00392 
00404     virtual void OnEstablished(
00405       OpalConnection & connection   
00406     );
00407 
00426     virtual void OnReleased(
00427       OpalConnection & connection   
00428     );
00429 
00436     void OnHold(
00437       OpalConnection & connection   
00438     );
00439 
00444     virtual BOOL OnForwarded(
00445       OpalConnection & connection,  
00446       const PString & remoteParty         
00447     );
00448 
00456     virtual BOOL ClearCall(
00457       const PString & token,    
00458       OpalConnection::CallEndReason reason = OpalConnection::EndedByLocalUser, 
00459       PSyncPoint * sync = NULL  
00460     );
00461 
00466     virtual BOOL ClearCallSynchronous(
00467       const PString & token,    
00468       OpalConnection::CallEndReason reason = OpalConnection::EndedByLocalUser, 
00469       PSyncPoint * sync = NULL  
00470     );
00471 
00478     virtual void ClearAllCalls(
00479       OpalConnection::CallEndReason reason = OpalConnection::EndedByLocalUser, 
00480       BOOL wait = TRUE   
00481     );
00482 
00487     PSafePtr<OpalConnection> GetConnectionWithLock(
00488       const PString & token,     
00489       PSafetyMode mode = PSafeReadWrite
00490     ) { return connectionsActive.FindWithLock(token, mode); }
00491 
00494     PStringList GetAllConnections();
00495 
00498     virtual BOOL HasConnection(
00499       const PString & token   
00500     );
00501 
00504     virtual void DestroyConnection(
00505       OpalConnection * connection  
00506     );
00508 
00520     virtual OpalMediaFormatList GetMediaFormats() const = 0;
00521 
00530     virtual void AdjustMediaFormats(
00531       const OpalConnection & connection,  
00532       OpalMediaFormatList & mediaFormats  
00533     ) const;
00534 
00546     virtual BOOL OnOpenMediaStream(
00547       OpalConnection & connection,  
00548       OpalMediaStream & stream      
00549     );
00550 
00555     virtual void OnClosedMediaStream(
00556       const OpalMediaStream & stream     
00557     );
00558 
00563     virtual void AddVideoMediaFormats(
00564       OpalMediaFormatList & mediaFormats, 
00565       const OpalConnection * connection = NULL  
00566     ) const;
00567 
00570     virtual BOOL CreateVideoInputDevice(
00571       const OpalConnection & connection,    
00572       const OpalMediaFormat & mediaFormat,  
00573       PVideoInputDevice * & device,         
00574       BOOL & autoDelete                     
00575     );
00576 
00580     virtual BOOL CreateVideoOutputDevice(
00581       const OpalConnection & connection,    
00582       const OpalMediaFormat & mediaFormat,  
00583       BOOL preview,                         
00584       PVideoOutputDevice * & device,        
00585       BOOL & autoDelete                     
00586     );
00588 
00595     virtual void OnUserInputString(
00596       OpalConnection & connection,  
00597       const PString & value   
00598     );
00599 
00606     virtual void OnUserInputTone(
00607       OpalConnection & connection,  
00608       char tone,                    
00609       int duration                  
00610     );
00612 
00625     virtual OpalT120Protocol * CreateT120ProtocolHandler(
00626       const OpalConnection & connection  
00627     ) const;
00628 
00639     virtual OpalT38Protocol * CreateT38ProtocolHandler(
00640       const OpalConnection & connection  
00641     ) const;
00642 
00644 
00649     OpalManager & GetManager() const { return manager; }
00650 
00653     const PString & GetPrefixName() const { return prefixName; }
00654 
00657     BOOL HasAttribute(Attributes opt) const { return (attributeBits&opt) != 0; }
00658 
00661     WORD GetDefaultSignalPort() const { return defaultSignalPort; }
00662 
00665     const PString & GetDefaultLocalPartyName() const { return defaultLocalPartyName; }
00666 
00669     void SetDefaultLocalPartyName(const PString & name) { defaultLocalPartyName = name; }
00670 
00673     const PString & GetDefaultDisplayName() const { return defaultDisplayName; }
00674 
00677     void SetDefaultDisplayName(const PString & name) { defaultDisplayName = name; }
00678 
00681     unsigned GetInitialBandwidth() const { return initialBandwidth; }
00682 
00685     void SetInitialBandwidth(unsigned bandwidth) { initialBandwidth = bandwidth; }
00686 
00689     const OpalListenerList & GetListeners() const { return listeners; }
00691 
00692 
00693   protected:
00694     OpalManager   & manager;
00695     PCaselessString prefixName;
00696     unsigned        attributeBits;
00697     WORD            defaultSignalPort;
00698     PString         defaultLocalPartyName;
00699     PString         defaultDisplayName;
00700 
00701     unsigned initialBandwidth;  // in 100s of bits/sev
00702 
00703     OpalListenerList   listeners;
00704     PSyncPoint         allConnectionsCleared;
00705 
00706     class ConnectionDict : public PSafeDictionary<PString, OpalConnection>
00707     {
00708         virtual void DeleteObject(PObject * object) const;
00709     } connectionsActive;
00710 
00711     PMutex inUseFlag;
00712 
00713   friend void OpalManager::GarbageCollection();
00714   friend void OpalConnection::Release(CallEndReason reason);
00715 };
00716 
00717 
00718 #endif // __OPAL_ENDPOINT_H
00719 
00720 
00721 // End of File ///////////////////////////////////////////////////////////////

Generated on Mon Sep 25 16:19:33 2006 for OPAL by  doxygen 1.4.7