transports.h

Go to the documentation of this file.

/*
 * transport.h
 *
 * Transport declarations
 *
 * Open Phone Abstraction Library (OPAL)
 * Formally known as the Open H323 project.
 *
 * Copyright (c) 2001 Equivalence Pty. Ltd.
 * Portions Copyright (C) 2006 by Post Increment
 *
 * 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): Post Increment
 *     Portions of this code were written with the assistance of funding from
 *     US Joint Forces Command Joint Concept Development & Experimentation (J9)
 *     http://www.jfcom.mil/about/abt_j9.htm
 *
 * $Revision: 30514 $
 * $Author: rjongbloed $
 * $Date: 2013-09-17 11:38:19 +1000 (Tue, 17 Sep 2013) $
 */

#ifndef OPAL_OPAL_TRANSPORT_H
#define OPAL_OPAL_TRANSPORT_H

#ifdef P_USE_PRAGMA
#pragma interface
#endif

#include <opal/buildopts.h>

#include <ptlib/sockets.h>
#include <ptclib/psockbun.h>


class OpalManager;
class OpalEndPoint;
class OpalListener;
class OpalTransport;
class OpalInternalTransport;

typedef PSafePtr<OpalTransport> OpalTransportPtr;



class OpalTransportAddress : public PCaselessString
{
  PCLASSINFO(OpalTransportAddress, PCaselessString);
  public:
    static const PCaselessString & IpPrefix();
    static const PCaselessString & UdpPrefix();
    static const PCaselessString & TcpPrefix();
#if OPAL_PTLIB_SSL
    static const PCaselessString & TlsPrefix();
#endif

    OpalTransportAddress();
    OpalTransportAddress(
      const char * address,      
      WORD port = 0,             
      const char * proto = NULL  
    );
    OpalTransportAddress(
      const PString & address,   
      WORD port = 0,             
      const char * proto = NULL  
    );
    OpalTransportAddress(
      const PIPSocket::Address & ip,  
      WORD port,                      
      const char * proto = NULL       
    );

    virtual PObject * Clone() const { return new OpalTransportAddress(*this); }

    PBoolean IsEquivalent(
      const OpalTransportAddress & address,   
      bool wildcards = false   
    ) const;

    PBoolean IsCompatible(
      const OpalTransportAddress & address
    ) const;

    PCaselessString GetProtoPrefix() const { return Left(Find('$')+1); }

    // For backward compatibility
    PCaselessString GetProto(bool withDollar = false) const { return Left(Find('$')+(withDollar?1:0)); }

    PBoolean GetIpAddress(PIPSocket::Address & ip) const;

    PBoolean GetIpAndPort(PIPSocket::Address & ip, WORD & port) const;
    PBoolean GetIpAndPort(PIPSocketAddressAndPort & ipPort) const;

    virtual PString GetHostName(
      bool includeService = false
    ) const;

    enum BindOptions {
      NoBinding,
      HostOnly,
      FullTSAP,
      Streamed,
      Datagram,
      RouteInterface,
      NumBindOptions
    };

    OpalListener * CreateListener(
      OpalEndPoint & endpoint,   
      BindOptions option         
    ) const;

    virtual OpalTransport * CreateTransport(
      OpalEndPoint & endpoint,   
      BindOptions option = HostOnly 
    ) const;


  protected:
    void SetInternalTransport(
      WORD port,             
      const char * proto     
    );

    OpalInternalTransport * m_transport;
};


class OpalTransportAddressArray : public PArray<OpalTransportAddress>
{
    typedef PArray<OpalTransportAddress> ParentClass;
    PCLASSINFO(OpalTransportAddressArray, ParentClass);

  protected:
    inline OpalTransportAddressArray(int dummy, const OpalTransportAddressArray * c)
      : ParentClass(dummy, c) { }

  public:
    OpalTransportAddressArray(PINDEX initialSize = 0)
      : ParentClass(initialSize) { }
    OpalTransportAddressArray(
      const OpalTransportAddress & address
    ) { AppendAddress(address); }
    OpalTransportAddressArray(
      const PStringArray & array
    ) { AppendStringCollection(array); }
    OpalTransportAddressArray(
      const PStringList & list
    ) { AppendStringCollection(list); }
    OpalTransportAddressArray(
      const PSortedStringList & list
    ) { AppendStringCollection(list); }

    void AppendString(
      const char * address
    );
    void AppendString(
      const PString & address
    );
    void AppendAddress(
      const OpalTransportAddress & address
    );

    virtual PObject * Clone() const
    {
      return new OpalTransportAddressArray(0, this);
    }

  protected:
    void AppendStringCollection(
      const PCollection & coll
    );
};





class OpalListener : public PObject
{
    PCLASSINFO(OpalListener, PObject);
  public:
    OpalListener(
      OpalEndPoint & endpoint   
    );

    void PrintOn(
      ostream & strm
    ) const;

    enum ThreadMode {
      SpawnNewThreadMode,
      HandOffThreadMode,
      SingleThreadMode
    };

    typedef PNotifierTemplate<const OpalTransportPtr &> AcceptHandler;
    #define PDECLARE_AcceptHandlerNotifier(cls, fn) PDECLARE_NOTIFIER2(OpalListener, cls, fn, const OpalTransportPtr &)


    virtual bool Open(
      const AcceptHandler & acceptHandler,  
      ThreadMode mode = SpawnNewThreadMode 
    );

    virtual bool IsOpen() const = 0;

    virtual void Close() = 0;

    virtual OpalTransport * Accept(
      const PTimeInterval & timeout  
    ) = 0;

    virtual OpalTransport * CreateTransport(
      const OpalTransportAddress & localAddress,
      const OpalTransportAddress & remoteAddress
    ) const = 0;

    virtual OpalTransportAddress GetLocalAddress(
      const OpalTransportAddress & remoteAddress = OpalTransportAddress()
    ) const = 0;

    void CloseWait();

    void CleanUpOnTermination() { CloseWait(); }


  protected:
    void ListenForConnections();
    void TransportThreadMain(OpalTransportPtr transport);

    OpalEndPoint & endpoint;
    PThread      * thread;
    AcceptHandler  acceptHandler;
    ThreadMode     threadMode;
};


PLIST(OpalListenerList, OpalListener);


class OpalListenerIP : public OpalListener
{
  PCLASSINFO(OpalListenerIP, OpalListener);
  public:
    OpalListenerIP(
      OpalEndPoint & endpoint,                 
      PIPSocket::Address binding = PIPSocket::GetDefaultIpAny(), 
      WORD port = 0,                           
      PBoolean exclusive = true               
    );
    OpalListenerIP(
      OpalEndPoint & endpoint,                  
      const OpalTransportAddress & binding,     
      OpalTransportAddress::BindOptions option  
    );

    virtual OpalTransportAddress GetLocalAddress(
      const OpalTransportAddress & remoteAddress = OpalTransportAddress()
    ) const;

    WORD GetListenerPort() const { return listenerPort; }

    virtual const PCaselessString & GetProtoPrefix() const = 0;


  protected:
    bool CanCreateTransport(
      const OpalTransportAddress & localAddress,
      const OpalTransportAddress & remoteAddress
    ) const;

    PIPSocket::Address localAddress;
    WORD               listenerPort;
    bool               exclusiveListener;
};


class OpalListenerTCP : public OpalListenerIP
{
  PCLASSINFO(OpalListenerTCP, OpalListenerIP);
  public:
    OpalListenerTCP(
      OpalEndPoint & endpoint,                 
      PIPSocket::Address binding = PIPSocket::GetDefaultIpAny(), 
      WORD port = 0,                           
      PBoolean exclusive = true               
    );
    OpalListenerTCP(
      OpalEndPoint & endpoint,                  
      const OpalTransportAddress & binding,     
      OpalTransportAddress::BindOptions option  
    );

    ~OpalListenerTCP();

    virtual bool Open(
      const AcceptHandler & acceptHandler,  
      ThreadMode mode = SpawnNewThreadMode 
    );

    virtual bool IsOpen() const;

    virtual void Close();

    virtual OpalTransport * Accept(
      const PTimeInterval & timeout  
    );

    virtual OpalTransport * CreateTransport(
      const OpalTransportAddress & localAddress,
      const OpalTransportAddress & remoteAddress
    ) const;


  protected:
    virtual const PCaselessString & GetProtoPrefix() const;

    PTCPSocket listener;
};


class OpalListenerUDP : public OpalListenerIP
{
  PCLASSINFO(OpalListenerUDP, OpalListenerIP);
  public:
    OpalListenerUDP(
      OpalEndPoint & endpoint,  
      PIPSocket::Address binding = PIPSocket::GetDefaultIpAny(), 
      WORD port = 0,            
      PBoolean exclusive = true  
    );
    OpalListenerUDP(
      OpalEndPoint & endpoint,                  
      const OpalTransportAddress & binding,     
      OpalTransportAddress::BindOptions option  
    );

    ~OpalListenerUDP();

    virtual bool Open(
      const AcceptHandler & acceptHandler,  
      ThreadMode mode = SpawnNewThreadMode 
    );

    virtual bool IsOpen() const;

    virtual void Close();

    virtual OpalTransport * Accept(
      const PTimeInterval & timeout  
    );

    virtual OpalTransport * CreateTransport(
      const OpalTransportAddress & localAddress,
      const OpalTransportAddress & remoteAddress
    ) const;

    virtual OpalTransportAddress GetLocalAddress(
      const OpalTransportAddress & remoteAddress = OpalTransportAddress()
    ) const;

    void SetBufferSize(
      PINDEX size
    ) { m_bufferSize = size; }


  protected:
    virtual const PCaselessString & GetProtoPrefix() const;

    PMonitoredSocketsPtr listenerBundle;
    PINDEX               m_bufferSize;
};



class OpalTransport : public PSafeObject
{
    PCLASSINFO(OpalTransport, PSafeObject);
  protected:
    OpalTransport(OpalEndPoint & endpoint, PChannel * channel);

  public:
    ~OpalTransport();

    void PrintOn(
      ostream & strm
    ) const;

    virtual PBoolean Write(
      const void * buf, 
      PINDEX len        
    );

    virtual PBoolean IsReliable() const = 0;

    virtual bool IsAuthenticated(
      const PString & /*domain*/
    ) const { return true; }

    virtual PString GetInterface() const;

    virtual bool SetInterface(
      const PString & iface  
    );

    virtual OpalTransportAddress GetLocalAddress(
      bool allowNAT = true   
    ) const = 0;

    virtual PBoolean SetLocalAddress(
      const OpalTransportAddress & address
    ) = 0;

    virtual OpalTransportAddress GetRemoteAddress() const = 0;

    virtual PBoolean SetRemoteAddress(
      const OpalTransportAddress & address
    ) = 0;

    virtual PBoolean Connect() = 0;

    PBoolean ConnectTo(
      const OpalTransportAddress & address
    ) { return SetRemoteAddress(address) && Connect(); }

    virtual PBoolean Close();

    void CloseWait();

    void CleanUpOnTermination() { CloseWait(); }

    virtual PBoolean IsCompatibleTransport(
      const OpalTransportAddress & address
    ) const = 0;

    enum PromisciousModes {
      AcceptFromRemoteOnly,
      AcceptFromAnyAutoSet,
      AcceptFromAny,
      NumPromisciousModes
    };

    virtual void SetPromiscuous(
      PromisciousModes promiscuous
    );

    virtual OpalTransportAddress GetLastReceivedAddress() const;

    virtual PString GetLastReceivedInterface() const;

    virtual PBoolean ReadPDU(
      PBYTEArray & packet   
    ) = 0;

    virtual PBoolean WritePDU(
      const PBYTEArray & pdu     
    ) = 0;

    typedef PNotifierTemplate<bool &> WriteConnectCallback;
    #define PDECLARE_WriteConnectCallback(cls, fn) PDECLARE_NOTIFIER2(OpalTransport, cls, fn, bool &)

    virtual bool WriteConnect(
      const WriteConnectCallback & function  
    );

    void SetKeepAlive(
      const PTimeInterval & timeout,
      const PBYTEArray & data
    );

    virtual void AttachThread(
      PThread * thread
    );

    virtual PBoolean IsRunning() const;

    OpalEndPoint & GetEndPoint() const { return endpoint; }

    virtual const PCaselessString & GetProtoPrefix() const = 0;

    bool IsOpen() const
      { return m_channel != NULL && m_channel->IsOpen(); }

    bool IsGood() const
      { return IsOpen() && !m_channel->bad() && !m_channel->eof(); }

    PChannel::Errors GetErrorCode(PChannel::ErrorGroup group = PChannel::NumErrorGroups) const
      { return m_channel != NULL ? m_channel->GetErrorCode(group) : PChannel::NotOpen; }

    PString GetErrorText(PChannel::ErrorGroup group = PChannel::NumErrorGroups) const
      { return m_channel != NULL ? m_channel->GetErrorText(group) : PString::Empty(); }

    int GetErrorNumber(PChannel::ErrorGroup group = PChannel::NumErrorGroups) const
      { return m_channel != NULL ? m_channel->GetErrorNumber(group) : -1; }

    void SetReadTimeout(const PTimeInterval & t)
      { if (m_channel != NULL) m_channel->SetReadTimeout(t); }

    PChannel * GetChannel() const { return m_channel; }
    void SetChannel(PChannel * chan) { m_channel = chan; }

    bool IsIdle() const { return m_referenceCount == 0 && m_idleTimer.HasExpired(); }

    void Reference()   { ++m_referenceCount; }
    void Dereference() { --m_referenceCount; }

  protected:
    PDECLARE_NOTIFIER(PTimer, OpalTransport, KeepAlive);

    OpalEndPoint & endpoint;
    PChannel     * m_channel;
    PThread      * m_thread;      
    PTimer         m_keepAliveTimer;
    PBYTEArray     m_keepAliveData;
    PSimpleTimer   m_idleTimer;
    PAtomicInteger m_referenceCount;
};


class OpalTransportIP : public OpalTransport
{
    PCLASSINFO(OpalTransportIP, OpalTransport);
  protected:
    OpalTransportIP(
      OpalEndPoint & endpoint,    
      PChannel * channel,         
      PIPSocket::Address binding, 
      WORD port                   
    );

  public:
    virtual OpalTransportAddress GetLocalAddress(
      bool allowNAT = true   
    ) const;

    virtual PBoolean SetLocalAddress(
      const OpalTransportAddress & address
    );

    virtual OpalTransportAddress GetRemoteAddress() const;

    virtual PBoolean SetRemoteAddress(
      const OpalTransportAddress & address
    );


  protected:
    virtual const PCaselessString & GetProtoPrefix() const = 0;

    PIPSocket::Address localAddress;  // Address of the local interface
    WORD               localPort;
    PIPSocket::Address remoteAddress; // Address of the remote host
    WORD               remotePort;
};


class OpalTransportTCP : public OpalTransportIP
{
    PCLASSINFO(OpalTransportTCP, OpalTransportIP);
  public:
    OpalTransportTCP(
      OpalEndPoint & endpoint,    
      PIPSocket::Address binding = PIPSocket::GetDefaultIpAny(), 
      WORD port = 0,              
      PBoolean reuseAddr = false      
    );
    OpalTransportTCP(
      OpalEndPoint & endpoint,    
      PChannel * socket           
    );

    ~OpalTransportTCP();

    virtual PBoolean IsReliable() const;

    virtual PBoolean IsCompatibleTransport(
      const OpalTransportAddress & address
    ) const;

    virtual PBoolean Connect();

    virtual PBoolean ReadPDU(
      PBYTEArray & pdu  
    );

    virtual PBoolean WritePDU(
      const PBYTEArray & pdu     
    );


  protected:
    virtual const PCaselessString & GetProtoPrefix() const;

    bool OnConnectedSocket(PTCPSocket * socket);

    PBoolean reuseAddressFlag;
};


class OpalTransportUDP : public OpalTransportIP
{
  PCLASSINFO(OpalTransportUDP, OpalTransportIP);
  public:
    OpalTransportUDP(
      OpalEndPoint & endpoint,    
      PIPSocket::Address binding = PIPSocket::GetDefaultIpAny(), 
      WORD port = 0,              
      bool reuseAddr = false,     
      bool preOpen = false        
    );

    OpalTransportUDP(
      OpalEndPoint & endpoint,              
      const PMonitoredSocketsPtr & sockets, 
      const PString & iface                 
    );

    ~OpalTransportUDP();

    virtual PBoolean Read(
      void * buffer,
      PINDEX length
    );

    virtual PBoolean IsReliable() const;

    virtual PBoolean IsCompatibleTransport(
      const OpalTransportAddress & address
    ) const;

    virtual PBoolean Connect();

    virtual PString GetInterface() const;

    virtual bool SetInterface(
      const PString & iface  
    );

    virtual OpalTransportAddress GetLocalAddress(
      bool allowNAT = true   
    ) const;

    virtual PBoolean SetLocalAddress(
      const OpalTransportAddress & address
    );

    virtual PBoolean SetRemoteAddress(
      const OpalTransportAddress & address
    );

    virtual void SetPromiscuous(
      PromisciousModes promiscuous
    );

    virtual OpalTransportAddress GetLastReceivedAddress() const;

    virtual PString GetLastReceivedInterface() const;

    virtual PBoolean ReadPDU(
      PBYTEArray & packet   
    );

    virtual PBoolean WritePDU(
      const PBYTEArray & pdu     
    );

    virtual bool WriteConnect(
      const WriteConnectCallback & function  
    );

    void SetBufferSize(
      PINDEX size
    ) { m_bufferSize = size; }

  protected:
    virtual const PCaselessString & GetProtoPrefix() const;

    OpalManager & manager;
    PINDEX        m_bufferSize;
    PBYTEArray    m_preReadPacket;
    bool          m_preReadOK;

  friend class OpalListenerUDP;
};



class OpalInternalTransport : public PObject
{
    PCLASSINFO(OpalInternalTransport, PObject);
  public:
    virtual bool Parse(
      OpalTransportAddress & address,
      WORD port
    ) const = 0;

    virtual PString GetHostName(
      const OpalTransportAddress & address,
      bool includeService
    ) const;

    virtual PBoolean GetIpAndPort(
      const OpalTransportAddress & address,
      PIPSocket::Address & ip,
      WORD & port
    ) const;

    virtual OpalListener * CreateListener(
      const OpalTransportAddress & address,
      OpalEndPoint & endpoint,
      OpalTransportAddress::BindOptions options
    ) const  = 0;

    virtual OpalTransport * CreateTransport(
      const OpalTransportAddress & address,
      OpalEndPoint & endpoint,
      OpalTransportAddress::BindOptions options
    ) const = 0;
};



class OpalInternalIPTransport : public OpalInternalTransport
{
    PCLASSINFO(OpalInternalIPTransport, OpalInternalTransport);
  public:
    virtual bool Parse(
      OpalTransportAddress & address,
      WORD port
    ) const;
    virtual PString GetHostName(
      const OpalTransportAddress & address,
      bool includeService
    ) const;
    virtual PBoolean GetIpAndPort(
      const OpalTransportAddress & address,
      PIPSocket::Address & ip,
      WORD & port
    ) const;

    static PBoolean GetAdjustedIpAndPort(const OpalTransportAddress & address,
                                     OpalEndPoint & endpoint,
                                     OpalTransportAddress::BindOptions option,
                                     PIPSocket::Address & ip,
                                     WORD & port,
                                     PBoolean & reuseAddr);
};

template <class ListenerType, class TransportType, unsigned AltTypeOption, class AltTypeClass>
class OpalInternalIPTransportTemplate : public OpalInternalIPTransport
{
  public:
    OpalListener * CreateListener(
      const OpalTransportAddress & address,
      OpalEndPoint & endpoint,
      OpalTransportAddress::BindOptions options
    ) const
    {
      return new ListenerType(endpoint, address, options);
    }

    OpalTransport * CreateTransport(
      const OpalTransportAddress & address,
      OpalEndPoint & endpoint,
      OpalTransportAddress::BindOptions options
    ) const
    {
      PIPSocket::Address ip;
      WORD port;
      PBoolean reuseAddr;
      if (GetAdjustedIpAndPort(address, endpoint, options, ip, port, reuseAddr)) {
        if (options == AltTypeOption)
          return new AltTypeClass(endpoint, ip, 0, reuseAddr);
        else
          return new TransportType(endpoint, ip, 0, reuseAddr);
      }
      return NULL;
    }
};

typedef OpalInternalIPTransportTemplate<OpalListenerTCP, OpalTransportTCP, OpalTransportAddress::Datagram, OpalTransportUDP> OpalInternalTCPTransport;
typedef OpalInternalIPTransportTemplate<OpalListenerUDP, OpalTransportUDP, OpalTransportAddress::Streamed, OpalTransportTCP> OpalInternalUDPTransport;

#if OPAL_PTLIB_SSL

class PSSLContext;
class PSSLChannel;

class OpalListenerTLS : public OpalListenerTCP
{
  PCLASSINFO(OpalListenerTLS, OpalListenerTCP);
  public:
    OpalListenerTLS(
      OpalEndPoint & endpoint,                 
      PIPSocket::Address binding = PIPSocket::GetDefaultIpAny(), 
      WORD port = 0,                           
      PBoolean exclusive = true               
    );
    OpalListenerTLS(
      OpalEndPoint & endpoint,                  
      const OpalTransportAddress & binding,     
      OpalTransportAddress::BindOptions option  
    );

    ~OpalListenerTLS();

    virtual PBoolean Open(const AcceptHandler & acceptHandler, ThreadMode mode = SpawnNewThreadMode);
    virtual OpalTransport * Accept(const PTimeInterval & timeout);
    virtual const PCaselessString & GetProtoPrefix() const;
    virtual OpalTransport * CreateTransport(
      const OpalTransportAddress & localAddress,
      const OpalTransportAddress & remoteAddress
    ) const;

  protected:
    PSSLContext * m_sslContext;
};


class OpalTransportTLS : public OpalTransportTCP
{
  PCLASSINFO(OpalTransportTLS, OpalTransportTCP);
    public:
      OpalTransportTLS(
        OpalEndPoint & endpoint,    
        PSSLChannel * ssl
      );

      OpalTransportTLS(
        OpalEndPoint & endpoint,    
        PIPSocket::Address binding = PIPSocket::GetDefaultIpAny(), 
        WORD port = 0,              
        PBoolean reuseAddr = false      
      );

      ~OpalTransportTLS();

      // Overrides
      virtual PBoolean IsCompatibleTransport(const OpalTransportAddress & address) const;
      virtual PBoolean Connect();
      virtual const PCaselessString & GetProtoPrefix() const;
      virtual bool IsAuthenticated(const PString & domain) const;
};

typedef OpalInternalIPTransportTemplate<OpalListenerTLS, OpalTransportTLS, OpalTransportAddress::Datagram, OpalTransportUDP> OpalInternalTLSTransport;

typedef OpalTransportTLS OpalTransportTCPS; // For backward compatibility
typedef OpalListenerTLS OpalListenerTCPS;


#endif // OPAL_PTLIB_SSL


#endif  // OPAL_OPAL_TRANSPORT_H


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