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  2005/11/30 13:35:26  csoutheren
00029  * Changed tags for Doxygen
00030  *
00031  * Revision 2.18  2005/09/19 20:48:23  dsandras
00032  * Added the "can reuse address" flag to the OpalTransportUDP class.
00033  *
00034  * Revision 2.17  2005/01/16 23:07:33  csoutheren
00035  * Fixed problem with IPv6 INADDR_ANY
00036  *
00037  * Revision 2.16  2004/03/22 11:39:44  rjongbloed
00038  * Fixed problems with correctly terminating the OpalTransportUDP that is generated from
00039  *   an OpalListenerUDP, this should not close the socket or stop the thread.
00040  *
00041  * Revision 2.15  2004/03/13 06:25:52  rjongbloed
00042  * Slight rearrangement of local party name and alias list to beter match common
00043  *   behaviour in ancestor.
00044  * Abstracted local party name for endpoint into ancestor from H.,323.
00045  *
00046  * Revision 2.14  2004/03/11 06:54:27  csoutheren
00047  * Added ability to disable SIP or H.323 stacks
00048  *
00049  * Revision 2.13  2004/02/19 10:47:01  rjongbloed
00050  * Merged OpenH323 version 1.13.1 changes.
00051  *
00052  * Revision 2.12  2003/01/07 04:39:53  robertj
00053  * Updated to OpenH323 v1.11.2
00054  *
00055  * Revision 2.11  2002/11/10 11:33:17  robertj
00056  * Updated to OpenH323 v1.10.3
00057  *
00058  * Revision 1.43  2003/12/29 13:28:45  dominance
00059  * fixed docbook syntax trying to generate LaTeX formula with ip$10.x.x.x.
00060  *
00061  * Revision 1.42  2003/04/10 09:44:55  robertj
00062  * Added associated transport to new GetInterfaceAddresses() function so
00063  *   interfaces can be ordered according to active transport links. Improves
00064  *   interoperability.
00065  * Replaced old listener GetTransportPDU() with GetInterfaceAddresses()
00066  *   and H323SetTransportAddresses() functions.
00067  *
00068  * Revision 1.41  2003/04/10 01:03:25  craigs
00069  * Added functions to access to lists of interfaces
00070  *
00071  * Revision 1.40  2003/03/21 05:24:02  robertj
00072  * Added setting of remote port in UDP transport constructor.
00073  *
00074  * Revision 1.39  2003/02/06 04:29:23  robertj
00075  * Added more support for adding things to H323TransportAddressArrays
00076  *
00077  * Revision 1.38  2002/11/21 06:39:56  robertj
00078  * Changed promiscuous mode to be three way. Fixes race condition in gkserver
00079  *   which can cause crashes or more PDUs to be sent to the wrong place.
00080  *
00081  * Revision 1.37  2002/11/10 08:10:43  robertj
00082  * Moved constants for "well known" ports to better place (OPAL change).
00083  *
00084  * Revision 2.10  2002/09/16 02:52:35  robertj
00085  * Added #define so can select if #pragma interface/implementation is used on
00086  *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
00087  *
00088  * Revision 2.9  2002/09/12 06:58:17  robertj
00089  * Removed protocol prefix strings as static members as has problems with
00090  *   use in DLL environment.
00091  *
00092  * Revision 2.8  2002/09/06 02:41:00  robertj
00093  * Added ability to specify stream or datagram (TCP or UDP) transport is to
00094  * be created from a transport address regardless of the addresses mode.
00095  *
00096  * Revision 2.7  2002/07/01 04:56:31  robertj
00097  * Updated to OpenH323 v1.9.1
00098  *
00099  * Revision 2.6  2002/06/16 23:07:47  robertj
00100  * Fixed several memory leaks, thanks Ted Szoczei
00101  *
00102  * Revision 2.5  2002/04/09 00:12:10  robertj
00103  * Added ability to set the local address on a transport, under some circumstances.
00104  *
00105  * Revision 2.4  2001/11/13 04:29:47  robertj
00106  * Changed OpalTransportAddress CreateTransport and CreateListsner functions
00107  *   to have extra parameter to control local binding of sockets.
00108  *
00109  * Revision 2.3  2001/11/12 05:32:12  robertj
00110  * Added OpalTransportAddress::GetIpAddress when don't need port number.
00111  *
00112  * Revision 2.2  2001/11/09 05:49:47  robertj
00113  * Abstracted UDP connection algorithm
00114  *
00115  * Revision 2.1  2001/11/06 05:40:13  robertj
00116  * Added OpalListenerUDP class to do listener semantics on a UDP socket.
00117  *
00118  * Revision 2.0  2001/07/27 15:48:24  robertj
00119  * Conversion of OpenH323 to Open Phone Abstraction Library (OPAL)
00120  *
00121  */
00122 
00123 #ifndef __OPAL_TRANSPORT_H
00124 #define __OPAL_TRANSPORT_H
00125 
00126 #ifdef P_USE_PRAGMA
00127 #pragma interface
00128 #endif
00129 
00130 #include <opal/buildopts.h>
00131 
00132 #include <ptlib/sockets.h>
00133 
00134 
00135 class OpalEndPoint;
00136 class OpalListener;
00137 class OpalTransport;
00138 class OpalInternalTransport;
00139 
00140 
00142 
00143 class OpalTransportAddress : public PString
00144 {
00145   PCLASSINFO(OpalTransportAddress, PString);
00146   public:
00149     OpalTransportAddress();
00150     OpalTransportAddress(
00151       const char * address,      
00152       WORD port = 0,             
00153       const char * proto = NULL  
00154     );
00155     OpalTransportAddress(
00156       const PString & address,   
00157       WORD port = 0,             
00158       const char * proto = NULL  
00159     );
00160     OpalTransportAddress(
00161       const PIPSocket::Address & ip,
00162       WORD port,
00163       const char * proto = NULL 
00164     );
00166 
00171     BOOL IsEquivalent(
00172       const OpalTransportAddress & address
00173     );
00174 
00178     BOOL GetIpAddress(PIPSocket::Address & ip) const;
00179 
00183     BOOL GetIpAndPort(PIPSocket::Address & ip, WORD & port) const;
00184 
00188     virtual PString GetHostName() const;
00189 
00190     enum BindOptions {
00191       NoBinding,
00192       HostOnly,
00193       FullTSAP,
00194       Streamed,
00195       Datagram,
00196       NumBindOptions
00197     };
00198 
00226     OpalListener * CreateListener(
00227       OpalEndPoint & endpoint,   
00228       BindOptions option         
00229     ) const;
00230 
00258     virtual OpalTransport * CreateTransport(
00259       OpalEndPoint & endpoint,   
00260       BindOptions option = HostOnly 
00261     ) const;
00263 
00264 
00265   protected:
00266     void SetInternalTransport(
00267       WORD port,             
00268       const char * proto     
00269     );
00270 
00271     OpalInternalTransport * transport;
00272 };
00273 
00274 
00275 PDECLARE_ARRAY(OpalTransportAddressArray, OpalTransportAddress)
00276   public:
00277     OpalTransportAddressArray(
00278       const OpalTransportAddress & address
00279     ) { AppendAddress(address); }
00280     OpalTransportAddressArray(
00281       const PStringArray & array
00282     ) { AppendStringCollection(array); }
00283     OpalTransportAddressArray(
00284       const PStringList & list
00285     ) { AppendStringCollection(list); }
00286     OpalTransportAddressArray(
00287       const PSortedStringList & list
00288     ) { AppendStringCollection(list); }
00289 
00290     void AppendString(
00291       const char * address
00292     );
00293     void AppendString(
00294       const PString & address
00295     );
00296     void AppendAddress(
00297       const OpalTransportAddress & address
00298     );
00299 
00300   protected:
00301     void AppendStringCollection(
00302       const PCollection & coll
00303     );
00304 };
00305 
00306 
00307 
00308 
00310 
00323 class OpalListener : public PObject
00324 {
00325     PCLASSINFO(OpalListener, PObject);
00326   public:
00331     OpalListener(
00332       OpalEndPoint & endpoint   
00333     );
00335 
00340     void PrintOn(
00341       ostream & strm
00342     ) const;
00344 
00361     virtual BOOL Open(
00362       const PNotifier & acceptHandler,  
00363       BOOL singleThread = FALSE         
00364     ) = 0;
00365 
00368     virtual BOOL IsOpen() = 0;
00369 
00372     virtual void Close() = 0;
00373 
00376     virtual OpalTransport * Accept(
00377       const PTimeInterval & timeout  
00378     ) = 0;
00379 
00382     virtual OpalTransportAddress GetLocalAddress(
00383       const OpalTransportAddress & preferredAddress = OpalTransportAddress()
00384     ) const = 0;
00385 
00389     OpalTransportAddress GetTransportAddress() const { return GetLocalAddress(); }
00390 
00393     void CloseWait();
00394 
00398     void CleanUpOnTermination() { CloseWait(); }
00400 
00401 
00402   protected:
00411     PDECLARE_NOTIFIER(PThread, OpalListener, ListenForConnections);
00412     BOOL StartThread(
00413       const PNotifier & acceptHandler,  
00414       BOOL singleThread                
00415     );
00416 
00417     OpalEndPoint & endpoint;
00418     PThread      *  thread;
00419     PNotifier      acceptHandler;
00420     BOOL           singleThread;
00421 };
00422 
00423 
00424 PLIST(OpalListenerList, OpalListener);
00425 
00426 
00429 OpalTransportAddressArray OpalGetInterfaceAddresses(
00430   const OpalListenerList & listeners, 
00431   BOOL excludeLocalHost = TRUE,       
00432   OpalTransport * associatedTransport = NULL
00434 );
00435 
00436 OpalTransportAddressArray OpalGetInterfaceAddresses(
00437   const OpalTransportAddress & addr,  
00438   BOOL excludeLocalHost = TRUE,       
00439   OpalTransport * associatedTransport = NULL
00441 );
00442 
00443 
00444 class OpalListenerIP : public OpalListener
00445 {
00446   PCLASSINFO(OpalListenerIP, OpalListener);
00447   public:
00452     OpalListenerIP(
00453       OpalEndPoint & endpoint,                 
00454       PIPSocket::Address binding = PIPSocket::GetDefaultIpAny(), 
00455       WORD port = 0,                           
00456       BOOL exclusive = TRUE
00457     );
00459 
00464     virtual OpalTransportAddress GetLocalAddress(
00465       const OpalTransportAddress & preferredAddress = OpalTransportAddress()
00466     ) const;
00468 
00471     WORD GetListenerPort() const { return listenerPort; }
00472 
00473     virtual const char * GetProtoPrefix() const = 0;
00475 
00476 
00477   protected:
00478     PIPSocket::Address localAddress;
00479     WORD               listenerPort;
00480     BOOL               exclusiveListener;
00481 };
00482 
00483 
00484 class OpalListenerTCP : public OpalListenerIP
00485 {
00486   PCLASSINFO(OpalListenerTCP, OpalListenerIP);
00487   public:
00492     OpalListenerTCP(
00493       OpalEndPoint & endpoint,                 
00494       PIPSocket::Address binding = PIPSocket::GetDefaultIpAny(), 
00495       WORD port = 0,                           
00496       BOOL exclusive = TRUE
00497     );
00498 
00501     ~OpalListenerTCP();
00503 
00526     virtual BOOL Open(
00527       const PNotifier & acceptHandler,  
00528       BOOL singleThread = FALSE         
00529     );
00530 
00533     virtual BOOL IsOpen();
00534 
00537     virtual void Close();
00538 
00541     virtual OpalTransport * Accept(
00542       const PTimeInterval & timeout  
00543     );
00545 
00546 
00547   protected:
00548     virtual const char * GetProtoPrefix() const;
00549 
00550     PTCPSocket listener;
00551 };
00552 
00553 
00554 class OpalListenerUDP : public OpalListenerIP
00555 {
00556   PCLASSINFO(OpalListenerUDP, OpalListenerIP);
00557   public:
00562     OpalListenerUDP(
00563       OpalEndPoint & endpoint,                 
00564       PIPSocket::Address binding = PIPSocket::GetDefaultIpAny(), 
00565       WORD port = 0,                           
00566       BOOL exclusive = TRUE
00567     );
00568 
00571     ~OpalListenerUDP();
00573 
00596     virtual BOOL Open(
00597       const PNotifier & acceptHandler,  
00598       BOOL singleThread = TRUE          
00599     );
00600 
00603     virtual BOOL IsOpen();
00604 
00607     virtual void Close();
00608 
00611     virtual OpalTransport * Accept(
00612       const PTimeInterval & timeout  
00613     );
00615 
00616 
00617   protected:
00618     virtual const char * GetProtoPrefix() const;
00619     BOOL OpenOneSocket(const PIPSocket::Address & address);
00620 
00621     PSocketList listeners;
00622 };
00623 
00624 
00626 
00631 class OpalTransport : public PIndirectChannel
00632 {
00633     PCLASSINFO(OpalTransport, PIndirectChannel);
00634   public:
00639     OpalTransport(OpalEndPoint & endpoint);
00640 
00643     ~OpalTransport();
00645 
00650     void PrintOn(
00651       ostream & strm
00652     ) const;
00654 
00659     virtual BOOL IsReliable() const = 0;
00660 
00663     virtual OpalTransportAddress GetLocalAddress() const = 0;
00664 
00669     virtual BOOL SetLocalAddress(
00670       const OpalTransportAddress & address
00671     ) = 0;
00672 
00675     virtual OpalTransportAddress GetRemoteAddress() const = 0;
00676 
00682     virtual BOOL SetRemoteAddress(
00683       const OpalTransportAddress & address
00684     ) = 0;
00685 
00688     virtual BOOL Connect() = 0;
00689 
00692     BOOL ConnectTo(
00693       const OpalTransportAddress & address
00694     ) { return SetRemoteAddress(address) && Connect(); }
00695 
00702     virtual void EndConnect(
00703       const OpalTransportAddress & localAddress  
00704     );
00705 
00708     virtual BOOL Close();
00709 
00712     void CloseWait();
00713 
00717     void CleanUpOnTermination() { CloseWait(); }
00718 
00721     virtual BOOL IsCompatibleTransport(
00722       const OpalTransportAddress & address
00723     ) const = 0;
00724 
00726     enum PromisciousModes {
00727       AcceptFromRemoteOnly,
00728       AcceptFromAnyAutoSet,
00729       AcceptFromAny,
00730       NumPromisciousModes
00731     };
00732 
00743     virtual void SetPromiscuous(
00744       PromisciousModes promiscuous
00745     );
00746 
00751     virtual OpalTransportAddress GetLastReceivedAddress() const;
00752 
00758     virtual BOOL ReadPDU(
00759       PBYTEArray & packet   
00760     ) = 0;
00761 
00767     virtual BOOL WritePDU(
00768       const PBYTEArray & pdu     
00769     ) = 0;
00770 
00771     typedef BOOL (*WriteConnectCallback)(OpalTransport & transport, void * userData);
00772 
00785     virtual BOOL WriteConnect(
00786       WriteConnectCallback function,  
00787       void * userData                 
00788     );
00789 
00792     virtual void AttachThread(
00793       PThread * thread
00794     );
00795 
00798     virtual BOOL IsRunning() const;
00800 
00801     OpalEndPoint & GetEndPoint() const { return endpoint; }
00802 
00803   protected:
00804     OpalEndPoint & endpoint;
00805     PThread      * thread;      
00806 };
00807 
00808 
00809 class OpalTransportIP : public OpalTransport
00810 {
00811   PCLASSINFO(OpalTransportIP, OpalTransport);
00812   public:
00817     OpalTransportIP(
00818       OpalEndPoint & endpoint,    
00819       PIPSocket::Address binding, 
00820       WORD port                   
00821     );
00823 
00828     virtual OpalTransportAddress GetLocalAddress() const;
00829 
00834     virtual BOOL SetLocalAddress(
00835       const OpalTransportAddress & address
00836     );
00837 
00840     virtual OpalTransportAddress GetRemoteAddress() const;
00841 
00847     virtual BOOL SetRemoteAddress(
00848       const OpalTransportAddress & address
00849     );
00850 
00852 
00853   protected:
00856     virtual const char * GetProtoPrefix() const = 0;
00857 
00858     PIPSocket::Address localAddress;  // Address of the local interface
00859     WORD               localPort;
00860     PIPSocket::Address remoteAddress; // Address of the remote host
00861     WORD               remotePort;
00862 };
00863 
00864 
00865 class OpalTransportTCP : public OpalTransportIP
00866 {
00867     PCLASSINFO(OpalTransportTCP, OpalTransportIP);
00868   public:
00873     OpalTransportTCP(
00874       OpalEndPoint & endpoint,    
00875       PIPSocket::Address binding = INADDR_ANY, 
00876       WORD port = 0,              
00877       BOOL reuseAddr = FALSE      
00878     );
00879     OpalTransportTCP(
00880       OpalEndPoint & endpoint,    
00881       PTCPSocket * socket         
00882     );
00883 
00885     ~OpalTransportTCP();
00887 
00892     virtual BOOL IsReliable() const;
00893 
00896     virtual BOOL IsCompatibleTransport(
00897       const OpalTransportAddress & address
00898     ) const;
00899 
00902     virtual BOOL Connect();
00903 
00909     virtual BOOL ReadPDU(
00910       PBYTEArray & pdu  
00911     );
00912 
00918     virtual BOOL WritePDU(
00919       const PBYTEArray & pdu     
00920     );
00922 
00923 
00924   protected:
00927     virtual const char * GetProtoPrefix() const;
00928 
00938     virtual BOOL OnOpen();
00939 
00940 
00941     BOOL reuseAddressFlag;
00942 };
00943 
00944 
00945 class OpalTransportUDP : public OpalTransportIP
00946 {
00947   PCLASSINFO(OpalTransportUDP, OpalTransportIP);
00948   public:
00953     OpalTransportUDP(
00954       OpalEndPoint & endpoint,    
00955       PIPSocket::Address binding = PIPSocket::GetDefaultIpAny(), 
00956       WORD port = 0,                           
00957       BOOL reuseAddr = FALSE      
00958     );
00959 
00962     OpalTransportUDP(
00963       OpalEndPoint & endpoint,    
00964       PUDPSocket & socket         
00965     );
00966 
00969     OpalTransportUDP(
00970       OpalEndPoint & endpoint,          
00971       PIPSocket::Address localAddress,  
00972       const PBYTEArray & preReadPacket, 
00973       PIPSocket::Address remoteAddress, 
00974       WORD remotePort                   
00975     );
00976 
00978     ~OpalTransportUDP();
00980 
00983     virtual BOOL Read(
00984       void * buffer,
00985       PINDEX length
00986     );
00987 
00990     virtual BOOL Close();
00992 
00997     virtual BOOL IsReliable() const;
00998 
01001     virtual BOOL IsCompatibleTransport(
01002       const OpalTransportAddress & address
01003     ) const;
01004 
01012     virtual BOOL Connect();
01013 
01021     virtual void EndConnect(
01022       const OpalTransportAddress & localAddress  
01023     );
01024 
01029     virtual BOOL SetLocalAddress(
01030       const OpalTransportAddress & address
01031     );
01032 
01038     virtual BOOL SetRemoteAddress(
01039       const OpalTransportAddress & address
01040     );
01041 
01053     virtual void SetPromiscuous(
01054       PromisciousModes promiscuous
01055     );
01056 
01061     virtual OpalTransportAddress GetLastReceivedAddress() const;
01062 
01068     virtual BOOL ReadPDU(
01069       PBYTEArray & packet   
01070     );
01071 
01077     virtual BOOL WritePDU(
01078       const PBYTEArray & pdu     
01079     );
01080 
01091     virtual BOOL WriteConnect(
01092       WriteConnectCallback function,  
01093       void * userData                 
01094     );
01096 
01097 
01098   protected:
01101     virtual const char * GetProtoPrefix() const;
01102 
01103     PromisciousModes     promiscuousReads;
01104     OpalTransportAddress lastReceivedAddress;
01105     BOOL                 socketOwnedByListener;
01106     PBYTEArray           preReadPacket;
01107     PSocketList          connectSockets;
01108     BOOL                 reuseAddressFlag;
01109 };
01110 
01111 
01112 #endif  // __OPAL_TRANSPORT_H
01113 
01114 
01115 // End of File ///////////////////////////////////////////////////////////////

Generated on Mon Sep 25 16:20:12 2006 for OPAL by  doxygen 1.4.7