include/ptlib/ethsock.h

   1 /*
   2  * ethsock.h
   3  *
   4  * Direct Ethernet 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.17  2004/04/18 04:33:36  rjongbloed
  31  * Changed all operators that return BOOL to return standard type bool. This is primarily
  32  *   for improved compatibility with std STL usage removing many warnings.
  33  *
  34  * Revision 1.16  2003/09/17 05:41:58  csoutheren
  35  * Removed recursive includes
  36  *
  37  * Revision 1.15  2003/09/17 01:18:02  csoutheren
  38  * Removed recursive include file system and removed all references
  39  * to deprecated coooperative threading support
  40  *
  41  * Revision 1.14  2002/09/16 01:08:59  robertj
  42  * Added #define so can select if #pragma interface/implementation is used on
  43  *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
  44  *
  45  * Revision 1.13  2001/10/03 03:15:05  robertj
  46  * Changed to allow use of NULL pointer to indicate address of all zeros.
  47  *
  48  * Revision 1.12  2001/05/22 12:49:32  robertj
  49  * Did some seriously wierd rewrite of platform headers to eliminate the
  50  *   stupid GNU compiler warning about braces not matching.
  51  *
  52  * Revision 1.11  1999/03/09 02:59:49  robertj
  53  * Changed comments to doc++ compatible documentation.
  54  *
  55  * Revision 1.10  1999/02/16 08:07:11  robertj
  56  * MSVC 6.0 compatibility changes.
  57  *
  58  * Revision 1.9  1998/11/20 03:18:24  robertj
  59  * Split rad and write buffers to separate pools.
  60  *
  61  * Revision 1.8  1998/11/19 05:18:21  robertj
  62  * Added route table manipulation functions to PIPSocket class.
  63  *
  64  * Revision 1.7  1998/10/12 09:34:40  robertj
  65  * New method for getting IP addresses of interfaces.
  66  *
  67  * Revision 1.6  1998/09/23 06:20:31  robertj
  68  * Added open source copyright license.
  69  *
  70  * Revision 1.5  1998/09/14 12:27:21  robertj
  71  * Added function to parse type out of ethernet/802.2 frame.
  72  *
  73  * Revision 1.4  1998/08/25 11:06:34  robertj
  74  * Fixed output of PEthSocket::Address variables to streams.
  75  *
  76  * Revision 1.3  1998/08/22 04:07:42  robertj
  77  * Fixed GNU problem with structure packing
  78  *
  79  * Revision 1.2  1998/08/21 05:26:34  robertj
  80  * Fine tuning of interface.
  81  *
  82  * Revision 1.1  1998/08/20 05:46:45  robertj
  83  * Initial revision
  84  *
  85  */
  86
  87 #ifndef _PETHSOCKET
  88 #define _PETHSOCKET
  89
  90 #ifdef P_USE_PRAGMA
  91 #pragma interface
  92 #endif
  93
  94 #include <ptlib/socket.h>
  95
  96 #ifdef _WIN32
  97 class PWin32PacketDriver;
  98 class PWin32SnmpLibrary;
  99 class PWin32PacketBuffer;
 100
 101 PARRAY(PWin32PackBufArray, PWin32PacketBuffer);
 102 #endif
 103
 104 /**This class describes a type of socket that will communicate using
 105    raw ethernet packets.
 106  */
 107 class PEthSocket : public PSocket
 108 {
 109   PCLASSINFO(PEthSocket, PSocket);
 110
 111   public:
 112   /**@name Constructor */
 113   //@{
 114     /**Create a new ethernet packet socket. Some platforms require a set of
 115        buffers to be allocated to avoid losing frequent packets.
 116      */
 117     PEthSocket(
 118       PINDEX nReadBuffers = 8,  /// Number of buffers used for reading.
 119       PINDEX nWriteBuffers = 1, /// Number of buffers used for writing.
 120       PINDEX size = 1514        /// Size of each buffer.
 121     );
 122
 123       /// Close the socket
 124     ~PEthSocket();
 125   //@}
 126
 127
 128   public:
 129 #pragma pack(1)
 130     /** An ethernet MAC Address specification.
 131      */
 132     union Address {
 133       BYTE b[6];
 134       WORD w[3];
 135       struct {
 136         DWORD l;
 137         WORD  s;
 138       } ls;
 139
 140       Address();
 141       Address(const BYTE * addr);
 142       Address(const Address & addr);
 143       Address(const PString & str);
 144       Address & operator=(const Address & addr);
 145       Address & operator=(const PString & str);
 146
 147       bool operator==(const BYTE * eth) const;
 148       bool operator!=(const BYTE * eth) const;
 149       bool operator==(const Address & eth) const { return ls.l == eth.ls.l && ls.s == eth.ls.s; }
 150       bool operator!=(const Address & eth) const { return ls.l != eth.ls.l || ls.s != eth.ls.s; }
 151
 152       operator PString() const;
 153
 154       friend ostream & operator<<(ostream & s, const Address & a)
 155         { return s << (PString)a; }
 156     };
 157
 158     /** An ethernet MAC frame.
 159      */
 160     struct Frame {
 161       Address dst_addr;
 162       Address src_addr;
 163       union {
 164         struct {
 165           WORD type;
 166           BYTE payload[1500];
 167         } ether;
 168         struct {
 169           WORD length;
 170           BYTE dsap;
 171           BYTE ssap;
 172           BYTE ctrl;
 173           BYTE oui[3];
 174           WORD type;
 175           BYTE payload[1492];
 176         } snap;
 177       };
 178
 179       /**Parse the Ethernet Frame to extract the frame type and the address of
 180          the payload. The length should be the original bytes read in the frame
 181          and may be altered to information contained in the frame, if available.
 182        */
 183       void Parse(
 184         WORD & type,      // Type of frame
 185         BYTE * & payload, // Pointer to payload
 186         PINDEX & length   // Length of payload (on input is full frame length)
 187       );
 188     };
 189 #pragma pack()
 190
 191   /**@name Overrides from class PChannel */
 192   //@{
 193     /**Close the channel, shutting down the link to the data source.
 194
 195        @return
 196        TRUE if the channel successfully closed.
 197      */
 198     virtual BOOL Close();
 199
 200     /**Low level read from the channel. This function may block until the
 201        requested number of characters were read or the read timeout was
 202        reached. The GetLastReadCount() function returns the actual number
 203        of bytes read.
 204
 205        The GetErrorCode() function should be consulted after Read() returns
 206        FALSE to determine what caused the failure.
 207
 208        @return
 209        TRUE indicates that at least one character was read from the channel.
 210        FALSE means no bytes were read due to timeout or some other I/O error.
 211      */
 212     virtual BOOL Read(
 213       void * buf,   /// Pointer to a block of memory to receive the read bytes.
 214       PINDEX len    /// Maximum number of bytes to read into the buffer.
 215     );
 216
 217     /**Low level write to the channel. This function will block until the
 218        requested number of characters are written or the write timeout is
 219        reached. The GetLastWriteCount() function returns the actual number
 220        of bytes written.
 221
 222        The GetErrorCode() function should be consulted after Write() returns
 223        FALSE to determine what caused the failure.
 224
 225        @return
 226        TRUE if at least len bytes were written to the channel.
 227      */
 228     virtual BOOL Write(
 229       const void * buf, /// Pointer to a block of memory to write.
 230       PINDEX len        /// Number of bytes to write.
 231     );
 232   //@}
 233
 234   /**@name Overrides from class PSocket */
 235   //@{
 236     /**Connect a socket to an interface. The first form opens an interface by
 237        a name as returned by the EnumInterfaces() function. The second opens
 238        the interface that has the specified MAC address.
 239
 240        @return
 241        TRUE if the channel was successfully connected to the interface.
 242      */
 243     virtual BOOL Connect(
 244       const PString & address   /// Name of interface to connect to.
 245     );
 246
 247     /**This function is illegal and will assert if attempted. You must be
 248        connected to an interface using Connect() to do I/O on the socket.
 249
 250        @return
 251        TRUE if the channel was successfully opened.
 252      */
 253     virtual BOOL Listen(
 254       unsigned queueSize = 5,  /// Number of pending accepts that may be queued.
 255       WORD port = 0,           /// Port number to use for the connection.
 256       Reusability reuse = AddressIsExclusive /// Can/Cant listen more than once.
 257     );
 258   //@}
 259
 260
 261   /**@name Information functions */
 262   //@{
 263     /**Enumerate all the interfaces that are capable of being accessed at the
 264        ethernet level. Begin with index 0, and increment until the function
 265        returns FALSE. The name string returned can be passed, unchanged, to
 266        the Connect() function.
 267
 268        Note that the driver does not need to be open for this function to work.
 269
 270        @return
 271        TRUE if an interface has the index supplied.
 272      */
 273     BOOL EnumInterfaces(
 274       PINDEX idx,      /// Index of interface
 275       PString & name   /// Interface name
 276     );
 277
 278
 279     /**Get the low level MAC address of the open interface.
 280
 281        @return
 282        TRUE if the address is returned, FALSE on error.
 283      */
 284     BOOL GetAddress(
 285       Address & addr   /// Variable to receive the MAC address.
 286     );
 287
 288     /**Get the prime IP number bound to the open interface.
 289
 290        @return
 291        TRUE if the address is returned, FALSE on error.
 292      */
 293     BOOL GetIpAddress(
 294       PIPSocket::Address & addr     /// Variable to receive the IP address.
 295     );
 296
 297     /**Get the prime IP number bound to the open interface.
 298        This also returns the net mask associated with the open interface.
 299
 300        @return
 301        TRUE if the address is returned, FALSE on error.
 302      */
 303     BOOL GetIpAddress(
 304       PIPSocket::Address & addr,    /// Variable to receive the IP address.
 305       PIPSocket::Address & netMask  /// Variable to receive the net mask.
 306     );
 307
 308     /**Enumerate all of the IP addresses and net masks bound to the open
 309        interface. This allows all the addresses to be found on multi-homed
 310        hosts. Begin with index 0 and increment until the function returns
 311        FALSE to enumerate all the addresses.
 312
 313        @return
 314        TRUE if the address is returned, FALSE on error or if there are no more
 315        addresses bound to the interface.
 316      */
 317     BOOL EnumIpAddress(
 318       PINDEX idx,                   /// Index
 319       PIPSocket::Address & addr,    /// Variable to receive the IP address.
 320       PIPSocket::Address & netMask  /// Variable to receive the net mask.
 321     );
 322
 323
 324     /// Medium types for the open interface.
 325     enum MediumTypes {
 326       /// A Loopback Network
 327       MediumLoop,
 328       /// An ethernet Network Interface Card (10base2, 10baseT etc)
 329       Medium802_3,
 330       /// A Wide Area Network (modem etc)
 331       MediumWan,
 332       /// Something else
 333       MediumUnknown,
 334       NumMediumTypes
 335     };
 336     /**Return the type of the interface.
 337
 338        @return
 339        Type enum for the interface, or NumMediumTypes if interface not open.
 340      */
 341     MediumTypes GetMedium();
 342   //@}
 343
 344
 345   /**@name Filtering functions */
 346   //@{
 347     /// Type codes for ethernet frames.
 348     enum EthTypes {
 349       /// All frames (3 is value for Linux)
 350       TypeAll = 3,
 351       /// Internet Protocol
 352       TypeIP  = 0x800,
 353       /// X.25
 354       TypeX25 = 0x805,
 355       /// Address Resolution Protocol
 356       TypeARP = 0x806,
 357       /// Appletalk DDP
 358       TypeAtalk = 0x809B,
 359       /// Appletalk AARP
 360       TypeAARP = 0x80F3,
 361       /// Novell IPX
 362       TypeIPX = 0x8137,
 363       /// Bluebook IPv6
 364       TypeIPv6 = 0x86DD
 365     };
 366
 367     /// Mask filter bits for GetFilter() function.
 368     enum FilterMask {
 369       /// Packets directed at the interface.
 370       FilterDirected     = 0x01,
 371       /// Multicast packets directed at the interface.
 372       FilterMulticast    = 0x02,
 373       /// All multicast packets.
 374       FilterAllMulticast = 0x04,
 375       /// Packets with a broadcast address.
 376       FilterBroadcast    = 0x08,
 377       /// All packets.
 378       FilterPromiscuous  = 0x10
 379     };
 380
 381     /**Get the current filtering criteria for receiving packets.
 382
 383        A bit-wise OR of the FilterMask values will filter packets so that
 384        they do not appear in the Read() function at all.
 385
 386        The type is be the specific frame type to accept. A value of TypeAll
 387        may be used to match all frame types.
 388
 389        @return
 390        A bit mask is returned, a value of 0 indicates an error.
 391      */
 392     BOOL GetFilter(
 393       unsigned & mask,  /// Bits for filtering on address
 394       WORD & type       /// Code for filtering on type.
 395     );
 396
 397     /**Set the current filtering criteria for receiving packets. A bit-wise OR
 398        of the FilterMask values will filter packets so that they do not appear
 399        in the Read() function at all.
 400
 401        The type is be the specific frame type to accept. A value of TypeAll
 402        may be used to match all frame types.
 403
 404        A value of zero for the filter mask is useless and will assert.
 405
 406        @return
 407        TRUE if the address is returned, FALSE on error.
 408      */
 409     BOOL SetFilter(
 410       unsigned mask,       /// Bits for filtering on address
 411       WORD type = TypeAll  /// Code for filtering on type.
 412     );
 413   //@}
 414
 415
 416   /**@name I/O functions */
 417   //@{
 418     /**Reset the interface.
 419      */
 420     BOOL ResetAdaptor();
 421
 422     /**Read a packet from the interface and parse out the information
 423        specified by the parameters. This will automatically adjust for 802.2
 424        and 802.3 ethernet frames.
 425
 426        @return
 427        TRUE if the packet read, FALSE on error.
 428      */
 429     BOOL ReadPacket(
 430       PBYTEArray & buffer,  /// Buffer to receive the raw packet
 431       Address & dest,       /// Destination address of packet
 432       Address & src,        /// Source address of packet
 433       WORD & type,          /// Packet frame type ID
 434       PINDEX & len,         /// Length of payload
 435       BYTE * & payload      /// Pointer into #buffer# of payload.
 436     );
 437   //@}
 438
 439   protected:
 440     virtual BOOL OpenSocket();
 441     virtual const char * GetProtocolName() const;
 442
 443
 444     WORD filterType;  // Remember the set filter frame type
 445
 446
 447 // Include platform dependent part of class
 448 #ifdef _WIN32
 449 #include "msos/ptlib/ethsock.h"
 450 #else
 451 #include "unix/ptlib/ethsock.h"
 452 #endif
 453 };
 454
 455 #endif
 456
 457 // End Of File ///////////////////////////////////////////////////////////////