Changing license to New BSD (3-Clause version)

[anna.git] / include / anna / diameter / codec / Message.hpp

// ANNA - Anna is Not Nothingness Anymore
//
// (c) Copyright 2005-2014 Eduardo Ramos Testillano & Francisco Ruiz Rayo
//
// http://redmine.teslayout.com/projects/anna-suite
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions
// are met:
//
//     * Redistributions of source code must retain the above copyright
// notice, this list of conditions and the following disclaimer.
//     * Redistributions in binary form must reproduce the above
// copyright notice, this list of conditions and the following disclaimer
// in the documentation and/or other materials provided with the
// distribution.
//     *  Neither the name of the copyright holder nor the names of its
// contributors may be used to endorse or promote products derived from
// this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
//
// Authors: eduardo.ramos.testillano@gmail.com
//          cisco.tierra@gmail.com


#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;

/**
* Diameter message generic container
* <pre>
*    RFC 3588                Diameter Based Protocol           September 2003
*    3.  Diameter Header
*
*       A summary of the Diameter header format is shown below.  The fields
*       are transmitted in network byte order.
*
*        0                   1                   2                   3
*        0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
*       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
*       |    Version    |                 Message Length                |
*       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
*       | command flags |                  Command-Code                 |
*       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
*       |                         Application-ID                        |
*       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
*       |                      Hop-by-Hop Identifier                    |
*       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
*       |                      End-to-End Identifier                    |
*       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
*       |  AVPs ...
*       +-+-+-+-+-+-+-+-+-+-+-+-+-
* </pre>
*/
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 throw(anna::RuntimeException);

  // --- 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() throw() { return a_avps.begin(); }
  avp_iterator avp_end() throw() { return a_avps.end(); }
  const_avp_iterator avp_begin() const throw() { return a_avps.begin(); }
  const_avp_iterator avp_end() const throw() { return a_avps.end(); }

  /**
  * Gets avp total message length.
  */
  U24 getLength() const throw();


  // Internal
  bool flagsOK(int &rc) const throw(); // flags coherence regarding dictionary. Only must be called when Message is identified at the dictionary.
  int addChild(Avp *avp) throw() { return Avp::addChild(a_avps, a_insertionPositionForChilds, avp); }
  const anna::diameter::stack::Command *getStackCommand(CommandId id) const throw(anna::RuntimeException);
  Avp * addFailedAVP() throw(); // returns Failed-AVP if exists, creates it when missing

protected:

  /** Codec Engine */
  mutable Engine *a_engine;

  /** Codec Engine getter: avoids have to create base engine when using its child */
  virtual Engine * getEngine() const throw(anna::RuntimeException);

  /**
  * Initializes Message class information.
  * Any reimplementation must first invoke base class method.
  */
  virtual void initialize() throw();


public:

  /**
  * Default constructor
  */
  Message();

  /**
  * Identified constructor
  * @param id Command identifier as pair (code,request-indicator).
  */
  Message(CommandId id);


  // 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;


  /**
  * Destructor
  */
  ~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

  /**
     Sets the command identifier and clear the former content.

     @param id Command identifier as pair (code,request-indicator).
     @param _clear Message will be cleared when updating the command identifier (default behaviour).
  */
  void setId(CommandId id, bool _clear = true) throw(anna::RuntimeException);

  /**
     Same as #setId but providing dictionary logical name for Avp searched
  */
  void setId(const char *name) throw(anna::RuntimeException);

  /**
     Sets the command version. By default, messages initializes with value 1.

     @param version Version provided
  */
  void setVersion(U8 version) throw() { a_version = version; }

  /**
     Sets/unsets P bit activation.
     Application should not have to use this because dictionary information is used in order to configure flags when Message identifier is stored.

     @param activate Activates/deactivates the bit. True by default.
  */
  void setProxiableBit(bool activate = true) throw() { if(activate) a_flags |= PBitMask; else a_flags &= (~PBitMask); }

  /**
     Sets/unsets E bit activation.
     Application should not have to use this because dictionary information is used in order to configure flags when Message identifier is stored.

     @param activate Activates/deactivates the bit. True by default.
  */
  void setErrorBit(bool activate = true) throw() { if(activate) a_flags |= EBitMask; else a_flags &= (~EBitMask); }

  /**
     Sets/unsets T bit activation.
     Application should not have to use this because dictionary information is used in order to configure flags when Message identifier is stored.

     @param activate Activates/deactivates the bit. True by default.
  */
  void setPotentiallyReTransmittedMessageBit(bool activate = true) throw() { if(activate) a_flags |= TBitMask; else a_flags &= (~TBitMask); }

  /**
     Sets the message application id
     @param aid Application-id.
  */
  void setApplicationId(U32 aid) throw() { a_applicationId = aid; }

  /**
     Sets the message hop-by-hop
     @param hbh Hop-by-hop identifier.
  */
  void setHopByHop(U32 hbh) throw() { a_hopByHop = hbh; }

  /**
     Sets the message end-to-end
     @param ete End-to-end identifier.
  */
  void setEndToEnd(U32 ete) throw() { a_endToEnd = ete; }


  /**
     Sets header to be an answer regarding provided request message code.
     Internally, updates command identifier (indeed request flag), promotes version, application identifier, hop-by-hop and end-to-end fields.

     @param request Message to be answered.

     @warning Request provided must be a request, in other case method do nothing.
  */
  void setHeaderToAnswer(const Message &request) throw() {
    if(!request.getId().second) return;

    setId(CommandId(request.getId().first, !request.getId().second), false /* don't clear */);
    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).
  }


  /**
    Standard minimum-answer building from requests. Adds Session-Id (mirrored from request if present), Origin-Host and Origin-Realm
    (which could be configured, extracted from optional Destination AVPs, etc.), and all the Proxy-Info AVPs (added in same order as
    appear on the request). Of course, answer message header is built from request information through #setHeaderToAnswer. Finally,
    message is fixed regarding dictionary elements order (#fix).

    Summing up, as RFC 6733 Section 6.2, says:

    <pre>

        6.2.  Diameter Answer Processing

           When a request is locally processed, the following procedures MUST be
           applied to create the associated answer, in addition to any
           additional procedures that MAY be discussed in the Diameter
           application defining the command:

           o  The same Hop-by-Hop Identifier in the request is used in the
              answer.

           o  The local host's identity is encoded in the Origin-Host AVP.

           o  The Destination-Host and Destination-Realm AVPs MUST NOT be
              present in the answer message.

           o  The Result-Code AVP is added with its value indicating success or
              failure.

           o  If the Session-Id is present in the request, it MUST be included
              in the answer.

           o  Any Proxy-Info AVPs in the request MUST be added to the answer
              message, in the same order they were present in the request.

           o  The 'P' bit is set to the same value as the one in the request.

           o  The same End-to-End identifier in the request is used in the
              answer.

           Note that the error messages (see Section 7) are also subjected to
           the above processing rules.

   Regarding errors, is recommended to use this over automatic answer built at #decode and/or #valid procedures, which would had added
   Result-Code and/or Failed-AVP AVPs if proceed, but be aware of DIAMETER_COMMAND_UNSUPPORTED Result-Code, because becomes impossible
   to fix (Session-Id SHOULD appear immediately following the Diameter header, and #fix do this manually even if no information about
   the command structure is known, but perhaps another fixed AVPs could not comply... use #getResultCode to find out this situation before
   using #setStandardToAnswer).

   If application decoding and/or validation operations are ok, user may search for other problems and put the appropiate Result-Code.
   For example, DIAMETER_TOO_BUSY (3004) depends on congestion issues at business layer and cannot be decided with the only message
   information automatically (not all the Result-Code values are taken into account, only those which correspond to anomalies managed
   by anna::diameter::codec). Application Result-Codes could be provided in this prototype, being DIAMETER_SUCCESS the default value if missing.

   </pre>
   @param request Message to be answered.
   @param originHost Mandatory Origin-Host diameter identity value provided by application. If answer has already an Origin-Host, this will be ignored.
   @param originRealm Mandatory Origin-Realm diameter identity value provided by application. If answer has already an Origin-Realm, this will be ignored.
   @param resultCode Result-Code value assigned by application. If non-success value is already assigned, this will be ignored. DIAMETER_SUCCESS is provided by default.

   @warning Request provided must be a request, in other case method do nothing.
  */
  void setStandardToAnswer(const Message &request, const std::string &originHost, const std::string &originRealm, int resultCode = helpers::base::AVPVALUES__Result_Code::DIAMETER_SUCCESS) throw();


  /**
     Sets a Result-Code AVP over an answer message (for requests, do nothing).
     If Result-Code AVP doesn't exists, is added and then filled with the value provided.
     If Result-Code AVP already exists, value detected is replaced if was DIAMETER_SUCCESS (non success codes are unchanged).
     When provided value corresponds to an protocol error, that is to say within range [3001,3010], message (E)rror bit is
     automatically activated.

     This method is internally used during #decode and/or #valid procedures in order to build automatic answers, but application
     could call this for set another Result-Code no detected by these methods within its category or for other one (application
     layer). These are the Result-Codes implemented (detected) by ANNA::diameter::codec:

     <pre>
        Protocol Errors:

           DIAMETER_COMMAND_UNSUPPORTED
           DIAMETER_INVALID_HDR_BITS
           DIAMETER_INVALID_AVP_BITS

        Permanent Failures:

           DIAMETER_AVP_UNSUPPORTED (F)
           DIAMETER_INVALID_AVP_VALUE (F)
           DIAMETER_MISSING_AVP (F)
           DIAMETER_AVP_NOT_ALLOWED (F)
           DIAMETER_AVP_OCCURS_TOO_MANY_TIMES (F)
           DIAMETER_INVALID_BIT_IN_HEADER
           DIAMETER_INVALID_AVP_LENGTH (F)
           DIAMETER_INVALID_MESSAGE_LENGTH

           (F) Generates Failed-AVP (also DIAMETER_CONTRADICTING_AVPS and DIAMETER_INVALID_AVP_BIT_COMBO
                                     values does, but these are not managed by anna::diameter::codec).
     </pre>

     @param rc Result-Code value. DIAMETER_SUCCESS by default.
  */
  void setResultCode(int rc = helpers::base::AVPVALUES__Result_Code::DIAMETER_SUCCESS) throw(anna::RuntimeException);


  /**
     Gets the Result-Code AVP value from an answer message (for requests, returns -1).
     If missing, -1 value is returned.

     @return Result-Code value for answers, -1 for request and answers without Result-Code AVP inside
  */
  int getResultCode() const throw();


  /**
     Adds a new AVP within a Failed-AVP over an answer message (for requests, do nothing).
     If Failed-AVP AVP doesn't exists, is added and then filled (added within) with the value provided (empty AVP id representantion).
     If Failed-AVP AVP already exists, is filled (added within) with the value provided (empty AVP id representantion).

     This method is internally used during #decode and/or #valid procedures in order to build automatic answers.

     @param id Avp identifier as pair (code,vendor-id).

     @return Pointer to the new AVP added within Failed-AVP, to make easy data-part accessif needed.
  */
  Avp * setNewFailedAvp(AvpId id) throw(anna::RuntimeException) { if(isRequest()) return NULL; return (addFailedAVP()->addAvp(id)); }

  /**
     Adds a new AVP within a Failed-AVP over an answer message (for requests, do nothing).
     If Failed-AVP AVP doesn't exists, is added and then filled (added within) with the value provided (empty AVP id representantion).
     If Failed-AVP AVP already exists, is filled (added within) with the value provided (empty AVP id representantion).

     This method is internally used during #decode and/or #valid procedures in order to build automatic answers, but application
     could call this for set another Failed-AVP content no detected by these methods, for example: DIAMETER_CONTRADICTING_AVPS or
     DIAMETER_INVALID_AVP_BIT_COMBO).

     @param id Avp identifier as pair (code,vendor-id).

     @return Pointer to the new AVP added within Failed-AVP, to make easy data-part accessif needed.
  */
  Avp * setNewFailedAvp(Avp *avp) throw() { if(!avp || isRequest()) return NULL; return (addFailedAVP()->addAvp(avp)); }


  /**
     Adds an avp child providing its identifier and reserve internal memory it.

     @param id Avp identifier as pair (code,vendor-id).

     @return Pointer to the new created avp.
  */
  Avp * addAvp(AvpId id) throw(anna::RuntimeException) { return Avp::addAvp(a_avps, a_insertionPositionForChilds, id, getEngine()); }


  /**
     Same as #addAvp but providing dictionary logical name for Avp searched
  */
  Avp * addAvp(const char *name) throw(anna::RuntimeException);


  /**
     Adds an avp child providing a persistent pointer (must be maintained by application).

     @param avp Avp external pointer. If NULL provided, nothing is done and NULL returned.

     @return Pointer to the added avp (again).
  */
  Avp * addAvp(Avp * avp) throw() { if(!avp) return NULL; addChild(avp); return avp; }


  /**
     Removes an Avp within message (first level) and free resources.

     @param id Avp identifier (pair code + vendor-id).
     @param ocurrence Order of appearance for the searched avp. Zero value means remove all avps with provided identifier at first level (no recursiveness would be allowed in the API in order to avoid unexpected behaviour).
     Negative values could be used to reverse access positions: i.e. -1 is the last ocurrence, -2 is the second to last (penultimate), etc.

     @return Returns true if something was removed. False in other cases (including i.e. when this message is empty).
  */
  bool removeAvp(AvpId id, int ocurrence = 1) throw(anna::RuntimeException) { return Avp::removeAvp(a_avps, (find_container&)a_finds, id, ocurrence, getEngine()); }


  /**
     Same as #removeAvp but providing dictionary logical name for Avp searched
  */
  bool removeAvp(const char *name, int ocurrence = 1) throw(anna::RuntimeException);


  /**
  * Clears and initializes Message class information.
  * Application must clear auxiliary message objects before adding Avps in a new context.
  * Application don't need to clear a message object before decode operation (decode invokes #clear before any other task).
  * Any reimplementation must first invoke base class method.
  */
  virtual void clear() throw(anna::RuntimeException);

  /**
     Decodes buffer provided over class content. If an error ocurred, decoding will stop launching exception (fatal error) or a warning trace (perhaps the achieved
     message is valid against all odds then validation will go on). In case that validation is enabled (codec::Engine::ValidationMode) an exception will be launched
     in a moment which depends on validation depth (codec::Engine::ValidationDepth).

     @param db buffer data block processed. Before decoding, the whole message instance will be cleared (no need to invoke #clear before #decode).
     @param ptrAnswer Answer set by application (could be empty or not), who is responsible for its memory reservation,
     and automatically built regarding standard. If message analyzed realizes to be an answer, internal reference becomes
     NULL because no answer is built for answers. By default, automatic answer is not built.
  */
  void decode(const anna::DataBlock &db, Message *ptrAnswer = NULL) throw(anna::RuntimeException);

  /**
    Fix childrens content regarding dictionary avp positions.
    Message could remain invalid because of possible fixed/mandatory avps.
    This is useful to give flexibility to the application during message construction before encoding or representing the data.
    Is not recommended to fix a recently decoded message because possible validation problems will be hidden.
  */
  void fix() throw();

  /**
     Validates the message regarding dictionary rules like enumerated range, flags coherence, mandatory and fixed types, cardinality qualifiers, etc.
     @return Boolean indicating validation result
     @param ptrAnswer Answer set by application (could be empty or not), who is responsible for its memory reservation,
     and automatically built regarding standard. If message analyzed realizes to be an answer, internal reference becomes
     NULL because no answer is built for answers. By default, automatic answer is not built.
  */
  bool valid(Message *ptrAnswer = NULL) const throw(anna::RuntimeException);


  /**
     Interpret xml data in order to dump over the class content.
     \param messageNode Message root node
  */
  void fromXML(const anna::xml::Node* messageNode) throw(anna::RuntimeException);

  /**
     Interpret xml string representation in order to dump over the class content.
     DTD validation is used in the same way that #loadXML does.
     \param xmlString XML string representation with relevant information for this instance
  */
  void fromXMLString(const std::string &xmlString) throw(anna::RuntimeException);

  /**
     Loads an xml file based on this message DTD (could be accumulative, no initialization will be performed by this method).

     <pre>
     <!ELEMENT message (avp*)>
     <!ELEMENT avp (avp*)>

     <!ATTLIST message version CDATA #IMPLIED name CDATA #IMPLIED code CDATA #IMPLIED flags CDATA #IMPLIED application-id CDATA #REQUIRED hop-by-hop-id CDATA #IMPLIED end-by-end-id CDATA #IMPLIED>
     <!--
        version: Diameter version. Sets '1' by default
        name:    Command name within working stack (dictionary identifier)

        In order to get more coding capabilities, command code and flags could be established instead of former command name,
         but neither of them are allowed if 'name' is provided (and vice versa):

        code:    Command code
        flags:   Command flags byte value (0-255) where standard bit set for flags is 'RPET rrrr': (R)equest, (P)roxiable, (E)rror, Potentially re-(T)ransmitted message and (r)eserved


        application-id:   Message application id
        hop-by-hop-id:    Message hop by hop id. Sets '0' by default
        end-by-end-id:    Message end by end id. Sets '0' by default
     -->

     <!ATTLIST avp name CDATA #IMPLIED code CDATA #IMPLIED vendor-code CDATA #IMPLIED flags CDATA #IMPLIED data CDATA #IMPLIED hex-data CDATA #IMPLIED>
     <!--
        name:   Avp name within working stack (dictionary identifier)

        In order to get more coding capabilities, avp code, vendor-id and flags could be established instead of former avp name,
         but neither of them are allowed if 'name' is provided (and vice versa):

        code:          Avp code
        vendor-code:   Avp vendor code
        flags:         Avp flags byte value (0-255) where standard bit set for flags is 'VMPr rrrr': (V)endor-specific, (M)andatory, end to end encry(P)tion and r(eserved)


        data:          Natural string representation for avp data. Specially applicable with numbers and printable strings, but also
                        useful for certain formats which could be easily understandable in such friendly/smart representation. We will
                        achieve different human-readable strings depending on data format:

                          [ OctetString ] (if printable, but not recommended)
                          [ Integer32, Integer64, Unsigned32, Unsigned64, Float32, Float64 ] (normal number representation)
                          [ Time ] (NTP timestamp, normal number representation)
                          [ Address ] (auto detects IPv4 or IPv6 address version, then only ip address is specified: IPv4 with dots, IPv6 with colons)
                          [ UTF8String, DiameterIdentity, DiameterURI ] (printable)
                          [ IPFilterRule, QoSFilterRule ] (uses ASCII charset, printable)

                          New application formats must define specific natural representation for internal raw data

        hex-data:      Hexadecimal octet sequence representation (i.e. 'af012fb3', with even number of digits). Suitable for whatever kind
                        of diameter format, but mandatory for non printable information. OctetString usually transport non human-readable
                        data and should better be encoded within this field although being printable. Unknown avps (which fails identifying
                        provided name or code/vendor-code) must always use this representation.

        Xml representation for decoded messages shows natural content except for 'OctetString' format and unknown avps. Anyway, when printable,
         OctetString could show such information at data field apart from hex-data, because many implementations use this format to transport
         readable-string data. In general, one of the data fields is mandatory except for 'Grouped' type (its data is another level of avps).
        Application-specific formats must decide the way to represent its contents, being recommended to use a natural representation if possible,
         because xml is read by humans with testing and monitoring purposes.
     -->
     </pre>

     @param xmlPathFile Complete path file to the xml document which represents the diameter message
     @see fromXMLString
  */
  void loadXML(const std::string & xmlPathFile) throw(anna::RuntimeException);



  // getters

  /**
     Gets Message identifier as pair (code, request indicator).
  */
  const CommandId & getId() const throw() { return a_id; }

  /**
     Gets the command version. By default, messages initializes with value 1.

     @return version Message version
  */
  U8 getVersion() const throw() { return a_version; }

  /**
     Gets Message request indicator.
  */
  bool isRequest() const throw() { return a_id.second; }

  /**
     Gets Message answer indicator.
  */
  bool isAnswer() const throw() { return !isRequest(); }

  /**
     Gets the message application id
     @return aid Application-id.
  */
  const U32 & getApplicationId() const throw() { return a_applicationId; }

  /**
     Gets the message hop-by-hop
     @return hbh Hop-by-hop identifier.
  */
  const U32 & getHopByHop() const throw() { return a_hopByHop; }

  /**
     Gets the message end-to-end
     @return ete End-to-end identifier.
  */
  const U32 & getEndToEnd() const throw() { return a_endToEnd; }

  /**
     Gets stack command (dictionary command reference).
  */
  const anna::diameter::stack::Command *getStackCommand() const throw(anna::RuntimeException) { return getStackCommand(a_id); }

  /** Returns R bit activation state */
  bool requestBit() const throw() { return ((a_flags & RBitMask) != 0x00); }

  /** Returns P bit activation state */
  bool proxiableBit() const throw() { return ((a_flags & PBitMask) != 0x00); }

  /** Returns E bit activation state */
  bool errorBit() const throw() { return ((a_flags & EBitMask) != 0x00); }

  /** Returns T bit activation state */
  bool potentiallyReTransmittedMessageBit() const throw() { return ((a_flags & TBitMask) != 0x00); }


  /**
     Access content for internal Avps. Exception mode allows different combinations like cascade access:
     <pre>

        try {
           message->getAvp(anna::diameter::helpers::base::AVP__Multiple_Services_Credit_Control, anna::Exception::Mode::Throw)
                  ->getAvp(anna::diameter::helpers::base::AVP__Rating_Group, anna::Exception::Mode::Throw);
        }
        catch(anna::RuntimeException) {;}
     </pre>

     Or step access:

     <pre>
        const Avp *mscc = message->getAvp(anna::diameter::helpers::base::AVP__Multiple_Services_Credit_Control);
        const Avp *rg;
        if (mscc) rg = mscc->getAvp(anna::diameter::helpers::base::AVP__Rating_Group);
     </pre>

     Replacing procedures becomes easy because an Avp can be searched and its pointer reconfigured by mean #setId and data part setters.
     Deleting procedures must use #removeAvp.
     Access is internally cached to speed up the search operations. This cache is reset after calling #fix or #removeAvp methods.

     @param id Avp identifier (pair code + vendor-id).
     @param ocurrence Order of appearance for the searched avp. Zero position is rejected, but negative values could be used to reverse
     access positions: i.e. -1 is the last ocurrence, -2 is the second to last (penultimate), etc.
     @param emode Excepcion mode handling: Ignore (no action is taken), Throw (excepcion when missing avp), Trace (trace situation as warning).
  */
  const Avp* getAvp(AvpId id, int ocurrence = 1, anna::Exception::Mode::_v emode = anna::Exception::Mode::Throw) const throw(anna::RuntimeException) {
    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) throw(anna::RuntimeException) {
    return const_cast<Avp*>(Avp::getAvp(a_avps, (find_container&)a_finds, id, ocurrence, getEngine(), emode));
  }


  /**
     Same as #getAvp but providing dictionary logical name for Avp searched
  */
  const Avp* getAvp(const char *name, int ocurrence = 1, anna::Exception::Mode::_v emode = anna::Exception::Mode::Throw) const throw(anna::RuntimeException) {
    return _getAvp(name, ocurrence, emode);
  }

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

// Helpers

  /**
     Counts the number of ocurrences of Avps (first level) with the identifier provided

     @param id Avp identifier (pair code + vendor-id).
  */
  int countAvp(AvpId id) const throw() { return Avp::countAvp(a_avps, id); }

  /**
     Same as #countAvp but providing dictionary logical name for Avp searched
  */
  int countAvp(const char *name) const throw(anna::RuntimeException);

  /**
     Counts the number of children

     @param id Avp identifier (pair code + vendor-id).
  */
  int countChilds() const throw() { return Avp::countChilds(a_avps); }

  /**
     Encodes datablock with the class content. In case that validation is enabled (codec::Engine::ValidationMode) an exception will be launched
     in a moment which depends on validation depth (codec::Engine::ValidationDepth). If you want to see validation errors but go on with encoding,
     you should try/catch #valid() procedure out of #code.

     @return DataBlock encoded (internal memory used)
  */
  const anna::DataBlock & code() throw(anna::RuntimeException);

  /**
     Class xml representation
     \param parent Parent XML node on which hold this instance information.
     \return XML document with relevant information for this instance.
  */
  anna::xml::Node* asXML(anna::xml::Node* parent) const throw();

  /**
     Class xml string representation
     \return XML string representation with relevant information for this instance.
  */
  std::string asXMLString() const throw();

  /**
     Comparison operator

     @param m1 Instance 1 for Message class
     @param m2 Instance 2 for Message class

     @return Comparison result
  */
  friend bool operator == (const Message & m1, const Message & m2) throw() { return (m1.asXMLString() == m2.asXMLString()); }

  /**
     Match a regular expression (string pattern) regarding xml string serialization for this message.
     Using a complex pattern (many avps, grouped ones) it could be necessary to fix the message before
     using the method in order to perform a more controlled comparison. In the same way, flags could be
     ignored to simplify message xml presentation.
     This powerful tool could be used to program traffic analysis and decide future behaviour (routing,
     traslation, etc.).

     <pre>
     Examples:

     The pattern '<avp name="Service-Context-Id" data="(.)*32251@3gpp.org"/>' detects PS charging contexts
     because of data suffix specification '32251@3gpp.org' for that AVP.

     The pattern '<message version="1" name="Capabilities-Exchange-Request"' detects a CER message.

     The pattern (string including carriage returns):

     '<avp name="Subscription-Id">
        <avp name="Subscription-Id-Type" data="0" alias="END_USER_E164"/>
        <avp name="Subscription-Id-Data" data="606000106"/>
     </avp>'

     detects MSISDN (not IMSI) equal to 606000106

     It would seems strange or 'creative' to use regular expressions within an hex string representation,
     but anyway you could also do such kind of things to check non-printable data parts within the message:
     for example, the pattern '<avp name="Framed-IP-Address" hex-data="0a[A-Fa-f0-9][A-Fa-f0-9]0a0a"/>'
     matchs IP addresses for '10.x.10.10' where x = [0..255].

     Note that string pattern could also be generated via #loadXML and then #asXML, that is to say, you
     could get patterns through xml files which act as conditional triggers over message. In that case,
     it is not possible to specify regular expressions within xml 'hex-data' fields because parser will fail
     during hexadecimal read. Normally only printable 'data' fields are used for matching issues.

     For example, imagine a 'pattern.xml' file like:
     <message version="1" name="Credit-Control-Request" application-id="16777236" hop-by-hop-id="0" end-by-end-id="0">
        <avp name="Subscription-Id">
           <avp name="Subscription-Id-Type" data="0" alias="END_USER_E164"/>
           <avp name="Subscription-Id-Data" data="616[0-9]{6,6}"/>
        </avp>
     </message>

     Then you could do:

     anna::diameter::codec::Message patternMessage;
     patternMessage.loadXML("pattern.xml");
     std::string pattern = patternMessage.getAvp("Subscription-Id")->getAvp("Subscription-Id-Type")->asXMLString();
     // Former is '<avp name="Subscription-Id-Data" data="616[0-9]{6,6}"/>'
     bool match = incomingMessage.isLike(pattern);

     Then, messages having MSISDN numbers starting with '616' will match the pattern.
     Note, that any other message codes (and not only Credit-Control-Request ones), could pass the test...
     You could also build that string manually:

     Example 1:
     std::string pattern = "<avp name=\"Subscription-Id\">\n";
     pattern += ANNA_XML_COMPILER_TAB; pattern += "<avp name=\"Subscription-Id-Type\" data=\"0\" alias=\"END_USER_E164\"/>\n"
     pattern += ANNA_XML_COMPILER_TAB; pattern += "<avp name=\"Subscription-Id-Data\" data=\"616[0-9]{6,6}\"/>"

     Example 2:
     std::string pattern = "name=\"Subscription-Id\"(.)*name=\"Subscription-Id-Type\" data=\"0\"(.)*name=\"Subscription-Id-Data\" data=\"616[0-9]{6,6}\"";
     </pre>

     \return Returns the match result
  */
  bool isLike(const std::string &pattern) const throw();


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

}
}
}


#endif