X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Packets%2FPacketRegistry.hh;h=2311f3eba1c2434ee36055d4e7621fb270b0ffcc;hb=92f8630b75f3ef50e73c48cde58645dcd1534e27;hp=da9964a20dd6ce77881a801855e867e8ec767aba;hpb=9357448dc66bc9acfd3bd8db423deb75bcd6a2c4;p=senf.git diff --git a/Packets/PacketRegistry.hh b/Packets/PacketRegistry.hh index da9964a..2311f3e 100644 --- a/Packets/PacketRegistry.hh +++ b/Packets/PacketRegistry.hh @@ -1,9 +1,9 @@ // $Id$ // // Copyright (C) 2006 -// Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS) -// Kompetenzzentrum fuer Satelitenkommunikation (SatCom) -// Stefan Bund +// Fraunhofer Institute for Open Communication Systems (FOKUS) +// Competence Center NETwork research (NET), St. Augustin, GERMANY +// Stefan Bund // // This program is free software; you can redistribute it and/or modify // it under the terms of the GNU General Public License as published by @@ -20,77 +20,87 @@ // Free Software Foundation, Inc., // 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +/** \file + \brief PacketRegistry public header */ -#ifndef HH_PacketRegistryImpl_ -#define HH_PacketRegistryImpl_ 1 +#ifndef HH_SENF_Packets_PacketRegistry_ +#define HH_SENF_Packets_PacketRegistry_ 1 // Custom includes #include #include // for boost::noncopyable -#include +#include +#include +#include "../Utils/Exception.hh" #include "Packet.hh" +#include "PacketRegistry.ih" //#include "PacketRegistry.mpp" ///////////////////////////////hh.p//////////////////////////////////////// namespace senf { + /** \brief %Packet registration facility - namespace impl { template class PacketRegistryImpl; } + The %PacketRegistry provides a generic facility to associate an arbitrary key with + Packets. Example keys are Ethertype or IP protocols. - /** \brief Packet registration facility - - The PacketRegistry provides a generic facility to associate an - arbitrary key with Packets. Example keys are Ethertype or IP - protocols. - - Every PacketRegistry is identified by a type tag: + Every %PacketRegistry is identified by a type tag: \code - struct SomeTag { - typedef some_key_type key_t; - }; + struct SomeTag { + typedef some_key_type key_t; + }; \endcode - The key type can be an arbitrary value type. The PacketRegistry - for this Tag can then be accessed using - PacketRegistry::. + The key type can be an arbitrary value type. The %PacketRegistry for this Tag can then be + accessed using senf::PacketRegistry::. - The PacketRegistry class has only static members and provides - access to the packet registry. It allows to register Packet - classes and to create new Packets given a key. Methods are - also provided to find the key of a Packet type. + The %PacketRegistry class has only static members and provides access to the packet + registry. It allows two-way lookup either by key or by packet type. \code - PacketRegistry::registerPacket(key_of_somePacket); - p = PacketRegistry::create(some_key,begin,end); - SomeTag::key_t key = PacketRegistry::key(); + senf::Packet::factory_t factory (senf::PacketRegistry::lookup(some_key).factory()); + SomeTag::key_t key = PacketRegistry::key(); \endcode - Normally, packet classes are registered statically and not - procedurally. To this end, the RegistrationProxy is provided: + Packets can be registered either dynamically or statically. Dynamic: \code - PacketRegistry::RegistrationProxy - registerSomePacket (key_of_somePacket); + // dynamic registration + senf::PacketRegistry::registerPacket(key_of_somePacket); + + // static registration. 'registerSomePacket' is an arbitrary symbol name + senf::PacketRegistry::RegistrationProxy + registerSomePacket (key_of_somePacket); \endcode - This global variable declaration will register \c SomePacket - with the \c SomeTag registry under the key \c - key_of_somePacket. The variable \c registerSomePacket is a - dummy. It's only function is to force the call of it's - constructor during global construction time. - - The PacketRegistry's purpose is mostly to assist in - implementing the v_nextInterpreter() member of packet - facades. This is further supported by the PacketRegistryMixin - class. - - \todo Add parameterless create() method + + This global variable declaration will register \a SomePacket with the \a SomeTag registry + under the key \a key_of_somePacket. The variable \a registerSomePacket is a dummy. It's only + function is to force the call of it's constructor during global construction time. This + static registration only works when the symbol is included into the final binary. To force + this inclusion, you should not put packet registrations into a library but into an object + file. + + \ingroup packet_module */ template class PacketRegistry { public: + typedef typename detail::PacketRegistryImpl::iterator iterator; + /** \brief Statically register a packet type in a PacketRegistry + + To use this class, define a global symbol in the following way: + \code + namespace { + senf::PacketRegistry::RegistrationProxy + registerPacketType (key); + } + \endcode Here \a Tag is the type tag of the registry to register the packet in, \a + PacketType is the packet to register (this is the ConcretePacket of that packet) and \a + key is the key of type \c Tag::key_t under which the packet is to be registered. \a + registerPacketType is an arbitrary name for the global symbol. */ - template + template struct RegistrationProxy { RegistrationProxy(typename Tag::key_t key); @@ -98,111 +108,135 @@ namespace senf { /** \brief Register new packet type - Register \c OtherPacket in the packet registry \c Tag - under the given \c key. + Register \a PacketType in the packet registry \a Tag under the given \a key. \par Preconditions: - The given \c key must be unique and not be assigned to - any other packet class in this registry. - The Packet must not already be registered in the registry. + The given \a key must be unique and not be assigned to any other + packet class in this registry. The %Packet must not already be registered in the + registry. - \param OtherPacket packet to register - \param key key of the packet + \tparam PacketType ConcretePacket instantiation of packet to register + \param key The key of the packet */ - template + template static void registerPacket(typename Tag::key_t key); - /** \brief Find key of a packet + /** \brief Find key of a packet type - Return the key of \c OtherPacket as registered in the \c - Tag registry + Return the key of \a PacketType as registered in the \a Tag registry - \param OtherPacket packet of which the key is requested + \tparam PacketType packet of which the key is requested \returns key of the packet - \throws PacketTypeNotRegistered if the packet type is not - found in the registry. + \throws PacketTypeNotRegistered if the packet type is not found in the registry. */ - template + template static typename Tag::key_t key(); - /** \brief Create new Packet + /** \brief Find key of a packet type + + Return the key of \a PacketType as registered in the \a Tag registry + + \tparam PacketType packet of which the key is requested + \returns key of the packet wrapped in a boost::optional or + an unbound optional, if the key is not found. + */ + template + static typename boost::optional key(NoThrow_t); + + /** \brief Find key of a packet - \param key Key of packet type to create instance of - \param b begin iterator argument to Packet::create() - \param e end iterator argument to Packet::create() - \returns new Instance of the packet type registered under - key or DataPacket, if the key is not registered. + Return the key of \a packet, an arbitrary packet, as registered in the \a Tag registry. + + \param packet The packet of which the key is requested + \returns key of the packet + \throws PacketTypeNotRegistered if the packet type is not found in the registry. */ - template - static Packet::ptr create(typename Tag::key_t key, InputIterator b, InputIterator e); + static typename Tag::key_t key(Packet const & packet); + + /** \brief Find key of a packet + + Return the key of \a packet, an arbitrary packet, as registered in the \a Tag registry. + + \param packet The packet of which the key is requested + \returns key of the packet wrapped in a boost::optional or + an unbound optional, if the key is not found. + */ + static typename boost::optional key(Packet const & packet, NoThrow_t); + + /** \brief Lookup a packet by it's key + + \throws PacketTypeNotRegistered if the \a key is not found in the registry + \return %Packet entry for given \a key + */ + static PkReg_Entry const & lookup(typename Tag::key_t key); + + /** \brief Lookup a packet by it's key + \return Pointer to packet entry for given \a key or 0, if the key is not found in the + registry. + */ + static PkReg_Entry const * lookup(typename Tag::key_t key, NoThrow_t); + + /** \brief Beginning iterator to list of registered keys + */ + static iterator begin(); + + /** \brief End iterator to list of registered keys + */ + static iterator end(); private: - typedef impl::PacketRegistryImpl Registry; + typedef detail::PacketRegistryImpl Registry; static Registry & registry(); - - template friend class PacketRegistryMixin; }; - /** \brief Helper class for v_nextInterpreter implementations + /** \brief Statically add an entry to a packet registry - This class is a helper class which is to be inherited from in - a packet facade which wants to register a new interpreter with - the packet framework depending on a packet registry. + This macro will declare an anonymous global variable in such a way, that constructing this + variable will add a registration to the given packet registry. - This mixin class provides a new registerInterpreter - implementation which can be used besides the methods provided - by senf::Packet to add a new interpreter to the - interpreter chain. + \hideinitializer + */ +# define SENF_PACKET_REGISTRY_REGISTER( registry, value, type ) \ + namespace { \ + senf::PacketRegistry< registry >::RegistrationProxy< type > \ + BOOST_PP_CAT(packetRegistration_, __LINE__) ( value ); \ + } - \code - class SomePacket - : public Packet, - private PacketRegistryMixin - { - using Packet::retgisterInterpreter; - using PacketRegistryMixin::registerInterpreter; - - virtual void v_nextInterpreter() - { - registerInterpreter(some_key_value, subpacket_begin, subpacket_end); - } - }; - \endcode - This example is not complete, it only contains the parts - concerned with PacketRegistryMixin. + /** \brief Dump all packet registries + + This command will dump all packet registries to the given stream. This is to help debugging + registration problems. */ - template - class PacketRegistryMixin - { - protected: - /** \brief add interpreter to interpreter chain - - This method is used by v_nextInterpreter() to add a new - interpreter to the interpreter chain (see the Packet - reference for more). Instead of specifying the type of - packet to use as a template argument it is specified using - the \c key value from the \c Tag registry - */ - void registerInterpreter(typename Tag::key_t key, - Packet::iterator b, Packet::iterator e) const; - }; + void dumpPacketRegistries(std::ostream & os); - struct PacketTypeNotRegistered : public std::exception - { virtual char const * what() const throw() { return "packet type not registered"; } }; + /** \brief Entry not found in registry + + This exception is signaled whenever a throwing lookup operation fails. + */ + struct PacketTypeNotRegisteredException : public senf::Exception + { PacketTypeNotRegisteredException() : senf::Exception("packet type not registered"){} }; } ///////////////////////////////hh.e//////////////////////////////////////// -//#include "PacketRegistry.cci" +#endif +#if !defined(HH_SENF_Packets_Packets__decls_) && !defined(HH_SENF_Packets_PacketRegistry_i_) +#define HH_SENF_Packets_PacketRegistry_i_ +#include "PacketRegistry.cci" #include "PacketRegistry.ct" #include "PacketRegistry.cti" #endif - + // Local Variables: // mode: c++ // fill-column: 100 // c-file-style: "senf" // indent-tabs-mode: nil // ispell-local-dictionary: "american" +// compile-command: "scons -u test" +// comment-column: 40 // End: +