/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */

/*

 * Copyright (c) 2005, 2006 INRIA

 * Copyright (c) 2009 MIRKO BANCHI

 *

 * This program is free software; you can redistribute it and/or modify

 * it under the terms of the GNU General Public License version 2 as

 * published by the Free Software Foundation;

 *

 * This program is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

 * GNU General Public License for more details.

 *

 * You should have received a copy of the GNU General Public License

 * along with this program; if not, write to the Free Software

 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

 *

 * Authors: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>

 *          Mirko Banchi <mk.banchi@gmail.com>

 */

#ifndef MAC_LOW_H

#define MAC_LOW_H

#include <map>

#include "ns3/object.h"

#include "ns3/nstime.h"

#include "channel-access-manager.h"

#include "block-ack-cache.h"

#include "mac-low-transmission-parameters.h"

#include "qos-utils.h"

#include "wifi-mac-header.h"

#include "wifi-tx-vector.h"

#include "block-ack-type.h"

#include "wifi-mpdu-type.h"

class TwoLevelAggregationTest;

class AmpduAggregationTest;

namespace ns3 {

class WifiPhy;

class Txop;

class QosTxop;

class WifiMacQueueItem;

class WifiMacQueue;

class BlockAckAgreement;

class MgtAddBaResponseHeader;

class WifiRemoteStationManager;

class CtrlBAckRequestHeader;

class CtrlBAckResponseHeader;

/**

 * \ingroup wifi

 * \brief handle RTS/CTS/DATA/ACK transactions.

 */

class MacLow : public Object

{

public:

  /// Allow test cases to access private members

  friend class ::TwoLevelAggregationTest;

  /// Allow test cases to access private members

  friend class ::AmpduAggregationTest;

  /**

   * typedef for a callback for MacLowRx

   */

  typedef Callback<void, Ptr<Packet>, const WifiMacHeader*> MacLowRxCallback;

  MacLow ();

  virtual ~MacLow ();

  /**

   * Register this type.

   * \return The TypeId.

   */

  static TypeId GetTypeId (void);

  /**

   * Set up WifiPhy associated with this MacLow.

   *

   * \param phy WifiPhy associated with this MacLow

   */

  void SetPhy (const Ptr<WifiPhy> phy);

  /**

   * \return current attached PHY device

   */

  Ptr<WifiPhy> GetPhy (void) const;

  /**

   * Remove WifiPhy associated with this MacLow.

   */

  void ResetPhy (void);

  /**

   * Set up WifiRemoteStationManager associated with this MacLow.

   *

   * \param manager WifiRemoteStationManager associated with this MacLow

   */

  void SetWifiRemoteStationManager (const Ptr<WifiRemoteStationManager> manager);

  /**

   * Set MAC address of this MacLow.

   *

   * \param ad Mac48Address of this MacLow

   */

  void SetAddress (Mac48Address ad);

  /**

   * Set ACK timeout of this MacLow.

   *

   * \param ackTimeout ACK timeout of this MacLow

   */

  void SetAckTimeout (Time ackTimeout);

  /**

   * Set Basic Block ACK timeout of this MacLow.

   *

   * \param blockAckTimeout Basic Block ACK timeout of this MacLow

   */

  void SetBasicBlockAckTimeout (Time blockAckTimeout);

  /**

   * Set Compressed Block ACK timeout of this MacLow.

   *

   * \param blockAckTimeout Compressed Block ACK timeout of this MacLow

   */

  void SetCompressedBlockAckTimeout (Time blockAckTimeout);

  /**

   * Enable or disable CTS-to-self capability.

   *

   * \param enable Enable or disable CTS-to-self capability

   */

  void SetCtsToSelfSupported (bool enable);

  /**

   * Set CTS timeout of this MacLow.

   *

   * \param ctsTimeout CTS timeout of this MacLow

   */

  void SetCtsTimeout (Time ctsTimeout);

  /**

   * Set Short Interframe Space (SIFS) of this MacLow.

   *

   * \param sifs SIFS of this MacLow

   */

  void SetSifs (Time sifs);

  /**

   * Set Reduced Interframe Space (RIFS) of this MacLow.

   *

   * \param rifs RIFS of this MacLow

   */

  void SetRifs (Time rifs);

  /**

   * Set slot duration of this MacLow.

   *

   * \param slotTime slot duration of this MacLow

   */

  void SetSlotTime (Time slotTime);

  /**

   * Set PCF Interframe Space (PIFS) of this MacLow.

   *

   * \param pifs PIFS of this MacLow

   */

  void SetPifs (Time pifs);

  /**

   * \param interval the expected interval between two beacon transmissions.

   */

  void SetBeaconInterval (Time interval);

  /**

   * \param duration the maximum duration for the CF period.

   */

  void SetCfpMaxDuration (Time duration);

  /**

   * Set the Basic Service Set Identification.

   *

   * \param ad the BSSID

   */

  void SetBssid (Mac48Address ad);

  /**

   * Enable promiscuous mode.

   */

  void SetPromisc (void);

  /**

   * Return whether CTS-to-self capability is supported.

   *

   * \return true if CTS-to-self is supported, false otherwise

   */

  bool GetCtsToSelfSupported () const;

  /**

   * Return the MAC address of this MacLow.

   *

   * \return Mac48Address of this MacLow

   */

  Mac48Address GetAddress (void) const;

  /**

   * Return ACK timeout of this MacLow.

   *

   * \return ACK timeout

   */

  Time GetAckTimeout (void) const;

  /**

   * Return Basic Block ACK timeout of this MacLow.

   *

   * \return Basic Block ACK timeout

   */

  Time GetBasicBlockAckTimeout () const;

  /**

   * Return Compressed Block ACK timeout of this MacLow.

   *

   * \return Compressed Block ACK timeout

   */

  Time GetCompressedBlockAckTimeout () const;

  /**

   * Return CTS timeout of this MacLow.

   *

   * \return CTS timeout

   */

  Time GetCtsTimeout (void) const;

  /**

   * Return Short Interframe Space (SIFS) of this MacLow.

   *

   * \return SIFS

   */

  Time GetSifs (void) const;

  /**

   * Return slot duration of this MacLow.

   *

   * \return slot duration

   */

  Time GetSlotTime (void) const;

  /**

   * Return PCF Interframe Space (PIFS) of this MacLow.

   *

   * \return PIFS

   */

  Time GetPifs (void) const;

  /**

   * Return Reduced Interframe Space (RIFS) of this MacLow.

   *

   * \return RIFS

   */

  Time GetRifs (void) const;

  /**

   * \return the expected interval between two beacon transmissions.

   */

  Time GetBeaconInterval (void) const;

  /**

   * \return the maximum duration for the CF period.

   */

  Time GetCfpMaxDuration (void) const;

  /**

   * \return the remaining duration for the CF period.

   */

  Time GetRemainingCfpDuration (void) const;

  /**

   * Return the Basic Service Set Identification.

   *

   * \return BSSID

   */

  Mac48Address GetBssid (void) const;

  /**

   * Check if MacLow is operating in promiscuous mode.

   *

   * \return true if MacLow is operating in promiscuous mode,

   *         false otherwise

   */

  bool IsPromisc (void) const;

  /**

   * \param callback the callback which receives every incoming packet.

   *

   * This callback typically forwards incoming packets to

   * an instance of ns3::MacRxMiddle.

   */

  void SetRxCallback (Callback<void,Ptr<Packet>,const WifiMacHeader *> callback);

  /**

   * \param dcf listen to NAV events for every incoming and outgoing packet.

   */

  void RegisterDcf (Ptr<ChannelAccessManager> dcf);

  /**

   * \param packet to send (does not include the 802.11 MAC header and checksum)

   * \param hdr header associated to the packet to send.

   * \param parameters transmission parameters of packet.

   * \return the transmission time that includes the time for the next packet transmission

   *

   * This transmission time includes the time required for

   * the next packet transmission if one was selected.

   */

  Time CalculateTransmissionTime (Ptr<const Packet> packet,

                                  const WifiMacHeader* hdr,

                                  const MacLowTransmissionParameters& parameters) const;

  /**

   * \param packet to send (does not include the 802.11 MAC header and checksum)

   * \param hdr header associated to the packet to send.

   * \param params transmission parameters of packet.

   * \param fragmentSize the packet fragment size (if fragmentation is used)

   * \return the transmission time that includes the time for the next packet transmission

   *

   * This transmission time includes the time required for

   * the next packet transmission if one was selected.

   */

  Time CalculateOverallTxTime (Ptr<const Packet> packet,

                               const WifiMacHeader* hdr,

                               const MacLowTransmissionParameters& params,

                               uint32_t fragmentSize = 0) const;

  /**

   * \param packet packet to send

   * \param hdr 802.11 header for packet to send

   * \param parameters the transmission parameters to use for this packet.

   * \param txop pointer to the calling Txop.

   *

   * Start the transmission of the input packet and notify the listener

   * of transmission events.

   */

  virtual void StartTransmission (Ptr<const Packet> packet,

                                  const WifiMacHeader* hdr,

                                  MacLowTransmissionParameters parameters,

                                  Ptr<Txop> txop);

  /**

   * \param packet packet received

   * \param rxSnr snr of packet received

   * \param txVector TXVECTOR of packet received

   * \param ampduSubframe true if this MPDU is part of an A-MPDU

   *

   * This method is typically invoked by the lower PHY layer to notify

   * the MAC layer that a packet was successfully received.

   */

  void ReceiveOk (Ptr<Packet> packet, double rxSnr, WifiTxVector txVector, bool ampduSubframe);

  /**

   * \param packet packet received.

   * \param rxSnr snr of packet received.

   *

   * This method is typically invoked by the lower PHY layer to notify

   * the MAC layer that a packet was unsuccessfully received.

   */

  void ReceiveError (Ptr<Packet> packet, double rxSnr);

  /**

   * \param duration switching delay duration.

   *

   * This method is typically invoked by the PhyMacLowListener to notify

   * the MAC layer that a channel switching occurred. When a channel switching

   * occurs, pending MAC transmissions (RTS, CTS, DATA and ACK) are cancelled.

   */

  void NotifySwitchingStartNow (Time duration);

  /**

   * This method is typically invoked by the PhyMacLowListener to notify

   * the MAC layer that the device has been put into sleep mode. When the device is put

   * into sleep mode, pending MAC transmissions (RTS, CTS, DATA and ACK) are cancelled.

   */

  void NotifySleepNow (void);

  /**

   * This method is typically invoked by the PhyMacLowListener to notify

   * the MAC layer that the device has been put into off mode. When the device is put

   * into off mode, pending MAC transmissions (RTS, CTS, DATA and ACK) are cancelled.

   */

  void NotifyOffNow (void);

  /**

   * \param respHdr Add block ack response from originator (action

   * frame).

   * \param originator Address of peer station involved in block ack

   * mechanism.

   * \param startingSeq Sequence number of the first MPDU of all

   * packets for which block ack was negotiated.

   *

   * This function is typically invoked only by ns3::RegularWifiMac

   * when the STA (which may be non-AP in ESS, or in an IBSS) has

   * received an ADDBA Request frame and is transmitting an ADDBA

   * Response frame. At this point MacLow must allocate buffers to

   * collect all correctly received packets belonging to the category

   * for which Block Ack was negotiated.

   */

  void CreateBlockAckAgreement (const MgtAddBaResponseHeader *respHdr,

                                Mac48Address originator,

                                uint16_t startingSeq);

  /**

   * \param originator Address of peer participating in Block Ack mechanism.

   * \param tid TID for which Block Ack was created.

   *

   * Checks if exists an established block ack agreement with <i>originator</i>

   * for tid <i>tid</i>. If the agreement exists, tears down it. This function is typically

   * invoked when a DELBA frame is received from <i>originator</i>.

   */

  void DestroyBlockAckAgreement (Mac48Address originator, uint8_t tid);

  /**

   * \param ac Access class managed by the queue.

   * \param edca the QosTxop for the queue.

   *

   * The lifetime of the registered QosTxop is typically equal to the lifetime of the queue

   * associated to this AC.

   */

  void RegisterEdcaForAc (AcIndex ac, Ptr<QosTxop> edca);

  /**

   * \param packet the packet to be aggregated. If the aggregation is successful, it corresponds either to the first data packet that will be aggregated or to the BAR that will be piggybacked at the end of the A-MPDU.

   * \param hdr the WifiMacHeader for the packet.

   * \return the A-MPDU packet if aggregation is successful, the input packet otherwise

   *

   * This function adds the packets that will be added to an A-MPDU to an aggregate queue

   *

   */

  Ptr<Packet> AggregateToAmpdu (Ptr<const Packet> packet, const WifiMacHeader hdr);

  /**

   * \param aggregatedPacket which is the current A-MPDU

   * \param rxSnr snr of packet received

   * \param txVector TXVECTOR of packet received

   *

   * This function de-aggregates an A-MPDU and decide if each MPDU is received correctly or not

   *

   */

  void DeaggregateAmpduAndReceive (Ptr<Packet> aggregatedPacket, double rxSnr, WifiTxVector txVector);

  /**

   * \param peekedPacket the packet to be aggregated

   * \param peekedHdr the WifiMacHeader for the packet.

   * \param aggregatedPacket the current A-MPDU

   * \param blockAckSize the size of a piggybacked block ack request

   * \return false if the given packet can be added to an A-MPDU, true otherwise

   *

   * This function decides if a given packet can be added to an A-MPDU or not

   *

   */

  bool StopMpduAggregation (Ptr<const Packet> peekedPacket, WifiMacHeader peekedHdr, Ptr<Packet> aggregatedPacket, uint8_t blockAckSize) const;

  /**

   *

   * This function is called to flush the aggregate queue, which is used for A-MPDU

   * \param tid the Traffic ID

   *

   */

  void FlushAggregateQueue (uint8_t tid);

  /**

   * Return a TXVECTOR for the DATA frame given the destination.

   * The function consults WifiRemoteStationManager, which controls the rate

   * to different destinations.

   *

   * \param packet the packet being asked for TXVECTOR

   * \param hdr the WifiMacHeader

   * \return TXVECTOR for the given packet

   */

  virtual WifiTxVector GetDataTxVector (Ptr<const Packet> packet, const WifiMacHeader *hdr) const;

  /**

   * Start NAV with the given duration.

   *

   * \param duration the duration

   * \return true if NAV is reset

   */

  bool DoNavStartNow (Time duration);

  /**

   * This function indicates whether it is the CF period.

   */

  virtual bool IsCfPeriod (void) const;

  /**

   * This function decides if a CF frame can be transmitted in the current CFP.

   */

  bool CanTransmitNextCfFrame (void) const;

private:

  /**

   * Cancel all scheduled events. Called before beginning a transmission

   * or switching channel.

   */

  void CancelAllEvents (void);

  /**

   * Return the total CF-END size (including FCS trailer).

   *

   * \return the total CF-END size

   */

  uint32_t GetCfEndSize (void) const;

  /**

   * Forward the packet down to WifiPhy for transmission. This is called for the entire A-MPDu when MPDU aggregation is used.

   *

   * \param packet the packet

   * \param hdr the header

   * \param txVector the transmit vector

   */

  void ForwardDown (Ptr<const Packet> packet, const WifiMacHeader *hdr, WifiTxVector txVector);

  /**

   * Forward the MPDU down to WifiPhy for transmission. This is called for each MPDU when MPDU aggregation is used.

   *

   * \param packet the packet

   * \param txVector the transmit vector

   * \param mpdutype the MPDU type

   */

  void SendMpdu (Ptr<const Packet> packet, WifiTxVector txVector, MpduType mpdutype);

  /**

   * Return a TXVECTOR for the RTS frame given the destination.

   * The function consults WifiRemoteStationManager, which controls the rate