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