# 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: 30003 $
    00028  * $Author: rjongbloed $
    00029  * $Date: 2013-06-19 22:38:44 -0500 (Wed, 19 Jun 2013) $
    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
    00046 class OpalCall;
    00047 class OpalMediaStream;
    00048
    00049
    00069 class OpalEndPoint : public PObject
    00070 {
    00071     PCLASSINFO(OpalEndPoint, PObject);
    00072   public:
    00073     enum Attributes {
    00074       CanTerminateCall = 1,
    00075       SupportsE164 = 2
    00076     };
    00077
    00082     OpalEndPoint(
    00083       OpalManager & manager,
    00084       const PCaselessString & prefix,
    00085       unsigned attributes
    00086     );
    00087
    00090     ~OpalEndPoint();
    00091
    00096     virtual void ShutDown();
    00098
    00105     void PrintOn(
    00106       ostream & strm
    00107     ) const;
    00109
    00127     bool StartListeners(
    00128       const PStringArray & interfaces,
    00129       bool add = true
    00130     );
    00131
    00139     PBoolean StartListener(
    00140       const OpalTransportAddress & iface
    00141     );
    00142
    00148     PBoolean StartListener(
    00149       OpalListener * listener
    00150     );
    00151
    00156     virtual PStringArray GetDefaultListeners() const;
    00157
    00164     virtual PString GetDefaultTransport() const;
    00165
    00168     virtual WORD GetDefaultSignalPort() const;
    00169
    00170 #if OPAL_PTLIB_SSL
    00171
    00173     virtual bool ApplySSLCredentials(
    00174       PSSLContext & context,
    00175       bool create
    00176     ) const;
    00177 #endif
    00178
    00181     OpalListener * FindListener(
    00182         const OpalTransportAddress & iface
    00183     );
    00184
    00187     bool FindListenerForProtocol(
    00188       const char * proto,
    00189       OpalTransportAddress & addr
    00190     );
    00191
    00195     PBoolean StopListener(
    00196         const OpalTransportAddress & iface
    00197     );
    00198
    00202     PBoolean RemoveListener(
    00203       OpalListener * listener
    00204     );
    00205
    00208     OpalTransportAddressArray GetInterfaceAddresses(
    00209       PBoolean excludeLocalHost = true,
    00210       const OpalTransport * associatedTransport = NULL
    00212     ) const;
    00213
    00218 #if DOXYGEN
    00219     virtual void NewIncomingConnection(
    00220       OpalListener & listener,
    00221       const OpalTransportPtr & transport
    00222     );
    00223 #endif
    00224     PDECLARE_AcceptHandlerNotifier(OpalEndPoint, NewIncomingConnection);
    00225
    00231     virtual void OnNewConnection(
    00232       OpalCall & call,
    00233       OpalConnection & connection
    00234     );
    00236
    00268     virtual PSafePtr<OpalConnection> MakeConnection(
    00269       OpalCall & call,
    00270       const PString & party,
    00271       void * userData = NULL,
    00272       unsigned int options = 0,
    00273       OpalConnection::StringOptions * stringOptions = NULL
    00274     ) = 0;
    00275
    00279     virtual PBoolean OnSetUpConnection(OpalConnection &connection);
    00280
    00302     virtual PBoolean OnIncomingConnection(
    00303       OpalConnection & connection,
    00304       unsigned options,
    00305       OpalConnection::StringOptions * stringOptions
    00306     );
    00307
    00322     virtual void OnProceeding(
    00323       OpalConnection & connection
    00324     );
    00325
    00341     virtual void OnAlerting(
    00342       OpalConnection & connection
    00343     );
    00344
    00361     virtual OpalConnection::AnswerCallResponse OnAnswerCall(
    00362       OpalConnection & connection,
    00363        const PString & caller
    00364     );
    00365
    00376     virtual void OnConnected(
    00377       OpalConnection & connection
    00378     );
    00379
    00391     virtual void OnEstablished(
    00392       OpalConnection & connection
    00393     );
    00394
    00413     virtual void OnReleased(
    00414       OpalConnection & connection
    00415     );
    00416
    00423     virtual void OnHold(
    00424       OpalConnection & connection,
    00425       bool fromRemote,
    00426       bool onHold
    00427     );
    00428     virtual void OnHold(OpalConnection & connection); // For backward compatibility
    00429
    00434     virtual PBoolean OnForwarded(
    00435       OpalConnection & connection,
    00436       const PString & remoteParty
    00437     );
    00438
    00486     virtual bool OnTransferNotify(
    00487       OpalConnection & connection,
    00488       const PStringToString & info
    00489     );
    00490
    00500     virtual PBoolean ClearCall(
    00501       const PString & token,
    00502       OpalConnection::CallEndReason reason = OpalConnection::EndedByLocalUser,
    00503       PSyncPoint * sync = NULL
    00504     );
    00505
    00510     virtual PBoolean ClearCallSynchronous(
    00511       const PString & token,
    00512       OpalConnection::CallEndReason reason = OpalConnection::EndedByLocalUser,
    00513       PSyncPoint * sync = NULL
    00514     );
    00515
    00522     virtual void ClearAllCalls(
    00523       OpalConnection::CallEndReason reason = OpalConnection::EndedByLocalUser,
    00524       PBoolean wait = true
    00525     );
    00526
    00539     PSafePtr<OpalConnection> GetConnectionWithLock(
    00540       const PString & token,
    00541       PSafetyMode mode = PSafeReadWrite
    00542     ) const;
    00543
    00550     template <class ConnClass>
    00551     PSafePtr<ConnClass> GetConnectionWithLockAs(
    00552       const PString & token,
    00553       PSafetyMode mode = PSafeReadWrite
    00554     ) const
    00555     {
    00556       PSafePtr<ConnClass> connection = PSafePtrCast<OpalConnection, ConnClass>(GetConnectionWithLock(token, mode));
    00557       if (connection == NULL) {
    00558         PSafePtr<OpalCall> call = manager.FindCallWithLock(token, PSafeReadOnly);
    00559         if (call != NULL) {
    00560           connection = PSafePtrCast<OpalConnection, ConnClass>(call->GetConnection(0, mode));
    00561           if (connection == NULL)
    00562             connection = PSafePtrCast<OpalConnection, ConnClass>(call->GetConnection(1, mode));
    00563         }
    00564       }
    00565       return connection;
    00566     }
    00567
    00570     PStringList GetAllConnections();
    00571
    00574     PINDEX GetConnectionCount() const { return connectionsActive.GetSize(); }
    00575
    00578     virtual PBoolean HasConnection(
    00579       const PString & token
    00580     );
    00581
    00584     virtual void DestroyConnection(
    00585       OpalConnection * connection
    00586     );
    00588
    00600     virtual OpalMediaFormatList GetMediaFormats() const = 0;
    00601
    00610     virtual void AdjustMediaFormats(
    00611       bool local,
    00612       const OpalConnection & connection,
    00613       OpalMediaFormatList & mediaFormats
    00614     ) const;
    00615
    00627     virtual PBoolean OnOpenMediaStream(
    00628       OpalConnection & connection,
    00629       OpalMediaStream & stream
    00630     );
    00631
    00636     virtual void OnClosedMediaStream(
    00637       const OpalMediaStream & stream
    00638     );
    00639
    00648     void SetMediaCryptoSuites(
    00649       const PStringArray & security
    00650     );
    00651
    00656     PStringArray GetMediaCryptoSuites() const
    00657       { return m_mediaCryptoSuites.IsEmpty() ? GetAllMediaCryptoSuites() : m_mediaCryptoSuites; }
    00658
    00662     virtual PStringArray GetAllMediaCryptoSuites() const;
    00663
    00664 #if P_NAT
    00665
    00667     PNatStrategy & GetNatMethods() const;
    00668
    00674     virtual PNatMethod * GetNatMethod(
    00675       const PIPSocket::Address & remoteAddress = PIPSocket::GetDefaultIpAny()
    00676     ) const;
    00677 #endif
    00678
    00679 #if OPAL_VIDEO
    00680
    00682     virtual PBoolean CreateVideoInputDevice(
    00683       const OpalConnection & connection,
    00684       const OpalMediaFormat & mediaFormat,
    00685       PVideoInputDevice * & device,
    00686       PBoolean & autoDelete
    00687     );
    00688
    00692     virtual PBoolean CreateVideoOutputDevice(
    00693       const OpalConnection & connection,
    00694       const OpalMediaFormat & mediaFormat,
    00695       PBoolean preview,
    00696       PVideoOutputDevice * & device,
    00697       PBoolean & autoDelete
    00698     );
    00699 #endif
    00700
    00701
    00708     virtual void OnUserInputString(
    00709       OpalConnection & connection,
    00710       const PString & value
    00711     );
    00712
    00719     virtual void OnUserInputTone(
    00720       OpalConnection & connection,
    00721       char tone,
    00722       int duration
    00723     );
    00724
    00727     virtual PString ReadUserInput(
    00728       OpalConnection & connection,
    00729       const char * terminators = "#\r\n",
    00730       unsigned lastDigitTimeout = 4,
    00731       unsigned firstDigitTimeout = 30
    00732     );
    00734
    00735
    00736 #if OPAL_HAS_IM
    00737
    00741     virtual PBoolean Message(
    00742       const PString & to,
    00743       const PString & body
    00744     );
    00745     virtual PBoolean Message(
    00746       const PURL & to,
    00747       const PString & type,
    00748       const PString & body,
    00749       PURL & from,
    00750       PString & conversationId
    00751     );
    00752     virtual PBoolean Message(
    00753       OpalIM & Message
    00754     );
    00755
    00758     virtual void OnMessageReceived(
    00759       const OpalIM & message
    00760     );
    00762 #endif // OPAL_HAS_IM
    00763
    00764
    00777     virtual void OnMWIReceived (
    00778       const PString & party,
    00779       OpalManager::MessageWaitingType type,
    00780       const PString & extraInfo
    00781     );
    00782
    00798     virtual bool GetConferenceStates(
    00799       OpalConferenceStates & states,
    00800       const PString & name = PString::Empty()
    00801     ) const;
    00802
    00812     virtual void OnConferenceStatusChanged(
    00813       OpalEndPoint & endpoint,
    00814       const PString & uri,
    00815       OpalConferenceState::ChangeType change
    00816     );
    00817
    00822     virtual PStringList GetNetworkURIs(
    00823       const PString & name
    00824     ) const;
    00825
    00830     virtual PBoolean GarbageCollection();
    00832
    00837     OpalManager & GetManager() const { return manager; }
    00838
    00841     const PString & GetPrefixName() const { return prefixName; }
    00842
    00845     PBoolean HasAttribute(Attributes opt) const { return (attributeBits&opt) != 0; }
    00846
    00849     const OpalProductInfo & GetProductInfo() const { return productInfo; }
    00850
    00853     void SetProductInfo(
    00854       const OpalProductInfo & info
    00855     ) { productInfo = info; }
    00856
    00859     const PString & GetDefaultLocalPartyName() const { return defaultLocalPartyName; }
    00860
    00863     virtual void SetDefaultLocalPartyName(
    00864       const PString & name
    00865     ) { defaultLocalPartyName = name; }
    00866
    00869     const PString & GetDefaultDisplayName() const { return defaultDisplayName; }
    00870
    00873     void SetDefaultDisplayName(const PString & name) { defaultDisplayName = name; }
    00874
    00877     OpalBandwidth GetInitialBandwidth(
    00878       OpalBandwidth::Direction dir
    00879     ) const;
    00880
    00883     void SetInitialBandwidth(
    00884       OpalBandwidth::Direction dir,
    00885       OpalBandwidth bandwidth
    00886     );
    00887
    00890     const OpalListenerList & GetListeners() const { return listeners; }
    00891
    00894     const OpalConnection::StringOptions & GetDefaultStringOptions() const { return m_defaultStringOptions; }
    00895
    00898     void SetDefaultStringOptions(const OpalConnection::StringOptions & opts) { m_defaultStringOptions = opts; }
    00899
    00902     void SetDefaultStringOption(const PCaselessString & key, const PString & data) { m_defaultStringOptions.SetAt(key, data); }
    00903
    00906     OpalConnection::SendUserInputModes GetSendUserInputMode() const { return defaultSendUserInputMode; }
    00907
    00910     void SetSendUserInputMode(OpalConnection::SendUserInputModes mode) { defaultSendUserInputMode = mode; }
    00912
    00913   protected:
    00914     OpalManager   & manager;
    00915     PCaselessString prefixName;
    00916     unsigned        attributeBits;
    00917     PINDEX          m_maxSizeUDP;
    00918     OpalProductInfo productInfo;
    00919     PString         defaultLocalPartyName;
    00920     PString         defaultDisplayName;
    00921     PStringArray    m_mediaCryptoSuites;
    00922
    00923     OpalBandwidth m_initialRxBandwidth;
    00924     OpalBandwidth m_initialTxBandwidth;
    00925     OpalConnection::StringOptions      m_defaultStringOptions;
    00926     OpalConnection::SendUserInputModes defaultSendUserInputMode;
    00927
    00928     OpalListenerList   listeners;
    00929
    00930     class ConnectionDict : public PSafeDictionary<PString, OpalConnection>
    00931     {
    00932         virtual void DeleteObject(PObject * object) const;
    00933     } connectionsActive;
    00934     OpalConnection * AddConnection(OpalConnection * connection);
    00935
    00936     friend void OpalManager::GarbageCollection();
    00937     friend void OpalConnection::Release(CallEndReason,bool);
    00938
    00939   private:
    00940     P_REMOVE_VIRTUAL(PBoolean, OnIncomingConnection(OpalConnection &, unsigned), false);
    00941     P_REMOVE_VIRTUAL(PBoolean, OnIncomingConnection(OpalConnection &), false);
    00942     P_REMOVE_VIRTUAL_VOID(AdjustMediaFormats(const OpalConnection &, OpalMediaFormatList &) const);
    00943     P_REMOVE_VIRTUAL_VOID(OnMessageReceived(const PURL&,const PString&,const PURL&,const PString&,const PString&,const PString&));
    00944     P_REMOVE_VIRTUAL(OpalMediaSession *, CreateMediaSession(OpalConnection &, unsigned, const OpalMediaType &), NULL);
    00945     P_REMOVE_VIRTUAL(PBoolean, NewIncomingConnection(OpalTransport *), false);
    00946 };
    00947
    00948
    00950 bool OpalIsE164(
    00951   const PString & number,
    00952   bool strict = false
    00953 );
    00954
    00955
    00956 #endif // OPAL_OPAL_ENDPOINT_H
    00957
    00958
    00959 // End of File ///////////////////////////////////////////////////////////////