functions.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_functions_hpp
#define anna_diameter_codec_functions_hpp


// Project
#include <anna/diameter/defines.hpp>
#include <anna/core/RuntimeException.hpp>
#include <anna/xml/xml.hpp>

// STL
#include <string>
#include <vector>


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

// Diameter words are four-byte size. Store n bytes requires 1 word more than former multiple of 4:
#define REQUIRED_WORDS(bytes)  ((bytes)/4+((((bytes)%4)!=0)?1:0 ))



namespace anna {
class DataBlock;
}


namespace anna {

namespace diameter {

namespace codec {


static const char *MessageDTD = "\
<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n\
<!-- Diameter message DTD -->\n\
\n\
<!ELEMENT message (avp*)>\n\
<!ELEMENT avp (avp*)>\n\
\n\
<!ATTLIST message version CDATA #IMPLIED name CDATA #IMPLIED code CDATA #IMPLIED flags CDATA #IMPLIED p-bit (yes | no) #IMPLIED e-bit (yes | no) #IMPLIED t-bit (yes | no) #IMPLIED application-id CDATA #REQUIRED hop-by-hop-id CDATA #IMPLIED end-to-end-id CDATA #IMPLIED>\n\
<!--\n\
   version: Diameter version. Sets '1' by default\n\
   name:    Command name within working stack (dictionary identifier)\n\
   p-bit:   (P)roxiable bit flag (yes, no). By default is 'no'\n\
   e-bit:   (E)rror bit flag (yes, no). By default is 'no'\n\
   t-bit:   Potentially re-(T)ransmitted bit flag (yes, no). By default is 'no'\n\
\n\
   In order to get more coding capabilities, command code and flags could be established instead of former fields,\n\
    but neither of them are allowed if the other are present (and vice versa):\n\
\n\
   code:    Command code\n\
   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\n\
\n\
\n\
   application-id:   Message application id\n\
   hop-by-hop-id:    Message hop by hop id. Sets '0' by default\n\
   end-to-end-id:    Message end to end id. Sets '0' by default\n\
-->\n\
\n\
<!ATTLIST avp name CDATA #IMPLIED code CDATA #IMPLIED vendor-code CDATA #IMPLIED flags CDATA #IMPLIED data CDATA #IMPLIED hex-data CDATA #IMPLIED alias CDATA #IMPLIED>\n\
<!--\n\
   name:   Avp name within working stack (dictionary identifier)\n\
\n\
   In order to get more coding capabilities, avp code, vendor-id and flags could be established instead of former avp name,\n\
    but neither of them are allowed if 'name' is provided (and vice versa):\n\
\n\
   code:          Avp code\n\
   vendor-code:   Avp vendor code\n\
   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)\n\
   alias:         Descriptive/helper field for certain numeric data values. Aliases are defined at diameter dictionary, but are ignored (not checked) at xml message parsing\n\
                  The reason to include it in dtd definition, is because xml messages traced by the diameter codec could add alias field for some Avps\n\
\n\
\n\
   data:          Natural string representation for avp data. Specially applicable with numbers and printable strings, but also\n\
                   useful for certain formats which could be easily understandable in such friendly/smart representation. We will\n\
                   achieve different human-readable strings depending on data format:\n\
\n\
                     [ OctetString ] (if printable, but not recommended)\n\
                     [ Integer32, Integer64, Unsigned32, Unsigned64, Float32, Float64 ] (normal number representation)\n\
                     [ Time ] (NTP timestamp, normal number representation)\n\
                     [ Address ] ('<type (IANA Address Family Number)>|<value>' representation; i.e. '1|192.168.0.1'(IPv4), '8|34616279266'(E164), etc.\n\
                                 Type (and pipe) field could be avoided for IPv4 and IPv6 address types (a light parse checking is done: one colon for\n\
                                 IPv6, one dot for IPv4). Internal engine always includes type on data field, which is also recommended for inputs.\n\
                                 Currently, only IPv4, IPv6 and E164 address types have a known printable presentation, anyway using printable format\n\
                                 for another types will encode the address value directly as E164 does)\n\
                     [ UTF8String, DiameterIdentity, DiameterURI ] (printable)\n\
                     [ IPFilterRule, QoSFilterRule ] (uses ASCII charset, printable)\n\
\n\
                     New application formats must define specific natural representation for internal raw data\n\
\n\
   hex-data:      Hexadecimal octet sequence representation (i.e. 'af012fb3', with even number of digits). Suitable for whatever kind\n\
                   of diameter format, but mandatory for non printable information. OctetString usually transport non human-readable\n\
                   data and should better be encoded within this field although being printable. Unknown avps (which fails identifying\n\
                   provided name or code/vendor-code) must always use this representation.\n\
\n\
   Xml representation for decoded messages shows natural content except for 'OctetString' format and unknown avps. Anyway, when printable,\n\
    OctetString could show such information at data field apart from hex-data, because many implementations use this format to transport\n\
    readable-string data. In general, one of the data fields is mandatory except for 'Grouped' type (its data is another level of avps).\n\
   Application-specific formats must decide the way to represent its contents, being recommended to use a natural representation if possible,\n\
    because xml is read by humans with testing and monitoring purposes.\n\
-->\n\
\n\
";


// Used for alarms, tracing and Failed-AVP construction:
typedef struct parent {

  // Used on decoding:
  anna::diameter::CommandId MessageId;
  std::string MessageName;

  std::vector<anna::diameter::AvpId> AvpsId;
  std::vector<std::string> AvpsName;

  void setMessage(const anna::diameter::CommandId & mid, const char *mname = NULL /* well known in validation */) ;
  void addAvp(const anna::diameter::AvpId & aid, const char *aname = NULL /* well known in validation */) ;
  std::string asString() const ;

} parent_t;




struct functions {

  // getters & helpers
  static CommandId getCommandId(const anna::DataBlock &) noexcept(false);
  static ApplicationId getApplicationId(const anna::DataBlock &) noexcept(false);
  static HopByHop getHopByHop(const anna::DataBlock &) noexcept(false);
  static EndToEnd getEndToEnd(const anna::DataBlock &) noexcept(false);

  static bool requestBit(const anna::DataBlock &) noexcept(false);
  static bool proxiableBit(const anna::DataBlock &) noexcept(false);
  static bool errorBit(const anna::DataBlock &) noexcept(false);
  static bool potentiallyReTransmittedMessageBit(const anna::DataBlock &) noexcept(false);

  static bool isRequest(const CommandId & cid) { return (cid.second); }
  static bool isRequest(const anna::DataBlock & db) noexcept(false) { return requestBit(db); }

  static bool isAnswer(const CommandId & cid) { return (!isRequest(cid)); }
  static bool isAnswer(const anna::DataBlock & db) noexcept(false) { return (!isRequest(db)); }



  static void decodeCommandHeader(const char *start, char & version, U24 & length, char & flags, CommandId & id, int & appId, int & hbh, int & ete) noexcept(false);

  static void decodeAVP(const char *start, AvpId & id, char & flags, int & length, std::string & data) noexcept(false);

  static const char * nextAVP(const char *avpsDB, int avpsLen, const char *start) noexcept(false);

  //  /**
  //  * Gets the next AVP pointer reference starting from a first-avp datablock. It could be the first avp within
  //  * a command, or within an grouped avp.
  //  *
  //  * @param avpsDB AVPs set as datablock
  //  * @param start Point to start the search. Must be a valid avp start (point to the 32-bits avp code word).
  //  *
  //  * @return Pointer to the next AVP found. NULL if no more.
  //  */
  //  static const char * nextAVP(const anna::DataBlock & avpsDB, const char *start) noexcept(false);

  static const char *findAVP(const char *avpsDB, int avpsLen, const diameter::AvpId & id, int n = 1) noexcept(false);

  //  /**
  //  * Gets the next AVP pointer reference within an AVPs set datablock with a certain AVP identification.
  //  *
  //  * @param avpsDB AVPs set as datablock
  //  * @param id Avp identification (code, vendorId).
  //  * @param n Ocurrence number (first avp, second avp, etc.). 1 by default.
  //  *
  //  * @return Pointer to first AVP found with identification provided. NULL if not found.
  //  */
  //  static const char * findAVP(const anna::DataBlock & avpsDB, const AvpId & id, int n = 1) noexcept(false);



  // modifiers
  static void setHopByHop(anna::DataBlock &, HopByHop) noexcept(false);
  static void setEndToEnd(anna::DataBlock &, EndToEnd) noexcept(false);
  static void setPotentiallyReTransmittedMessageBit(const anna::DataBlock & db, bool activate = true) noexcept(false);


  static void messageXmlDocumentFromXmlFile(anna::xml::DocumentFile &xmlDocument, const std::string & xmlPathFile) noexcept(false);

  static void messageXmlDocumentFromXmlString(anna::xml::DocumentMemory &xmlDocument, const std::string &xmlString) noexcept(false);
};


}
}
}


#endif