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

/*

 * Copyright (c) 2007 INRIA, Gustavo Carneiro

 *

 * 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: Gustavo Carneiro <gjcarneiro@gmail.com>,

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

 */

#ifndef OBJECT_H

#define OBJECT_H

#include <stdint.h>

#include <string>

#include "ptr.h"

#include "trace-resolver.h"

#include "callback.h"

#include "value.h"

#include "object-base.h"

#define NS_OBJECT_ENSURE_REGISTERED(type)       \

  static struct X##type##RegistrationClass      \

  {                                             \

    X##type##RegistrationClass () {             \

      ns3::TypeId tid = type::GetTypeId ();     \

      tid.GetParent ();                         \

    }                                           \

} x_##type##RegistrationVariable

namespace ns3 {

class TraceContext;

class CallbackBase;

class Object;

class ParamSpec;

class Value;

class Parameters;

/**

 * \brief a unique identifier for an interface.

 *

 * This class records a lot of meta-information about a 

 * subclass of the Object base class:

 *  - the base class of the subclass

 *  - the set of accessible constructors in the subclass

 *  - the set of 'parameters' accessible in the subclass

 */

class TypeId

{

public:

  enum {

    ATTR_GET = 1<<0,

    ATTR_SET = 1<<1,

    ATTR_CONSTRUCT = 1<<2,

    ATTR_SGC = ATTR_GET | ATTR_SET | ATTR_CONSTRUCT,

  };

  /**

   * \param name the name of the requested interface

   * \returns the unique id associated with the requested

   *          name. 

   *

   * This method cannot fail: it will crash if the input 

   * name is not a valid interface name.

   */

  static TypeId LookupByName (std::string name);

  /**

   * \returns the number of TypeId instances constructed

   */

  static uint32_t GetRegisteredN (void);

  /**

   * \param i index

   * \returns the TypeId instance whose index is \i.

   */

  static TypeId GetRegistered (uint32_t i);

  /**

   * \param name the name of the interface to construct.

   *

   * No two instances can share the same name.

   */

  TypeId (std::string name);

  /**

   * \returns the parent of this TypeId

   *

   * This method cannot fail: it will crash if the input

   * id is not a valid interface id.

   */

  TypeId GetParent (void) const;

  /**

   * \returns the name of the group associated to this TypeId.

   */

  std::string GetGroupName (void) const;

  /**

   * \returns the fully-qualified C++ typename of this TypeId.

   */

  std::string GetTypeName (void) const;

  /**

   * \returns the name of this interface.

   */

  std::string GetName (void) const;

  /**

   * \returns true if this TypeId has a constructor

   */

  bool HasConstructor (void) const;

  /**

   * \returns the number of parameters associated to this TypeId

   */

  uint32_t GetParametersN (void) const;

  /**

   * \param i index into parameter array

   * \returns the name associated to the parameter whose

   *          index is \i i.

   */

  std::string GetParameterName (uint32_t i) const;

  /**

   * \param i index into parameter array

   * \returns the full name associated to the parameter whose

   *          index is \i i.

   */

  std::string GetParameterFullName (uint32_t i) const;

  Ptr<Object> CreateObject (const Parameters &parameters) const;

  Ptr<Object> CreateObject (void) const;

  template <typename T1>

  Ptr<Object> CreateObject (T1 a1) const;

  template <typename T1, typename T2>

  Ptr<Object> CreateObject (T1 a1, T2 a2) const;

  /**

   * \param tid the TypeId of the base class.

   * \return this TypeId instance.

   *

   * Record in this TypeId which TypeId is the TypeId

   * of the base class of the subclass.

   */

  TypeId SetParent (TypeId tid);

  /**

   * \return this TypeId instance.

   *

   * Record in this TypeId which TypeId is the TypeId

   * of the base class of the subclass.

   */

  template <typename T>

  TypeId SetParent (void);

  /**

   * \param groupName the name of the group this TypeId belongs to.

   * \returns this TypeId instance.

   *

   * The group name is purely an advisory information used to 

   * group together types according to a user-specific grouping

   * scheme.

   */

  TypeId SetGroupName (std::string groupName);

  /**

   * \param typeName the fully-qualified C++ typename of this TypeId.

   * \returns this TypeId instance.

   */

  TypeId SetTypeName (std::string typeName);

  /**

   * \returns this TypeId instance

   *

   * Record in this TypeId the fact that the default constructor

   * is accessible.

   */

  template <typename T>

  TypeId AddConstructor (void);

  template <typename T, typename T1>

  TypeId AddConstructor (void);

  template <typename T, typename T1, typename T2>

  TypeId AddConstructor (void);

  /**

   * \param name the name of the new parameter

   * \param help some help text which describes the purpose of this

   *        parameter

   * \param param an instance of the associated ParamSpec subclass

   * \returns this TypeId instance

   *

   * Record in this TypeId the fact that a new parameter exists.

   */

  TypeId AddParameter (std::string name,

                       std::string help, 

                       Ptr<const ParamSpec> spec,

                       Ptr<const AttributeChecker> checker);

  /**

   * \param name the name of the new parameter

   * \param help some help text which describes the purpose of this

   *        parameter

   * \param flags flags which describe how this parameter can be read and/or written.

   * \param param an instance of the associated ParamSpec subclass

   * \returns this TypeId instance

   *

   * Record in this TypeId the fact that a new parameter exists.

   */

  TypeId AddParameter (std::string name,

                       std::string help, 

                       uint32_t flags,

                       Ptr<const ParamSpec> spec,

                       Ptr<const AttributeChecker> checker);

  // construct an invalid TypeId.

  TypeId ();

  ~TypeId ();

private:

  friend class Object;

  friend class Parameters;

  friend bool operator == (TypeId a, TypeId b);

  friend bool operator != (TypeId a, TypeId b);

  struct ParameterInfo {

    Ptr<const ParamSpec> spec;

    uint32_t flags;

    Ptr<const AttributeChecker> checker;

  };

  /**

   * \param name the name of the requested parameter

   * \returns the ParamSpec associated to the requested parameter

   */

  bool LookupParameterByName (std::string name, struct ParameterInfo *info) const;

  /**

   * \param i the position of the requested parameter

   * \returns the ParamSpec associated to the requested parameter

   */

  bool LookupParameterByPosition (uint32_t i, struct ParameterInfo *info) const;

  /**

   * \param fullName the full name of the requested parameter

   * \returns the ParamSpec associated to the requested parameter

   */

  static bool LookupParameterByFullName (std::string fullName, struct ParameterInfo *info);

  explicit TypeId (uint16_t tid);

  void DoAddConstructor (CallbackBase callback, uint32_t nArguments);

  CallbackBase LookupConstructor (uint32_t nArguments) const;

  Ptr<const ParamSpec> GetParameterParamSpec (uint32_t i) const;

  uint32_t GetParameterFlags (uint32_t i) const;

  Ptr<const AttributeChecker> GetParameterChecker (uint32_t i) const;

  uint16_t m_tid;

};

/**

 * \brief a container of parameters to be used during object's construction

 *        and in ns3::Object::Set.

 *

 */

class Parameters

{

public:

  Parameters ();

  Parameters (const Parameters &o);

  Parameters &operator = (const Parameters &o);

  ~Parameters ();

  /**

   * \param name the name of the parameter to set

   * \param value the value to set

   *

   * This method checks that a parameter with the requested

   * name exists and that the value specified is an acceptable

   * value of that parameter. If any of these checks fails,

   * the program terminates with a message.

   */

  /**

   * Clear the content of this instance.

   */

  void Reset (void);

  /**

   * \returns the global parameter container

   *

   * The global parameter container can be used to specify

   * a set of parameter values without having to re-specify

   * them for each object when it is created. This container

   * is checked only during object construction and 

   * it is always checked last, after any per-object

   * container is checked.

   */

  static Parameters *GetGlobal (void);

  std::string SerializeToString (void) const;

  bool DeserializeFromString (std::string value);

private:

  friend class Object;

  struct Param {

    Ptr<const AttributeChecker> checker;

  };

  typedef std::vector<struct Param> Params;

  typedef Params::iterator Iterator;

  typedef Params::const_iterator CIterator;

  std::string LookupParameterFullNameByChecker (Ptr<const AttributeChecker> checker) const;

  Params m_parameters;

};

/**

 * \brief a base class which provides memory management and object aggregation

 *

 */

class Object : public ObjectBase

{

public:

  static TypeId GetTypeId (void);

  Object ();

  virtual ~Object ();

  /**

   * \param name the name of the parameter to set

   * \param value the name of the parameter to set

   *

   * Set a single parameter.

   */

  /**

   * \param name the name of the parameter to read

   * \param value a reference to the string where the value of the 

   *        parameter should be stored.

   * \returns true if the requested parameter was found, false otherwise.

   */

  bool Get (std::string name, std::string &value) const;

  /**

   * \param name the name of the parameter to read

   * \param value a reference to the object where the value of the 

   *        parameter should be stored.

   * \returns true if the requested parameter was found, false otherwise.

   */

  /**

   * Increment the reference count. This method should not be called

   * by user code. Object instances are expected to be used in conjunction

   * of the Ptr template which would make calling Ref unecessary and 

   * dangerous.

   */

  inline void Ref (void) const;

  /**

   * Decrement the reference count. This method should not be called

   * by user code. Object instances are expected to be used in conjunction

   * of the Ptr template which would make calling Ref unecessary and 

   * dangerous.

   */

  inline void Unref (void) const;

  /**

   * \returns a pointer to the requested interface or zero if it could not be found.

   */

  template <typename T>

  Ptr<T> GetObject (void) const;

  /**

   * \param tid the interface id of the requested interface

   * \returns a pointer to the requested interface or zero if it could not be found.

   */

  template <typename T>

  Ptr<T> GetObject (TypeId tid) const;

  /**

   * Run the DoDispose methods of this object and all the

   * objects aggregated to it.

   * After calling this method, the object is expected to be

   * totally unusable except for the Ref and Unref methods.

   * It is an error to call Dispose twice on the same object 

   * instance

   */

  void Dispose (void);

  /**

   * \param other another object pointer

   *

   * This method aggregates the two objects together: after this

   * method returns, it becomes possible to call GetObject

   * on one to get the other, and vice-versa. 

   */

  void AggregateObject (Ptr<Object> other);

  /**

   * \param path the path to match for the callback

   * \param cb callback to connect

   *

   * Connect the input callback to all trace sources which

   * match the input path.

   *

   */

  void TraceConnect (std::string path, const CallbackBase &cb) const;

  /**

   * \param path the path to match for the callback

   * \param cb callback to disconnect

   *

   * Disconnect the input callback from all trace sources which

   * match the input path.

   */

  void TraceDisconnect (std::string path, const CallbackBase &cb) const;

  /**

   * \returns the trace resolver associated to this object.

   *

   * This method should be rarely called by users.

   */

  virtual Ptr<TraceResolver> GetTraceResolver (void) const;

protected:

  /**

   * This method is called by Object::Dispose.

   * Subclasses are expected to override this method and chain

   * up to their parent's implementation once they are done.

   */

  virtual void DoDispose (void);

  virtual void NotifyConstructionCompleted (void);

private:

  friend class TypeIdTraceResolver;

  template <typename T>

  friend Ptr<T> CreateObject (const Parameters &parameters);

  template <typename T>

  friend Ptr<T> CreateObject (void);

  template <typename T, typename T1>

  friend Ptr<T> CreateObject (T1 a1);

  template <typename T, typename T1, typename T2>

  friend Ptr<T> CreateObject (T1 a1, T2 a2);

  template <typename T, typename T1, typename T2, typename T3>

  friend Ptr<T> CreateObject (T1 a1, T2 a2, T3 a3);

  template <typename T, typename T1, typename T2, typename T3, typename T4>

  friend Ptr<T> CreateObject (T1 a1, T2 a2, T3 a3, T4 a4);

  template <typename T, typename T1, typename T2, typename T3, typename T4, typename T5>

  friend Ptr<T> CreateObject (T1 a1, T2 a2, T3 a3, T4 a4, T5 a5);

  template <typename T, typename T1, typename T2, typename T3, typename T4, typename T5, typename T6>

  friend Ptr<T> CreateObject (T1 a1, T2 a2, T3 a3, T4 a4, T5 a5, T6 a6);

  template <typename T, typename T1, typename T2, typename T3, typename T4, typename T5, typename T6, typename T7>

  friend Ptr<T> CreateObject (T1 a1, T2 a2, T3 a3, T4 a4, T5 a5, T6 a6, T7 a7);

  Ptr<Object> DoGetObject (TypeId tid) const;

  void DoCollectSources (std::string path, const TraceContext &context, 

                         TraceResolver::SourceCollection *collection) const;

  void DoTraceAll (std::ostream &os, const TraceContext &context) const;

  bool Check (void) const;

  bool CheckLoose (void) const;

  /**

   * Attempt to delete this object. This method iterates

   * over all aggregated objects to check if they all 

   * have a zero refcount. If yes, the object and all

   * its aggregates are deleted. If not, nothing is done.

   */

  void MaybeDelete (void) const;

  /**