socket.h

Go to the documentation of this file.

00001 /*
00002  * socket.h
00003  *
00004  * Berkley Socket channel ancestor class.
00005  *
00006  * Portable Windows Library
00007  *
00008  * Copyright (c) 1993-1998 Equivalence Pty. Ltd.
00009  *
00010  * The contents of this file are subject to the Mozilla Public License
00011  * Version 1.0 (the "License"); you may not use this file except in
00012  * compliance with the License. You may obtain a copy of the License at
00013  * http://www.mozilla.org/MPL/
00014  *
00015  * Software distributed under the License is distributed on an "AS IS"
00016  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
00017  * the License for the specific language governing rights and limitations
00018  * under the License.
00019  *
00020  * The Original Code is Portable Windows Library.
00021  *
00022  * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
00023  *
00024  * Portions are Copyright (C) 1993 Free Software Foundation, Inc.
00025  * All Rights Reserved.
00026  *
00027  * Contributor(s): ______________________________________.
00028  *
00029  * $Log: socket.h,v $
00030  * Revision 1.49  2005/11/25 03:43:47  csoutheren
00031  * Fixed function argument comments to be compatible with Doxygen
00032  *
00033  * Revision 1.48  2004/08/24 07:08:13  csoutheren
00034  * Added use of recvmsg to determine which interface UDP packets arrive on
00035  *
00036  * Revision 1.47  2004/05/06 11:28:30  rjongbloed
00037  * Changed P_fd_set to use malloc/free isntead of new/delete due to pedantry about [].
00038  *
00039  * Revision 1.46  2004/04/27 04:37:50  rjongbloed
00040  * Fixed ability to break of a PSocket::Select call under linux when a socket
00041  *   is closed by another thread.
00042  *
00043  * Revision 1.45  2004/01/28 08:53:02  csoutheren
00044  * Fixed missing delete[] operator. Thanks to Borko Jandras
00045  *
00046  * Revision 1.44  2003/09/17 05:41:59  csoutheren
00047  * Removed recursive includes
00048  *
00049  * Revision 1.43  2003/09/17 01:18:02  csoutheren
00050  * Removed recursive include file system and removed all references
00051  * to deprecated coooperative threading support
00052  *
00053  * Revision 1.42  2002/10/18 08:07:41  robertj
00054  * Fixed use of FD_ZERO as (strangely) crashes on some paltforms and would
00055  *   not have cleared enough of an enlarges fd_set anyway.
00056  *
00057  * Revision 1.41  2002/10/17 07:17:42  robertj
00058  * Added ability to increase maximum file handles on a process.
00059  *
00060  * Revision 1.40  2002/09/16 01:08:59  robertj
00061  * Added #define so can select if #pragma interface/implementation is used on
00062  *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
00063  *
00064  * Revision 1.39  2002/04/12 01:42:41  robertj
00065  * Changed return value on os_connect() and os_accept() to make sure
00066  *   get the correct error codes propagated up under unix.
00067  *
00068  * Revision 1.38  2002/02/14 03:34:18  craigs
00069  * Added comment on using SetReadTimeout to set maximum wait for Connect
00070  *
00071  * Revision 1.37  2001/09/06 02:30:17  robertj
00072  * Fixed mismatched declarations, thanks Vjacheslav Andrejev
00073  *
00074  * Revision 1.36  2001/05/22 12:49:32  robertj
00075  * Did some seriously wierd rewrite of platform headers to eliminate the
00076  *   stupid GNU compiler warning about braces not matching.
00077  *
00078  * Revision 1.35  2001/03/20 06:44:25  robertj
00079  * Lots of changes to fix the problems with terminating threads that are I/O
00080  *   blocked, especially when doing orderly shutdown of service via SIGTERM.
00081  *
00082  * Revision 1.34  2000/06/26 13:58:42  robertj
00083  * Nucleus port (again)
00084  *
00085  * Revision 1.33  2000/06/26 11:17:19  robertj
00086  * Nucleus++ port (incomplete).
00087  *
00088  * Revision 1.32  2000/02/18 09:55:21  robertj
00089  * Added parameter so get/setsockopt can have other levels to SOL_SOCKET.
00090  *
00091  * Revision 1.31  1999/03/09 02:59:51  robertj
00092  * Changed comments to doc++ compatible documentation.
00093  *
00094  * Revision 1.30  1999/02/16 08:11:10  robertj
00095  * MSVC 6.0 compatibility changes.
00096  *
00097  * Revision 1.29  1998/11/30 02:51:58  robertj
00098  * New directory structure
00099  *
00100  * Revision 1.28  1998/09/23 06:21:25  robertj
00101  * Added open source copyright license.
00102  *
00103  * Revision 1.27  1998/08/27 00:46:58  robertj
00104  * Resolved signedness problems with various GNU libraries.
00105  *
00106  * Revision 1.26  1998/08/25 14:07:42  robertj
00107  * Added getprotobyxxx wrapper functions.
00108  *
00109  * Revision 1.25  1998/01/26 00:35:21  robertj
00110  * Fixed documentation of PSocket::Select().
00111  *
00112  * Revision 1.24  1996/09/14 13:09:24  robertj
00113  * Major upgrade:
00114  *   rearranged sockets to help support IPX.
00115  *   added indirect channel class and moved all protocols to descend from it,
00116  *   separating the protocol from the low level byte transport.
00117  *
00118  * Revision 1.23  1996/07/27 04:14:00  robertj
00119  * Changed Select() calls to return error codes.
00120  *
00121  * Revision 1.22  1996/05/15 10:11:38  robertj
00122  * Added timeout to accept function.
00123  *
00124  * Revision 1.21  1996/03/31 08:52:36  robertj
00125  * Added socket shutdown function.
00126  *
00127  * Revision 1.20  1996/03/18 13:33:12  robertj
00128  * Fixed incompatibilities to GNU compiler where PINDEX != int.
00129  *
00130  * Revision 1.19  1996/03/03 07:37:58  robertj
00131  * Added Reusability clause to the Listen() function on sockets.
00132  *
00133  * Revision 1.18  1996/03/02 03:10:18  robertj
00134  * Added Apability to get and set Berkeley socket options.
00135  *
00136  * Revision 1.17  1996/02/25 03:02:14  robertj
00137  * Moved some socket functions to platform dependent code.
00138  * Added array of fds to os_select for unix threading support.
00139  *
00140  * Revision 1.16  1996/02/15 14:46:43  robertj
00141  * Added Select() function to PSocket.
00142  *
00143  * Revision 1.15  1995/12/23 03:46:54  robertj
00144  * Fixed portability issue with closingh sockets.
00145  *
00146  * Revision 1.14  1995/12/10 11:35:21  robertj
00147  * Numerous fixes for sockets.
00148  *
00149  * Revision 1.13  1995/10/14 15:05:54  robertj
00150  * Added functions for changing integer from host to network byte order.
00151  *
00152  * Revision 1.12  1995/06/17 11:13:25  robertj
00153  * Documentation update.
00154  *
00155  * Revision 1.11  1995/06/17 00:44:35  robertj
00156  * More logical design of port numbers and service names.
00157  * Changed overloaded Open() calls to 3 separate function names.
00158  *
00159  * Revision 1.10  1995/06/04 12:36:37  robertj
00160  * Slight redesign of port numbers on sockets.
00161  *
00162  * Revision 1.9  1995/03/14 12:42:39  robertj
00163  * Updated documentation to use HTML codes.
00164  *
00165  * Revision 1.8  1995/03/12  04:45:40  robertj
00166  * Added more functionality.
00167  *
00168  * Revision 1.7  1995/01/03  09:36:19  robertj
00169  * Documentation.
00170  *
00171  * Revision 1.6  1995/01/02  12:16:17  robertj
00172  * Moved constructor to platform dependent code.
00173  *
00174  * Revision 1.5  1994/08/23  11:32:52  robertj
00175  * Oops
00176  *
00177  * Revision 1.4  1994/08/22  00:46:48  robertj
00178  * Added pragma fro GNU C++ compiler.
00179  *
00180  * Revision 1.3  1994/08/21  23:43:02  robertj
00181  * Changed type of socket port number for better portability.
00182  *
00183  * Revision 1.2  1994/07/25  03:36:03  robertj
00184  * Added sockets to common, normalising to same comment standard.
00185  *
00186  */
00187 
00188 #ifndef _PSOCKETS
00189 #define _PSOCKETS
00190 
00191 #ifdef P_USE_PRAGMA
00192 #pragma interface
00193 #endif
00194 
00195 #include <ptlib/channel.h>
00196 
00197 #ifdef __NUCLEUS_PLUS__
00198 #include <sys/socket.h>
00199 #endif
00200 
00201 class PSocket;
00202 
00203 PLIST(PSocketList, PSocket);
00204 
00205 
00212 class PSocket : public PChannel
00213 {
00214   PCLASSINFO(PSocket, PChannel);
00215 
00216   protected:
00217     PSocket();
00218 
00219   public:
00232     virtual BOOL Connect(
00233       const PString & address   
00234     );
00235 
00236 
00238     enum Reusability {
00239       CanReuseAddress,
00240       AddressIsExclusive
00241     };
00242 
00256     virtual BOOL Listen(
00257       unsigned queueSize = 5,  
00258       WORD port = 0,           
00259       Reusability reuse = AddressIsExclusive 
00260     );
00261 
00262 
00284     virtual BOOL Accept(
00285       PSocket & socket          
00286     );
00287 
00293     virtual BOOL Shutdown(
00294       ShutdownValue option   
00295     );
00297 
00306     BOOL SetOption(
00307       int option,             
00308       int value,              
00309       int level = SOL_SOCKET  
00310     );
00311 
00318     BOOL SetOption(
00319       int option,             
00320       const void * valuePtr,  
00321       PINDEX valueSize,       
00322       int level = SOL_SOCKET  
00323     );
00324 
00331     BOOL GetOption(
00332       int option,             
00333       int & value,            
00334       int level = SOL_SOCKET  
00335     );
00336 
00343     BOOL GetOption(
00344       int option,             
00345       void * valuePtr,        
00346       PINDEX valueSize,       
00347       int level = SOL_SOCKET  
00348     );
00350 
00358     static WORD GetProtocolByName(
00359       const PString & name      
00360     );
00361 
00367     static PString GetNameByProtocol(
00368       WORD proto                
00369     );
00370 
00371 
00373     virtual WORD GetPortByService(
00374       const PString & service   
00375     ) const;
00393     static WORD GetPortByService(
00394       const char * protocol,     
00395       const PString & service    
00396     );
00397 
00399     virtual PString GetServiceByPort(
00400       WORD port   
00401     ) const;
00419     static PString GetServiceByPort(
00420       const char * protocol,  
00421       WORD port   
00422     );
00423 
00424 
00426     void SetPort(
00427       WORD port   
00428     );
00441     void SetPort(
00442       const PString & service   
00443     );
00444 
00450     WORD GetPort() const;
00451 
00459     PString GetService() const;
00461 
00464 
00465     class SelectList : public PSocketList
00466     {
00467       PCLASSINFO(SelectList, PSocketList)
00468       public:
00469         SelectList()
00470           { DisallowDeleteObjects(); }
00472         void operator+=(PSocket & sock )
00473           { Append(&sock); }
00475         void operator-=(PSocket & sock )
00476           { Remove(&sock); }
00477     };
00478 
00480     static int Select(
00481       PSocket & sock1,        
00482       PSocket & sock2         
00483     );
00485     static int Select(
00486       PSocket & sock1,        
00487       PSocket & sock2,        
00488       const PTimeInterval & timeout 
00489     );
00491     static Errors Select(
00492       SelectList & read       
00493     );
00495     static Errors Select(
00496       SelectList & read,      
00497       const PTimeInterval & timeout 
00498     );
00500     static Errors Select(
00501       SelectList & read,      
00502       SelectList & write      
00503     );
00505     static Errors Select(
00506       SelectList & read,      
00507       SelectList & write,     
00508       const PTimeInterval & timeout 
00509     );
00511     static Errors Select(
00512       SelectList & read,      
00513       SelectList & write,     
00514       SelectList & except     
PString GetNameByProtocol(
00368       WORD proto                
00369     );
00370 
00371 
00373     virtual WORD GetPortByService(
00374       const PString & service   
00375     ) const;
00393     static WORD GetPortByService(
00394       const char * protocol,     
00395       const PString & service    
00396     );
00397 
00399     virtual PString GetServiceByPort(
00400       WORD port   
00401     ) const;
00419     static PString GetServiceByPort(
00420       const char * protocol,  
00421       WORD port   
00422     );
00423 
00424 
00426     void SetPort(
00427       WORD port   
00428     );
00441     void SetPort(
00442       const PString & service   
00443     );
00444 
00450     WORD GetPort() const;
00451 
00459     PString GetService() const;
00461 
00464 
00465     class SelectList : public PSocketList
00466     {
00467       PCLASSINFO(SelectList, PSocketList)
00468       public:
00469         SelectList()
00470           { DisallowDeleteObjects(); }
00472         void operator+=(PSocket & sock )
00473           { Append(&sock); }
00475         void operator-=(PSocket & sock )
00476           { Remove(&sock); }
00477     };
00478 
00480     static int Select(
00481       PSocket & sock1,        
00482       PSocket & sock2         
00483     );
00485     static int Select(
00486       PSocket & sock1,        
00487       PSocket & sock2,        
00488       const PTimeInterval & timeout 
00489     );
00491     static Errors Select(
00492       SelectList & read       
00493     );
00495     static Errors Select(
00496       SelectList & read,      
00497       const PTimeInterval & timeout 
00498     );
00500     static Errors Select(
00501       SelectList & read,      
00502       SelectList & write      
00503     );
00505     static Errors Select(
00506       SelectList & read,      
00507       SelectList & write,     
00508       const PTimeInterval & timeout 
00509     );
00511     static Errors Select(
00512       SelectList & read,      
00513       SelectList & write,     
00514       SelectList & except     
PString GetNameByProtocol(
00368       WORD proto                
00369     );
00370 
00371 
00373     virtual WORD GetPortByService(
00374       const PString & service   
00375     ) const;
00393     static WORD GetPortByService(
00394       const char * protocol,     
00395       const PString & service    
00396     );
00397 
00399     virtual PString GetServiceByPort(
00400       WORD port   
00401     ) const;
00419     static PString GetServiceByPort(
00420       const char * protocol,  
00421       WORD port   
00422     );
00423 
00424 
00426     void SetPort(
00427       WORD port   
00428     );
00441     void SetPort(
00442       const PString & service   
00443     );
00444 
00450     WORD GetPort() const;
00451 
00459     PString GetService() const;
00461 
00464 
00465     class SelectList : public PSocketList
00466     {
00467       PCLASSINFO(SelectList, PSocketList)
00468       public:
00469         SelectList()
00470           { DisallowDeleteObjects(); }
00472         void operator+=(PSocket & sock )
00473           { Append(&sock); }
00475         void operator-=(PSocket & sock )
00476           { Remove(&sock); }
00477     };
00478 
00480     static int Select(
00481       PSocket & sock1,        
00482       PSocket & sock2         
00483     );
00485     static int Select(
00486       PSocket & sock1,        
00487       PSocket & sock2,        
00488       const PTimeInterval & timeout 
0048