vendor/github.com/google/gopacket/layers/doc.go

   1 // Copyright 2012 Google, Inc. All rights reserved.
   2 //
   3 // Use of this source code is governed by a BSD-style license
   4 // that can be found in the LICENSE file in the root of the source
   5 // tree.
   6
   7 /*
   8 Package layers provides decoding layers for many common protocols.
   9
  10 The layers package contains decode implementations for a number of different
  11 types of packet layers.  Users of gopacket will almost always want to also use
  12 layers to actually decode packet data into useful pieces. To see the set of
  13 protocols that gopacket/layers is currently able to decode,
  14 look at the set of LayerTypes defined in the Variables sections. The
  15 layers package also defines endpoints for many of the common packet layers
  16 that have source/destination addresses associated with them, for example IPv4/6
  17 (IPs) and TCP/UDP (ports).
  18 Finally, layers contains a number of useful enumerations (IPProtocol,
  19 EthernetType, LinkType, PPPType, etc...).  Many of these implement the
  20 gopacket.Decoder interface, so they can be passed into gopacket as decoders.
  21
  22 Most common protocol layers are named using acronyms or other industry-common
  23 names (IPv4, TCP, PPP).  Some of the less common ones have their names expanded
  24 (CiscoDiscoveryProtocol).
  25 For certain protocols, sub-parts of the protocol are split out into their own
  26 layers (SCTP, for example).  This is done mostly in cases where portions of the
  27 protocol may fulfill the capabilities of interesting layers (SCTPData implements
  28 ApplicationLayer, while base SCTP implements TransportLayer), or possibly
  29 because splitting a protocol into a few layers makes decoding easier.
  30
  31 This package is meant to be used with its parent,
  32 http://github.com/google/gopacket.
  33
  34 Port Types
  35
  36 Instead of using raw uint16 or uint8 values for ports, we use a different port
  37 type for every protocol, for example TCPPort and UDPPort.  This allows us to
  38 override string behavior for each port, which we do by setting up port name
  39 maps (TCPPortNames, UDPPortNames, etc...).  Well-known ports are annotated with
  40 their protocol names, and their String function displays these names:
  41
  42   p := TCPPort(80)
  43   fmt.Printf("Number: %d  String: %v", p, p)
  44   // Prints: "Number: 80  String: 80(http)"
  45
  46 Modifying Decode Behavior
  47
  48 layers links together decoding through its enumerations.  For example, after
  49 decoding layer type Ethernet, it uses Ethernet.EthernetType as its next decoder.
  50 All enumerations that act as decoders, like EthernetType, can be modified by
  51 users depending on their preferences.  For example, if you have a spiffy new
  52 IPv4 decoder that works way better than the one built into layers, you can do
  53 this:
  54
  55  var mySpiffyIPv4Decoder gopacket.Decoder = ...
  56  layers.EthernetTypeMetadata[EthernetTypeIPv4].DecodeWith = mySpiffyIPv4Decoder
  57
  58 This will make all future ethernet packets use your new decoder to decode IPv4
  59 packets, instead of the built-in decoder used by gopacket.
  60 */
  61 package layers