include/ptlib/tcpsock.h

   1 /*
   2  * tcpsock.h
   3  *
   4  * Transmission Control Protocol socket channel class.
   5  *
   6  * Portable Windows Library
   7  *
   8  * Copyright (c) 1993-1998 Equivalence Pty. Ltd.
   9  *
  10  * The contents of this file are subject to the Mozilla Public License
  11  * Version 1.0 (the "License"); you may not use this file except in
  12  * compliance with the License. You may obtain a copy of the License at
  13  * http://www.mozilla.org/MPL/
  14  *
  15  * Software distributed under the License is distributed on an "AS IS"
  16  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
  17  * the License for the specific language governing rights and limitations
  18  * under the License.
  19  *
  20  * The Original Code is Portable Windows Library.
  21  *
  22  * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
  23  *
  24  * Portions are Copyright (C) 1993 Free Software Foundation, Inc.
  25  * All Rights Reserved.
  26  *
  27  * Contributor(s): ______________________________________.
  28  *
  29  * $Log$
  30  * Revision 1.30  2003/09/17 05:41:59  csoutheren
  31  * Removed recursive includes
  32  *
  33  * Revision 1.29  2003/09/17 01:18:02  csoutheren
  34  * Removed recursive include file system and removed all references
  35  * to deprecated coooperative threading support
  36  *
  37  * Revision 1.28  2002/10/08 12:41:51  robertj
  38  * Changed for IPv6 support, thanks Sébastien Josset.
  39  *
  40  * Revision 1.27  2002/09/16 01:08:59  robertj
  41  * Added #define so can select if #pragma interface/implementation is used on
  42  *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
  43  *
  44  * Revision 1.26  2001/05/22 12:49:32  robertj
  45  * Did some seriously wierd rewrite of platform headers to eliminate the
  46  *   stupid GNU compiler warning about braces not matching.
  47  *
  48  * Revision 1.25  1999/09/28 00:08:59  robertj
  49  * Fixed some comment typoes
  50  *
  51  * Revision 1.24  1999/09/28 00:07:54  robertj
  52  * Fixed some comment typoes
  53  *
  54  * Revision 1.23  1999/08/30 02:21:03  robertj
  55  * Added ability to listen to specific interfaces for IP sockets.
  56  *
  57  * Revision 1.22  1999/03/09 02:59:51  robertj
  58  * Changed comments to doc++ compatible documentation.
  59  *
  60  * Revision 1.21  1999/02/16 08:11:17  robertj
  61  * MSVC 6.0 compatibility changes.
  62  *
  63  * Revision 1.20  1998/12/22 10:23:08  robertj
  64  * Added clone() function to support SOCKS in FTP style protocols.
  65  *
  66  * Revision 1.19  1998/09/23 06:21:37  robertj
  67  * Added open source copyright license.
  68  *
  69  * Revision 1.18  1998/08/21 05:24:46  robertj
  70  * Fixed bug where write streams out to non-stream socket.
  71  *
  72  * Revision 1.17  1996/09/14 13:09:42  robertj
  73  * Major upgrade:
  74  *   rearranged sockets to help support IPX.
  75  *   added indirect channel class and moved all protocols to descend from it,
  76  *   separating the protocol from the low level byte transport.
  77  *
  78  * Revision 1.16  1996/03/26 00:57:15  robertj
  79  * Added contructor that takes PTCPSocket so avoid copy constructor being used instead of accept.
  80  *
  81  * Revision 1.15  1996/03/03 07:37:59  robertj
  82  * Added Reusability clause to the Listen() function on sockets.
  83  *
  84  * Revision 1.14  1996/02/25 03:01:27  robertj
  85  * Moved some socket functions to platform dependent code.
  86  *
  87  * Revision 1.13  1995/12/10 11:43:34  robertj
  88  * Numerous fixes for sockets.
  89  *
  90  * Revision 1.12  1995/06/17 11:13:31  robertj
  91  * Documentation update.
  92  *
  93  * Revision 1.11  1995/06/17 00:47:31  robertj
  94  * Changed overloaded Open() calls to 3 separate function names.
  95  * More logical design of port numbers and service names.
  96  *
  97  * Revision 1.10  1995/06/04 12:46:25  robertj
  98  * Slight redesign of port numbers on sockets.
  99  *
 100  * Revision 1.9  1995/03/14 12:42:46  robertj
 101  * Updated documentation to use HTML codes.
 102  *
 103  * Revision 1.8  1995/03/12  04:46:40  robertj
 104  * Added more functionality.
 105  *
 106  * Revision 1.7  1995/01/03  09:36:22  robertj
 107  * Documentation.
 108  *
 109  * Revision 1.6  1995/01/01  01:07:33  robertj
 110  * More implementation.
 111  *
 112  * Revision 1.5  1994/08/23  11:32:52  robertj
 113  * Oops
 114  *
 115  * Revision 1.4  1994/08/22  00:46:48  robertj
 116  * Added pragma fro GNU C++ compiler.
 117  *
 118  * Revision 1.3  1994/08/21  23:43:02  robertj
 119  * Changed type of socket port number for better portability.
 120  * Added Out of Band data functions.
 121  *
 122  * Revision 1.2  1994/07/25  03:36:03  robertj
 123  * Added sockets to common, normalising to same comment standard.
 124  *
 125  */
 126
 127 #ifndef _PTCPSOCKET
 128 #define _PTCPSOCKET
 129
 130 #ifdef P_USE_PRAGMA
 131 #pragma interface
 132 #endif
 133
 134
 135 /** A socket that uses the TCP transport on the Internet Protocol.
 136  */
 137 class PTCPSocket : public PIPSocket
 138 {
 139   PCLASSINFO(PTCPSocket, PIPSocket);
 140   public:
 141   /**@name Construction. */
 142   //@{
 143     /**Create a TCP/IP protocol socket channel. If a remote machine address or
 144        a "listening" socket is specified then the channel is also opened.
 145
 146        Note that what looks like a "copy" constructor here is really a
 147        the accept of a "listening" socket the same as the PSocket & parameter
 148        version constructor.
 149      */
 150     PTCPSocket(
 151       WORD port = 0             /// Port number to use for the connection.
 152     );
 153     PTCPSocket(
 154       const PString & service   /// Service name to use for the connection.
 155     );
 156     PTCPSocket(
 157       const PString & address,  /// Address of remote machine to connect to.
 158       WORD port                 /// Port number to use for the connection.
 159     );
 160     PTCPSocket(
 161       const PString & address,  /// Address of remote machine to connect to.
 162       const PString & service   /// Service name to use for the connection.
 163     );
 164     PTCPSocket(
 165       PSocket & socket          /// Listening socket making the connection.
 166     );
 167     PTCPSocket(
 168       PTCPSocket & tcpSocket    /// Listening socket making the connection.
 169     );
 170   //@}
 171
 172   /**@name Overrides from class PObject. */
 173   //@{
 174     /** Create a copy of the class on the heap. The exact semantics of the
 175        descendent class determine what is required to make a duplicate of the
 176        instance. Not all classes can even {\bf do} a clone operation.
 177
 178        The main user of the clone function is the #PDictionary# class as
 179        it requires copies of the dictionary keys.
 180
 181        The default behaviour is for this function to assert.
 182
 183        @return
 184        pointer to new copy of the class instance.
 185      */
 186     virtual PObject * Clone() const;
 187   //@}
 188
 189   /**@name Overrides from class PChannel. */
 190   //@{
 191     /** Low level write to the channel. This function will block until the
 192        requested number of characters are written or the write timeout is
 193        reached. The GetLastWriteCount() function returns the actual number
 194        of bytes written.
 195
 196        The GetErrorCode() function should be consulted after Write() returns
 197        FALSE to determine what caused the failure.
 198
 199        This override repeatedly writes if there is no error until all of the
 200        requested bytes have been written.
 201
 202        @return
 203        TRUE if at least len bytes were written to the channel.
 204      */
 205     virtual BOOL Write(
 206       const void * buf, /// Pointer to a block of memory to write.
 207       PINDEX len        /// Number of bytes to write.
 208     );
 209   //@}
 210
 211   /**@name Overrides from class PSocket. */
 212   //@{
 213     /** Listen on a socket for a remote host on the specified port number. This
 214        may be used for server based applications. A "connecting" socket begins
 215        a connection by initiating a connection to this socket. An active socket
 216        of this type is then used to generate other "accepting" sockets which
 217        establish a two way communications channel with the "connecting" socket.
 218
 219        If the #port# parameter is zero then the port number as
 220        defined by the object instance construction or the
 221        #PIPSocket::SetPort()# function.
 222
 223        @return
 224        TRUE if the channel was successfully opened.
 225      */
 226     virtual BOOL Listen(
 227       unsigned queueSize = 5,  /// Number of pending accepts that may be queued.
 228       WORD port = 0,           /// Port number to use for the connection.
 229       Reusability reuse = AddressIsExclusive /// Can/Can't listen more than once.
 230     );
 231     virtual BOOL Listen(
 232       const Address & bind,     /// Local interface address to bind to.
 233       unsigned queueSize = 5,   /// Number of pending accepts that may be queued.
 234       WORD port = 0,            /// Port number to use for the connection.
 235       Reusability reuse = AddressIsExclusive /// Can/Can't listen more than once.
 236     );
 237
 238     /** Open a socket to a remote host on the specified port number. This is an
 239        "accepting" socket. When a "listening" socket has a pending connection
 240        to make, this will accept a connection made by the "connecting" socket
 241        created to establish a link.
 242
 243        The port that the socket uses is the one used in the #Listen()#
 244        command of the #socket# parameter.
 245
 246        Note that this function will block until a remote system connects to the
 247        port number specified in the "listening" socket.
 248
 249        @return
 250        TRUE if the channel was successfully opened.
 251      */
 252     virtual BOOL Accept(
 253       PSocket & socket          /// Listening socket making the connection.
 254     );
 255   //@}
 256
 257   /**@name New functions for class. */
 258   //@{
 259     /** Write out of band data from the TCP/IP stream. This data is sent as TCP
 260        URGENT data which does not follow the usual stream sequencing of the
 261        normal channel data.
 262
 263        This is subject to the write timeout and sets the
 264        #lastWriteCount# member variable in the same way as usual
 265        #PChannel::Write()# function.
 266
 267        @return
 268        TRUE if all the bytes were sucessfully written.
 269      */
 270     virtual BOOL WriteOutOfBand(
 271       const void * buf,   /// Data to be written as URGENT TCP data.
 272       PINDEX len          /// Number of bytes pointed to by #buf#.
 273     );
 274
 275     /** This is callback function called by the system whenever out of band data
 276        from the TCP/IP stream is received. A descendent class may interpret
 277        this data according to the semantics of the high level protocol.
 278
 279        The default behaviour is for the out of band data to be ignored.
 280      */
 281     virtual void OnOutOfBand(
 282       const void * buf,   /// Data to be received as URGENT TCP data.
 283       PINDEX len          /// Number of bytes pointed to by #buf#.
 284     );
 285   //@}
 286
 287
 288   protected:
 289     // Open an IPv4 socket (for backward compatibility)
 290     virtual BOOL OpenSocket();
 291
 292     // Open an IPv4 or IPv6 socket
 293     virtual BOOL OpenSocket(
 294       int ipAdressFamily
 295     );
 296
 297     virtual const char * GetProtocolName() const;
 298
 299
 300 // Include platform dependent part of class
 301 #ifdef _WIN32
 302 #include "msos/ptlib/tcpsock.h"
 303 #else
 304 #include "unix/ptlib/tcpsock.h"
 305 #endif
 306 };
 307
 308 #endif
 309
 310 // End Of File ///////////////////////////////////////////////////////////////