Added comments and changes for Doxygen compliance
authorAshwin Narayan
Sat, 16 Jul 2011 13:18:48 -0400
changeset 733207a8e2881ec2
parent 7331 9da649b6670f
child 7333 f5584b38c721
Added comments and changes for Doxygen compliance
src/wifi/model/mac-low.h
src/wifi/model/monitor-wifi-mac.cc
src/wifi/model/monitor-wifi-mac.h
src/wifi/model/regular-wifi-mac.h
     1.1 --- a/src/wifi/model/mac-low.h	Sat Jul 16 10:44:13 2011 -0400
     1.2 +++ b/src/wifi/model/mac-low.h	Sat Jul 16 13:18:48 2011 -0400
     1.3 @@ -445,6 +445,7 @@
     1.4     * \param rxSnr snr of packet received
     1.5     * \param txMode transmission mode of packet received
     1.6     * \param preamble type of preamble used for the packet received
     1.7 +   * \param radiotaphdr radiotap header created in YansWifiPhy
     1.8     *
     1.9     * This method is typically invoked by the lower PHY layer to notify
    1.10     * the MAC layer that a packet was successfully received.
     2.1 --- a/src/wifi/model/monitor-wifi-mac.cc	Sat Jul 16 10:44:13 2011 -0400
     2.2 +++ b/src/wifi/model/monitor-wifi-mac.cc	Sat Jul 16 13:18:48 2011 -0400
     2.3 @@ -15,7 +15,8 @@
     2.4   * along with this program; if not, write to the Free Software
     2.5   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
     2.6   *
     2.7 - * Author: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>, Ashwin Narayan <ashwin.narayan89@gmail.com>
     2.8 + * Author: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>, 
     2.9 + *         Ashwin Narayan <ashwin.narayan89@gmail.com>
    2.10   */
    2.11  #include "monitor-wifi-mac.h"
    2.12  
    2.13 @@ -24,6 +25,7 @@
    2.14  #include "ns3/pointer.h"
    2.15  #include "ns3/uinteger.h"
    2.16  #include "ns3/trace-source-accessor.h"
    2.17 +#include "ns3/abort.h"
    2.18  
    2.19  #include "mac-rx-middle.h"
    2.20  #include "mac-tx-middle.h"
    2.21 @@ -50,6 +52,16 @@
    2.22    return tid;
    2.23  }
    2.24  
    2.25 +/*
    2.26 + * Please note that WifiNetDevice::SetMonitorMode () must 
    2.27 + * be invoked for this to work correctly.
    2.28 + *
    2.29 + * Functions that have been inherited but not used have been
    2.30 + * given empty implementations owing to the fact that they 
    2.31 + * are not applicable.
    2.32 + *
    2.33 + */
    2.34 +
    2.35  MonitorWifiMac::MonitorWifiMac ()
    2.36  {
    2.37    NS_LOG_FUNCTION (this);
    2.38 @@ -60,7 +72,7 @@
    2.39  
    2.40    m_low = CreateObject<MacLow> ();
    2.41    m_low->SetRxCallback (MakeCallback (&MacRxMiddle::Receive, m_rxMiddle));
    2.42 -  m_low->SetMonitorMode ();
    2.43 +  m_low->SetMonitorMode (); // Enables Monitor Mode functionality
    2.44  
    2.45    m_dcfManager = new DcfManager ();
    2.46    m_dcfManager->SetupLowListener (m_low);
    2.47 @@ -138,7 +150,7 @@
    2.48  void
    2.49  MonitorWifiMac::SetQosSupported (bool enable)
    2.50  {
    2.51 -  NS_FATAL_ERROR ("QoS Functionality not supported in MonitorWifiMac");
    2.52 +  NS_ABORT_MSG ("QoS Functionality not supported in MonitorWifiMac");
    2.53  }
    2.54  
    2.55  bool
    2.56 @@ -266,40 +278,42 @@
    2.57    return m_low->GetAddress ();
    2.58  }
    2.59  
    2.60 +/**
    2.61 + * Not applicable in Monitor Mode
    2.62 + */
    2.63  void
    2.64  MonitorWifiMac::SetSsid (Ssid ssid)
    2.65  {
    2.66 -  NS_LOG_FUNCTION (this << ssid);
    2.67 -  m_ssid = ssid;
    2.68  }
    2.69 -
    2.70 +/**
    2.71 + * Not applicable in Monitor Mode
    2.72 + */
    2.73  Ssid
    2.74  MonitorWifiMac::GetSsid (void) const
    2.75  {
    2.76    return m_ssid;
    2.77  }
    2.78 -
    2.79 +/**
    2.80 + * Not applicable in Monitor Mode
    2.81 + */
    2.82  void
    2.83  MonitorWifiMac::SetBssid (Mac48Address bssid)
    2.84  {
    2.85 -  NS_LOG_FUNCTION (this << bssid);
    2.86 -  m_low->SetBssid (bssid);
    2.87  }
    2.88 -
    2.89 +/**
    2.90 + * Not applicable in Monitor Mode
    2.91 + */
    2.92  Mac48Address
    2.93  MonitorWifiMac::GetBssid (void) const
    2.94  {
    2.95    return m_low->GetBssid ();
    2.96  }
    2.97 -
    2.98 +/**
    2.99 + * Not applicable in Monitor Mode
   2.100 + */
   2.101  void
   2.102  MonitorWifiMac::SetWifiRemoteStationManager (Ptr<WifiRemoteStationManager> stationManager)
   2.103  {
   2.104 -  NS_LOG_FUNCTION (this << stationManager);
   2.105 -  m_stationManager = stationManager;
   2.106 -  m_low->SetWifiRemoteStationManager (stationManager);
   2.107 -
   2.108 -  m_dca->SetWifiRemoteStationManager (stationManager);
   2.109  }
   2.110  
   2.111  void
   2.112 @@ -317,18 +331,27 @@
   2.113    m_low->SetPromisc ();
   2.114  }
   2.115  
   2.116 +/**
   2.117 + * Not applicable in Monitor Mode
   2.118 + */
   2.119  void
   2.120  MonitorWifiMac::Enqueue (Ptr<const Packet> packet,
   2.121                           Mac48Address to, Mac48Address from)
   2.122  {
   2.123 +  NS_ABORT_MSG ("Not applicable in MonitorMacWifi");
   2.124  }
   2.125 -
   2.126 +/**
   2.127 + * Not applicable in Monitor Mode
   2.128 + */
   2.129  void
   2.130  MonitorWifiMac::Enqueue (Ptr<const Packet> packet,
   2.131                           Mac48Address to)
   2.132  {
   2.133 +  NS_ABORT_MSG ("Not applicable in MonitorMacWifi");
   2.134  }
   2.135 -
   2.136 +/**
   2.137 + * Not applicable in Monitor Mode
   2.138 + */
   2.139  bool
   2.140  MonitorWifiMac::SupportsSendFrom (void) const
   2.141  {
     3.1 --- a/src/wifi/model/monitor-wifi-mac.h	Sat Jul 16 10:44:13 2011 -0400
     3.2 +++ b/src/wifi/model/monitor-wifi-mac.h	Sat Jul 16 13:18:48 2011 -0400
     3.3 @@ -15,7 +15,8 @@
     3.4   * along with this program; if not, write to the Free Software
     3.5   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
     3.6   *
     3.7 - * Author: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>, Ashwin Narayan <ashwin.narayan89@gmail.com>
     3.8 + * Author: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>, 
     3.9 + *         Ashwin Narayan <ashwin.narayan89@gmail.com>
    3.10   */
    3.11  #ifndef MONITOR_WIFI_MAC_H
    3.12  #define MONITOR_WIFI_MAC_H
    3.13 @@ -43,7 +44,28 @@
    3.14   * \brief base class for Monitor Wifi Mac objects.
    3.15   *
    3.16   * This class is essentially a copy of the non-QoS
    3.17 - * functionality of RegularWifiMac
    3.18 + * functionality of RegularWifiMac and serves as an
    3.19 + * abstraction for Monitor mode usage.
    3.20 + *
    3.21 + * This mode is generally used for passive sniffing. 
    3.22 + * The interface receives all packets in its listening 
    3.23 + * channel, even though it may not be destined for it.
    3.24 + * The 802.11 MAC packet contains extra header radiotap 
    3.25 + * which includes physical layer information such as
    3.26 + * received channel, signal quality, signal to noise 
    3.27 + * ratio, antenna scheme, etc. 
    3.28 + *
    3.29 + * The other purpose of monitor mode is packet injection. 
    3.30 + * It is possible to inject random IEEE 802.11 MAC frames 
    3.31 + * using the radiotap header and monitor mode WLAN network 
    3.32 + * interface.
    3.33 + *
    3.34 + * Please note that WifiNetDevice::SetMonitorMode () must 
    3.35 + * be invoked for this to work correctly.
    3.36 + *
    3.37 + * Functions that have been inherited but not used have been
    3.38 + * given empty implementations owing to the fact that they 
    3.39 + * are not applicable.
    3.40   *
    3.41   */
    3.42  
    3.43 @@ -55,34 +77,137 @@
    3.44    MonitorWifiMac ();
    3.45    virtual ~MonitorWifiMac ();
    3.46  
    3.47 +  /**
    3.48 +  * \param slotTime the slot duration
    3.49 +  */
    3.50    void SetSlot (Time slotTime);
    3.51 +  /**
    3.52 +   * \param sifs the sifs duration
    3.53 +   */
    3.54    void SetSifs (Time sifs);
    3.55 +  /**
    3.56 +   * \param eifsNoDifs the duration of an EIFS minus DIFS.
    3.57 +   *
    3.58 +   * This value is used to calculate the EIFS depending
    3.59 +   * on AIFSN.
    3.60 +   */
    3.61    void SetEifsNoDifs (Time eifsNoDifs);
    3.62 +  /**
    3.63 +   * \param pifs the pifs duration.
    3.64 +   */
    3.65    void SetPifs (Time pifs);
    3.66 +  /**
    3.67 +   * \param ctsTimeout the duration of a CTS timeout.
    3.68 +   */
    3.69    void SetCtsTimeout (Time ctsTimeout);
    3.70 +  /**
    3.71 +   * \param ackTimeout the duration of an ACK timeout.
    3.72 +   */
    3.73    void SetAckTimeout (Time ackTimeout);
    3.74 +  /**
    3.75 +   * \returns the current PIFS duration.
    3.76 +   */
    3.77    Time GetPifs (void) const;
    3.78 +  /**
    3.79 +   * \returns the current SIFS duration.
    3.80 +   */ 
    3.81    Time GetSifs (void) const;
    3.82 +  /**
    3.83 +   * \returns the current slot duration.
    3.84 +   */ 
    3.85    Time GetSlot (void) const;
    3.86 +  /**
    3.87 +   * \returns the current EIFS minus DIFS duration
    3.88 +   */  
    3.89    Time GetEifsNoDifs (void) const;
    3.90 +  /**
    3.91 +   * \returns the current CTS timeout duration.
    3.92 +   */
    3.93    Time GetCtsTimeout (void) const;
    3.94 +  /**
    3.95 +   * \returns the current ACK timeout duration.
    3.96 +   */
    3.97    Time GetAckTimeout (void) const;
    3.98 +  /**
    3.99 +   * \returns the MAC address associated to this MAC layer.
   3.100 +   */
   3.101    virtual Mac48Address GetAddress (void) const;
   3.102 +  /**
   3.103 +   * Not applicable in Monitor Mode node
   3.104 +   */
   3.105    virtual Ssid GetSsid (void) const;
   3.106 +  /**
   3.107 +   * \param address the current address of this MAC layer.
   3.108 +   */
   3.109    virtual void SetAddress (Mac48Address address);
   3.110 +  /**
   3.111 +   * Not applicable in Monitor Mode
   3.112 +   */
   3.113    virtual void SetSsid (Ssid ssid);
   3.114 +  /**
   3.115 +   * Not applicable in Monitor Mode
   3.116 +   */
   3.117    virtual void SetBssid (Mac48Address bssid);
   3.118 +  /**
   3.119 +   * Not applicable in Monitor Mode
   3.120 +   */
   3.121    virtual Mac48Address GetBssid (void) const;
   3.122 +  /**
   3.123 +   * \brief Sets the interface in promiscuous mode.
   3.124 +   *
   3.125 +   * Enables promiscuous mode on the interface. Note that any further
   3.126 +   * filtering on the incoming frame path may affect the overall
   3.127 +   * behavior.
   3.128 +   */
   3.129    virtual void SetPromisc (void);
   3.130 +  
   3.131 +  /**
   3.132 +   * Not applicable in Monitor Mode
   3.133 +   */
   3.134    virtual void Enqueue (Ptr<const Packet> packet, Mac48Address to, Mac48Address from);
   3.135 +  /**
   3.136 +   * Not applicable in Monitor Mode
   3.137 +   */
   3.138    virtual bool SupportsSendFrom (void) const;
   3.139 +  /**
   3.140 +   * Not applicable in Monitor Mode
   3.141 +   */
   3.142    virtual void Enqueue (Ptr<const Packet> packet, Mac48Address to);
   3.143 +  /**
   3.144 +   * \param phy the physical layer attached to this MAC.
   3.145 +   */
   3.146    virtual void SetWifiPhy (Ptr<WifiPhy> phy);
   3.147 +  /**
   3.148 +   * \param stationManager the station manager attached to this MAC.
   3.149 +   */
   3.150    virtual void SetWifiRemoteStationManager (Ptr<WifiRemoteStationManager> stationManager);
   3.151 +
   3.152 +  /**
   3.153 +   * This type defines the callback of a higher layer that a
   3.154 +   * WifiMac(-derived) object invokes to pass a packet up the stack.
   3.155 +   *
   3.156 +   * \param packet the packet that has been received.
   3.157 +   * \param from the MAC address of the device that sent the packet.
   3.158 +   * \param to the MAC address ot the device that the packet is
   3.159 +   * destined for.
   3.160 +   */
   3.161    typedef Callback<void, Ptr<Packet>, Mac48Address, Mac48Address> ForwardUpCallback;
   3.162 +  /**
   3.163 +   * \param upCallback the callback to invoke when a packet must be
   3.164 +   * forwarded up the stack.
   3.165 +   */
   3.166    virtual void SetForwardUpCallback (ForwardUpCallback upCallback);
   3.167 +  /**
   3.168 +   * \param linkUp the callback to invoke when the link becomes up.
   3.169 +   */
   3.170    virtual void SetLinkUpCallback (Callback<void> linkUp);
   3.171 +  /**
   3.172 +   * \param linkDown the callback to invoke when the link becomes down.
   3.173 +   */
   3.174    virtual void SetLinkDownCallback (Callback<void> linkDown);
   3.175 +  /* Next functions are not pure virtual so non Qos WifiMacs are not
   3.176 +   * forced to implement them.
   3.177 +   */ 
   3.178    virtual void SetBasicBlockAckTimeout (Time blockAckTimeout);
   3.179    virtual Time GetBasicBlockAckTimeout (void) const;
   3.180    virtual void SetCompressedBlockAckTimeout (Time blockAckTimeout);
   3.181 @@ -106,26 +231,70 @@
   3.182  
   3.183    Ssid m_ssid;
   3.184  
   3.185 +  /** This holds a pointer to the DCF instance for this WifiMac - used
   3.186 +  for transmission of frames to non-QoS peers. */
   3.187    Ptr<DcaTxop> m_dca;
   3.188  
   3.189 +  /**
   3.190 +   * \param standard the phy standard to be used
   3.191 +   *
   3.192 +   * This method is called by ns3::WifiMac::ConfigureStandard to
   3.193 +   * complete the configuration process for a requested phy standard.
   3.194 +   *
   3.195 +   * This method may be overriden by a derived class (e.g., in order
   3.196 +   * to apply DCF parameters specific to the usage model it is
   3.197 +   * dealing with), in which case the reimplementation may choose to
   3.198 +   * deal with certain values in the WifiPhyStandard enumeration, and
   3.199 +   * chain up to this implementation to deal with the remainder.
   3.200 +   */
   3.201    virtual void FinishConfigureStandard (enum WifiPhyStandard standard);
   3.202  
   3.203 +  /**
   3.204 +   * This method acts as the MacRxMiddle receive callback and is
   3.205 +   * invoked to notify us that a frame has been received. The radiotap
   3.206 +   * header is added to the packet here and then sent up the stack after
   3.207 +   * extracting the origin and destination addresses from the MAC header.
   3.208 +   *
   3.209 +   * \param packet the packet that has been received.
   3.210 +   * \param hdr a pointer to the MAC header of the received frame.
   3.211 +   * \param radiotaphdr a pointer to the Radiotap Header of the packet.
   3.212 +   */
   3.213    virtual void Receive (Ptr<Packet> packet, const WifiMacHeader *hdr, const RadiotapHeader *radiotaphdr);
   3.214    virtual void TxOk (const WifiMacHeader &hdr);
   3.215    virtual void TxFailed (const WifiMacHeader &hdr);
   3.216  
   3.217    void ForwardUp (Ptr<Packet> packet, Mac48Address from, Mac48Address to);
   3.218  
   3.219 +  /**
   3.220 +   * Not applicable to Monitor Mode 
   3.221 +   *
   3.222 +   */
   3.223    virtual void DeaggregateAmsduAndForward (Ptr<Packet> aggregatedPacket,
   3.224                                             const WifiMacHeader *hdr);
   3.225 -
   3.226 +  /**
   3.227 +   * Not applicable to Monitor Mode 
   3.228 +   *
   3.229 +   */
   3.230    virtual void SendAddBaResponse (const MgtAddBaRequestHeader *reqHdr,
   3.231                                    Mac48Address originator);
   3.232  
   3.233 +  /**
   3.234 +   * Not applicable to Monitor Mode 
   3.235 +   *
   3.236 +   */
   3.237    bool m_qosSupported;
   3.238 +  /**
   3.239 +   * Not applicable to Monitor Mode 
   3.240 +   *
   3.241 +   */
   3.242    void SetQosSupported (bool enable);
   3.243 +  /**
   3.244 +   * Not applicable to Monitor Mode 
   3.245 +   *
   3.246 +   */
   3.247    bool GetQosSupported () const;
   3.248  private:
   3.249 +  /** Accessor for the DCF object */
   3.250    Ptr<DcaTxop> GetDcaTxop (void) const;
   3.251  
   3.252    TracedCallback<const WifiMacHeader &> m_txOkCallback;
     4.1 --- a/src/wifi/model/regular-wifi-mac.h	Sat Jul 16 10:44:13 2011 -0400
     4.2 +++ b/src/wifi/model/regular-wifi-mac.h	Sat Jul 16 13:18:48 2011 -0400
     4.3 @@ -276,6 +276,7 @@
     4.4     *
     4.5     * \param packet the packet that has been received.
     4.6     * \param hdr a pointer to the MAC header of the received frame.
     4.7 +   * \param radiotaphdr a point to the radiotap header of the packet.
     4.8     */
     4.9    virtual void Receive (Ptr<Packet> packet, const WifiMacHeader *hdr, const RadiotapHeader *radiotaphdr);
    4.10    virtual void TxOk (const WifiMacHeader &hdr);