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