Ensures normalization on waitfe/fc-xml operations

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

diff --git a/include/anna/diameter/codec/Avp.hpp b/include/anna/diameter/codec/Avp.hpp
index 6deb5d7..2454d4d 100644 (file)
--- a/include/anna/diameter/codec/Avp.hpp
+++ b/include/anna/diameter/codec/Avp.hpp
@@ -373,18 +373,35 @@ public:
 
   /**
   * Default constructor
+  * @param engine Codec engine used
   */
-  Avp();
+  Avp(Engine *engine = NULL);
 
   /**
   * Identified constructor
   * @param id Avp identifier as pair (code,vendor-id).
+  * @param engine Codec engine used
   */
-  Avp(AvpId id);
+  Avp(AvpId id, Engine *engine = NULL);
 
 
-  /** Sets the codec engine */
-  void setEngine(Engine *engine) throw() { a_engine = engine; }
+  /**
+  * Sets the codec engine
+  *
+  * Once assigned (here or at constructor), this method SHALL NOT be used anymore.
+  * Also, the associated dictionary SHOULD NOT BE CHANGED through the engine,
+  * unless you know what are you doing. If you want to reconfigure the engine,
+  * first #clear the avp and then you could reuse the same object with
+  * different configurations (execution contexts).
+  *
+  * Setting a new different engine with different stack, even same engine where the
+  * stack has been dynamically changed, could cause a bad behaviour depending on the
+  * changes: in general, if the dictionary grows, nothing bad will happen, but if
+  * you remove or modified some elements which were processed with a certain format,
+  * will be interpreted as 'unknown' with the new dictionary, and then some problems
+  * may occur. If you add elements (vendors, avps, messages) is not a problem.
+  */
+  void setEngine(Engine *engine) throw();
 
 
   // Length references
@@ -408,7 +425,7 @@ public:
   /**
   * Destructor
   */
-  ~Avp();
+  virtual ~Avp();
 
 
   // setters
@@ -460,7 +477,7 @@ public:
 
   /**
      Adds an avp child providing its identifier and reserve internal memory it.
-     An exception is launched is the Avp is not a grouped avp.
+     An exception is launched is the Avp over which we add the new avp, is not a grouped avp.
 
      @param id Avp identifier as pair (code,vendor-id).
 
@@ -474,16 +491,19 @@ public:
   */
   Avp * addAvp(const char *name) throw(anna::RuntimeException);
 
-
   /**
      Adds an avp child providing a persistent pointer (must be maintained by application).
-     An exception is launched is the Avp is not a grouped avp.
+     An exception is launched is the Avp over which we add the new avp, is not a grouped avp.
+     It is not allowed to add an avp with no codec engine configured, neither if the engine
+     is not the same.
 
      @param avp Avp external pointer. If NULL provided, nothing is done and NULL returned.
+     Also NULL returned for bad engine configuration.
 
      @return Pointer to the added avp (again).
   */
-  Avp * addAvp(Avp * avp) throw(anna::RuntimeException) { if(!avp) return NULL; addChild(avp); return avp; }
+  Avp * addAvp(Avp * avp) throw(anna::RuntimeException);
+
 
   // Data part access
   /** Access content for OctetString Avp in order to set data part */
@@ -692,9 +712,12 @@ public:
 
   /**
      Class xml string representation
+     @param normalize Optional normalization which sorts attribute names and removes
+     newlines in the xml representation in order to ease regexp matching.
+
      \return XML string representation with relevant information for this instance.
   */
-  std::string asXMLString() const throw();
+  std::string asXMLString(bool normalize = false) const throw();
 
   /**
      Comparison operator by mean serialization