OPAL  Version 3.10.4
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  * $Revision: 26937 $
00028  * $Author: rjongbloed $
00029  * $Date: 2012-02-06 19:54:19 -0600 (Mon, 06 Feb 2012) $
00030  */
00031 
00032 #ifndef OPAL_OPAL_ENDPOINT_H
00033 #define OPAL_OPAL_ENDPOINT_H
00034 
00035 #ifdef P_USE_PRAGMA
00036 #pragma interface
00037 #endif
00038 
00039 #include <opal/buildopts.h>
00040 
00041 #include <opal/manager.h>
00042 #include <opal/mediafmt.h>
00043 #include <opal/transports.h>
00044 
00045 class OpalCall;
00046 class OpalMediaStream;
00047 
00067 class OpalEndPoint : public PObject
00068 {
00069     PCLASSINFO(OpalEndPoint, PObject);
00070   public:
00071     enum Attributes {
00072       CanTerminateCall = 1,
00073       SupportsE164 = 2
00074     };
00075 
00080     OpalEndPoint(
00081       OpalManager & manager,          
00082       const PCaselessString & prefix, 
00083       unsigned attributes             
00084     );
00085 
00088     ~OpalEndPoint();
00089 
00094     virtual void ShutDown();
00096 
00103     void PrintOn(
00104       ostream & strm    
00105     ) const;
00107 
00120     PBoolean StartListeners(
00121       const PStringArray & interfaces 
00122     );
00123 
00131     PBoolean StartListener(
00132       const OpalTransportAddress & iface 
00133     );
00134 
00140     PBoolean StartListener(
00141       OpalListener * listener 
00142     );
00143 
00148     virtual PStringArray GetDefaultListeners() const;
00149 
00153     virtual PString GetDefaultTransport() const;
00154 
00157     OpalListener * FindListener(
00158         const OpalTransportAddress & iface 
00159     );
00160 
00163     bool FindListenerForProtocol(
00164       const char * proto,         
00165       OpalTransportAddress & addr 
00166     );
00167 
00171     PBoolean StopListener(
00172         const OpalTransportAddress & iface 
00173     );
00174 
00178     PBoolean RemoveListener(
00179       OpalListener * listener 
00180     );
00181 
00184     OpalTransportAddressArray GetInterfaceAddresses(
00185       PBoolean excludeLocalHost = true,       
00186       const OpalTransport * associatedTransport = NULL
00188     );
00189 
00194     PDECLARE_NOTIFIER(PThread, OpalEndPoint, ListenerCallback);
00195 
00204     virtual PBoolean NewIncomingConnection(
00205       OpalTransport * transport  
00206     );
00207 
00213     virtual void OnNewConnection(
00214       OpalCall & call,              
00215       OpalConnection & connection   
00216     );
00218 
00250     virtual PSafePtr<OpalConnection> MakeConnection(
00251       OpalCall & call,          
00252       const PString & party,    
00253       void * userData = NULL,          
00254       unsigned int options = 0,     
00255       OpalConnection::StringOptions * stringOptions = NULL 
00256     ) = 0;
00257 
00261     virtual PBoolean OnSetUpConnection(OpalConnection &connection);
00262     
00284     virtual PBoolean OnIncomingConnection(
00285       OpalConnection & connection,  
00286       unsigned options,             
00287       OpalConnection::StringOptions * stringOptions  
00288     );
00289 
00304     virtual void OnProceeding(
00305       OpalConnection & connection   
00306     );
00307 
00323     virtual void OnAlerting(
00324       OpalConnection & connection   
00325     );
00326 
00343     virtual OpalConnection::AnswerCallResponse OnAnswerCall(
00344       OpalConnection & connection,    
00345        const PString & caller         
00346     );
00347 
00358     virtual void OnConnected(
00359       OpalConnection & connection   
00360     );
00361 
00373     virtual void OnEstablished(
00374       OpalConnection & connection   
00375     );
00376 
00395     virtual void OnReleased(
00396       OpalConnection & connection   
00397     );
00398 
00405     virtual void OnHold(
00406       OpalConnection & connection,   
00407       bool fromRemote,               
00408       bool onHold                    
00409     );
00410     virtual void OnHold(OpalConnection & connection); // For backward compatibility
00411 
00416     virtual PBoolean OnForwarded(
00417       OpalConnection & connection,  
00418       const PString & remoteParty         
00419     );
00420 
00468     virtual bool OnTransferNotify(
00469       OpalConnection & connection,  
00470       const PStringToString & info  
00471     );
00472 
00480     virtual PBoolean ClearCall(
00481       const PString & token,    
00482       OpalConnection::CallEndReason reason = OpalConnection::EndedByLocalUser, 
00483       PSyncPoint * sync = NULL  
00484     );
00485 
00490     virtual PBoolean ClearCallSynchronous(
00491       const PString & token,    
00492       OpalConnection::CallEndReason reason = OpalConnection::EndedByLocalUser, 
00493       PSyncPoint * sync = NULL  
00494     );
00495 
00502     virtual void ClearAllCalls(
00503       OpalConnection::CallEndReason reason = OpalConnection::EndedByLocalUser, 
00504       PBoolean wait = true   
00505     );
00506 
00511     PSafePtr<OpalConnection> GetConnectionWithLock(
00512       const PString & token,     
00513       PSafetyMode mode = PSafeReadWrite 
00514     ) { return connectionsActive.FindWithLock(token, mode); }
00515 
00522     template <class ConnClass>
00523     PSafePtr<ConnClass> GetConnectionWithLockAs(
00524       const PString & token,     
00525       PSafetyMode mode = PSafeReadWrite 
00526     )
00527     {
00528       PSafePtr<ConnClass> connection = PSafePtrCast<OpalConnection, ConnClass>(GetConnectionWithLock(token, mode));
00529       if (connection == NULL) {
00530         PSafePtr<OpalCall> call = manager.FindCallWithLock(token, PSafeReadOnly);
00531         if (call != NULL) {
00532           connection = PSafePtrCast<OpalConnection, ConnClass>(call->GetConnection(0, mode));
00533           if (connection == NULL)
00534             connection = PSafePtrCast<OpalConnection, ConnClass>(call->GetConnection(1, mode));
00535         }
00536       }
00537       return connection;
00538     }
00539 
00542     PStringList GetAllConnections();
00543     
00546     PINDEX GetConnectionCount() const { return connectionsActive.GetSize(); }
00547 
00550     virtual PBoolean HasConnection(
00551       const PString & token   
00552     );
00553 
00556     virtual void DestroyConnection(
00557       OpalConnection * connection  
00558     );
00560 
00572     virtual OpalMediaFormatList GetMediaFormats() const = 0;
00573 
00582     virtual void AdjustMediaFormats(
00583       bool local,                         
00584       const OpalConnection & connection,  
00585       OpalMediaFormatList & mediaFormats  
00586     ) const;
00587 
00599     virtual PBoolean OnOpenMediaStream(
00600       OpalConnection & connection,  
00601       OpalMediaStream & stream      
00602     );
00603 
00608     virtual void OnClosedMediaStream(
00609       const OpalMediaStream & stream     
00610     );
00611 
00612 #if OPAL_VIDEO
00613 
00615     virtual PBoolean CreateVideoInputDevice(
00616       const OpalConnection & connection,    
00617       const OpalMediaFormat & mediaFormat,  
00618       PVideoInputDevice * & device,         
00619       PBoolean & autoDelete                     
00620     );
00621 
00625     virtual PBoolean CreateVideoOutputDevice(
00626       const OpalConnection & connection,    
00627       const OpalMediaFormat & mediaFormat,  
00628       PBoolean preview,                         
00629       PVideoOutputDevice * & device,        
00630       PBoolean & autoDelete                     
00631     );
00632 #endif
00633 
00634 
00641     virtual void OnUserInputString(
00642       OpalConnection & connection,  
00643       const PString & value   
00644     );
00645 
00652     virtual void OnUserInputTone(
00653       OpalConnection & connection,  
00654       char tone,                    
00655       int duration                  
00656     );
00657 
00660     virtual PString ReadUserInput(
00661       OpalConnection & connection,        
00662       const char * terminators = "#\r\n", 
00663       unsigned lastDigitTimeout = 4,      
00664       unsigned firstDigitTimeout = 30     
00665     );
00667 
00672     virtual PBoolean Message(
00673       const PString & to, 
00674       const PString & body
00675     );
00676     virtual PBoolean Message(
00677       const PURL & to, 
00678       const PString & type,
00679       const PString & body,
00680       PURL & from, 
00681       PString & conversationId
00682     );
00683     virtual PBoolean Message(
00684       OpalIM & Message
00685     );
00686 
00689     virtual void OnMessageReceived(
00690       const OpalIM & message
00691     );
00693 
00706     virtual void OnMWIReceived (
00707       const PString & party,                
00708       OpalManager::MessageWaitingType type, 
00709       const PString & extraInfo             
00710     );
00711 
00716     virtual PBoolean GarbageCollection();
00718 
00723     OpalManager & GetManager() const { return manager; }
00724 
00727     const PString & GetPrefixName() const { return prefixName; }
00728 
00731     PBoolean HasAttribute(Attributes opt) const { return (attributeBits&opt) != 0; }
00732 
00735     WORD GetDefaultSignalPort() const { return defaultSignalPort; }
00736 
00739     const OpalProductInfo & GetProductInfo() const { return productInfo; }
00740 
00743     void SetProductInfo(
00744       const OpalProductInfo & info
00745     ) { productInfo = info; }
00746 
00749     const PString & GetDefaultLocalPartyName() const { return defaultLocalPartyName; }
00750 
00753     virtual void SetDefaultLocalPartyName(
00754       const PString & name  
00755     ) { defaultLocalPartyName = name; }
00756 
00759     const PString & GetDefaultDisplayName() const { return defaultDisplayName; }
00760 
00763     void SetDefaultDisplayName(const PString & name) { defaultDisplayName = name; }
00764 
00767     unsigned GetInitialBandwidth() const { return initialBandwidth; }
00768 
00771     void SetInitialBandwidth(unsigned bandwidth) { initialBandwidth = bandwidth; }
00772 
00775     const OpalListenerList & GetListeners() const { return listeners; }
00776 
00779     const OpalConnection::StringOptions & GetDefaultStringOptions() const { return m_defaultStringOptions; }
00780 
00783     void SetDefaultStringOptions(const OpalConnection::StringOptions & opts) { m_defaultStringOptions = opts; }
00784 
00787     void SetDefaultStringOption(const PCaselessString & key, const PString & data) { m_defaultStringOptions.SetAt(key, data); }
00788 
00791     OpalConnection::SendUserInputModes GetSendUserInputMode() const { return defaultSendUserInputMode; }
00792 
00795     void SetSendUserInputMode(OpalConnection::SendUserInputModes mode) { defaultSendUserInputMode = mode; }
00797 
00798 #if OPAL_PTLIB_SSL
00799 
00801     PString GetSSLCertificate() const;
00802 #endif
00803 
00804   protected:
00805     OpalManager   & manager;
00806     PCaselessString prefixName;
00807     unsigned        attributeBits;
00808     WORD            defaultSignalPort;
00809     PINDEX          m_maxSizeUDP;
00810     OpalProductInfo productInfo;
00811     PString         defaultLocalPartyName;
00812     PString         defaultDisplayName;
00813 
00814     unsigned initialBandwidth;  // in 100s of bits/sev
00815     OpalConnection::StringOptions      m_defaultStringOptions;
00816     OpalConnection::SendUserInputModes defaultSendUserInputMode;
00817 
00818     OpalListenerList   listeners;
00819 
00820     class ConnectionDict : public PSafeDictionary<PString, OpalConnection>
00821     {
00822         virtual void DeleteObject(PObject * object) const;
00823     } connectionsActive;
00824     OpalConnection * AddConnection(OpalConnection * connection);
00825 
00826     PMutex inUseFlag;
00827 
00828     friend void OpalManager::GarbageCollection();
00829     friend void OpalConnection::Release(CallEndReason reason);
00830 
00831   private:
00832     P_REMOVE_VIRTUAL(PBoolean, OnIncomingConnection(OpalConnection &, unsigned), false);
00833     P_REMOVE_VIRTUAL(PBoolean, OnIncomingConnection(OpalConnection &), false);
00834     P_REMOVE_VIRTUAL_VOID(AdjustMediaFormats(const OpalConnection &, OpalMediaFormatList &) const);
00835     P_REMOVE_VIRTUAL_VOID(OnMessageReceived(const PURL&,const PString&,const PURL&,const PString&,const PString&,const PString&));
00836 };
00837 
00838 
00840 bool OpalIsE164(
00841   const PString & number,   
00842   bool strict = false     
00843 );
00844 
00845 
00846 #endif // OPAL_OPAL_ENDPOINT_H
00847 
00848 
00849 // End of File ///////////////////////////////////////////////////////////////