1 // ANNA - Anna is Not Nothingness Anymore
3 // (c) Copyright 2005-2014 Eduardo Ramos Testillano & Francisco Ruiz Rayo
5 // http://redmine.teslayout.com/projects/anna-suite
7 // Redistribution and use in source and binary forms, with or without
8 // modification, are permitted provided that the following conditions
11 // * Redistributions of source code must retain the above copyright
12 // notice, this list of conditions and the following disclaimer.
13 // * Redistributions in binary form must reproduce the above
14 // copyright notice, this list of conditions and the following disclaimer
15 // in the documentation and/or other materials provided with the
17 // * Neither the name of the copyright holder nor the names of its
18 // contributors may be used to endorse or promote products derived from
19 // this software without specific prior written permission.
21 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
24 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
25 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
26 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
27 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
28 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
29 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
30 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
31 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
33 // Authors: eduardo.ramos.testillano@gmail.com
34 // cisco.tierra@gmail.com
37 #ifndef anna_diameter_codec_Message_hpp
38 #define anna_diameter_codec_Message_hpp
42 #include <anna/config/defines.hpp>
43 #include <anna/diameter/defines.hpp>
44 #include <anna/diameter/codec/Avp.hpp>
45 #include <anna/diameter/helpers/base/defines.hpp>
47 #include <anna/core/DataBlock.hpp>
48 #include <anna/core/RuntimeException.hpp>
53 //------------------------------------------------------------------------------
54 //---------------------------------------------------------------------- #define
55 //------------------------------------------------------------------------------
77 * Diameter message generic container
79 * RFC 3588 Diameter Based Protocol September 2003
82 * A summary of the Diameter header format is shown below. The fields
83 * are transmitted in network byte order.
86 * 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
87 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
88 * | Version | Message Length |
89 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
90 * | command flags | Command-Code |
91 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
93 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
94 * | Hop-by-Hop Identifier |
95 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
96 * | End-to-End Identifier |
97 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
99 * +-+-+-+-+-+-+-+-+-+-+-+-+-
105 CommandId a_id; // code and request indicator
110 avp_container a_avps; // childrens
111 find_container a_finds; // fast access for message first-level avps
114 int a_insertionPositionForChilds; // used with childrens
115 anna::DataBlock a_forCode;
117 const Avp* _getAvp(const char *name, int ocurrence, anna::Exception::Mode::_v emode) const throw(anna::RuntimeException);
119 // --- Developer notes ---
120 // 'AVP Length' does not include posible data padding. Thanks to this, 'Data Length'
121 // is the difference between 'AVP Length' and sum of code, length, flags and
122 // optionally the vendor-ID (all of them are 32-bit boundary), that is to say:
123 // 8 or 12 (vendor-specific avps).
125 // Grouped avps 'AVP Length' includes own headers plus the total length of all
126 // underlying AVPs, including their headers and padding, then 'AVP Length' is
127 // always multiple of 4 (library will check this), and smae for 'Data Length'
128 // which is an 'whole avp Length with padding' itself.
134 avp_iterator avp_begin() throw() { return a_avps.begin(); }
135 avp_iterator avp_end() throw() { return a_avps.end(); }
136 const_avp_iterator avp_begin() const throw() { return a_avps.begin(); }
137 const_avp_iterator avp_end() const throw() { return a_avps.end(); }
140 * Gets avp total message length.
142 U24 getLength() const throw();
146 bool flagsOK(int &rc) const throw(); // flags coherence regarding dictionary. Only must be called when Message is identified at the dictionary.
147 int addChild(Avp *avp) throw() { return Avp::addChild(a_avps, a_insertionPositionForChilds, avp); }
148 const anna::diameter::stack::Command *getStackCommand(CommandId id) const throw(anna::RuntimeException);
149 Avp * addFailedAVP() throw(); // returns Failed-AVP if exists, creates it when missing
154 mutable Engine *a_engine;
156 /** Codec Engine getter: avoids have to create base engine when using its child */
157 virtual Engine * getEngine() const throw(anna::RuntimeException);
160 * Initializes Message class information.
161 * Any reimplementation must first invoke base class method.
163 virtual void initialize() throw();
169 * Default constructor
174 * Identified constructor
175 * @param id Command identifier as pair (code,request-indicator).
177 Message(CommandId id);
181 static const int HeaderLength;
192 // T(Potentially re-transmitted message)
193 // r(eserved) - these flag bits are reserved for future use, and
194 // MUST be set to zero, and ignored by the receiver.
195 static const U8 RBitMask;
196 static const U8 PBitMask;
197 static const U8 EBitMask;
198 static const U8 TBitMask;
205 // Virtual destructors are useful when you can delete an instance of a derived class through a pointer to base class:
206 // 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.
207 // My current solution: virtualizing method 'clear'
210 // To sum up, always make base classes' destructors virtual when they're meant to be manipulated polymorphically.
215 Sets the command identifier and clear the former content.
217 @param id Command identifier as pair (code,request-indicator).
218 @param _clear Message will be cleared when updating the command identifier (default behaviour).
220 void setId(CommandId id, bool _clear = true) throw(anna::RuntimeException);
223 Same as #setId but providing dictionary logical name for Avp searched
225 void setId(const char *name) throw(anna::RuntimeException);
228 Sets the command version. By default, messages initializes with value 1.
230 @param version Version provided
232 void setVersion(U8 version) throw() { a_version = version; }
235 Sets/unsets P bit activation.
236 Application should not have to use this because dictionary information is used in order to configure flags when Message identifier is stored.
238 @param activate Activates/deactivates the bit. True by default.
240 void setProxiableBit(bool activate = true) throw() { if(activate) a_flags |= PBitMask; else a_flags &= (~PBitMask); }
243 Sets/unsets E bit activation.
244 Application should not have to use this because dictionary information is used in order to configure flags when Message identifier is stored.
246 @param activate Activates/deactivates the bit. True by default.
248 void setErrorBit(bool activate = true) throw() { if(activate) a_flags |= EBitMask; else a_flags &= (~EBitMask); }
251 Sets/unsets T bit activation.
252 Application should not have to use this because dictionary information is used in order to configure flags when Message identifier is stored.
254 @param activate Activates/deactivates the bit. True by default.
256 void setPotentiallyReTransmittedMessageBit(bool activate = true) throw() { if(activate) a_flags |= TBitMask; else a_flags &= (~TBitMask); }
259 Sets the message application id
260 @param aid Application-id.
262 void setApplicationId(U32 aid) throw() { a_applicationId = aid; }
265 Sets the message hop-by-hop
266 @param hbh Hop-by-hop identifier.
268 void setHopByHop(U32 hbh) throw() { a_hopByHop = hbh; }
271 Sets the message end-to-end
272 @param ete End-to-end identifier.
274 void setEndToEnd(U32 ete) throw() { a_endToEnd = ete; }
278 Sets header to be an answer regarding provided request message code.
279 Internally, updates command identifier (indeed request flag), promotes version, application identifier, hop-by-hop and end-to-end fields.
281 @param request Message to be answered.
283 @warning Request provided must be a request, in other case method do nothing.
285 void setHeaderToAnswer(const Message &request) throw() {
286 if(!request.getId().second) return;
288 setId(CommandId(request.getId().first, !request.getId().second), false /* don't clear */);
289 setVersion(request.getVersion());
290 setApplicationId(request.getApplicationId());
291 setHopByHop(request.getHopByHop()); // The same Hop-by-Hop Identifier in the request is used in the answer (RFC 6733 Section 6.2).
292 setEndToEnd(request.getEndToEnd()); // The same End-to-End Identifier in the request is used in the answer (RFC 6733 Section 6.2).
293 setProxiableBit(request.proxiableBit()); // The 'P' bit is set to the same value as the one in the request (RFC 6733 Section 6.2).
298 Standard minimum-answer building from requests. Adds Session-Id (mirrored from request if present), Origin-Host and Origin-Realm
299 (which could be configured, extracted from optional Destination AVPs, etc.), and all the Proxy-Info AVPs (added in same order as
300 appear on the request). Of course, answer message header is built from request information through #setHeaderToAnswer. Finally,
301 message is fixed regarding dictionary elements order (#fix).
303 Summing up, as RFC 6733 Section 6.2, says:
307 6.2. Diameter Answer Processing
309 When a request is locally processed, the following procedures MUST be
310 applied to create the associated answer, in addition to any
311 additional procedures that MAY be discussed in the Diameter
312 application defining the command:
314 o The same Hop-by-Hop Identifier in the request is used in the
317 o The local host's identity is encoded in the Origin-Host AVP.
319 o The Destination-Host and Destination-Realm AVPs MUST NOT be
320 present in the answer message.
322 o The Result-Code AVP is added with its value indicating success or
325 o If the Session-Id is present in the request, it MUST be included
328 o Any Proxy-Info AVPs in the request MUST be added to the answer
329 message, in the same order they were present in the request.
331 o The 'P' bit is set to the same value as the one in the request.
333 o The same End-to-End identifier in the request is used in the
336 Note that the error messages (see Section 7) are also subjected to
337 the above processing rules.
339 Regarding errors, is recommended to use this over automatic answer built at #decode and/or #valid procedures, which would had added
340 Result-Code and/or Failed-AVP AVPs if proceed, but be aware of DIAMETER_COMMAND_UNSUPPORTED Result-Code, because becomes impossible
341 to fix (Session-Id SHOULD appear immediately following the Diameter header, and #fix do this manually even if no information about
342 the command structure is known, but perhaps another fixed AVPs could not comply... use #getResultCode to find out this situation before
343 using #setStandardToAnswer).
345 If application decoding and/or validation operations are ok, user may search for other problems and put the appropiate Result-Code.
346 For example, DIAMETER_TOO_BUSY (3004) depends on congestion issues at business layer and cannot be decided with the only message
347 information automatically (not all the Result-Code values are taken into account, only those which correspond to anomalies managed
348 by anna::diameter::codec). Application Result-Codes could be provided in this prototype, being DIAMETER_SUCCESS the default value if missing.
351 @param request Message to be answered.
352 @param originHost Mandatory Origin-Host diameter identity value provided by application. If answer has already an Origin-Host, this will be ignored.
353 @param originRealm Mandatory Origin-Realm diameter identity value provided by application. If answer has already an Origin-Realm, this will be ignored.
354 @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.
356 @warning Request provided must be a request, in other case method do nothing.
358 void setStandardToAnswer(const Message &request, const std::string &originHost, const std::string &originRealm, int resultCode = helpers::base::AVPVALUES__Result_Code::DIAMETER_SUCCESS) throw();
362 Sets a Result-Code AVP over an answer message (for requests, do nothing).
363 If Result-Code AVP doesn't exists, is added and then filled with the value provided.
364 If Result-Code AVP already exists, value detected is replaced if was DIAMETER_SUCCESS (non success codes are unchanged).
365 When provided value corresponds to an protocol error, that is to say within range [3001,3010], message (E)rror bit is
366 automatically activated.
368 This method is internally used during #decode and/or #valid procedures in order to build automatic answers, but application
369 could call this for set another Result-Code no detected by these methods within its category or for other one (application
370 layer). These are the Result-Codes implemented (detected) by ANNA::diameter::codec:
375 DIAMETER_COMMAND_UNSUPPORTED
376 DIAMETER_INVALID_HDR_BITS
377 DIAMETER_INVALID_AVP_BITS
381 DIAMETER_AVP_UNSUPPORTED (F)
382 DIAMETER_INVALID_AVP_VALUE (F)
383 DIAMETER_MISSING_AVP (F)
384 DIAMETER_AVP_NOT_ALLOWED (F)
385 DIAMETER_AVP_OCCURS_TOO_MANY_TIMES (F)
386 DIAMETER_INVALID_BIT_IN_HEADER
387 DIAMETER_INVALID_AVP_LENGTH (F)
388 DIAMETER_INVALID_MESSAGE_LENGTH
390 (F) Generates Failed-AVP (also DIAMETER_CONTRADICTING_AVPS and DIAMETER_INVALID_AVP_BIT_COMBO
391 values does, but these are not managed by anna::diameter::codec).
394 @param rc Result-Code value. DIAMETER_SUCCESS by default.
396 void setResultCode(int rc = helpers::base::AVPVALUES__Result_Code::DIAMETER_SUCCESS) throw(anna::RuntimeException);
400 Gets the Result-Code AVP value from an answer message (for requests, returns -1).
401 If missing, -1 value is returned.
403 @return Result-Code value for answers, -1 for request and answers without Result-Code AVP inside
405 int getResultCode() const throw();
409 Adds a new AVP within a Failed-AVP over an answer message (for requests, do nothing).
410 If Failed-AVP AVP doesn't exists, is added and then filled (added within) with the value provided (empty AVP id representantion).
411 If Failed-AVP AVP already exists, is filled (added within) with the value provided (empty AVP id representantion).
413 This method is internally used during #decode and/or #valid procedures in order to build automatic answers.
415 @param id Avp identifier as pair (code,vendor-id).
417 @return Pointer to the new AVP added within Failed-AVP, to make easy data-part accessif needed.
419 Avp * setNewFailedAvp(AvpId id) throw(anna::RuntimeException) { if(isRequest()) return NULL; return (addFailedAVP()->addAvp(id)); }
422 Adds a new AVP within a Failed-AVP over an answer message (for requests, do nothing).
423 If Failed-AVP AVP doesn't exists, is added and then filled (added within) with the value provided (empty AVP id representantion).
424 If Failed-AVP AVP already exists, is filled (added within) with the value provided (empty AVP id representantion).
426 This method is internally used during #decode and/or #valid procedures in order to build automatic answers, but application
427 could call this for set another Failed-AVP content no detected by these methods, for example: DIAMETER_CONTRADICTING_AVPS or
428 DIAMETER_INVALID_AVP_BIT_COMBO).
430 @param id Avp identifier as pair (code,vendor-id).
432 @return Pointer to the new AVP added within Failed-AVP, to make easy data-part accessif needed.
434 Avp * setNewFailedAvp(Avp *avp) throw() { if(!avp || isRequest()) return NULL; return (addFailedAVP()->addAvp(avp)); }
438 Adds an avp child providing its identifier and reserve internal memory it.
440 @param id Avp identifier as pair (code,vendor-id).
442 @return Pointer to the new created avp.
444 Avp * addAvp(AvpId id) throw(anna::RuntimeException) { return Avp::addAvp(a_avps, a_insertionPositionForChilds, id, getEngine()); }
448 Same as #addAvp but providing dictionary logical name for Avp searched
450 Avp * addAvp(const char *name) throw(anna::RuntimeException);
454 Adds an avp child providing a persistent pointer (must be maintained by application).
456 @param avp Avp external pointer. If NULL provided, nothing is done and NULL returned.
458 @return Pointer to the added avp (again).
460 Avp * addAvp(Avp * avp) throw() { if(!avp) return NULL; addChild(avp); return avp; }
464 Removes an Avp within message (first level) and free resources.
466 @param id Avp identifier (pair code + vendor-id).
467 @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).
468 Negative values could be used to reverse access positions: i.e. -1 is the last ocurrence, -2 is the second to last (penultimate), etc.
470 @return Returns true if something was removed. False in other cases (including i.e. when this message is empty).
472 bool removeAvp(AvpId id, int ocurrence = 1) throw(anna::RuntimeException) { return Avp::removeAvp(a_avps, (find_container&)a_finds, id, ocurrence, getEngine()); }
476 Same as #removeAvp but providing dictionary logical name for Avp searched
478 bool removeAvp(const char *name, int ocurrence = 1) throw(anna::RuntimeException);
482 * Clears and initializes Message class information.
483 * Application must clear auxiliary message objects before adding Avps in a new context.
484 * Application don't need to clear a message object before decode operation (decode invokes #clear before any other task).
485 * Any reimplementation must first invoke base class method.
487 virtual void clear() throw(anna::RuntimeException);
490 Decodes buffer provided over class content. If an error ocurred, decoding will stop launching exception (fatal error) or a warning trace (perhaps the achieved
491 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
492 in a moment which depends on validation depth (codec::Engine::ValidationDepth).
494 @param db buffer data block processed. Before decoding, the whole message instance will be cleared (no need to invoke #clear before #decode).
495 @param ptrAnswer Answer set by application (could be empty or not), who is responsible for its memory reservation,
496 and automatically built regarding standard. If message analyzed realizes to be an answer, internal reference becomes
497 NULL because no answer is built for answers. By default, automatic answer is not built.
499 void decode(const anna::DataBlock &db, Message *ptrAnswer = NULL) throw(anna::RuntimeException);
502 Fix childrens content regarding dictionary avp positions.
503 Message could remain invalid because of possible fixed/mandatory avps.
504 This is useful to give flexibility to the application during message construction before encoding or representing the data.
505 Is not recommended to fix a recently decoded message because possible validation problems will be hidden.
510 Validates the message regarding dictionary rules like enumerated range, flags coherence, mandatory and fixed types, cardinality qualifiers, etc.
511 @return Boolean indicating validation result
512 @param ptrAnswer Answer set by application (could be empty or not), who is responsible for its memory reservation,
513 and automatically built regarding standard. If message analyzed realizes to be an answer, internal reference becomes
514 NULL because no answer is built for answers. By default, automatic answer is not built.
516 bool valid(Message *ptrAnswer = NULL) const throw(anna::RuntimeException);
520 Interpret xml data in order to dump over the class content.
521 \param messageNode Message root node
523 void fromXML(const anna::xml::Node* messageNode) throw(anna::RuntimeException);
526 Interpret xml string representation in order to dump over the class content.
527 DTD validation is used in the same way that #loadXML does.
528 \param xmlString XML string representation with relevant information for this instance
530 void fromXMLString(const std::string &xmlString) throw(anna::RuntimeException);
533 Loads an xml file based on this message DTD (could be accumulative, no initialization will be performed by this method).
536 <!ELEMENT message (avp*)>
537 <!ELEMENT avp (avp*)>
539 <!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>
541 version: Diameter version. Sets '1' by default
542 name: Command name within working stack (dictionary identifier)
544 In order to get more coding capabilities, command code and flags could be established instead of former command name,
545 but neither of them are allowed if 'name' is provided (and vice versa):
548 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
551 application-id: Message application id
552 hop-by-hop-id: Message hop by hop id. Sets '0' by default
553 end-by-end-id: Message end by end id. Sets '0' by default
556 <!ATTLIST avp name CDATA #IMPLIED code CDATA #IMPLIED vendor-code CDATA #IMPLIED flags CDATA #IMPLIED data CDATA #IMPLIED hex-data CDATA #IMPLIED>
558 name: Avp name within working stack (dictionary identifier)
560 In order to get more coding capabilities, avp code, vendor-id and flags could be established instead of former avp name,
561 but neither of them are allowed if 'name' is provided (and vice versa):
564 vendor-code: Avp vendor code
565 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)
568 data: Natural string representation for avp data. Specially applicable with numbers and printable strings, but also
569 useful for certain formats which could be easily understandable in such friendly/smart representation. We will
570 achieve different human-readable strings depending on data format:
572 [ OctetString ] (if printable, but not recommended)
573 [ Integer32, Integer64, Unsigned32, Unsigned64, Float32, Float64 ] (normal number representation)
574 [ Time ] (NTP timestamp, normal number representation)
575 [ Address ] (auto detects IPv4 or IPv6 address version, then only ip address is specified: IPv4 with dots, IPv6 with colons)
576 [ UTF8String, DiameterIdentity, DiameterURI ] (printable)
577 [ IPFilterRule, QoSFilterRule ] (uses ASCII charset, printable)
579 New application formats must define specific natural representation for internal raw data
581 hex-data: Hexadecimal octet sequence representation (i.e. 'af012fb3', with even number of digits). Suitable for whatever kind
582 of diameter format, but mandatory for non printable information. OctetString usually transport non human-readable
583 data and should better be encoded within this field although being printable. Unknown avps (which fails identifying
584 provided name or code/vendor-code) must always use this representation.
586 Xml representation for decoded messages shows natural content except for 'OctetString' format and unknown avps. Anyway, when printable,
587 OctetString could show such information at data field apart from hex-data, because many implementations use this format to transport
588 readable-string data. In general, one of the data fields is mandatory except for 'Grouped' type (its data is another level of avps).
589 Application-specific formats must decide the way to represent its contents, being recommended to use a natural representation if possible,
590 because xml is read by humans with testing and monitoring purposes.
594 @param xmlPathFile Complete path file to the xml document which represents the diameter message
597 void loadXML(const std::string & xmlPathFile) throw(anna::RuntimeException);
604 Gets Message identifier as pair (code, request indicator).
606 const CommandId & getId() const throw() { return a_id; }
609 Gets the command version. By default, messages initializes with value 1.
611 @return version Message version
613 U8 getVersion() const throw() { return a_version; }
616 Gets Message request indicator.
618 bool isRequest() const throw() { return a_id.second; }
621 Gets Message answer indicator.
623 bool isAnswer() const throw() { return !isRequest(); }
626 Gets the message application id
627 @return aid Application-id.
629 const U32 & getApplicationId() const throw() { return a_applicationId; }
632 Gets the message hop-by-hop
633 @return hbh Hop-by-hop identifier.
635 const U32 & getHopByHop() const throw() { return a_hopByHop; }
638 Gets the message end-to-end
639 @return ete End-to-end identifier.
641 const U32 & getEndToEnd() const throw() { return a_endToEnd; }
644 Gets stack command (dictionary command reference).
646 const anna::diameter::stack::Command *getStackCommand() const throw(anna::RuntimeException) { return getStackCommand(a_id); }
648 /** Returns R bit activation state */
649 bool requestBit() const throw() { return ((a_flags & RBitMask) != 0x00); }
651 /** Returns P bit activation state */
652 bool proxiableBit() const throw() { return ((a_flags & PBitMask) != 0x00); }
654 /** Returns E bit activation state */
655 bool errorBit() const throw() { return ((a_flags & EBitMask) != 0x00); }
657 /** Returns T bit activation state */
658 bool potentiallyReTransmittedMessageBit() const throw() { return ((a_flags & TBitMask) != 0x00); }
662 Access content for internal Avps. Exception mode allows different combinations like cascade access:
666 message->getAvp(anna::diameter::helpers::base::AVP__Multiple_Services_Credit_Control, anna::Exception::Mode::Throw)
667 ->getAvp(anna::diameter::helpers::base::AVP__Rating_Group, anna::Exception::Mode::Throw);
669 catch(anna::RuntimeException) {;}
675 const Avp *mscc = message->getAvp(anna::diameter::helpers::base::AVP__Multiple_Services_Credit_Control);
677 if (mscc) rg = mscc->getAvp(anna::diameter::helpers::base::AVP__Rating_Group);
680 Replacing procedures becomes easy because an Avp can be searched and its pointer reconfigured by mean #setId and data part setters.
681 Deleting procedures must use #removeAvp.
682 Access is internally cached to speed up the search operations. This cache is reset after calling #fix or #removeAvp methods.
684 @param id Avp identifier (pair code + vendor-id).
685 @param ocurrence Order of appearance for the searched avp. Zero position is rejected, but negative values could be used to reverse
686 access positions: i.e. -1 is the last ocurrence, -2 is the second to last (penultimate), etc.
687 @param emode Excepcion mode handling: Ignore (no action is taken), Throw (excepcion when missing avp), Trace (trace situation as warning).
689 const Avp* getAvp(AvpId id, int ocurrence = 1, anna::Exception::Mode::_v emode = anna::Exception::Mode::Throw) const throw(anna::RuntimeException) {
690 return Avp::getAvp(a_avps, (find_container&)a_finds, id, ocurrence, getEngine(), emode);
693 Avp* getAvp(AvpId id, int ocurrence = 1, anna::Exception::Mode::_v emode = anna::Exception::Mode::Throw) throw(anna::RuntimeException) {
694 return const_cast<Avp*>(Avp::getAvp(a_avps, (find_container&)a_finds, id, ocurrence, getEngine(), emode));
699 Same as #getAvp but providing dictionary logical name for Avp searched
701 const Avp* getAvp(const char *name, int ocurrence = 1, anna::Exception::Mode::_v emode = anna::Exception::Mode::Throw) const throw(anna::RuntimeException) {
702 return _getAvp(name, ocurrence, emode);
705 Avp* getAvp(const char *name, int ocurrence = 1, anna::Exception::Mode::_v emode = anna::Exception::Mode::Throw) throw(anna::RuntimeException) {
706 return const_cast<Avp*>(_getAvp(name, ocurrence, emode));
712 Counts the number of ocurrences of Avps (first level) with the identifier provided
714 @param id Avp identifier (pair code + vendor-id).
716 int countAvp(AvpId id) const throw() { return Avp::countAvp(a_avps, id); }
719 Same as #countAvp but providing dictionary logical name for Avp searched
721 int countAvp(const char *name) const throw(anna::RuntimeException);
724 Counts the number of children
726 @param id Avp identifier (pair code + vendor-id).
728 int countChilds() const throw() { return Avp::countChilds(a_avps); }
731 Encodes datablock with the class content. In case that validation is enabled (codec::Engine::ValidationMode) an exception will be launched
732 in a moment which depends on validation depth (codec::Engine::ValidationDepth). If you want to see validation errors but go on with encoding,
733 you should try/catch #valid() procedure out of #code.
735 @return DataBlock encoded (internal memory used)
737 const anna::DataBlock & code() throw(anna::RuntimeException);
740 Class xml representation
741 \param parent Parent XML node on which hold this instance information.
742 \return XML document with relevant information for this instance.
744 anna::xml::Node* asXML(anna::xml::Node* parent) const throw();
747 Class xml string representation
748 \return XML string representation with relevant information for this instance.
750 std::string asXMLString() const throw();
755 @param m1 Instance 1 for Message class
756 @param m2 Instance 2 for Message class
758 @return Comparison result
760 friend bool operator == (const Message & m1, const Message & m2) throw() { return (m1.asXMLString() == m2.asXMLString()); }
763 Match a regular expression (string pattern) regarding xml string serialization for this message.
764 Using a complex pattern (many avps, grouped ones) it could be necessary to fix the message before
765 using the method in order to perform a more controlled comparison. In the same way, flags could be
766 ignored to simplify message xml presentation.
767 This powerful tool could be used to program traffic analysis and decide future behaviour (routing,
773 The pattern '<avp name="Service-Context-Id" data="(.)*32251@3gpp.org"/>' detects PS charging contexts
774 because of data suffix specification '32251@3gpp.org' for that AVP.
776 The pattern '<message version="1" name="Capabilities-Exchange-Request"' detects a CER message.
778 The pattern (string including carriage returns):
780 '<avp name="Subscription-Id">
781 <avp name="Subscription-Id-Type" data="0" alias="END_USER_E164"/>
782 <avp name="Subscription-Id-Data" data="606000106"/>
785 detects MSISDN (not IMSI) equal to 606000106
787 It would seems strange or 'creative' to use regular expressions within an hex string representation,
788 but anyway you could also do such kind of things to check non-printable data parts within the message:
789 for example, the pattern '<avp name="Framed-IP-Address" hex-data="0a[A-Fa-f0-9][A-Fa-f0-9]0a0a"/>'
790 matchs IP addresses for '10.x.10.10' where x = [0..255].
792 Note that string pattern could also be generated via #loadXML and then #asXML, that is to say, you
793 could get patterns through xml files which act as conditional triggers over message. In that case,
794 it is not possible to specify regular expressions within xml 'hex-data' fields because parser will fail
795 during hexadecimal read. Normally only printable 'data' fields are used for matching issues.
797 For example, imagine a 'pattern.xml' file like:
798 <message version="1" name="Credit-Control-Request" application-id="16777236" hop-by-hop-id="0" end-by-end-id="0">
799 <avp name="Subscription-Id">
800 <avp name="Subscription-Id-Type" data="0" alias="END_USER_E164"/>
801 <avp name="Subscription-Id-Data" data="616[0-9]{6,6}"/>
807 anna::diameter::codec::Message patternMessage;
808 patternMessage.loadXML("pattern.xml");
809 std::string pattern = patternMessage.getAvp("Subscription-Id")->getAvp("Subscription-Id-Type")->asXMLString();
810 // Former is '<avp name="Subscription-Id-Data" data="616[0-9]{6,6}"/>'
811 bool match = incomingMessage.isLike(pattern);
813 Then, messages having MSISDN numbers starting with '616' will match the pattern.
814 Note, that any other message codes (and not only Credit-Control-Request ones), could pass the test...
815 You could also build that string manually:
818 std::string pattern = "<avp name=\"Subscription-Id\">\n";
819 pattern += ANNA_XML_COMPILER_TAB; pattern += "<avp name=\"Subscription-Id-Type\" data=\"0\" alias=\"END_USER_E164\"/>\n"
820 pattern += ANNA_XML_COMPILER_TAB; pattern += "<avp name=\"Subscription-Id-Data\" data=\"616[0-9]{6,6}\"/>"
823 std::string pattern = "name=\"Subscription-Id\"(.)*name=\"Subscription-Id-Type\" data=\"0\"(.)*name=\"Subscription-Id-Data\" data=\"616[0-9]{6,6}\"";
826 \return Returns the match result
828 bool isLike(const std::string &pattern) const throw();
831 //friend class Engine;