1 // ANNA - Anna is Not Nothingness Anymore //
3 // (c) Copyright 2005-2015 Eduardo Ramos Testillano & Francisco Ruiz Rayo //
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 //
9 #ifndef anna_diameter_codec_functions_hpp
10 #define anna_diameter_codec_functions_hpp
14 #include <anna/diameter/defines.hpp>
15 #include <anna/core/RuntimeException.hpp>
16 #include <anna/xml/xml.hpp>
23 //------------------------------------------------------------------------------
24 //---------------------------------------------------------------------- #define
25 //------------------------------------------------------------------------------
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 ))
44 static const char *MessageDTD = "\
45 <?xml version=\"1.0\" encoding=\"UTF-8\"?>\n\
46 <!-- Diameter message DTD -->\n\
48 <!ELEMENT message (avp*)>\n\
49 <!ELEMENT avp (avp*)>\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-to-end-id CDATA #IMPLIED>\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\
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\
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\
66 application-id: Message application id\n\
67 hop-by-hop-id: Message hop by hop id. Sets '0' by default\n\
68 end-to-end-id: Message end to end id. Sets '0' by default\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\
73 name: Avp name within working stack (dictionary identifier)\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\
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\
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\
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\
100 New application formats must define specific natural representation for internal raw data\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\
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\
117 // Used for alarms, tracing and Failed-AVP construction:
118 typedef struct parent {
121 anna::diameter::CommandId MessageId;
122 std::string MessageName;
124 std::vector<anna::diameter::AvpId> AvpsId;
125 std::vector<std::string> AvpsName;
127 void setMessage(const anna::diameter::CommandId & mid, const char *mname = NULL /* well known in validation */) throw();
128 void addAvp(const anna::diameter::AvpId & aid, const char *aname = NULL /* well known in validation */) throw();
129 std::string asString() const throw();
139 static CommandId getCommandId(const anna::DataBlock &) throw(anna::RuntimeException);
140 static ApplicationId getApplicationId(const anna::DataBlock &) throw(anna::RuntimeException);
141 static HopByHop getHopByHop(const anna::DataBlock &) throw(anna::RuntimeException);
142 static EndToEnd getEndToEnd(const anna::DataBlock &) throw(anna::RuntimeException);
144 static bool requestBit(const anna::DataBlock &) throw(anna::RuntimeException);
145 static bool proxiableBit(const anna::DataBlock &) throw(anna::RuntimeException);
146 static bool errorBit(const anna::DataBlock &) throw(anna::RuntimeException);
147 static bool potentiallyReTransmittedMessageBit(const anna::DataBlock &) throw(anna::RuntimeException);
149 static bool isRequest(const CommandId & cid) throw() { return (cid.second); }
150 static bool isRequest(const anna::DataBlock & db) throw(anna::RuntimeException) { return requestBit(db); }
152 static bool isAnswer(const CommandId & cid) throw() { return (!isRequest(cid)); }
153 static bool isAnswer(const anna::DataBlock & db) throw(anna::RuntimeException) { return (!isRequest(db)); }
158 * Decodes a Command Header. This helper cannot check boundaries. start pointer must be a valid command context.
160 * @param start Must be a valid command start (point to the command version byte).
161 * @param version Diameter version.
162 * @param length Message length.
163 * @param flags Command flags.
164 * @param id Command identification (code, request<true,false>).
165 * @param appId Application-ID.
166 * @param hbh Hop-by-Hop Identifier.
167 * @param ete End-to-End Identifier.
169 static void decodeCommandHeader(const char *start, char & version, U24 & length, char & flags, CommandId & id, int & appId, int & hbh, int & ete) throw(anna::RuntimeException);
172 * Decodes an AVP. This helper cannot check boundaries. start pointer must be a valid avp context.
174 * @param start Must be a valid avp start (point to the 32-bits avp code word).
175 * @param id Avp identification (code, vendorId).
176 * @param flags Avp flags byte.
177 * @param length Avp length (includes code, flags, length itself, vendorId if exists and data length).
178 * @param data Avp data part.
180 static void decodeAVP(const char *start, AvpId & id, char & flags, int & length, std::string & data) throw(anna::RuntimeException);
183 * Gets the next AVP pointer reference starting from a first-avp data block. It could be the first avp within
184 * a command, or within an grouped avp.
186 * @param avpsDB AVP data block buffer pointer
187 * @param avpsLen AVP data block buffer length
188 * @param start Point to start the search. Must be a valid avp start (point to the 32-bits avp code word).
190 * @return Pointer to the next AVP found. NULL if no more.
192 static const char * nextAVP(const char *avpsDB, int avpsLen, const char *start) throw(anna::RuntimeException);
195 // * Gets the next AVP pointer reference starting from a first-avp datablock. It could be the first avp within
196 // * a command, or within an grouped avp.
198 // * @param avpsDB AVPs set as datablock
199 // * @param start Point to start the search. Must be a valid avp start (point to the 32-bits avp code word).
201 // * @return Pointer to the next AVP found. NULL if no more.
203 // static const char * nextAVP(const anna::DataBlock & avpsDB, const char *start) throw(anna::RuntimeException);
206 * Gets the next AVP pointer reference within an AVPs set data block with a certain AVP identification.
208 * @param avpsDB AVP data block buffer pointer
209 * @param avpsLen AVP data block buffer length
210 * @param id Avp identification (code, vendorId).
211 * @param n Ocurrence number (first avp, second avp, etc.). 1 by default.
213 * @return Pointer to first AVP found with identification provided. NULL if not found.
215 static const char *findAVP(const char *avpsDB, int avpsLen, const diameter::AvpId & id, int n = 1) throw(anna::RuntimeException);
218 // * Gets the next AVP pointer reference within an AVPs set datablock with a certain AVP identification.
220 // * @param avpsDB AVPs set as datablock
221 // * @param id Avp identification (code, vendorId).
222 // * @param n Ocurrence number (first avp, second avp, etc.). 1 by default.
224 // * @return Pointer to first AVP found with identification provided. NULL if not found.
226 // static const char * findAVP(const anna::DataBlock & avpsDB, const AvpId & id, int n = 1) throw(anna::RuntimeException);
231 static void setHopByHop(anna::DataBlock &, HopByHop) throw(anna::RuntimeException);
232 static void setEndToEnd(anna::DataBlock &, EndToEnd) throw(anna::RuntimeException);
233 static void setPotentiallyReTransmittedMessageBit(const anna::DataBlock & db, bool activate = true) throw(anna::RuntimeException);
237 Interpret a xml file in order to create a memory xml document.
238 The xml file is based on this message DTD:
241 <!ELEMENT message (avp*)>
242 <!ELEMENT avp (avp*)>
244 <!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-to-end-id CDATA #IMPLIED>
246 version: Diameter version. Sets '1' by default
247 name: Command name within working stack (dictionary identifier)
249 In order to get more coding capabilities, command code and flags could be established instead of former command name,
250 but neither of them are allowed if 'name' is provided (and vice versa):
253 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 application-id: Message application id
257 hop-by-hop-id: Message hop by hop id. Sets '0' by default
258 end-to-end-id: Message end to end id. Sets '0' by default
261 <!ATTLIST avp name CDATA #IMPLIED code CDATA #IMPLIED vendor-code CDATA #IMPLIED flags CDATA #IMPLIED data CDATA #IMPLIED hex-data CDATA #IMPLIED>
263 name: Avp name within working stack (dictionary identifier)
265 In order to get more coding capabilities, avp code, vendor-id and flags could be established instead of former avp name,
266 but neither of them are allowed if 'name' is provided (and vice versa):
269 vendor-code: Avp vendor code
270 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 data: Natural string representation for avp data. Specially applicable with numbers and printable strings, but also
274 useful for certain formats which could be easily understandable in such friendly/smart representation. We will
275 achieve different human-readable strings depending on data format:
277 [ OctetString ] (if printable, but not recommended)
278 [ Integer32, Integer64, Unsigned32, Unsigned64, Float32, Float64 ] (normal number representation)
279 [ Time ] (NTP timestamp, normal number representation)
280 [ Address ] (auto detects IPv4 or IPv6 address version, then only ip address is specified: IPv4 with dots, IPv6 with colons)
281 [ UTF8String, DiameterIdentity, DiameterURI ] (printable)
282 [ IPFilterRule, QoSFilterRule ] (uses ASCII charset, printable)
284 New application formats must define specific natural representation for internal raw data
286 hex-data: Hexadecimal octet sequence representation (i.e. 'af012fb3', with even number of digits). Suitable for whatever kind
287 of diameter format, but mandatory for non printable information. OctetString usually transport non human-readable
288 data and should better be encoded within this field although being printable. Unknown avps (which fails identifying
289 provided name or code/vendor-code) must always use this representation.
291 Xml representation for decoded messages shows natural content except for 'OctetString' format and unknown avps. Anyway, when printable,
292 OctetString could show such information at data field apart from hex-data, because many implementations use this format to transport
293 readable-string data. In general, one of the data fields is mandatory except for 'Grouped' type (its data is another level of avps).
294 Application-specific formats must decide the way to represent its contents, being recommended to use a natural representation if possible,
295 because xml is read by humans with testing and monitoring purposes.
299 @param xmlDocument XML document allocated by the user of the function (anna::xml::DocumentMemory xmlDocument)
300 @param xmlPathFile Complete path file to the xml document which represents the diameter message
301 @see messageXmlDocumentFromXmlString
303 @warning Whatever you will do with the xml document, will be only valid inside the scope of such xml document.
304 For example, you could load the document to be decoded over a codec Message by mean #Message::fromXML (using
305 the xml document #getRootNode) during document lifetime. After that, it could be destroyed.
307 static void messageXmlDocumentFromXmlFile(anna::xml::DocumentFile &xmlDocument, const std::string & xmlPathFile) throw(anna::RuntimeException);
310 Interpret xml string representation in order to create a memory xml document.
311 DTD validation is used in the same way that #messageXmlDocumentFromXmlFile does.
313 @param xmlDocument XML document allocated by the user of the function (anna::xml::DocumentMemory xmlDocument)
314 @param xmlString XML string representation of the diameter message
315 @see messageXmlDocumentFromXmlFile
317 @warning Whatever you will do with the xml document, will be only valid inside the scope of such xml document.
318 For example, you could load the document to be decoded over a codec Message by mean #Message::fromXML (using
319 the xml document #getRootNode) during document lifetime. After that, it could be destroyed.
321 static void messageXmlDocumentFromXmlString(anna::xml::DocumentMemory &xmlDocument, const std::string &xmlString) throw(anna::RuntimeException);