start documenting the packet class family - explain why deriving from QObject is clever

1 files changed, 50 insertions, 17 deletions

diff --git a/libopie2/opienet/opcap.h b/libopie2/opienet/opcap.h
index 6bf7416..fe88e68 100644
--- a/libopie2/opienet/opcap.h
+++ b/libopie2/opienet/opcap.h
@@ -65,13 +65,55 @@ typedef struct pcap_pkthdr packetheaderstruct;
 class OPacketCapturer;
 class QSocketNotifier;
 
 /*======================================================================================
  * OPacket - A frame on the wire
  *======================================================================================*/
-// FIXME how many OPackets do we've at a time? QObject seams to be a big for that usage
+
+/** @brief A class representing a data frame on the wire.
+ *
+ * The whole family of the packet classes are used when capturing frames from a network.
+ * Most standard network protocols in use share a common architecture, which mostly is
+ * a packet header and then the packet payload. In layered architectures, each lower layer
+ * encapsulates data from its upper layer - that is it
+ * treats the data from its upper layer as payload and prepends an own header to the packet,
+ * which - again - is treated as the payload for the layer below. The figure below is an
+ * example for how such a data frame is composed out of packets, e.g. when sending a mail.
+ *
+ * <pre>
+ *                                                       | User Data |     == Mail Data
+ *                                         | SMTP Header | User Data |     == SMTP
+ *                           | TCP Header  | SMTP Header | User Data |     == TCP
+ *               | IP Header | TCP Header  | SMTP Header | User Data |     == IP
+ *  | MAC Header | IP Header | TCP Header  | SMTP Header | User Data |     == MAC
+ *
+ * </pre>
+ *
+ * The example is trimmed for simplicity, because the MAC (Medium Access Control) layer
+ * also contains a few more levels of encapsulation.
+ * Since the type of the payload is more or less independent from the encapsulating protocol,
+ * the header must be inspected before attempting to decode the payload. Hence, the
+ * encapsulation level varies and can't be deduced without actually looking into the packets.
+ *
+ * For actually working with captured frames, it's useful to identify the packets via names and
+ * insert them into a parent/child - relationship based on the encapsulation. This is why
+ * all packet classes derive from QObject. The amount of overhead caused by the QObject is
+ * not a problem in this case, because we're talking about a theoratical maximum of about
+ * 10 packets per captured frame. We need to stuff them into a searchable list anyway and the
+ * QObject also cares about destroying the sub-, (child-) packets.
+ *
+ * This enables us to perform a simple look for packets of a certain type:
+ * @code
+ * OPacketCapturer* pcap = new OPacketCapturer();
+ * pcap->open( "eth0" );
+ * OPacket* p = pcap->next();
+ * OIPPacket* ip = (OIPPacket*) p->child( "IP" ); // returns 0, if no such child exists
+ * odebug << "got ip packet from " << ip->fromIPAddress().toString() << " to " << ip->toIPAddress().toString() << oendl;
+ *
+ */
+
 class OPacket : public QObject
 {
   Q_OBJECT
 
   public:
     OPacket( int datalink, packetheaderstruct, const unsigned char*, QObject* parent );
@@ -92,13 +134,12 @@ class OPacket : public QObject
 };
 
 /*======================================================================================
  * OEthernetPacket - DLT_EN10MB frame
  *======================================================================================*/
 
-//FIXME same critic as above -zecke
 class OEthernetPacket : public QObject
 {
   Q_OBJECT
 
   public:
     OEthernetPacket( const unsigned char*, const struct ether_header*, QObject* parent = 0 );
@@ -113,13 +154,13 @@ class OEthernetPacket : public QObject
 };
 
 
 /*======================================================================================
  * OWaveLanPacket - DLT_IEEE802_11 frame
  *======================================================================================*/
-//FIXME same
+
 class OWaveLanPacket : public QObject
 {
   Q_OBJECT
 
   public:
     OWaveLanPacket( const unsigned char*, const struct ieee_802_11_header*, QObject* parent = 0 );
@@ -143,13 +184,13 @@ class OWaveLanPacket : public QObject
 };
 
 
 /*======================================================================================
  * OWaveLanManagementPacket - type: management (T_MGMT)
  *======================================================================================*/
-//FIXME same as above -zecke
+
 class OWaveLanManagementPacket : public QObject
 {
   Q_OBJECT
 
   public:
     OWaveLanManagementPacket( const unsigned char*, const struct ieee_802_11_mgmt_header*, OWaveLanPacket* parent = 0 );
@@ -172,13 +213,13 @@ class OWaveLanManagementPacket : public QObject
 };
 
 
 /*======================================================================================
  * OWaveLanManagementSSID
  *======================================================================================*/
-//FIXME is QObject necessary? -zecke
+
 class OWaveLanManagementSSID : public QObject
 {
   Q_OBJECT
 
   public:
     OWaveLanManagementSSID( const unsigned char*, const struct ssid_t*, QObject* parent = 0 );
@@ -190,13 +231,13 @@ class OWaveLanManagementSSID : public QObject
     const struct ssid_t* _data;
 };
 
 /*======================================================================================
  * OWaveLanManagementRates
  *======================================================================================*/
-// FIXME same as above -zecke
+
 class OWaveLanManagementRates : public QObject
 {
   Q_OBJECT
 
   public:
     OWaveLanManagementRates( const unsigned char*, const struct rates_t*, QObject* parent = 0 );
@@ -207,13 +248,12 @@ class OWaveLanManagementRates : public QObject
 };
 
 /*======================================================================================
  * OWaveLanManagementCF
  *======================================================================================*/
 
-//FIXME same....
 class OWaveLanManagementCF : public QObject
 {
   Q_OBJECT
 
   public:
     OWaveLanManagementCF( const unsigned char*, const struct cf_t*, QObject* parent = 0 );
@@ -224,13 +264,12 @@ class OWaveLanManagementCF : public QObject
 };
 
 /*======================================================================================
  * OWaveLanManagementFH
  *======================================================================================*/
 
-//FIXME same
 class OWaveLanManagementFH : public QObject
 {
   Q_OBJECT
 
   public:
     OWaveLanManagementFH( const unsigned char*, const struct fh_t*, QObject* parent = 0 );
@@ -240,13 +279,13 @@ class OWaveLanManagementFH : public QObject
     const struct fh_t* _data;
 };
 
 /*======================================================================================
  * OWaveLanManagementDS
  *======================================================================================*/
-//FIXME same
+
 class OWaveLanManagementDS : public QObject
 {
   Q_OBJECT
 
   public:
     OWaveLanManagementDS( const unsigned char*, const struct ds_t*, QObject* parent = 0 );
@@ -259,13 +298,12 @@ class OWaveLanManagementDS : public QObject
 };
 
 /*======================================================================================
  * OWaveLanManagementTim
  *======================================================================================*/
 
-//FIXME guess what?
 class OWaveLanManagementTim : public QObject
 {
   Q_OBJECT
 
   public:
     OWaveLanManagementTim( const unsigned char*, const struct tim_t*, QObject* parent = 0 );
@@ -276,13 +314,12 @@ class OWaveLanManagementTim : public QObject
 };
 
 /*======================================================================================
  * OWaveLanManagementIBSS
  *======================================================================================*/
 
-//FIXME same as above ( Qobject )
 class OWaveLanManagementIBSS : public QObject
 {
   Q_OBJECT
 
   public:
     OWaveLanManagementIBSS( const unsigned char*, const struct ibss_t*, QObject* parent = 0 );
@@ -325,13 +362,13 @@ class OWaveLanDataPacket : public QObject
     const struct ieee_802_11_data_header* _header;
 };
 
 /*======================================================================================
  * OWaveLanControlPacket - type: control (T_CTRL)
  *======================================================================================*/
-// Qobject needed?
+
 class OWaveLanControlPacket : public QObject
 {
   Q_OBJECT
 
   public:
     OWaveLanControlPacket( const unsigned char*, const struct ieee_802_11_control_header*, OWaveLanPacket* parent = 0 );
@@ -342,31 +379,28 @@ class OWaveLanControlPacket : public QObject
 };
 
 /*======================================================================================
  * OLLCPacket - IEEE 802.2 Link Level Control
  *======================================================================================*/
 
-// QObject needed?
 class OLLCPacket : public QObject
 {
   Q_OBJECT
 
   public:
     OLLCPacket( const unsigned char*, const struct ieee_802_11_802_2_header* data, QObject* parent = 0 );
     virtual ~OLLCPacket();
 
   private:
-  //FIXME how to get that header?
     const struct ieee_802_11_802_2_header* _header;
 };
 
 /*======================================================================================
  * OIPPacket
  *======================================================================================*/
 
-// Qobject as baseclass?
 class OIPPacket : public QObject
 {
   Q_OBJECT
 
   public:
     OIPPacket( const unsigned char*, const struct iphdr*, QObject* parent = 0 );
@@ -387,13 +421,13 @@ class OIPPacket : public QObject
     const struct iphdr* _iphdr;
 };
 
 /*======================================================================================
  * OUDPPacket
  *======================================================================================*/
-// QObject?
+
 class OUDPPacket : public QObject
 {
   Q_OBJECT
 
   public:
     OUDPPacket( const unsigned char*, const struct udphdr*, QObject* parent = 0 );
@@ -407,13 +441,12 @@ class OUDPPacket : public QObject
 };
 
 /*======================================================================================
  * OTCPPacket
  *======================================================================================*/
 
-// Qobect needed?
 class OTCPPacket : public QObject
 {
   Q_OBJECT
 
   public:
     OTCPPacket( const unsigned char*, const struct tcphdr*, QObject* parent = 0 );