-// ANNA - Anna is Not Nothingness Anymore
-//
-// (c) Copyright 2005-2014 Eduardo Ramos Testillano & Francisco Ruiz Rayo
-//
-// http://redmine.teslayout.com/projects/anna-suite
-//
-// Redistribution and use in source and binary forms, with or without
-// modification, are permitted provided that the following conditions
-// are met:
-//
-// * Redistributions of source code must retain the above copyright
-// notice, this list of conditions and the following disclaimer.
-// * Redistributions in binary form must reproduce the above
-// copyright notice, this list of conditions and the following disclaimer
-// in the documentation and/or other materials provided with the
-// distribution.
-// * Neither the name of the copyright holder nor the names of its
-// contributors may be used to endorse or promote products derived from
-// this software without specific prior written permission.
-//
-// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
-// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
-// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
-// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
-// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-//
-// Authors: eduardo.ramos.testillano@gmail.com
-// cisco.tierra@gmail.com
+// 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_Avp_hpp
*/
std::string getXMLdata(bool & isHex, const anna::diameter::stack::Format *stackFormat) const throw();
- /**
- Interpret xml data in order to dump over the class content.
-
- \param avpNode Avp root node
- */
- void fromXML(const anna::xml::Node* avpNode) throw(anna::RuntimeException);
-
-
- /**
- Encodes buffer with the class content.
-
- * @param buffer Raw data to be encoded
- * @param size Size of raw data to be encoded
- */
- void code(char* buffer, int &size) const throw(anna::RuntimeException);
-
/**
Decodes Avp data part.
/**
* 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
+ *
+ * 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
/**
* Destructor
*/
- ~Avp();
+ virtual ~Avp();
// setters
/**
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).
*/
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 */
const Unknown * getUnknown() const throw(anna::RuntimeException) { assertFormat("Unknown"); return a_Unknown; }
+ /**
+ Decodes buffer provided over class content. If an error ocurred, decoding will stop launching exception (fatal error) or a warning trace (perhaps the achieved
+ avp is valid against all odds then validation will go on). In case that validation is enabled (codec::Engine::ValidationMode) an exception will be launched
+ depending on validation depth (codec::Engine::ValidationDepth).
+
+ Useful as serialization procedure with #code
+
+ @param db Buffer data block processed
+ */
+ void decode(const anna::DataBlock &db) throw(anna::RuntimeException);
+
+
+ /**
+ Interpret xml data in order to dump over the class content.
+
+ \param avpNode Avp root node
+ */
+ void fromXML(const anna::xml::Node* avpNode) throw(anna::RuntimeException);
+
+
+ /**
+ Encodes buffer with the class content. This method is internally used to encode diameter messages, but is declared as public, to allow
+ its use as serialization procedure. Then, it's assumed that this Avp is valid (validation shall be applied as part of a whole diameter
+ message but nothing will be verified now).
+
+ * @param buffer Raw data to be encoded (shall be externally allocated)
+ * @param size Size of raw data to be encoded
+ */
+ void code(char* buffer, int &size) const throw(anna::RuntimeException);
+
+
// Helpers
/**
/**
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
+
+ @param a1 Instance 1 for Avp class
+ @param a2 Instance 2 for Avp class
+
+ @return Comparison result
+ */
+ friend bool operator == (const Avp & a1, const Avp & a2) throw() { return (a1.asXMLString() == a2.asXMLString()); }
+
+ /**
+ Match a regular expression (string pattern) regarding xml string serialization for this avp.
+ This works same as #Message::isLike
+
+ @param pattern Pattern to match
+
+ \return Returns the match result
+ */
+ bool isLike(const std::string &pattern) const throw();
/**
Counts the number of ocurrences of Avps (first level) with the identifier provided