include/anna/diameter/codec/functions.hpp

   1 // ANNA - Anna is Not Nothingness Anymore                                                         //
   2 //                                                                                                //
   3 // (c) Copyright 2005-2015 Eduardo Ramos Testillano & Francisco Ruiz Rayo                         //
   4 //                                                                                                //
   5 // See project site at http://redmine.teslayout.com/projects/anna-suite                           //
   6 // See accompanying file LICENSE or copy at http://www.teslayout.com/projects/public/anna.LICENSE //
   7
   8
   9 #ifndef anna_diameter_codec_functions_hpp
  10 #define anna_diameter_codec_functions_hpp
  11
  12
  13 // Project
  14 #include <anna/diameter/defines.hpp>
  15 #include <anna/core/RuntimeException.hpp>
  16 #include <anna/xml/xml.hpp>
  17
  18 // STL
  19 #include <string>
  20 #include <vector>
  21
  22
  23 //------------------------------------------------------------------------------
  24 //---------------------------------------------------------------------- #define
  25 //------------------------------------------------------------------------------
  26
  27 // Diameter words are four-byte size. Store n bytes requires 1 word more than former multiple of 4:
  28 #define REQUIRED_WORDS(bytes)  ((bytes)/4+((((bytes)%4)!=0)?1:0 ))
  29
  30
  31
  32 namespace anna {
  33 class DataBlock;
  34 }
  35
  36
  37 namespace anna {
  38
  39 namespace diameter {
  40
  41 namespace codec {
  42
  43
  44 static const char *MessageDTD = "\
  45 <?xml version=\"1.0\" encoding=\"UTF-8\"?>\n\
  46 <!-- Diameter message DTD -->\n\
  47 \n\
  48 <!ELEMENT message (avp*)>\n\
  49 <!ELEMENT avp (avp*)>\n\
  50 \n\
  51 <!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-by-end-id CDATA #IMPLIED>\n\
  52 <!--\n\
  53    version: Diameter version. Sets '1' by default\n\
  54    name:    Command name within working stack (dictionary identifier)\n\
  55    p-bit:   (P)roxiable bit flag (yes, no). By default is 'no'\n\
  56    e-bit:   (E)rror bit flag (yes, no). By default is 'no'\n\
  57    t-bit:   Potentially re-(T)ransmitted bit flag (yes, no). By default is 'no'\n\
  58 \n\
  59    In order to get more coding capabilities, command code and flags could be established instead of former fields,\n\
  60     but neither of them are allowed if the other are present (and vice versa):\n\
  61 \n\
  62    code:    Command code\n\
  63    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\
  64 \n\
  65 \n\
  66    application-id:   Message application id\n\
  67    hop-by-hop-id:    Message hop by hop id. Sets '0' by default\n\
  68    end-by-end-id:    Message end by end id. Sets '0' by default\n\
  69 -->\n\
  70 \n\
  71 <!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\
  72 <!--\n\
  73    name:   Avp name within working stack (dictionary identifier)\n\
  74 \n\
  75    In order to get more coding capabilities, avp code, vendor-id and flags could be established instead of former avp name,\n\
  76     but neither of them are allowed if 'name' is provided (and vice versa):\n\
  77 \n\
  78    code:          Avp code\n\
  79    vendor-code:   Avp vendor code\n\
  80    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\
  81    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\
  82                   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\
  83 \n\
  84 \n\
  85    data:          Natural string representation for avp data. Specially applicable with numbers and printable strings, but also\n\
  86                    useful for certain formats which could be easily understandable in such friendly/smart representation. We will\n\
  87                    achieve different human-readable strings depending on data format:\n\
  88 \n\
  89                      [ OctetString ] (if printable, but not recommended)\n\
  90                      [ Integer32, Integer64, Unsigned32, Unsigned64, Float32, Float64 ] (normal number representation)\n\
  91                      [ Time ] (NTP timestamp, normal number representation)\n\
  92                      [ Address ] ('<type (IANA Address Family Number)>|<value>' representation; i.e. '1|192.168.0.1'(IPv4), '8|34616279266'(E164), etc.\n\
  93                                  Type (and pipe) field could be avoided for IPv4 and IPv6 address types (a light parse checking is done: one colon for\n\
  94                                  IPv6, one dot for IPv4). Internal engine always includes type on data field, which is also recommended for inputs.\n\
  95                                  Currently, only IPv4, IPv6 and E164 address types have a known printable presentation, anyway using printable format\n\
  96                                  for another types will encode the address value directly as E164 does)\n\
  97                      [ UTF8String, DiameterIdentity, DiameterURI ] (printable)\n\
  98                      [ IPFilterRule, QoSFilterRule ] (uses ASCII charset, printable)\n\
  99 \n\
 100                      New application formats must define specific natural representation for internal raw data\n\
 101 \n\
 102    hex-data:      Hexadecimal octet sequence representation (i.e. 'af012fb3', with even number of digits). Suitable for whatever kind\n\
 103                    of diameter format, but mandatory for non printable information. OctetString usually transport non human-readable\n\
 104                    data and should better be encoded within this field although being printable. Unknown avps (which fails identifying\n\
 105                    provided name or code/vendor-code) must always use this representation.\n\
 106 \n\
 107    Xml representation for decoded messages shows natural content except for 'OctetString' format and unknown avps. Anyway, when printable,\n\
 108     OctetString could show such information at data field apart from hex-data, because many implementations use this format to transport\n\
 109     readable-string data. In general, one of the data fields is mandatory except for 'Grouped' type (its data is another level of avps).\n\
 110    Application-specific formats must decide the way to represent its contents, being recommended to use a natural representation if possible,\n\
 111     because xml is read by humans with testing and monitoring purposes.\n\
 112 -->\n\
 113 \n\
 114 ";
 115
 116
 117
 118
 119 // Used for alarms, tracing and Failed-AVP construction:
 120 typedef struct parent {
 121
 122   // Used on decoding:
 123   anna::diameter::CommandId MessageId;
 124   std::string MessageName;
 125
 126   std::vector<anna::diameter::AvpId> AvpsId;
 127   std::vector<std::string> AvpsName;
 128
 129   void setMessage(const anna::diameter::CommandId & mid, const char *mname = NULL /* well known in validation */) throw();
 130   void addAvp(const anna::diameter::AvpId & aid, const char *aname = NULL /* well known in validation */) throw();
 131   std::string asString() const throw();
 132
 133 } parent_t;
 134
 135
 136
 137
 138 struct functions {
 139
 140   // getters & helpers
 141   static CommandId getCommandId(const anna::DataBlock &) throw(anna::RuntimeException);
 142   static ApplicationId getApplicationId(const anna::DataBlock &) throw(anna::RuntimeException);
 143   static HopByHop getHopByHop(const anna::DataBlock &) throw(anna::RuntimeException);
 144   static EndToEnd getEndToEnd(const anna::DataBlock &) throw(anna::RuntimeException);
 145
 146   static bool requestBit(const anna::DataBlock &) throw(anna::RuntimeException);
 147   static bool proxiableBit(const anna::DataBlock &) throw(anna::RuntimeException);
 148   static bool errorBit(const anna::DataBlock &) throw(anna::RuntimeException);
 149   static bool potentiallyReTransmittedMessageBit(const anna::DataBlock &) throw(anna::RuntimeException);
 150
 151   static bool isRequest(const CommandId & cid) throw() { return (cid.second); }
 152   static bool isRequest(const anna::DataBlock & db) throw(anna::RuntimeException) { return requestBit(db); }
 153
 154   static bool isAnswer(const CommandId & cid) throw() { return (!isRequest(cid)); }
 155   static bool isAnswer(const anna::DataBlock & db) throw(anna::RuntimeException) { return (!isRequest(db)); }
 156
 157
 158
 159   /**
 160    * Decodes a Command Header. This helper cannot check boundaries. start pointer must be a valid command context.
 161    *
 162    * @param start Must be a valid command start (point to the command version byte).
 163    * @param version Diameter version.
 164    * @param length Message length.
 165    * @param flags Command flags.
 166    * @param id Command identification (code, request<true,false>).
 167    * @param appId Application-ID.
 168    * @param hbh Hop-by-Hop Identifier.
 169    * @param ete End-to-End Identifier.
 170    */
 171   static void decodeCommandHeader(const char *start, char & version, U24 & length, char & flags, CommandId & id, int & appId, int & hbh, int & ete) throw(anna::RuntimeException);
 172
 173   /**
 174    * Decodes an AVP. This helper cannot check boundaries. start pointer must be a valid avp context.
 175    *
 176    * @param start Must be a valid avp start (point to the 32-bits avp code word).
 177    * @param id Avp identification (code, vendorId).
 178    * @param flags Avp flags byte.
 179    * @param length Avp length (includes code, flags, length itself, vendorId if exists and data length).
 180    * @param data Avp data part.
 181    */
 182   static void decodeAVP(const char *start, AvpId & id, char & flags, int & length, std::string & data) throw(anna::RuntimeException);
 183
 184   /**
 185    * Gets the next AVP pointer reference starting from a first-avp data block. It could be the first avp within
 186    * a command, or within an grouped avp.
 187    *
 188    * @param avpsDB AVP data block buffer pointer
 189    * @param avpsLen AVP data block buffer length
 190    * @param start Point to start the search. Must be a valid avp start (point to the 32-bits avp code word).
 191    *
 192    * @return Pointer to the next AVP found. NULL if no more.
 193    */
 194   static const char * nextAVP(const char *avpsDB, int avpsLen, const char *start) throw(anna::RuntimeException);
 195
 196   //  /**
 197   //  * Gets the next AVP pointer reference starting from a first-avp datablock. It could be the first avp within
 198   //  * a command, or within an grouped avp.
 199   //  *
 200   //  * @param avpsDB AVPs set as datablock
 201   //  * @param start Point to start the search. Must be a valid avp start (point to the 32-bits avp code word).
 202   //  *
 203   //  * @return Pointer to the next AVP found. NULL if no more.
 204   //  */
 205   //  static const char * nextAVP(const anna::DataBlock & avpsDB, const char *start) throw(anna::RuntimeException);
 206
 207   /**
 208    * Gets the next AVP pointer reference within an AVPs set data block with a certain AVP identification.
 209    *
 210    * @param avpsDB AVP data block buffer pointer
 211    * @param avpsLen AVP data block buffer length
 212    * @param id Avp identification (code, vendorId).
 213    * @param n Ocurrence number (first avp, second avp, etc.). 1 by default.
 214    *
 215    * @return Pointer to first AVP found with identification provided. NULL if not found.
 216    */
 217   static const char *findAVP(const char *avpsDB, int avpsLen, const diameter::AvpId & id, int n = 1) throw(anna::RuntimeException);
 218
 219   //  /**
 220   //  * Gets the next AVP pointer reference within an AVPs set datablock with a certain AVP identification.
 221   //  *
 222   //  * @param avpsDB AVPs set as datablock
 223   //  * @param id Avp identification (code, vendorId).
 224   //  * @param n Ocurrence number (first avp, second avp, etc.). 1 by default.
 225   //  *
 226   //  * @return Pointer to first AVP found with identification provided. NULL if not found.
 227   //  */
 228   //  static const char * findAVP(const anna::DataBlock & avpsDB, const AvpId & id, int n = 1) throw(anna::RuntimeException);
 229
 230
 231
 232   // modifiers
 233   static void setHopByHop(anna::DataBlock &, HopByHop) throw(anna::RuntimeException);
 234   static void setEndToEnd(anna::DataBlock &, EndToEnd) throw(anna::RuntimeException);
 235   static void setPotentiallyReTransmittedMessageBit(const anna::DataBlock & db, bool activate = true) throw(anna::RuntimeException);
 236
 237
 238   /**
 239      Interpret a xml file in order to create a memory xml document.
 240      The xml file is based on this message DTD:
 241
 242      <pre>
 243      <!ELEMENT message (avp*)>
 244      <!ELEMENT avp (avp*)>
 245
 246      <!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>
 247      <!--
 248         version: Diameter version. Sets '1' by default
 249         name:    Command name within working stack (dictionary identifier)
 250
 251         In order to get more coding capabilities, command code and flags could be established instead of former command name,
 252          but neither of them are allowed if 'name' is provided (and vice versa):
 253
 254         code:    Command code
 255         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
 256
 257
 258         application-id:   Message application id
 259         hop-by-hop-id:    Message hop by hop id. Sets '0' by default
 260         end-by-end-id:    Message end by end id. Sets '0' by default
 261      -->
 262
 263      <!ATTLIST avp name CDATA #IMPLIED code CDATA #IMPLIED vendor-code CDATA #IMPLIED flags CDATA #IMPLIED data CDATA #IMPLIED hex-data CDATA #IMPLIED>
 264      <!--
 265         name:   Avp name within working stack (dictionary identifier)
 266
 267         In order to get more coding capabilities, avp code, vendor-id and flags could be established instead of former avp name,
 268          but neither of them are allowed if 'name' is provided (and vice versa):
 269
 270         code:          Avp code
 271         vendor-code:   Avp vendor code
 272         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)
 273
 274
 275         data:          Natural string representation for avp data. Specially applicable with numbers and printable strings, but also
 276                         useful for certain formats which could be easily understandable in such friendly/smart representation. We will
 277                         achieve different human-readable strings depending on data format:
 278
 279                           [ OctetString ] (if printable, but not recommended)
 280                           [ Integer32, Integer64, Unsigned32, Unsigned64, Float32, Float64 ] (normal number representation)
 281                           [ Time ] (NTP timestamp, normal number representation)
 282                           [ Address ] (auto detects IPv4 or IPv6 address version, then only ip address is specified: IPv4 with dots, IPv6 with colons)
 283                           [ UTF8String, DiameterIdentity, DiameterURI ] (printable)
 284                           [ IPFilterRule, QoSFilterRule ] (uses ASCII charset, printable)
 285
 286                           New application formats must define specific natural representation for internal raw data
 287
 288         hex-data:      Hexadecimal octet sequence representation (i.e. 'af012fb3', with even number of digits). Suitable for whatever kind
 289                         of diameter format, but mandatory for non printable information. OctetString usually transport non human-readable
 290                         data and should better be encoded within this field although being printable. Unknown avps (which fails identifying
 291                         provided name or code/vendor-code) must always use this representation.
 292
 293         Xml representation for decoded messages shows natural content except for 'OctetString' format and unknown avps. Anyway, when printable,
 294          OctetString could show such information at data field apart from hex-data, because many implementations use this format to transport
 295          readable-string data. In general, one of the data fields is mandatory except for 'Grouped' type (its data is another level of avps).
 296         Application-specific formats must decide the way to represent its contents, being recommended to use a natural representation if possible,
 297          because xml is read by humans with testing and monitoring purposes.
 298      -->
 299      </pre>
 300
 301      @param xmlDocument XML document allocated by the user of the function (anna::xml::DocumentMemory xmlDocument)
 302      @param xmlPathFile Complete path file to the xml document which represents the diameter message
 303      @see messageXmlDocumentFromXmlString
 304
 305      @warning Whatever you will do with the xml document, will be only valid inside the scope of such xml document.
 306      For example, you could load the document to be decoded over a codec Message by mean #Message::fromXML (using
 307      the xml document #getRootNode) during document lifetime. After that, it could be destroyed.
 308    */
 309   static void messageXmlDocumentFromXmlFile(anna::xml::DocumentFile &xmlDocument, const std::string & xmlPathFile) throw(anna::RuntimeException);
 310
 311   /**
 312      Interpret xml string representation in order to create a memory xml document.
 313      DTD validation is used in the same way that #messageXmlDocumentFromXmlFile does.
 314
 315      @param xmlDocument XML document allocated by the user of the function (anna::xml::DocumentMemory xmlDocument)
 316      @param xmlString XML string representation of the diameter message
 317      @see messageXmlDocumentFromXmlFile
 318
 319      @warning Whatever you will do with the xml document, will be only valid inside the scope of such xml document.
 320      For example, you could load the document to be decoded over a codec Message by mean #Message::fromXML (using
 321      the xml document #getRootNode) during document lifetime. After that, it could be destroyed.
 322    */
 323   static void messageXmlDocumentFromXmlString(anna::xml::DocumentFile &xmlDocument, const std::string &xmlString) throw(anna::RuntimeException);
 324 };
 325
 326
 327 }
 328 }
 329 }
 330
 331
 332 #endif
 333