endpoint.h

Go to the documentation of this file.

/*
 * endpoint.h
 *
 * Telephony endpoint abstraction
 *
 * Open Phone Abstraction Library (OPAL)
 * Formally known as the Open H323 project.
 *
 * Copyright (c) 2001 Equivalence Pty. Ltd.
 *
 * The contents of this file are subject to the Mozilla Public License
 * Version 1.0 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS"
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 * the License for the specific language governing rights and limitations
 * under the License.
 *
 * The Original Code is Open Phone Abstraction Library.
 *
 * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
 *
 * Contributor(s): ______________________________________.
 */

#ifndef OPAL_OPAL_ENDPOINT_H
#define OPAL_OPAL_ENDPOINT_H

#ifdef P_USE_PRAGMA
#pragma interface
#endif

#include <opal_config.h>

#include <opal/manager.h>
#include <opal/mediafmt.h>
#include <opal/transports.h>


class OpalCall;
class OpalMediaStream;


class OpalEndPoint : public PObject
{
    PCLASSINFO(OpalEndPoint, PObject);
  public:
    P_DECLARE_BITWISE_ENUM(Attributes, 2, (
      NoAttributes,
      IsNetworkEndPoint,
      SupportsE164
    ));

    OpalEndPoint(
      OpalManager & manager,          
      const PCaselessString & prefix, 
      Attributes attributes           
    );

    ~OpalEndPoint();

    virtual void ShutDown();

    void PrintOn(
      ostream & strm    
    ) const;

    bool StartListeners(
      const PStringArray & interfaces, 
      bool add = true                  
    );

    virtual bool StartListener(
      const PString & address 
    );

    virtual bool StartListener(
      OpalListener * listener 
    );

    virtual PStringArray GetDefaultListeners() const;

    virtual PString GetDefaultTransport() const;

    virtual WORD GetDefaultSignalPort() const;

#if OPAL_PTLIB_SSL

    virtual bool ApplySSLCredentials(
      PSSLContext & context,    
      bool create               
    ) const;
#endif

    OpalListener * FindListener(
        const OpalTransportAddress & iface 
    );

    bool FindListenerForProtocol(
      const char * proto,         
      OpalTransportAddress & addr 
    );

    PBoolean StopListener(
        const OpalTransportAddress & iface 
    );

    PBoolean RemoveListener(
      OpalListener * listener 
    );

    OpalTransportAddressArray GetInterfaceAddresses(
      const OpalTransport * associatedTransport = NULL
    ) const;

#if DOXYGEN
    virtual void NewIncomingConnection(
      OpalListener & listener,            
      const OpalTransportPtr & transport  
    );
#endif
    PDECLARE_AcceptHandlerNotifier(OpalEndPoint, NewIncomingConnection);

    virtual void OnNewConnection(
      OpalCall & call,              
      OpalConnection & connection   
    );

    virtual PSafePtr<OpalConnection> MakeConnection(
      OpalCall & call,          
      const PString & party,    
      void * userData = NULL,          
      unsigned int options = 0,     
      OpalConnection::StringOptions * stringOptions = NULL 
    ) = 0;

    virtual PBoolean OnSetUpConnection(OpalConnection &connection);
    
    virtual PBoolean OnIncomingConnection(
      OpalConnection & connection,  
      unsigned options,             
      OpalConnection::StringOptions * stringOptions  
    );

    virtual void OnProceeding(
      OpalConnection & connection   
    );

    virtual void OnAlerting(
      OpalConnection & connection,   
      bool withMedia                 
    );
    virtual void OnAlerting(OpalConnection & connection); // For backward compatibility

    virtual OpalConnection::AnswerCallResponse OnAnswerCall(
      OpalConnection & connection,    
       const PString & caller         
    );

    virtual void OnConnected(
      OpalConnection & connection   
    );

    virtual void OnEstablished(
      OpalConnection & connection   
    );

    virtual void OnReleased(
      OpalConnection & connection   
    );

    virtual void OnHold(
      OpalConnection & connection,   
      bool fromRemote,               
      bool onHold                    
    );
    virtual void OnHold(OpalConnection & connection); // For backward compatibility

    virtual PBoolean OnForwarded(
      OpalConnection & connection,  
      const PString & remoteParty         
    );

    virtual bool OnTransferNotify(
      OpalConnection & connection,  
      const PStringToString & info, 
      const OpalConnection * transferringConnection
    );

    virtual PBoolean ClearCall(
      const PString & token,    
      OpalConnection::CallEndReason reason = OpalConnection::EndedByLocalUser, 
      PSyncPoint * sync = NULL  
    );

    virtual PBoolean ClearCallSynchronous(
      const PString & token,    
      OpalConnection::CallEndReason reason = OpalConnection::EndedByLocalUser, 
      PSyncPoint * sync = NULL  
    );

    virtual void ClearAllCalls(
      OpalConnection::CallEndReason reason = OpalConnection::EndedByLocalUser, 
      PBoolean wait = true   
    );

    PSafePtr<OpalConnection> GetConnectionWithLock(
      const PString & token,     
      PSafetyMode mode = PSafeReadWrite 
    ) const;

    template <class ConnClass>
    PSafePtr<ConnClass> GetConnectionWithLockAs(
      const PString & token,     
      PSafetyMode mode = PSafeReadWrite 
    ) const
    {
      PSafePtr<ConnClass> connection = PSafePtrCast<OpalConnection, ConnClass>(GetConnectionWithLock(token, mode));
      if (connection == NULL) {
        PSafePtr<OpalCall> call = m_manager.FindCallWithLock(token, PSafeReadOnly);
        if (call != NULL) {
          connection = PSafePtrCast<OpalConnection, ConnClass>(call->GetConnection(0, mode));
          if (connection == NULL)
            connection = PSafePtrCast<OpalConnection, ConnClass>(call->GetConnection(1, mode));
        }
      }
      return connection;
    }

    PStringList GetAllConnections();
    
    PINDEX GetConnectionCount() const { return m_connectionsActive.GetSize(); }

    virtual PBoolean HasConnection(
      const PString & token   
    );

    virtual void DestroyConnection(
      OpalConnection * connection  
    );

    virtual OpalMediaFormatList GetMediaFormats() const = 0;

    virtual void AdjustMediaFormats(
      bool local,                         
      const OpalConnection & connection,  
      OpalMediaFormatList & mediaFormats  
    ) const;

    virtual bool GetMediaTransportAddresses(
      const OpalConnection & provider,       
      const OpalConnection & consumer,       
      unsigned sessionId,                    
      const OpalMediaType & mediaType,       
      OpalTransportAddressArray & transports 
    ) const;

    virtual PBoolean OnOpenMediaStream(
      OpalConnection & connection,  
      OpalMediaStream & stream      
    );

    virtual void OnClosedMediaStream(
      const OpalMediaStream & stream     
    );

    virtual void OnFailedMediaStream(
      OpalConnection & connection,  
      bool fromRemote,              
      const PString & reason        
    );

    void SetMediaCryptoSuites(
      const PStringArray & security   
    );

    PStringArray GetMediaCryptoSuites() const
      { return m_mediaCryptoSuites.IsEmpty() ? GetAllMediaCryptoSuites() : m_mediaCryptoSuites; }

    virtual PStringArray GetAllMediaCryptoSuites() const;

    virtual void OnUserInputString(
      OpalConnection & connection,  
      const PString & value   
    );

    virtual void OnUserInputTone(
      OpalConnection & connection,  
      char tone,                    
      int duration                  
    );

    virtual PString ReadUserInput(
      OpalConnection & connection,        
      const char * terminators = "#\r\n", 
      unsigned lastDigitTimeout = 4,      
      unsigned firstDigitTimeout = 30     
    );


#if OPAL_HAS_IM

    virtual PBoolean Message(
      const PString & to, 
      const PString & body
    );
    virtual PBoolean Message(
      const PURL & to, 
      const PString & type,
      const PString & body,
      PURL & from, 
      PString & conversationId
    );
    virtual PBoolean Message(
      OpalIM & Message
    );

    virtual void OnMessageReceived(
      const OpalIM & message
    );
#endif // OPAL_HAS_IM


    virtual void OnMWIReceived (
      const PString & party,                
      OpalManager::MessageWaitingType type, 
      const PString & extraInfo             
    );

    virtual bool GetConferenceStates(
      OpalConferenceStates & states,           
      const PString & name = PString::Empty() 
    ) const;

    virtual void OnConferenceStatusChanged(
      OpalEndPoint & endpoint,  
      const PString & uri,      
      OpalConferenceState::ChangeType change 
    );

    virtual PStringList GetNetworkURIs(
      const PString & name
    ) const;

    virtual PBoolean GarbageCollection();

    OpalManager & GetManager() const { return m_manager; }

    const PString & GetPrefixName() const { return m_prefixName; }

    bool HasAttribute(Attributes opt) const { return m_attributes & opt; }

    const OpalProductInfo & GetProductInfo() const { return m_productInfo; }

    void SetProductInfo(
      const OpalProductInfo & info
    ) { m_productInfo = info; }

    const PString & GetDefaultLocalPartyName() const { return m_defaultLocalPartyName; }

    virtual void SetDefaultLocalPartyName(
      const PString & name  
    ) { m_defaultLocalPartyName = name; }

    const PString & GetDefaultDisplayName() const { return m_defaultDisplayName; }

    void SetDefaultDisplayName(const PString & name) { m_defaultDisplayName = name; }

    OpalBandwidth GetInitialBandwidth(
      OpalBandwidth::Direction dir   
    ) const;

    bool SetInitialBandwidth(
      OpalBandwidth::Direction dir,   
      OpalBandwidth bandwidth         
    );

    const OpalListenerList & GetListeners() const { return m_listeners; }

    const OpalConnection::StringOptions & GetDefaultStringOptions() const { return m_defaultStringOptions; }

    void SetDefaultStringOptions(
      const OpalConnection::StringOptions & opts, 
      bool overwrite = false
    );

    void SetDefaultStringOption(const PCaselessString & key, const PString & data) { m_defaultStringOptions.SetAt(key, data); }

    void RemoveDefaultStringOption(const PCaselessString & key) { m_defaultStringOptions.RemoveAt(key); }

    virtual PStringList GetAvailableStringOptions() const;

    OpalConnection::SendUserInputModes GetSendUserInputMode() const { return m_defaultSendUserInputMode; }

    void SetSendUserInputMode(OpalConnection::SendUserInputModes mode) { m_defaultSendUserInputMode = mode; }

    const PIPSocket::QoS & GetSignalQoS() const { return m_signalQoS; }

    void SetSignalQoS(const PIPSocket::QoS & qos) { m_signalQoS = qos; }

    const PIPSocket::QoS & GetMediaQoS(const OpalMediaType & type) const;

    void SetMediaQoS(const OpalMediaType & type, const PIPSocket::QoS & qos);

    PINDEX GetMaxSizeUDP() const { return m_maxSizeUDP; }

    void SetMaxSizeUDP(PINDEX size) { m_maxSizeUDP = size; }

  protected:
    OpalManager   & m_manager;
    PCaselessString m_prefixName;
    Attributes      m_attributes;
    PINDEX          m_maxSizeUDP;
    OpalProductInfo m_productInfo;
    PString         m_defaultLocalPartyName;
    PString         m_defaultDisplayName;
    PStringArray    m_mediaCryptoSuites;
    PIPSocket::QoS  m_signalQoS;
    OpalManager::MediaQoSMap m_mediaQoS;

    OpalBandwidth m_initialRxBandwidth;
    OpalBandwidth m_initialTxBandwidth;
    OpalConnection::StringOptions      m_defaultStringOptions;
    OpalConnection::SendUserInputModes m_defaultSendUserInputMode;

    OpalListenerList   m_listeners;

    class ConnectionDict : public PSafeDictionary<PString, OpalConnection>
    {
        virtual void DeleteObject(PObject * object) const;
    } m_connectionsActive;
    OpalConnection * AddConnection(OpalConnection * connection);

    friend void OpalManager::GarbageCollection();
    friend void OpalConnection::SetToken(const PString & newToken);

  private:
    P_REMOVE_VIRTUAL(PBoolean, OnIncomingConnection(OpalConnection &, unsigned), false);
    P_REMOVE_VIRTUAL(PBoolean, OnIncomingConnection(OpalConnection &), false);
    P_REMOVE_VIRTUAL_VOID(AdjustMediaFormats(const OpalConnection &, OpalMediaFormatList &) const);
    P_REMOVE_VIRTUAL_VOID(OnMessageReceived(const PURL&,const PString&,const PURL&,const PString&,const PString&,const PString&));
    P_REMOVE_VIRTUAL(OpalMediaSession *, CreateMediaSession(OpalConnection &, unsigned, const OpalMediaType &), NULL);
    P_REMOVE_VIRTUAL(PBoolean, NewIncomingConnection(OpalTransport *), false);
    P_REMOVE_VIRTUAL(bool, OnTransferNotify(OpalConnection &, const PStringToString &), false);
#if OPAL_PTLIB_NAT
    P_REMOVE_VIRTUAL(PNatMethod *, GetNatMethod(const PIPSocket::Address &) const, NULL);
#endif
};


bool OpalIsE164(
  const PString & number,   
  bool strict = false     
);


#endif // OPAL_OPAL_ENDPOINT_H


// End of File ///////////////////////////////////////////////////////////////