/* -*- 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

 *

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

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

 */

#ifndef MAC_LOW_H

#define MAC_LOW_H

#include <vector>

#include <stdint.h>

#include <ostream>

#include <map>

#include "wifi-mac-header.h"

#include "wifi-mode.h"

#include "wifi-preamble.h"

#include "wifi-remote-station-manager.h"

#include "ctrl-headers.h"

#include "mgt-headers.h"

#include "block-ack-agreement.h"

#include "ns3/mac48-address.h"

#include "ns3/callback.h"

#include "ns3/event-id.h"

#include "ns3/packet.h"

#include "ns3/nstime.h"

#include "qos-utils.h"

#include "block-ack-cache.h"

#include "wifi-tx-vector.h"

namespace ns3 {

class WifiPhy;

class WifiMac;

class EdcaTxopN;

/**

 * \ingroup wifi

 * \brief listen to events coming from ns3::MacLow.

 */

class MacLowTransmissionListener

{

public:

  MacLowTransmissionListener ();

  virtual ~MacLowTransmissionListener ();

  /**

   * \param snr the snr of the cts

   * \param txMode the txMode of the cts

   *

   * ns3::MacLow received an expected CTS within

   * CtsTimeout.

   */

  virtual void GotCts (double snr, WifiMode txMode) = 0;

  /**

   * ns3::MacLow did not receive an expected CTS

   * within CtsTimeout.

   */

  virtual void MissedCts (void) = 0;

  /**

   * \param snr the snr of the ack

   * \param txMode the transmission mode of the ack

   *

   * ns3::MacLow received an expected ACL within

   * AckTimeout. The <i>snr</i> and <i>txMode</i>

   * arguments are not valid when SUPER_FAST_ACK is

   * used.

   */

  virtual void GotAck (double snr, WifiMode txMode) = 0;

  /**

   * ns3::MacLow did not receive an expected ACK within

   * AckTimeout.

   */

  virtual void MissedAck (void) = 0;

  /**

   * \param blockAck Block ack response header

   * \param source Address of block ack sender

   *

   * Invoked when ns3::MacLow receives a block ack frame.

   * Block ack frame is received after a block ack request

   * and contains information about the correct reception

   * of a set of packet for which a normal ack wasn't send.

   * Default implementation for this method is empty. Every

   * queue that intends to be notified by MacLow of reception

   * of a block ack must redefine this function.

   */

  virtual void GotBlockAck (const CtrlBAckResponseHeader *blockAck, Mac48Address source);

  /**

   * ns3::MacLow did not receive an expected BLOCK_ACK within

   * BlockAckTimeout. This method is used only for immediate

   * block ack variant. With delayed block ack, the MissedAck method will be

   * called instead: upon receipt of a block ack request, the rx station will

   * reply with a normal ack frame. Later, when the rx station gets a txop, it

   * will send the block ack back to the tx station which will reply with a

   * normal ack to the rx station.

   */

  virtual void MissedBlockAck (void);

  /**

   * Invoked when ns3::MacLow wants to start a new transmission

   * as configured by MacLowTransmissionParameters::EnableNextData.

   * The listener is expected to call again MacLow::StartTransmission

   * with the "next" data to send.

   */

  virtual void StartNext (void) = 0;

  /**

   * Invoked if this transmission was canceled

   * one way or another. When this method is invoked,

   * you can assume that the packet has not been passed

   * down the stack to the PHY.

   */

  virtual void Cancel (void) = 0;	

  /** 

   * Invoked upon the end of the transmission of a frame that does not

   * require an ACK (e.g., broadcast and multicast frames).

   * 

   */

  virtual void EndTxNoAck (void) = 0;

};

/**

 * \brief listen to NAV events

 * \ingroup wifi

 *

 * This class is typically connected to an instance of ns3::Dcf

 * and calls to its methods are forwards to the corresponding

 * ns3::Dcf methods.

 */

class MacLowDcfListener

{

public:

  MacLowDcfListener ();

  virtual ~MacLowDcfListener ();

  /**

   * Norify that NAV has started for the given duration.

   *

   * \param duration duration of NAV timer

   */

  virtual void NavStart (Time duration) = 0;

  /**

   * Notify that NAV has resetted.

   *

   * \param duration duration of NAV timer

   */

  virtual void NavReset (Time duration) = 0;

  /**

   * Notify that ACK timeout has started for a given duration.

   *

   * \param duration duration of ACK timeout

   */

  virtual void AckTimeoutStart (Time duration) = 0;

  /**

   * Notify that ACK timeout has resetted.

   */

  virtual void AckTimeoutReset () = 0;

  /**

   * Notify that CTS timeout has started for a given duration.

   *

   * \param duration duration of CTS timeout

   */

  virtual void CtsTimeoutStart (Time duration) = 0;

  /**

   * Notify that CTS timeout has resetted.

   */

  virtual void CtsTimeoutReset () = 0;

};

/**

 * \ingroup wifi

 * \brief listen for block ack events.

 */

class MacLowBlockAckEventListener

{

public:

  MacLowBlockAckEventListener ();

  virtual ~MacLowBlockAckEventListener ();

  /**

   * Typically is called in order to notify EdcaTxopN that a block ack inactivity

   * timeout occurs for the block ack agreement identified by the pair <i>originator</i>, <i>tid</i>.

   *

   * Rx station maintains an inactivity timer for each block ack

   * agreement. Timer is reset when a frame with ack policy block ack

   * or a block ack request are received. When this timer reaches zero

   * this method is called and a delba frame is scheduled for transmission.

   *

   * \param originator MAC address of the data originator

   * \param tid

   */

  virtual void BlockAckInactivityTimeout (Mac48Address originator, uint8_t tid) = 0;

};

/**

 * \brief control how a packet is transmitted.

 * \ingroup wifi

 *

 * The ns3::MacLow::StartTransmission method expects

 * an instance of this class to describe how the packet

 * should be transmitted.

 */

class MacLowTransmissionParameters

{

public:

  MacLowTransmissionParameters ();

  /**

   * Wait ACKTimeout for an ACK. If we get an ACK

   * on time, call MacLowTransmissionListener::GotAck.

   * Call MacLowTransmissionListener::MissedAck otherwise.

   */

  void EnableAck (void);

  /**

   *   - wait PIFS after end-of-tx. If idle, call

   *     MacLowTransmissionListener::MissedAck.

   *   - if busy at end-of-tx+PIFS, wait end-of-rx

   *   - if Ack ok at end-of-rx, call

   *     MacLowTransmissionListener::GotAck.

   *   - if Ack not ok at end-of-rx, report call

   *     MacLowTransmissionListener::MissedAck

   *     at end-of-rx+SIFS.

   *

   * This is really complicated but it is needed for

   * proper HCCA support.

   */

  void EnableFastAck (void);

  /**

   *  - if busy at end-of-tx+PIFS, call

   *    MacLowTransmissionListener::GotAck

   *  - if idle at end-of-tx+PIFS, call

   *    MacLowTransmissionListener::MissedAck

   */

  void EnableSuperFastAck (void);

  /**

   * Wait BASICBLOCKACKTimeout for a Basic Block Ack Response frame.

   */

  void EnableBasicBlockAck (void);

  /**

   * Wait COMPRESSEDBLOCKACKTimeout for a Compressed Block Ack Response frame.

   */

  void EnableCompressedBlockAck (void);

  /**

   * NOT IMPLEMENTED FOR NOW

   */

  void EnableMultiTidBlockAck (void);

  /**

   * Send a RTS, and wait CTSTimeout for a CTS. If we get a

   * CTS on time, call MacLowTransmissionListener::GotCts

   * and send data. Otherwise, call MacLowTransmissionListener::MissedCts

   * and do not send data.

   */

  void EnableRts (void);

  /**

   * \param size size of next data to send after current packet is

   *        sent.

   *

   * Add the transmission duration of the next data to the

   * durationId of the outgoing packet and call

   * MacLowTransmissionListener::StartNext at the end of

   * the current transmission + SIFS.

   */

  void EnableNextData (uint32_t size);

  /**

   * \param durationId the value to set in the duration/Id field of

   *        the outgoing packet.

   *

   * Ignore all other durationId calculation and simply force the

   * packet's durationId field to this value.

   */

  void EnableOverrideDurationId (Time durationId);

  /**

   * Do not wait for Ack after data transmission. Typically

   * used for Broadcast and multicast frames.

   */

  void DisableAck (void);

  /**

   * Do not send rts and wait for cts before sending data.

   */

  void DisableRts (void);

  /**

   * Do not attempt to send data burst after current transmission

   */

  void DisableNextData (void);

  /**

   * Do not force the duration/id field of the packet: its

   * value is automatically calculated by the MacLow before

   * calling WifiPhy::Send.

   */

  void DisableOverrideDurationId (void);

  /**

   * \returns true if must wait for ACK after data transmission,

   *          false otherwise.

   *

   * This methods returns true when any of MustWaitNormalAck,

   * MustWaitFastAck, or MustWaitSuperFastAck return true.

   */

  bool MustWaitAck (void) const;

  /**

   * \returns true if normal ACK protocol should be used, false

   *          otherwise.

   *

   * \sa EnableAck

   */

  bool MustWaitNormalAck (void) const;

  /**

   * \returns true if fast ack protocol should be used, false

   *          otherwise.

   *

   * \sa EnableFastAck

   */

  bool MustWaitFastAck (void) const;

  /**

   * \returns true if super fast ack protocol should be used, false

   *          otherwise.

   *

   * \sa EnableSuperFastAck

   */

  bool MustWaitSuperFastAck (void) const;

  /**

   * \returns true if block ack mechanism is used, false otherwise.

   *

   * \sa EnableBlockAck

   */

  bool MustWaitBasicBlockAck (void) const;

  /**

   * \returns true if compressed block ack mechanism is used, false otherwise.

   *

   * \sa EnableCompressedBlockAck

   */

  bool MustWaitCompressedBlockAck (void) const;

  /**

   * \returns true if multi-tid block ack mechanism is used, false otherwise.

   *

   * \sa EnableMultiTidBlockAck

   */

  bool MustWaitMultiTidBlockAck (void) const;

  /**

   * \returns true if RTS should be sent and CTS waited for before

   *          sending data, false otherwise.

   */

  bool MustSendRts (void) const;

  /**

   * \returns true if a duration/id was forced with

   *         EnableOverrideDurationId, false otherwise.

   */

  bool HasDurationId (void) const;

  /**

   * \returns the duration/id forced by EnableOverrideDurationId

   */

  Time GetDurationId (void) const;

  /**

   * \returns true if EnableNextData was called, false otherwise.

   */

  bool HasNextPacket (void) const;

  /**

   * \returns the size specified by EnableNextData.

   */

  uint32_t GetNextPacketSize (void) const;

private:

  friend std::ostream &operator << (std::ostream &os, const MacLowTransmissionParameters &params);

  uint32_t m_nextSize;

  enum

  {

    ACK_NONE,

    ACK_NORMAL,

    ACK_FAST,

    ACK_SUPER_FAST,

    BLOCK_ACK_BASIC,

    BLOCK_ACK_COMPRESSED,

    BLOCK_ACK_MULTI_TID

  } m_waitAck;

  bool m_sendRts;

  Time m_overrideDurationId;

};

/**

 * Serialize MacLowTransmissionParameters to ostream in a human-readable form.

 *

 * \param os std::ostream

 * \param params MacLowTransmissionParameters

 * \return std::ostream

 */

std::ostream &operator << (std::ostream &os, const MacLowTransmissionParameters &params);

/**

 * \ingroup wifi

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

 */

class MacLow : public Object

{

public:

  /**

   * typedef for a callback for MacLowRx

   */

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

  MacLow ();

  virtual ~MacLow ();

  /**

   * Set up WifiPhy associated with this MacLow.

   *

   * \param phy WifiPhy associated with this MacLow

   */

  void SetPhy (Ptr<WifiPhy> phy);

  /**

   * Set up WifiRemoteStationManager associated with this MacLow.

   *

   * \param manager WifiRemoteStationManager associated with this MacLow

   */

  void SetWifiRemoteStationManager (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);

  /**