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

     2 /*

     3  * Copyright (c) 2007 INRIA

     4  * All rights reserved.

     5  *

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

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

     8  * published by the Free Software Foundation;

     9  *

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

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

    12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

    13  * GNU General Public License for more details.

    14  *

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

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

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

    18  *

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

    20  */

    21 #ifndef TRACE_RESOLVER_H

    22 #define TRACE_RESOLVER_H

    23 

    24 #include <string>

    25 #include <list>

    26 #include "trace-context.h"

    27 

    28 namespace ns3 {

    29 

    30 class CallbackBase;

    31 

    32 /**

    33  * \brief the base class which is used to incremental perform trace

    34  *        namespace resolution.

    35  * \ingroup lowleveltracing

    36  *

    37  * This class provides a public API to the ns3::TraceRoot object:

    38  *   - ns3::TraceResolver::Connect

    39  *   - ns3::TraceResolver::Disconnect

    40  *

    41  * It also provides an API for its subclasses. Each subclass should 

    42  * implement one of:

    43  *   - ns3::TraceResolver::DoLookup

    44  *   - ns3::TraceResolver::DoConnect and ns3::TraceResolver::DoDisconnect

    45  * Each subclass must also provide an ns3::TraceContext to the TraceResolver

    46  * constructor. Finally, each subclass can access the ns3::TraceContext 

    47  * associated to this  ns3::TraceResolver through the 

    48  * ns3::TraceResolver::GetContext method.

    49  */

    50 class TraceResolver

    51 {

    52 public:

    53   virtual ~TraceResolver ();

    54   /**

    55    * \param path the namespace path to resolver

    56    * \param cb the callback to connect to the matching namespace

    57    *

    58    * This method is typically invoked by ns3::TraceRoot but advanced

    59    * users could also conceivably call it directly if they want to

    60    * skip the ns3::TraceRoot.

    61    */

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

    63   /**

    64    * \param path the namespace path to resolver

    65    * \param cb the callback to disconnect in the matching namespace

    66    *

    67    * This method is typically invoked by ns3::TraceRoot but advanced

    68    * users could also conceivably call it directly if they want to

    69    * skip the ns3::TraceRoot.

    70    */

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

    72 protected:

    73   /**

    74    * \param context the context used to initialize this TraceResolver.

    75    *

    76    * Every subclass must call this constructor

    77    */

    78   TraceResolver (TraceContext const &context);

    79   /**

    80    * \returns the ns3::TraceContext stored in this ns3::TraceResolver.

    81    *

    82    * Subclasses usually invoke this method to get access to the

    83    * TraceContext stored here to pass it down to the TraceResolver

    84    * constructors invoked from within the DoLookup method.

    85    */

    86   TraceContext const &GetContext (void) const;

    87   typedef std::list<TraceResolver *> TraceResolverList;

    88 private:

    89   TraceResolver ();

    90   /**

    91    * \param id the id to resolve. This is supposed to be

    92    * one element of the global tracing namespace.

    93    * \returns a list of reslvers which match the input namespace element

    94    *

    95    * A subclass which overrides this method should return a potentially

    96    * empty list of pointers to ns3::TraceResolver instances which match

    97    * the input namespace element. Each of these TraceResolver should be

    98    * instanciated with a TraceContext which holds enough context

    99    * information to identify the type of the TraceResolver.

   100    */

   101   virtual TraceResolverList DoLookup (std::string id) const;

   102   /**

   103    * \param cb callback to connect

   104    *

   105    * This method is invoked on leaf trace resolvers.

   106    */

   107   virtual void DoConnect (CallbackBase const &cb);

   108   /**

   109    * \param cb callback to disconnect

   110    *

   111    * This method is invoked on leaf trace resolvers.

   112    */

   113   virtual void DoDisconnect (CallbackBase const &cb);

   114   TraceContext m_context;

   115 };

   116 

   117 }//namespace ns3

   118 

   119 #endif /* TRACE_RESOLVER_H */