Message.hpp

Go to the documentation of this file.

// ANNA - Anna is Not Nothingness Anymore                                                         //
//                                                                                                //
// (c) Copyright 2005-2015 Eduardo Ramos Testillano & Francisco Ruiz Rayo                         //
//                                                                                                //
// See project site at http://redmine.teslayout.com/projects/anna-suite                           //
// See accompanying file LICENSE or copy at http://www.teslayout.com/projects/public/anna.LICENSE //


#ifndef anna_diameter_codec_Message_hpp
#define anna_diameter_codec_Message_hpp


// Local
#include <anna/config/defines.hpp>
#include <anna/diameter/defines.hpp>
#include <anna/diameter/codec/Avp.hpp>
#include <anna/diameter/helpers/base/defines.hpp>

#include <anna/core/DataBlock.hpp>
#include <anna/core/RuntimeException.hpp>

// STL
#include <string>

//------------------------------------------------------------------------------
//---------------------------------------------------------------------- #define
//------------------------------------------------------------------------------

namespace anna {
class Node;
}

namespace anna {

namespace diameter {

namespace stack {
class Dictionary;
class Format;
class Command;
}

namespace codec {

class Avp;
class Engine;

class Message {

  U8 a_version;
  CommandId a_id;          // code and request indicator
  U8 a_flags;
  U32 a_applicationId;
  U32 a_hopByHop;
  U32 a_endToEnd;
  avp_container a_avps; // childrens
  find_container a_finds; // fast access for message first-level avps

  // auxiliary
  int a_insertionPositionForChilds; // used with childrens
  anna::DataBlock a_forCode;

  const Avp* _getAvp(const char *name, int ocurrence, anna::Exception::Mode::_v emode) const noexcept(false);

  // --- Developer notes ---
  // 'AVP Length' does not include posible data padding. Thanks to this, 'Data Length'
  // is the difference between 'AVP Length' and sum of code, length, flags and
  // optionally the vendor-ID (all of them are 32-bit boundary), that is to say:
  // 8 or 12 (vendor-specific avps).
  //
  // Grouped avps 'AVP Length' includes own headers plus the total length of all
  //  underlying AVPs, including their headers and padding, then 'AVP Length' is
  //  always multiple of 4 (library will check this), and smae for 'Data Length'
  //  which is an 'whole avp Length with padding' itself.


  // Children helpers

  // Own
  avp_iterator avp_begin() { return a_avps.begin(); }
  avp_iterator avp_end() { return a_avps.end(); }
  const_avp_iterator avp_begin() const { return a_avps.begin(); }
  const_avp_iterator avp_end() const { return a_avps.end(); }

  U24 getLength() const ;


  // Internal
  bool flagsOK(int &rc) const ; // flags coherence regarding dictionary. Only must be called when Message is identified at the dictionary.
  int addChild(Avp *avp) { return Avp::addChild(a_avps, a_insertionPositionForChilds, avp); }
  const anna::diameter::stack::Command *getStackCommand(CommandId id) const noexcept(false);

  void setFailedAvp(const parent_t &parent, AvpId wrong, const char *wrongName = NULL) noexcept(false);
  // During message decoding and validation, the first wrong avp is stored and all the tracking is managed to find out its
  //  nested path for the case of grouped avps with wrong avps inside. Remember the RFC 6733, section 7.5:
  //
  //           In the case where the offending AVP is embedded within a Grouped AVP,
  //           the Failed-AVP MAY contain the grouped AVP, which in turn contains
  //           the single offending AVP.  The same method MAY be employed if the
  //           grouped AVP itself is embedded in yet another grouped AVP and so on.
  //           In this case, the Failed-AVP MAY contain the grouped AVP hierarchy up
  //           to the single offending AVP.  This enables the recipient to detect
  //           the location of the offending AVP when embedded in a group.
  //
  // The first wrong avp found will set the final result code, as the RFC recommends:
  //
  //           The value of the Result-Code AVP will provide information on the reason
  //           for the Failed-AVP AVP.  A Diameter answer message SHOULD contain an
  //           instance of the Failed-AVP AVP that corresponds to the error
  //           indicated by the Result-Code AVP.  For practical purposes, this
  //           Failed-AVP would typically refer to the first AVP processing error
  //           that a Diameter node encounters.
  //
  // The message keeps the list (reverse order) of avps hierarchy (in case of grouping) for the final Failed-AVP construction,
  // which is done at the end of decoding or validation, and only the first wrong avp is stored with its corresponding path.


protected:

  mutable Engine *a_engine;

  virtual Engine * getEngine() const noexcept(false);

  virtual void initialize() ;


public:

  Message(Engine *engine = NULL);

  Message(CommandId id, Engine *engine = NULL);


  void setEngine(Engine *engine) ;


  // Length references
  static const int HeaderLength;


  //    Command Flags
  //    +-+-+-+-+-+-+-+-+
  //    |R P E T r r r r|
  //    +-+-+-+-+-+-+-+-+
  //
  //      R(equest)
  //      P(roxiable)
  //      E(rror)
  //      T(Potentially re-transmitted message)
  //      r(eserved)  - these flag bits are reserved for future use, and
  //                    MUST be set to zero, and ignored by the receiver.
  static const U8 RBitMask;
  static const U8 PBitMask;
  static const U8 EBitMask;
  static const U8 TBitMask;


  virtual ~Message();

  // Virtual destructors are useful when you can delete an instance of a derived class through a pointer to base class:
  // This destructor is not virtual, then a pointer to base class (even pointing to a children one) will invoke this destructor, not the derived one.
  // My current solution: virtualizing method 'clear'
  //
  // Recommendation:
  // To sum up, always make base classes' destructors virtual when they're meant to be manipulated polymorphically.

  // setters

  void setId(CommandId id) noexcept(false);

  void setId(const char *name) noexcept(false);

  void setVersion(U8 version) { a_version = version; }

  void setProxiableBit(bool activate = true) { if(activate) a_flags |= PBitMask; else a_flags &= (~PBitMask); }

  void setErrorBit(bool activate = true) { if(isRequest()) return; if(activate) a_flags |= EBitMask; else a_flags &= (~EBitMask); }

  void setPotentiallyReTransmittedMessageBit(bool activate = true) { if(isAnswer()) return; if(activate) a_flags |= TBitMask; else a_flags &= (~TBitMask); }

  void setApplicationId(U32 aid) noexcept(false);

  void setHopByHop(U32 hbh) { a_hopByHop = hbh; }

  void setEndToEnd(U32 ete) { a_endToEnd = ete; }


  void setHeaderToAnswer(const Message &request) noexcept(false) {
    if(!request.getId().second) return;

    a_engine = request.getEngine(); // we know this will be

    setId(CommandId(request.getId().first, !request.getId().second));
    setVersion(request.getVersion());
    setApplicationId(request.getApplicationId());
    setHopByHop(request.getHopByHop()); // The same Hop-by-Hop Identifier in the request is used in the answer (RFC 6733 Section 6.2).
    setEndToEnd(request.getEndToEnd()); // The same End-to-End Identifier in the request is used in the answer (RFC 6733 Section 6.2).
    setProxiableBit(request.proxiableBit()); // The 'P' bit is set to the same value as the one in the request (RFC 6733 Section 6.2).
  }


  void setStandardToAnswer(const Message &request, const std::string &originHost, const std::string &originRealm, int resultCode = helpers::base::AVPVALUES__Result_Code::DIAMETER_SUCCESS) noexcept(false);


  void setResultCode(int rc = helpers::base::AVPVALUES__Result_Code::DIAMETER_SUCCESS) noexcept(false);


  int getResultCode() const ;


  Avp * addAvp(AvpId id) noexcept(false) { return Avp::addAvp(a_avps, a_insertionPositionForChilds, id, getEngine()); }


  Avp * addAvp(const char *name) noexcept(false);


  Avp * addAvp(Avp * avp) ;


  bool removeAvp(AvpId id, int ocurrence = 1) noexcept(false) { return Avp::removeAvp(a_avps, (find_container&)a_finds, id, ocurrence, getEngine()); }


  bool removeAvp(const char *name, int ocurrence = 1) noexcept(false);


  virtual void clear(bool resetEngine = true) noexcept(false);

  void decode(const anna::DataBlock &db, Message *ptrAnswer = NULL) noexcept(false);

  void fix() ;

  bool valid(Message *ptrAnswer = NULL) const noexcept(false);

  void fromXML(const anna::xml::Node* messageNode) noexcept(false);

  void loadXMLFile(const std::string &xmlPathFile) noexcept(false);

  void loadXMLString(const std::string &xmlString) noexcept(false);


  // getters

  const CommandId & getId() const { return a_id; }

  U8 getVersion() const { return a_version; }

  bool isRequest() const { return a_id.second; }

  bool isAnswer() const { return !isRequest(); }

  const U32 & getApplicationId() const { return a_applicationId; }

  const U32 & getHopByHop() const { return a_hopByHop; }

  const U32 & getEndToEnd() const { return a_endToEnd; }

  const anna::diameter::stack::Command *getStackCommand() const noexcept(false) { return getStackCommand(a_id); }

  bool requestBit() const { return ((a_flags & RBitMask) != 0x00); }

  bool proxiableBit() const { return ((a_flags & PBitMask) != 0x00); }

  bool errorBit() const { return ((a_flags & EBitMask) != 0x00); }

  bool potentiallyReTransmittedMessageBit() const { return ((a_flags & TBitMask) != 0x00); }


  const Avp* getAvp(AvpId id, int ocurrence = 1, anna::Exception::Mode::_v emode = anna::Exception::Mode::Throw) const noexcept(false) {
    return Avp::getAvp(a_avps, (find_container&)a_finds, id, ocurrence, getEngine(), emode);
  }

  Avp* getAvp(AvpId id, int ocurrence = 1, anna::Exception::Mode::_v emode = anna::Exception::Mode::Throw) noexcept(false) {
    return const_cast<Avp*>(Avp::getAvp(a_avps, (find_container&)a_finds, id, ocurrence, getEngine(), emode));
  }


  const Avp* getAvp(const char *name, int ocurrence = 1, anna::Exception::Mode::_v emode = anna::Exception::Mode::Throw) const noexcept(false) {
    return _getAvp(name, ocurrence, emode);
  }

  Avp* getAvp(const char *name, int ocurrence = 1, anna::Exception::Mode::_v emode = anna::Exception::Mode::Throw) noexcept(false) {
    return const_cast<Avp*>(_getAvp(name, ocurrence, emode));
  }

// Helpers

  int countAvp(AvpId id) const { return Avp::countAvp(a_avps, id); }

  int countAvp(const char *name) const noexcept(false);

  int countChilds() const { return Avp::countChilds(a_avps); }

  const anna::DataBlock & code() noexcept(false);

  anna::xml::Node* asXML(anna::xml::Node* parent) const ;

  std::string asXMLString(bool normalize = false) const ;

  friend bool operator == (const Message & m1, const Message & m2) { return (m1.asXMLString() == m2.asXMLString()); }

  bool isLike(const std::string &pattern) const ;


//friend class Engine;
  friend class Avp;
};

}
}
}


#endif