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): ______________________________________.
 *
 * $Revision: 30003 $
 * $Author: rjongbloed $
 * $Date: 2013-06-20 13:38:44 +1000 (Thu, 20 Jun 2013) $
 */

#ifndef OPAL_OPAL_ENDPOINT_H
#define OPAL_OPAL_ENDPOINT_H

#ifdef P_USE_PRAGMA
#pragma interface
#endif

#include <opal/buildopts.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:
    enum Attributes {
      CanTerminateCall = 1,
      SupportsE164 = 2
    };

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

    ~OpalEndPoint();

    virtual void ShutDown();

    void PrintOn(
      ostream & strm    
    ) const;

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

    PBoolean StartListener(
      const OpalTransportAddress & iface 
    );

    PBoolean 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(
      PBoolean excludeLocalHost = true,       
      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   
    );

    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  
    );

    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 = 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 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 PBoolean OnOpenMediaStream(
      OpalConnection & connection,  
      OpalMediaStream & stream      
    );

    virtual void OnClosedMediaStream(
      const OpalMediaStream & stream     
    );

    void SetMediaCryptoSuites(
      const PStringArray & security   
    );

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

    virtual PStringArray GetAllMediaCryptoSuites() const;

#if P_NAT

    PNatStrategy & GetNatMethods() const;

    virtual PNatMethod * GetNatMethod(
      const PIPSocket::Address & remoteAddress = PIPSocket::GetDefaultIpAny()
    ) const;
#endif

#if OPAL_VIDEO

    virtual PBoolean CreateVideoInputDevice(
      const OpalConnection & connection,    
      const OpalMediaFormat & mediaFormat,  
      PVideoInputDevice * & device,         
      PBoolean & autoDelete                     
    );

    virtual PBoolean CreateVideoOutputDevice(
      const OpalConnection & connection,    
      const OpalMediaFormat & mediaFormat,  
      PBoolean preview,                         
      PVideoOutputDevice * & device,        
      PBoolean & autoDelete                     
    );
#endif


    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 manager; }

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

    PBoolean HasAttribute(Attributes opt) const { return (attributeBits&opt) != 0; }

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

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

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

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

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

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

    OpalBandwidth GetInitialBandwidth(
      OpalBandwidth::Direction dir   
    ) const;

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

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

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

    void SetDefaultStringOptions(const OpalConnection::StringOptions & opts) { m_defaultStringOptions = opts; }

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

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

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

  protected:
    OpalManager   & manager;
    PCaselessString prefixName;
    unsigned        attributeBits;
    PINDEX          m_maxSizeUDP;
    OpalProductInfo productInfo;
    PString         defaultLocalPartyName;
    PString         defaultDisplayName;
    PStringArray    m_mediaCryptoSuites;

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

    OpalListenerList   listeners;

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

    friend void OpalManager::GarbageCollection();
    friend void OpalConnection::Release(CallEndReason,bool);

  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);
};


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


#endif // OPAL_OPAL_ENDPOINT_H


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