include/ptlib/ipxsock.h

   1 /*
   2  * ipxsock.h
   3  *
   4  * IPX protocol socket I/O 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.12  2005/11/25 03:43:47  csoutheren
  31  * Fixed function argument comments to be compatible with Doxygen
  32  *
  33  * Revision 1.11  2003/09/17 05:41:58  csoutheren
  34  * Removed recursive includes
  35  *
  36  * Revision 1.10  2003/09/17 01:18:02  csoutheren
  37  * Removed recursive include file system and removed all references
  38  * to deprecated coooperative threading support
  39  *
  40  * Revision 1.9  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.8  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.7  1999/03/09 02:59:50  robertj
  49  * Changed comments to doc++ compatible documentation.
  50  *
  51  * Revision 1.6  1999/02/16 08:12:00  robertj
  52  * MSVC 6.0 compatibility changes.
  53  *
  54  * Revision 1.5  1998/11/30 02:50:58  robertj
  55  * New directory structure
  56  *
  57  * Revision 1.4  1998/09/23 06:20:47  robertj
  58  * Added open source copyright license.
  59  *
  60  * Revision 1.3  1996/10/08 13:21:04  robertj
  61  * More IPX implementation.
  62  *
  63  * Revision 1.1  1996/09/14 13:00:56  robertj
  64  * Initial revision
  65  *
  66  */
  67
  68 #ifndef _PIPXSOCKET
  69 #define _PIPXSOCKET
  70
  71 #ifdef P_USE_PRAGMA
  72 #pragma interface
  73 #endif
  74
  75 #include <ptlib/socket.h>
  76
  77
  78 /**This class describes a type of socket that will communicate using the
  79    IPX/SPX protocols.
  80  */
  81 class PIPXSocket : public PSocket
  82 {
  83   PCLASSINFO(PIPXSocket, PSocket);
  84
  85   public:
  86     /**Create a new IPX datagram socket.
  87      */
  88     PIPXSocket(
  89       WORD port = 0       ///< Port number to use for the connection.
  90     );
  91
  92
  93   public:
  94     /** IPX protocol address specification.
  95      */
  96     class Address {
  97       public:
  98         union {
  99           struct {
 100             BYTE b1,b2,b3,b4;
 101           } b;
 102           struct {
 103             WORD w1,s_w2;
 104           } w;
 105           DWORD dw;
 106         } network;
 107         BYTE node[6];
 108
 109         /** Create new, invalid, address. */
 110         Address();
 111         /** Create copy of existing address */
 112         Address(const Address & addr /** Address to copy */);
 113         /** Create address from string representation. */
 114         Address(const PString & str /** String representation of address */);
 115         /** Create address from node and net numbers. */
 116         Address(
 117           DWORD netNum, ///< IPX network number.
 118           const char * nodeNum  ///< IPX node number (MAC address)
 119         );
 120         /** Create copy of existing address */
 121         Address & operator=(const Address & addr /** Address to copy */);
 122         /** Get string representation of IPX address */
 123         operator PString() const;
 124         /** Determine if address is valid. Note that this does not mean that
 125             the host is online.
 126             @return TRUE is address is valid.
 127           */
 128         BOOL IsValid() const;
 129       /** Output string representation of IPX address to stream. */
 130       friend ostream & operator<<(
 131         ostream & strm, ///< Stream to output to
 132         Address & addr  ///< Address to output
 133       ) { return strm << (PString)addr; }
 134     };
 135
 136   /**@name Overrides from class PChannel */
 137   //@{
 138     /**Get the platform and I/O channel type name of the channel. For an
 139        IPX/SPX socket this returns the network number, node number of the
 140        peer the socket is connected to, followed by the socket number it
 141        is connected to.
 142
 143        @return
 144        the name of the channel.
 145      */
 146     virtual PString GetName() const;
 147   //@}
 148
 149
 150   /**@name Overrides from class PSocket */
 151   //@{
 152     /**Connect a socket to a remote host on the port number of the socket.
 153        This is
 154        typically used by the client or initiator of a communications channel.
 155        This connects to a "listening" socket at the other end of the
 156        communications channel.
 157
 158        The port number as defined by the object instance construction or the
 159        #PIPSocket::SetPort()# function.
 160
 161        @return
 162        TRUE if the channel was successfully connected to the remote host.
 163      */
 164     virtual BOOL Connect(
 165       const PString & address   ///< Address of remote machine to connect to.
 166     );
 167     /**Connect a socket to a remote host on the port number of the socket.
 168        This is
 169        typically used by the client or initiator of a communications channel.
 170        This connects to a "listening" socket at the other end of the
 171        communications channel.
 172
 173        The port number as defined by the object instance construction or the
 174        #PIPSocket::SetPort()# function.
 175
 176        @return
 177        TRUE if the channel was successfully connected to the remote host.
 178      */
 179     virtual BOOL Connect(
 180       const Address & address   ///< Address of remote machine to connect to.
 181     );
 182
 183     /**Listen on a socket for a remote host on the specified port number. This
 184        may be used for server based applications. A "connecting" socket begins
 185        a connection by initiating a connection to this socket. An active socket
 186        of this type is then used to generate other "accepting" sockets which
 187        establish a two way communications channel with the "connecting" socket.
 188
 189        If the #port# parameter is zero then the port number as
 190        defined by the object instance construction or the
 191        #PIPSocket::SetPort()# function.
 192
 193        For the UDP protocol, the #queueSize# parameter is ignored.
 194
 195        @return
 196        TRUE if the channel was successfully opened.
 197      */
 198     virtual BOOL Listen(
 199       unsigned queueSize = 5,  ///< Number of pending accepts that may be queued.
 200       WORD port = 0,           ///< Port number to use for the connection.
 201       Reusability reuse = AddressIsExclusive ///< Can/Cant listen more than once.
 202     );
 203   //@}
 204
 205   /**@name Address and name space look up functions */
 206   //@{
 207     /**Get the host name for the host specified server.
 208
 209        @return
 210        Name of the host or IPX number of host.
 211      */
 212     static PString GetHostName(
 213       const Address & addr    ///< Hosts IP address to get name for
 214     );
 215
 216     /**Get the IPX address for the specified host.
 217
 218        @return
 219        TRUE if the IPX number was returned.
 220      */
 221     static BOOL GetHostAddress(
 222       Address & addr    ///< Variable to receive this hosts IP address
 223     );
 224
 225     /**Get the IPX address for the specified host.
 226
 227        @return
 228        TRUE if the IPX number was returned.
 229      */
 230     static BOOL GetHostAddress(
 231       const PString & hostname,
 232       /** Name of host to get address for. This may be either a server name or
 233          an IPX number in "colon" format.
 234        */
 235       Address & addr    ///< Variable to receive hosts IPX address
 236     );
 237
 238     /**Get the IPX/SPX address for the local host.
 239
 240        @return
 241        TRUE if the IPX number was returned.
 242      */
 243     BOOL GetLocalAddress(
 244       Address & addr    ///< Variable to receive hosts IPX address
 245     );
 246
 247     /**Get the IPX/SPX address for the local host.
 248
 249        @return
 250        TRUE if the IPX number was returned.
 251      */
 252     BOOL GetLocalAddress(
 253       Address & addr,    ///< Variable to receive peer hosts IPX address
 254       WORD & port        ///< Variable to receive peer hosts port number
 255     );
 256
 257     /**Get the IPX/SPX address for the peer host the socket is
 258        connected to.
 259
 260        @return
 261        TRUE if the IPX number was returned.
 262      */
 263     BOOL GetPeerAddress(
 264       Address & addr    ///< Variable to receive hosts IPX address
 265     );
 266
 267     /**Get the IPX/SPX address for the peer host the socket is
 268        connected to.
 269
 270        @return
 271        TRUE if the IPX number was returned.
 272      */
 273     BOOL GetPeerAddress(
 274       Address & addr,    ///< Variable to receive peer hosts IPX address
 275       WORD & port        ///< Variable to receive peer hosts port number
 276     );
 277   //@}
 278
 279   /**@name I/O functions */
 280   //@{
 281     /**Sets the packet type for datagrams sent by this socket.
 282
 283        @return
 284        TRUE if the type was successfully set.
 285      */
 286     BOOL SetPacketType(
 287       int type    ///< IPX packet type for this socket.
 288     );
 289
 290     /**Gets the packet type for datagrams sent by this socket.
 291
 292        @return
 293        type of packets or -1 if error.
 294      */
 295     int GetPacketType();
 296
 297
 298     /**Read a datagram from a remote computer.
 299
 300        @return
 301        TRUE if all the bytes were sucessfully written.
 302      */
 303     virtual BOOL ReadFrom(
 304       void * buf,     ///< Data to be written as URGENT TCP data.
 305       PINDEX len,     ///< Number of bytes pointed to by #buf#.
 306       Address & addr, ///< Address from which the datagram was received.
 307       WORD & port     ///< Port from which the datagram was received.
 308     );
 309
 310     /**Write a datagram to a remote computer.
 311
 312        @return
 313        TRUE if all the bytes were sucessfully written.
 314      */
 315     virtual BOOL WriteTo(
 316       const void * buf,   ///< Data to be written as URGENT TCP data.
 317       PINDEX len,         ///< Number of bytes pointed to by #buf#.
 318       const Address & addr, ///< Address to which the datagram is sent.
 319       WORD port           ///< Port to which the datagram is sent.
 320     );
 321   //@}
 322
 323
 324   protected:
 325     virtual BOOL OpenSocket();
 326     virtual const char * GetProtocolName() const;
 327
 328
 329 // Include platform dependent part of class
 330 #ifdef _WIN32
 331 #include "msos/ptlib/ipxsock.h"
 332 #else
 333 #include "unix/ptlib/ipxsock.h"
 334 #endif
 335 };
 336
 337 #endif
 338
 339 // End Of File ///////////////////////////////////////////////////////////////