// $Id$
//
// Copyright (C) 2007 
// Fraunhofer Institute for Open Communication Systems (FOKUS) 
// Competence Center NETwork research (NET), St. Augustin, GERMANY 
//     Stefan Bund <g0dil@berlios.de>
//
// 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
// the Free Software Foundation; either version 2 of the License, or
// (at your option) any later version.
//
// 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.

namespace senf {

    /** \brief Example of a variant policy. ONLY FOR EXPOSITION

        This class shows the interace which must be impemented by a variant policy. It is \e not a
        variant policy, it is only a declaration of the interface:
        \code
        struct ExampleVariantPolicy
        {
            // optional typedefs used tosimplify all other declarations
            typedef PacketParserBase::data_iterator data_iterator;
            typedef PacketParserBase::state_type state_type;
            typedef PacketParserBase::size_type size_type;

            // mandatory members
            static size_type const init_bytes = 0;
            size_type bytes  (data_iterator i, state_type s) const;

            data_iterator begin(data_iterator i, state_type s) const;

            unsigned variant (data_iterator i, state_type s) const;
            void variant     (unsigned v, data_iterator i, state_type s);
        };
        \endcode

        The \a VariantPolicy may define additional data members if needed. It must be either default
        constructible or copy constructible. If a \a VariantPolicy is not default constructible, an
        additional \a VariantPolicy argument needs to be passed to the senf::Parse_Variant
        constructor which is used to copy-initialize the embeded policy.

        \see senf::Parse_Variant
     */
    struct ExampleVariantPolicy
    {
        typedef PacketParserBase::data_iterator data_iterator;
        typedef PacketParserBase::state_type state_type;
        typedef PacketParserBase::size_type size_type;

        static size_type const init_bytes = 0; ///< Additional initial size
                                        /**< This value is added to the size of the first variant
                                             sub-parser to calculate the \c init_bytes value. */

        size_type bytes  (data_iterator i, state_type s) const;
                                        ///< Additional parser size
                                        /**< The return value is added to the size of the current
                                             variant. */

        data_iterator begin(data_iterator i, state_type s) const;
                                        ///< Advance \a i to beginning of variant data
                                        /**< This member must return the beginning of the variant's
                                             data (the place, where the sub-parsers reside in the
                                             packet). */

        unsigned variant (data_iterator i, state_type s) const;
                                        ///< Get current variant index
                                        /**< \returns current variant sub-parser, interpreted as
                                             index into the 0-indexed list of sub-parsers. */

        void variant     (unsigned v, data_iterator i, state_type s);
                                        ///< Set current variant index
                                        /**< Must set the current variant to \a v which is the index
                                             into the 0-index list of sub-parsers of the currently
                                             active variant sub-parser.

                                             This member must not process the sub-parser data (like
                                             initializing the sub-parser or changing the data
                                             container size). */
    };

}


// Local Variables:
// mode: c++
// fill-column: 100
// comment-column: 40
// c-file-style: "senf"
// indent-tabs-mode: nil
// ispell-local-dictionary: "american"
// compile-command: "scons -u test"
// mode: flyspell
// mode: auto-fill
// End: