source: source/ariba/communication/modules/transport/protlib/ie.h@ 4721

/// ----------------------------------------*- mode: C++; -*--
/// @file ie.h
/// Basic information elements (PDUs and PDU objects)
/// ----------------------------------------------------------
/// $Id: ie.h 2549 2007-04-02 22:17:37Z bless $
/// $HeadURL: https://svn.ipv6.tm.uka.de/nsis/protlib/trunk/include/ie.h $
// ===========================================================
//                      
// Copyright (C) 2005-2007, all rights reserved by
// - Institute of Telematics, Universitaet Karlsruhe (TH)
//
// More information and contact:
// https://projekte.tm.uka.de/trac/NSIS
//                      
// 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; version 2 of the License
//
// 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.,
// 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
//
// ===========================================================

/** @ingroup ie
 * @todo Use objectpool by deriving classes from class poolobject and
 * linking executables against objectpool.o or including objectpool.o into
 * libie.a.
 *
 * This header file defines the base class of all information elements, the
 * information elements for the protocol and an IE manager object.
 *
 * For performance only pointers are exchanged. The copy member function is
 * the way to duplicate an IE. It does much the same as a copy constructor
 * but returns not the IE but a pointer to it. If the IE contains pointers,
 * their target objects are copied too.
 */

#ifndef _PROTLIB__IE_H_
#define _PROTLIB__IE_H_

#include <ext/hash_map>
#include <deque>
#include <string>
#include <iostream>
#include <map>

#include "protlib_types.h"
#include "network_message.h"

namespace protlib {



/** @addtogroup ie Information Elements
 * @{
 */

/// Catch bad_alloc and call throw_nomem_error
#define catch_bad_alloc(x) try { x; } catch(bad_alloc) { throw_nomem_error(); }

// forward declarations
class IEManager;
class IEErrorList;
class IEError;

/** Abstract Information Element (IE) interface
 */
class IE {
public:
        virtual ~IE() { }

        friend class IEManager;
        /// IE coding sheme
        /** All coding shemes have to be listed here. Each IE should support at
         * least one listed coding sheme. This is used when serializing or
         * deserializing from a NetMsg object to (de)code the IE in the right way.
         * Note that coding schemes and protocol version are not the same.
         * There could also be a coding sheme to (de)code IEs e.g. for router
         * configuration.
         */
        enum coding_t {
          nslp_v1     = 1,
          protocol_v1 = 1,
          protocol_v2 = 2,
          nslp_v2     = 3,
          nslp_v2_yoda = 4
        }; // end coding_t
protected:
        /// contructor
        IE(uint16 category);
        /// copy constructor
        IE(const IE& n);
public:
        /// get a new instance of the IE
        virtual IE* new_instance() const = 0;
        /// copy an IE
        virtual IE* copy() const = 0;
        /// deserialization
        virtual IE* deserialize(NetMsg& msg, coding_t coding, IEErrorList& errorlist, uint32& bread, bool skip = true) = 0;
        /// serialize
        virtual void serialize(NetMsg& msg, coding_t coding, uint32& wbytes) const = 0;
protected:
        /// check arguments for deserialization
        bool check_deser_args(coding_t cod, IEErrorList& errorlist, uint32 &bread) const;
        /// check arguments for serialization
        void check_ser_args(coding_t cod, uint32 &wbytes) const;
public:
        /// IE consistency check
        virtual bool check() const = 0;
        /// check if IE supports coding sheme
        virtual bool supports_coding(coding_t c) const = 0;
        /// IE serialized size
        virtual size_t get_serialized_size(coding_t coding) const = 0;
        /// get category
        uint16 get_category() const;
        /// equality
        virtual bool operator==(const IE& ie) const = 0;
        /// not equal
        inline bool operator!=(const IE& ie) const { return (!(*this==ie)); }
        /// get IE name
        /** This is mainly for error reporting. */
        virtual const char* get_ie_name() const = 0;
        /// print to a ostream
        virtual ostream& print(ostream& os, uint32 level, const uint32 indent, const char* name = NULL) const;
        /// get a string representing the IE content
        string to_string(const char* name = 0) const;
        /// input from an istream
        /** Attention: No checking, no warnings. This is ONLY for testing. */
        virtual istream& input(istream& is, bool istty, uint32 level, const uint32 indent, const char* name = NULL);
        /// clear all pointer fields
        virtual void clear_pointers();
protected:
        /// register this IE
        virtual void register_ie(IEManager *iem) const = 0;
        /// IE category
        const uint16 category;
        /// throw a NO_MEM exception
        void throw_nomem_error() const;
}; // end class IE



/**
 * IE Error base class.
 *
 * This is the base for all exceptions thrown during serialize() and
 * deserialize().
 *
 * @warning New code should use the exceptions derived from this class.
 * This class should be abstract but isn't for compatibility reasons.
 */
class IEError : public ProtLibException {
  public:
        /// IE error code - common parsing errors
        enum error_t {
                ERROR_REGISTER,
                ERROR_CODING,
                ERROR_CATEGORY,
                ERROR_NO_IEMANAGER,
                ERROR_MSG_TOO_SHORT,
                ERROR_INVALID_STATE,
                ERROR_WRONG_TYPE,
                ERROR_WRONG_SUBTYPE,
                ERROR_WRONG_LENGTH,
                ERROR_NO_MEM,
                ERROR_TOO_BIG_FOR_IMPL,
                ERROR_UNKNOWN_ERRORCODE,
                ERROR_WRONG_VERSION,
                ERROR_UNEXPECTED_OBJECT,
                ERROR_PDU_SYNTAX,
                ERROR_OBJ_SET_FAILED,
                ERROR_PROT_SPECIFIC
        }; // end error_t

        const error_t err;

        IEError(error_t e);
        virtual ~IEError() throw ();

        virtual const char *getstr() const;

  protected:
        IEError(std::string msg) throw ();

  private:
        static const char* err_str[];
};


/**
 * Syntax error during deserialization.
 *
 * This exception is thrown if a syntax error is detected during
 * deserialization.
 */
class PDUSyntaxError : public IEError {
  public:
        PDUSyntaxError(const char* msg); // deprecated!
        PDUSyntaxError(IE::coding_t coding, uint16 category, uint16 type,
                        uint16 subtype, uint32 pos, const char *msg = "");
        virtual ~PDUSyntaxError() throw () { }

        const IE::coding_t coding;
        const uint16 category;
        const uint16 type;
        const uint16 subtype;
        const uint32 errorpos;
        const string message;
};


/**
 * NetMsg is too short to serialize/deserialize.
 *
 * This exception is typically thrown if a NetMsg ended unexpectedly
 * which indicates a truncated message. It may also be thrown if a
 * NetMsg is too short to hold a serialized IE object.
 */
class IEMsgTooShort : public IEError {
  public:
        IEMsgTooShort(IE::coding_t coding, uint16 category, uint32 pos);
        virtual ~IEMsgTooShort() throw () { }

        const IE::coding_t coding;
        const uint16 category;
        const uint32 errorpos;
};


/**
 * Wrong protocol version.
 *
 * This exception is thrown in case of a version conflict, like a
 * deserialize() method not being able to handle a coding.
 */
class IEWrongVersion : public IEError {
  public:
        IEWrongVersion(IE::coding_t coding, uint16 category, uint32 pos);
        virtual ~IEWrongVersion() throw () { }

        const IE::coding_t coding;
        const uint16 category;
        const uint32 errorpos;
};


/**
 * Invalid IE type.
 *
 * Typically thrown if deserialize() fails because there is no matching IE
 * registered with the IEManager.
 */
class IEWrongType : public IEError {
  public:
        // The first constructor is deprecated!
        IEWrongType(IE::coding_t coding, uint16 category, uint32 pos);
        IEWrongType(IE::coding_t coding, uint16 category, uint16 type,
                        uint32 pos);
        virtual ~IEWrongType() throw () { }

        const IE::coding_t coding;
        const uint16 category;
        const uint16 type;
        const uint32 errorpos;
};


/**
 * Invalid IE subtype.
 *
 * Typically thrown if deserialize() fails because there is no matching IE
 * registered with the IEManager.
 */
class IEWrongSubtype : public IEError {
  public:
        // The first constructor is deprecated!
        IEWrongSubtype(IE::coding_t coding, uint16 category, uint16 type,
                        uint32 pos);
        IEWrongSubtype(IE::coding_t coding, uint16 category, uint16 type,
                        uint16 subtype, uint32 pos);
        virtual ~IEWrongSubtype() throw () { }

        const IE::coding_t coding;
        const uint16 category;
        const uint16 type;
        const uint16 subtype;
        const uint32 errorpos;
};


/**
 * An invalid length field was read.
 *
 * This exception is thrown if a length field inside a NetMsg has a wrong
 * length (either too long or too short, but makes no sense). Note that
 * this overlaps with IEMsgTooShort in some cases.
 */
class IEWrongLength : public IEError {
  public:
        IEWrongLength(IE::coding_t coding, uint16 category, uint16 type,
                        uint16 subtype, uint32 pos);
        virtual ~IEWrongLength() throw () { }

        const IE::coding_t coding;
        const uint16 category;
        const uint16 type;
        const uint16 subtype;
        const uint32 errorpos;
};


/**
 * Some entity is too big for this implementation.
 *
 * This exception is thrown if an operation can't be performed because
 * of some implementation limit.
 */
class IETooBigForImpl : public IEError {
  public:
        IETooBigForImpl(IE::coding_t coding, uint16 category, uint32 pos);
        virtual ~IETooBigForImpl() throw () { }

        const IE::coding_t coding;
        const uint16 category;
        const uint32 errorpos;
};


/**
 * Protocol Specific Error
 *
 * This exception is thrown if a protocol specific error
 * occurred.
 */
class IEProtocolSpecific : public IEError {
  public:
        IEProtocolSpecific(IE::coding_t coding, uint16 category, uint32 pos);
        virtual ~IEProtocolSpecific() throw () { }

        const IE::coding_t coding;
        const uint16 category;
        const uint32 errorpos;
};


/// IE error list
/** This represents a list of IE errors. */
class IEErrorList {
public:
        /// put an IEError on the list
        void put(IEError* iee);
        /// get and remove next IEError
        IEError* get();
        /// is list empty
        bool is_empty() const;
        /// clear list
        void clear();
        /// destructor
        ~IEErrorList();
private:
        /// internal queue type
        typedef deque<IEError*> queue_t;
        /// queue iterator type
        typedef queue_t::iterator queueit_t;
        /// IEError storage
        queue_t queue;
}; // end IEErrorList


/**
 * Represents a (category, type, subtype) tuple.
 *
 * Used internally by IEManager.
 */
class IE_Key {
  public:
        inline IE_Key(uint16 category, uint16 type, uint16 subtype)
                : category(category), type(type), subtype(subtype) { }

        inline bool operator==(const IE_Key &other) const {
                return category == other.category && type == other.type
                        && subtype == other.subtype;
        }

        inline uint16 get_category() const { return category; }
        inline uint16 get_type() const { return type; }
        inline uint16 get_subtype() const { return subtype; }

  private:
        uint16 category;
        uint16 type;
        uint16 subtype;
};

struct hash_IE_Key {
        inline size_t operator()(const protlib::IE_Key &k) const {
                return (k.get_category() << 16)
                        | ( k.get_type() ^ k.get_subtype() );
        }
};


/** 
 * A registry and factory for IEs.
 *
 * Each IE has to register at the IE Manager. The IEManager then provides
 * methods to deserialize IEs from or serialize IEs to a NetMsg object.
 * IEManager is abstract and thus can't be instantiated.
 *
 * In contrast to earlier implementations, IEManager itself is no longer a
 * singleton. Inheriting from singletons is a tricky business in C++ (and
 * much easier in Java) because static methods can't be virtual. Because
 * of this, multiple badly implemented child classes were unable to coexist
 * in a single program.
 *
 * The following has to be done in each protocol to use IEManager and
 * create a protocol-specific singleton (called PROT_IEManager):
 *
 *   - Inherit from IEManager.
 *   - Make the constructor private.
 *   - Provide a "private: static PROT_IEManager *inst" attribute.
 *   - Provide a "public: static PROT_IEManager *instance()" method.
 *   - Provide a "public: static void clear()" method.
 *   - Define your own category_t with categories appropriate for your protocol.
 * 
 * An example implementation can be found in the QSPEC code. Please note that
 * old code (r286 and earlier) won't compile because of interface changes.
 * The ability to register "default" IEs that are returned if no more specific
 * IE is found has been removed because it depended on coding_t. If derived
 * IEManagers need this functionality, they have to override lookup_ie().
 * 
 */
class IEManager {

  public:
        virtual ~IEManager();

        virtual void register_ie(const IE *ie);
        virtual void register_ie(uint16 category, uint16 type, uint16 subtype,
                        const IE *ie);

        virtual IE *new_instance(uint16 category, uint16 type, uint16 subtype);

        virtual void serialize(IE &ie, NetMsg &msg, IE::coding_t coding,
                        uint32 &bytes_written) const;

        virtual IE *deserialize(NetMsg &msg, uint16 category,
                        IE::coding_t coding, IEErrorList& errorlist,
                        uint32 &bytes_read, bool skip = true) = 0;

  protected:
        IEManager();

        virtual IE *lookup_ie(uint16 category, uint16 type, uint16 subtype);

        virtual void throw_nomem_error() const;

  private:
        typedef hash_map<IE_Key, IE *, hash_IE_Key> category_map_t;

        category_map_t registry;
};


/** This mainly calls the serialize member function of the given IE.
 * @param ie pointer to an IE
 * @param msg NetMsg object that will hold the serialized IE.
 * @param coding IE coding sheme
 * @param wbytes number of output bytes
 */
inline
void IEManager::serialize(IE& ie, NetMsg& msg, IE::coding_t coding, uint32& wbytes) const {
        ie.serialize(msg,coding,wbytes);
} // end serialize


/// print an IE to an ostream
ostream& operator<<(ostream& os, const IE& ie);

/// input operator
istream& operator>>(istream& is, IE& ie);

/// round uint32 up
/** Adds up the given uint32 to fit a 32-bit or 4-byte border. */
inline uint32 round_up4(uint32 i) {
        if (i%4) i = i-(i%4)+4;
        return i;
} // end round_up4

//@}

} // end namespace protlib

#endif // _PROTLIB__IE_H_