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

/*

 * Copyright (c) 2010 Dean Armstrong

 *

 * 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: Dean Armstrong <deanarm@gmail.com>

 */

#ifndef WIFI_INFORMATION_ELEMENT_H

#define WIFI_INFORMATION_ELEMENT_H

#include "ns3/header.h"

#include "ns3/simple-ref-count.h"

/**

 * \ingroup wifi

 *

 * \subsection wifi_ie Information Elements

 *

 * The IEEE 802.11 standard includes the notion of Information

 * Elements, which are encodings of management information to be

 * communicated between STAs in the payload of various frames of type

 * Management. Information Elements (IEs) have a common format, each

 * starting with a single octet - the Element ID, which indicates the

 * specific type of IE (a type to represent the options here is

 * encodes the number of octets in the third and final field, which is

 * the IE Information field.

 *

 * The class ns3::WifiInformationElement provides a base for classes

 * which represent specific Information Elements. This class defines

 * pure virtual methods for serialisation

 * (ns3::WifiInformationElement::SerializeInformation) and

 * deserialisation

 * (ns3::WifiInformationElement::DeserializeInformation) of IEs, from

 * or to data members or other objects that simulation objects use to

 * maintain the relevant state.

 *

 * This class also provides an implementation of the equality

 * operator, which operates by comparing the serialised versions of

 * the two WifiInformationElement objects concerned.

 */

namespace ns3 {

/**

 * This type is used to represent an Information Element ID. An

 * enumeration would be tidier, but doesn't provide for the

 * inheritance that is currently preferable to cleanly support

 * pre-standard modules such as mesh. Maybe there is a nice way of

 * doing this with a class.

 *

 * Until such time as a better way of implementing this is dreamt up

 * and applied, developers will need to be careful to avoid

 * duplication of IE IDs in the #definitions below (and in files which

 * declare "subclasses" of WifiInformationElement). Sorry.

 */

/**

 * Here we have definition of all Information Element IDs in IEEE

 * probably be done in a considerably tidier manner.

 */

// 17 to 31 are reserved in 802.11-2007

// 45 is reserved in 802.11-2007

// 47 is reserved in 802.11-2007

// 49 is reserved in 802.11-2007

// 51 to 126 are reserved in 802.11-2007

// 128 to 220 are reserved in 802.11-2007

// 222 to 255 are reserved in 802.11-2007

/**

 * \brief Information element, as defined in 802.11-2007 standard

 *

 * Elements are defined to have a common general format consisting of

 * a 1 octet Element ID field, a 1 octet length field, and a

 * variable-length element-specific information field. Each element is

 * assigned a unique Element ID as defined in this standard. The

 * Length field specifies the number of octets in the Information

 * field.

 *

 * This class is pure virtual and acts as base for classes which know

 * how to serialize specific IEs.

 */

class WifiInformationElement : public SimpleRefCount<WifiInformationElement>

{

public:

  virtual ~WifiInformationElement ();

  ///\name Each subclass must implement

  //\{

  virtual void Print (std::ostream &os) const = 0;

  /// Own unique Element ID

  /// Length of serialized information

  virtual uint8_t GetInformationSize () const = 0;

  /// Serialize information

  virtual void SerializeInformation (Buffer::Iterator start) const = 0;

  /// Deserialize information

  virtual uint8_t DeserializeInformation (Buffer::Iterator start,

                                          uint8_t length) = 0;

  //\}

  /// Compare information elements using Element ID

  virtual bool operator< (WifiInformationElement const & a) const;

  /// Compare two IEs for equality by ID & Length, and then through

  /// memcmp of serialised version

  virtual bool operator== (WifiInformationElement const & a) const;

};

}

#endif /* WIFI_INFORMATION_ELEMENT_H */