transports.h

Go to the documentation of this file.
00001 /*
00002  * transport.h
00003  *
00004  * Transport declarations
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  * $Log: transports.h,v $
00028  * Revision 2.19.2.1  2007/01/15 22:16:42  dsandras
00029  * Backported patches improving stability from HEAD to Phobos.
00030  *
00031  * Revision 2.19  2005/11/30 13:35:26  csoutheren
00032  * Changed tags for Doxygen
00033  *
00034  * Revision 2.18  2005/09/19 20:48:23  dsandras
00035  * Added the "can reuse address" flag to the OpalTransportUDP class.
00036  *
00037  * Revision 2.17  2005/01/16 23:07:33  csoutheren
00038  * Fixed problem with IPv6 INADDR_ANY
00039  *
00040  * Revision 2.16  2004/03/22 11:39:44  rjongbloed
00041  * Fixed problems with correctly terminating the OpalTransportUDP that is generated from
00042  *   an OpalListenerUDP, this should not close the socket or stop the thread.
00043  *
00044  * Revision 2.15  2004/03/13 06:25:52  rjongbloed
00045  * Slight rearrangement of local party name and alias list to beter match common
00046  *   behaviour in ancestor.
00047  * Abstracted local party name for endpoint into ancestor from H.,323.
00048  *
00049  * Revision 2.14  2004/03/11 06:54:27  csoutheren
00050  * Added ability to disable SIP or H.323 stacks
00051  *
00052  * Revision 2.13  2004/02/19 10:47:01  rjongbloed
00053  * Merged OpenH323 version 1.13.1 changes.
00054  *
00055  * Revision 2.12  2003/01/07 04:39:53  robertj
00056  * Updated to OpenH323 v1.11.2
00057  *
00058  * Revision 2.11  2002/11/10 11:33:17  robertj
00059  * Updated to OpenH323 v1.10.3
00060  *
00061  * Revision 1.43  2003/12/29 13:28:45  dominance
00062  * fixed docbook syntax trying to generate LaTeX formula with ip$10.x.x.x.
00063  *
00064  * Revision 1.42  2003/04/10 09:44:55  robertj
00065  * Added associated transport to new GetInterfaceAddresses() function so
00066  *   interfaces can be ordered according to active transport links. Improves
00067  *   interoperability.
00068  * Replaced old listener GetTransportPDU() with GetInterfaceAddresses()
00069  *   and H323SetTransportAddresses() functions.
00070  *
00071  * Revision 1.41  2003/04/10 01:03:25  craigs
00072  * Added functions to access to lists of interfaces
00073  *
00074  * Revision 1.40  2003/03/21 05:24:02  robertj
00075  * Added setting of remote port in UDP transport constructor.
00076  *
00077  * Revision 1.39  2003/02/06 04:29:23  robertj
00078  * Added more support for adding things to H323TransportAddressArrays
00079  *
00080  * Revision 1.38  2002/11/21 06:39:56  robertj
00081  * Changed promiscuous mode to be three way. Fixes race condition in gkserver
00082  *   which can cause crashes or more PDUs to be sent to the wrong place.
00083  *
00084  * Revision 1.37  2002/11/10 08:10:43  robertj
00085  * Moved constants for "well known" ports to better place (OPAL change).
00086  *
00087  * Revision 2.10  2002/09/16 02:52:35  robertj
00088  * Added #define so can select if #pragma interface/implementation is used on
00089  *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
00090  *
00091  * Revision 2.9  2002/09/12 06:58:17  robertj
00092  * Removed protocol prefix strings as static members as has problems with
00093  *   use in DLL environment.
00094  *
00095  * Revision 2.8  2002/09/06 02:41:00  robertj
00096  * Added ability to specify stream or datagram (TCP or UDP) transport is to
00097  * be created from a transport address regardless of the addresses mode.
00098  *
00099  * Revision 2.7  2002/07/01 04:56:31  robertj
00100  * Updated to OpenH323 v1.9.1
00101  *
00102  * Revision 2.6  2002/06/16 23:07:47  robertj
00103  * Fixed several memory leaks, thanks Ted Szoczei
00104  *
00105  * Revision 2.5  2002/04/09 00:12:10  robertj
00106  * Added ability to set the local address on a transport, under some circumstances.
00107  *
00108  * Revision 2.4  2001/11/13 04:29:47  robertj
00109  * Changed OpalTransportAddress CreateTransport and CreateListsner functions
00110  *   to have extra parameter to control local binding of sockets.
00111  *
00112  * Revision 2.3  2001/11/12 05:32:12  robertj
00113  * Added OpalTransportAddress::GetIpAddress when don't need port number.
00114  *
00115  * Revision 2.2  2001/11/09 05:49:47  robertj
00116  * Abstracted UDP connection algorithm
00117  *
00118  * Revision 2.1  2001/11/06 05:40:13  robertj
00119  * Added OpalListenerUDP class to do listener semantics on a UDP socket.
00120  *
00121  * Revision 2.0  2001/07/27 15:48:24  robertj
00122  * Conversion of OpenH323 to Open Phone Abstraction Library (OPAL)
00123  *
00124  */
00125 
00126 #ifndef __OPAL_TRANSPORT_H
00127 #define __OPAL_TRANSPORT_H
00128 
00129 #ifdef P_USE_PRAGMA
00130 #pragma interface
00131 #endif
00132 
00133 #include <opal/buildopts.h>
00134 
00135 #include <ptlib/sockets.h>
00136 
00137 
00138 class OpalEndPoint;
00139 class OpalListener;
00140 class OpalTransport;
00141 class OpalInternalTransport;
00142 
00143 
00145 
00146 class OpalTransportAddress : public PString
00147 {
00148   PCLASSINFO(OpalTransportAddress, PString);
00149   public:
00152     OpalTransportAddress();
00153     OpalTransportAddress(
00154       const char * address,      
00155       WORD port = 0,             
00156       const char * proto = NULL  
00157     );
00158     OpalTransportAddress(
00159       const PString & address,   
00160       WORD port = 0,             
00161       const char * proto = NULL  
00162     );
00163     OpalTransportAddress(
00164       const PIPSocket::Address & ip,
00165       WORD port,
00166       const char * proto = NULL 
00167     );
00169 
00174     BOOL IsEquivalent(
00175       const OpalTransportAddress & address
00176     );
00177 
00181     BOOL GetIpAddress(PIPSocket::Address & ip) const;
00182 
00186     BOOL GetIpAndPort(PIPSocket::Address & ip, WORD & port) const;
00187 
00191     virtual PString GetHostName() const;
00192 
00193     enum BindOptions {
00194       NoBinding,
00195       HostOnly,
00196       FullTSAP,
00197       Streamed,
00198       Datagram,
00199       NumBindOptions
00200     };
00201 
00229     OpalListener * CreateListener(
00230       OpalEndPoint & endpoint,   
00231       BindOptions option         
00232     ) const;
00233 
00261     virtual OpalTransport * CreateTransport(
00262       OpalEndPoint & endpoint,   
00263       BindOptions option = HostOnly 
00264     ) const;
00266 
00267 
00268   protected:
00269     void SetInternalTransport(
00270       WORD port,             
00271       const char * proto     
00272     );
00273 
00274     OpalInternalTransport * transport;
00275 };
00276 
00277 
00278 PDECLARE_ARRAY(OpalTransportAddressArray, OpalTransportAddress)
00279   public:
00280     OpalTransportAddressArray(
00281       const OpalTransportAddress & address
00282     ) { AppendAddress(address); }
00283     OpalTransportAddressArray(
00284       const PStringArray & array
00285     ) { AppendStringCollection(array); }
00286     OpalTransportAddressArray(
00287       const PStringList & list
00288     ) { AppendStringCollection(list); }
00289     OpalTransportAddressArray(
00290       const PSortedStringList & list
00291     ) { AppendStringCollection(list); }
00292 
00293     void AppendString(
00294       const char * address
00295     );
00296     void AppendString(
00297       const PString & address
00298     );
00299     void AppendAddress(
00300       const OpalTransportAddress & address
00301     );
00302 
00303   protected:
00304     void AppendStringCollection(
00305       const PCollection & coll
00306     );
00307 };
00308 
00309 
00310 
00311 
00313 
00326 class OpalListener : public PObject
00327 {
00328     PCLASSINFO(OpalListener, PObject);
00329   public:
00334     OpalListener(
00335       OpalEndPoint & endpoint   
00336     );
00338 
00343     void PrintOn(
00344       ostream & strm
00345     ) const;
00347 
00364     virtual BOOL Open(
00365       const PNotifier & acceptHandler,  
00366       BOOL singleThread = FALSE         
00367     ) = 0;
00368 
00371     virtual BOOL IsOpen() = 0;
00372 
00375     virtual void Close() = 0;
00376 
00379     virtual OpalTransport * Accept(
00380       const PTimeInterval & timeout  
00381     ) = 0;
00382 
00385     virtual OpalTransportAddress GetLocalAddress(
00386       const OpalTransportAddress & preferredAddress = OpalTransportAddress()
00387     ) const = 0;
00388 
00392     OpalTransportAddress GetTransportAddress() const { return GetLocalAddress(); }
00393 
00396     void CloseWait();
00397 
00401     void CleanUpOnTermination() { CloseWait(); }
00403 
00404 
00405   protected:
00414     PDECLARE_NOTIFIER(PThread, OpalListener, ListenForConnections);
00415     BOOL StartThread(
00416       const PNotifier & acceptHandler,  
00417       BOOL singleThread                
00418     );
00419 
00420     OpalEndPoint & endpoint;
00421     PThread      *  thread;
00422     PNotifier      acceptHandler;
00423     BOOL           singleThread;
00424 };
00425 
00426 
00427 PLIST(OpalListenerList, OpalListener);
00428 
00429 
00432 OpalTransportAddressArray OpalGetInterfaceAddresses(
00433   const OpalListenerList & listeners, 
00434   BOOL excludeLocalHost = TRUE,       
00435   OpalTransport * associatedTransport = NULL
00437 );
00438 
00439 OpalTransportAddressArray OpalGetInterfaceAddresses(
00440   const OpalTransportAddress & addr,  
00441   BOOL excludeLocalHost = TRUE,       
00442   OpalTransport * associatedTransport = NULL
00444 );
00445 
00446 
00447 class OpalListenerIP : public OpalListener
00448 {
00449   PCLASSINFO(OpalListenerIP, OpalListener);
00450   public:
00455     OpalListenerIP(
00456       OpalEndPoint & endpoint,                 
00457       PIPSocket::Address binding = PIPSocket::GetDefaultIpAny(), 
00458       WORD port = 0,                           
00459       BOOL exclusive = TRUE
00460     );
00462 
00467     virtual OpalTransportAddress GetLocalAddress(
00468       const OpalTransportAddress & preferredAddress = OpalTransportAddress()
00469     ) const;
00471 
00474     WORD GetListenerPort() const { return listenerPort; }
00475 
00476     virtual const char * GetProtoPrefix() const = 0;
00478 
00479 
00480   protected:
00481     PIPSocket::Address localAddress;
00482     WORD               listenerPort;
00483     BOOL               exclusiveListener;
00484 };
00485 
00486 
00487 class OpalListenerTCP : public OpalListenerIP
00488 {
00489   PCLASSINFO(OpalListenerTCP, OpalListenerIP);
00490   public:
00495     OpalListenerTCP(
00496       OpalEndPoint & endpoint,                 
00497       PIPSocket::Address binding = PIPSocket::GetDefaultIpAny(), 
00498       WORD port = 0,                           
00499       BOOL exclusive = TRUE
00500     );
00501 
00504     ~OpalListenerTCP();
00506 
00529     virtual BOOL Open(
00530       const PNotifier & acceptHandler,  
00531       BOOL singleThread = FALSE         
00532     );
00533 
00536     virtual BOOL IsOpen();
00537 
00540     virtual void Close();
00541 
00544     virtual OpalTransport * Accept(
00545       const PTimeInterval & timeout  
00546     );
00548 
00549 
00550   protected:
00551     virtual const char * GetProtoPrefix() const;
00552 
00553     PTCPSocket listener;
00554 };
00555 
00556 
00557 class OpalListenerUDP : public OpalListenerIP
00558 {
00559   PCLASSINFO(OpalListenerUDP, OpalListenerIP);
00560   public:
00565     OpalListenerUDP(
00566       OpalEndPoint & endpoint,                 
00567       PIPSocket::Address binding = PIPSocket::GetDefaultIpAny(), 
00568       WORD port = 0,                           
00569       BOOL exclusive = TRUE
00570     );
00571 
00574     ~OpalListenerUDP();
00576 
00599     virtual BOOL Open(
00600       const PNotifier & acceptHandler,  
00601       BOOL singleThread = TRUE          
00602     );
00603 
00606     virtual BOOL IsOpen();
00607 
00610     virtual void Close();
00611 
00614     virtual OpalTransport * Accept(
00615       const PTimeInterval & timeout  
00616     );
00618 
00619 
00620   protected:
00621     virtual const char * GetProtoPrefix() const;
00622     BOOL OpenOneSocket(const PIPSocket::Address & address);
00623 
00624     PSocketList listeners;
00625 };
00626 
00627 
00629 
00634 class OpalTransport : public PIndirectChannel
00635 {
00636     PCLASSINFO(OpalTransport, PIndirectChannel);
00637   public:
00642     OpalTransport(OpalEndPoint & endpoint);
00643 
00646     ~OpalTransport();
00648 
00653     void PrintOn(
00654       ostream & strm
00655     ) const;
00657 
00662     virtual BOOL IsReliable() const = 0;
00663 
00666     virtual OpalTransportAddress GetLocalAddress() const = 0;
00667 
00672     virtual BOOL SetLocalAddress(
00673       const OpalTransportAddress & address
00674     ) = 0;
00675 
00678     virtual OpalTransportAddress GetRemoteAddress() const = 0;
00679 
00685     virtual BOOL SetRemoteAddress(
00686       const OpalTransportAddress & address
00687     ) = 0;
00688 
00691     virtual BOOL Connect() = 0;
00692 
00695     BOOL ConnectTo(
00696       const OpalTransportAddress & address
00697     ) { return SetRemoteAddress(address) && Connect(); }
00698 
00705     virtual void EndConnect(
00706       const OpalTransportAddress & localAddress  
00707     );
00708 
00711     virtual BOOL Close();
00712 
00715     void CloseWait();
00716 
00720     void CleanUpOnTermination() { CloseWait(); }
00721 
00724     virtual BOOL IsCompatibleTransport(
00725       const OpalTransportAddress & address
00726     ) const = 0;
00727 
00729     enum PromisciousModes {
00730       AcceptFromRemoteOnly,
00731       AcceptFromAnyAutoSet,
00732       AcceptFromAny,
00733       NumPromisciousModes
00734     };
00735 
00746     virtual void SetPromiscuous(
00747       PromisciousModes promiscuous
00748     );
00749 
00754     virtual OpalTransportAddress GetLastReceivedAddress() const;
00755 
00761     virtual BOOL ReadPDU(
00762       PBYTEArray & packet   
00763     ) = 0;
00764 
00770     virtual BOOL WritePDU(
00771       const PBYTEArray & pdu     
00772     ) = 0;
00773 
00774     typedef BOOL (*WriteConnectCallback)(OpalTransport & transport, void * userData);
00775 
00788     virtual BOOL WriteConnect(
00789       WriteConnectCallback function,  
00790       void * userData                 
00791     );
00792 
00795     virtual void AttachThread(
00796       PThread * thread
00797     );
00798 
00801     virtual BOOL IsRunning() const;
00803 
00804     OpalEndPoint & GetEndPoint() const { return endpoint; }
00805 
00806   protected:
00807     OpalEndPoint & endpoint;
00808     PThread      * thread;      
00809 };
00810 
00811 
00812 class OpalTransportIP : public OpalTransport
00813 {
00814   PCLASSINFO(OpalTransportIP, OpalTransport);
00815   public:
00820     OpalTransportIP(
00821       OpalEndPoint & endpoint,    
00822       PIPSocket::Address binding, 
00823       WORD port                   
00824     );
00826 
00831     virtual OpalTransportAddress GetLocalAddress() const;
00832 
00837     virtual BOOL SetLocalAddress(
00838       const OpalTransportAddress & address
00839     );
00840 
00843     virtual OpalTransportAddress GetRemoteAddress() const;
00844 
00850     virtual BOOL SetRemoteAddress(
00851       const OpalTransportAddress & address
00852     );
00853 
00855 
00856   protected:
00859     virtual const char * GetProtoPrefix() const = 0;
00860 
00861     PIPSocket::Address localAddress;  // Address of the local interface
00862     WORD               localPort;
00863     PIPSocket::Address remoteAddress; // Address of the remote host
00864     WORD               remotePort;
00865 };
00866 
00867 
00868 class OpalTransportTCP : public OpalTransportIP
00869 {
00870     PCLASSINFO(OpalTransportTCP, OpalTransportIP);
00871   public:
00876     OpalTransportTCP(
00877       OpalEndPoint & endpoint,    
00878       PIPSocket::Address binding = INADDR_ANY, 
00879       WORD port = 0,              
00880       BOOL reuseAddr = FALSE      
00881     );
00882     OpalTransportTCP(
00883       OpalEndPoint & endpoint,    
00884       PTCPSocket * socket         
00885     );
00886 
00888     ~OpalTransportTCP();
00890 
00895     virtual BOOL IsReliable() const;
00896 
00899     virtual BOOL IsCompatibleTransport(
00900       const OpalTransportAddress & address
00901     ) const;
00902 
00905     virtual BOOL Connect();
00906 
00912     virtual BOOL ReadPDU(
00913       PBYTEArray & pdu  
00914     );
00915 
00921     virtual BOOL WritePDU(
00922       const PBYTEArray & pdu     
00923     );
00925 
00926 
00927   protected:
00930     virtual const char * GetProtoPrefix() const;
00931 
00941     virtual BOOL OnOpen();
00942 
00943 
00944     BOOL reuseAddressFlag;
00945 };
00946 
00947 
00948 class OpalTransportUDP : public OpalTransportIP
00949 {
00950   PCLASSINFO(OpalTransportUDP, OpalTransportIP);
00951   public:
00956     OpalTransportUDP(
00957       OpalEndPoint & endpoint,    
00958       PIPSocket::Address binding = PIPSocket::GetDefaultIpAny(), 
00959       WORD port = 0,                           
00960       BOOL reuseAddr = FALSE      
00961     );
00962 
00965     OpalTransportUDP(
00966       OpalEndPoint & endpoint,    
00967       PUDPSocket & socket         
00968     );
00969 
00972     OpalTransportUDP(
00973       OpalEndPoint & endpoint,          
00974       PIPSocket::Address localAddress,  
00975       const PBYTEArray & preReadPacket, 
00976       PIPSocket::Address remoteAddress, 
00977       WORD remotePort                   
00978     );
00979 
00981     ~OpalTransportUDP();
00983 
00986     virtual BOOL Read(
00987       void * buffer,
00988       PINDEX length
00989     );
00990 
00993     virtual BOOL Close();
00995 
01000     virtual BOOL IsReliable() const;
01001 
01004     virtual BOOL IsCompatibleTransport(
01005       const OpalTransportAddress & address
01006     ) const;
01007 
01015     virtual BOOL Connect();
01016 
01024     virtual void EndConnect(
01025       const OpalTransportAddress & localAddress  
01026     );
01027 
01032     virtual BOOL SetLocalAddress(
01033       const OpalTransportAddress & address
01034     );
01035 
01041     virtual BOOL SetRemoteAddress(
01042       const OpalTransportAddress & address
01043     );
01044 
01056     virtual void SetPromiscuous(
01057       PromisciousModes promiscuous
01058     );
01059 
01064     virtual OpalTransportAddress GetLastReceivedAddress() const;
01065 
01071     virtual BOOL ReadPDU(
01072       PBYTEArray & packet   
01073     );
01074 
01080     virtual BOOL WritePDU(
01081       const PBYTEArray & pdu     
01082     );
01083 
01094     virtual BOOL WriteConnect(
01095       WriteConnectCallback function,  
01096       void * userData                 
01097     );
01099 
01100 
01101   protected:
01104     virtual const char * GetProtoPrefix() const;
01105 
01106     PromisciousModes     promiscuousReads;
01107     OpalTransportAddress lastReceivedAddress;
01108     BOOL                 socketOwnedByListener;
01109     PBYTEArray           preReadPacket;
01110     PMutex               connectSocketsMutex;
01111     PSocketList          connectSockets;
01112     BOOL                 reuseAddressFlag;
01113 };
01114 
01115 
01116 #endif  // __OPAL_TRANSPORT_H
01117 
01118 
01119 // End of File ///////////////////////////////////////////////////////////////

Generated on Fri Jan 25 01:20:19 2008 for OPAL by  doxygen 1.5.4