anna::diameter::codec::EngineImpl Class Reference

#include <EngineImpl.hpp>

Inheritance diagram for anna::diameter::codec::EngineImpl:

Collaboration diagram for anna::diameter::codec::EngineImpl:

Classes
struct	FixMode
struct	ValidationDepth
struct	ValidationMode

Public Member Functions
Avp *	createAvp (const AvpId *id) noexcept(false)
Message *	createMessage (const CommandId *id) noexcept(false)
	EngineImpl (const char *className, const stack::Dictionary *dictionary)
virtual	~EngineImpl ()
const stack::Dictionary *	getDictionary () const
void	setValidationDepth (const ValidationDepth::_v validationDepth)
ValidationDepth::_v	getValidationDepth () const
void	ignoreFlagsOnValidation (bool ignoreFlags)
bool	ignoreFlagsOnValidation () const
void	setValidationMode (const ValidationMode::_v validationMode)
ValidationMode::_v	getValidationMode () const
void	setFixMode (const FixMode::_v fixMode)
FixMode::_v	getFixMode () const
void	setSingleFailedAVP (bool single=true)
bool	getSingleFailedAVP () const
Avp *	createAvp (AvpId id) noexcept(false)
Avp *	createAvp () noexcept(false)
Message *	createMessage (CommandId id) noexcept(false)
Message *	createMessage () noexcept(false)
Message *	createMessage (const std::string &xmlPathFile_or_string, bool pathfile_or_string=true) noexcept(false)
virtual void	releaseAvp (Avp *)=0
virtual void	releaseMessage (Message *)=0
virtual std::string	asString (void) const
virtual anna::xml::Node *	asXML (anna::xml::Node *parent) const
AvpId	avpIdForName (const char *name) noexcept(false)
CommandId	commandIdForName (const char *name) noexcept(false)
Public Member Functions inherited from anna::Component
virtual	~Component ()
const char *	getClassName () const
Public Member Functions inherited from anna::Mutex
	Mutex (const Mode::_v mode=Mode::Recursive)
virtual	~Mutex ()
virtual void	lock () noexcept(false)
virtual void	unlock ()
bool	trylock () noexcept(false)
	operator const pthread_mutex_t * () const

Protected Member Functions
virtual Avp *	allocateAvp ()=0
virtual Message *	allocateMessage ()=0
void	validationAnomaly (const std::string &description) const noexcept(false)
Protected Member Functions inherited from anna::Component
	Component (const char *className)
	Component (const Component &other)
Protected Member Functions inherited from anna::Safe
	Safe ()

Additional Inherited Members
Protected Attributes inherited from anna::Component
const std::string	a_className

Detailed Description

General component implementation of a diameter elements factory (messages, avps) and common resources which configure encode/decode operations behaviour.

Standard inheritance is done over codec::Engine, allocating basic Avp and Message classes. A child implementation could manage complex Avp classes with new data-part formats. Grouped ones could allocate new complex Avps through such engine which knows how to allocate this special Avp's (also for complex Message classes with application-specific setters and getters as credit-control related avps, or some another context items). For example tme::Avp and tme::Message classes support three new Avp formats: ISDNNumber, ISDNAddress and Unsigned16. Anyway, main Message/Avp and Engine classes stand for all contexts included in anna::diameter, that is to say, whole contexts (at the time only TME) will be included in future when needed apart from the independent namespace version. Thank to this, single threaded applications could use whole engine in a easy way.

An engine component is associated to a single diameter stack. It is application responsability to use message container initialized with the correct codec engine depending on the context. There are helpers to do this at anna::diameter::codec::functions::getApplicationId (from xml document or hexadecimal buffer).

It is recommended to use Message class to create Avps (adding them through pair identification <code + vendor-id> prototype), but we could create Avps separately (other program section, i.e) and join them after:

1. Recommended way:

   // Message creation:
   Message * msg = new Message(helpers::base::COMMANDID__Re_Auth_Answer, codecEngine);
   // Adding + creation:
   Avp * avp_sid = msg->addAvp(helpers::base::AVPID__Session_Id);
   Avp * avp_oh = msg->addAvp(helpers::base::AVPID__Origin_Host);
   Avp * avp_or = msg->addAvp(helpers::base::AVPID__Origin_Realm);
   Avp * avp_rc = msg->addAvp(helpers::base::AVPID__Result_Code);
   // Setting data:
   avp_sid->getUTF8String()->setValue("grump.example.com:33041;23432;893;0AF3B81");
   ...

2. External Avp creation:

   // Message creation:
   Message * msg = new Message(helpers::base::COMMANDID__Re_Auth_Answer, codecEngine);
   // Creation:
   Avp * avp_sid = new Avp(helpers::base::AVPID__Session_Id, codecEngine);
   Avp * avp_oh = new Avp(helpers::base::AVPID__Origin_Host, codecEngine);
   Avp * avp_or = new Avp(helpers::base::AVPID__Origin_Realm, codecEngine);
   Avp * avp_rc = new Avp(helpers::base::AVPID__Result_Code, codecEngine);
   // Adding:
   msg->addAvp(avp_sid);
   msg->addAvp(avp_oh);
   msg->addAvp(avp_or);
   msg->addAvp(avp_rc);
   // Setting data:
   avp_sid->getUTF8String()->setValue("grump.example.com:33041;23432;893;0AF3B81");
   ...

The main difference is that Avps created through Message (or through grouped Avps) are internally allocated
 through engine which normally implements a recycler to optimize memory use.

Implementation example:

class MyEngine : public EngineImpl {
public:
   MyEngine (const char *className = "MyEngine") : Engine(className) {;}

private:
   anna::Recycler<MyAvp> a_avps;
   anna::Recycler<MyMessage> a_messages;

   anna::diameter::codec::Avp* allocateAvp () { return a_avps.create (); }

   void releaseAvp (anna::diameter::codec::Avp* avp) {
        if (avp == NULL) return;
        MyAvp* aux = static_cast <MyAvp*> (avp);
        aux->clear(); // free internal data-part storage specially for grouped avps which will release its childrens
        a_avps.release (aux);
   }

   anna::diameter::codec::Message* allocateMessage () { return a_messages.create (); }

   void releaseMessage (anna::diameter::codec::Message* message) {
        if (message == NULL) return;
        MyMessage* aux = static_cast <MyMessage*> (message);
        aux->clear(); // free internal data-part storage specially for childrens releasing
        a_messages.release (aux);
   }
};

Constructor & Destructor Documentation

EngineImpl()

anna::diameter::codec::EngineImpl::EngineImpl	(	const char *	className,
		const stack::Dictionary *	dictionary
	)

Constructor

Parameters

className

Logical name for the class.

dictionary

Diameter dictionary. At single threaded processes, the same codec engine could be used with different diameter dictionaries (multi-stack applications). In that case the process must switch the stack for the whole decoding or enconding operation over a Message depending on the context (normally the message header Application-Id is used as stack identifier). But the smart way implies inherit from this engine creating a component for each diameter stack managed in the application. Inheritance is mandatory in multi-threaded processes: one engine, a unique stack.

~EngineImpl()

virtual anna::diameter::codec::EngineImpl::~EngineImpl ( )

inlinevirtual

Destructor

{;}

Member Function Documentation

allocateAvp()

virtual Avp* anna::diameter::codec::EngineImpl::allocateAvp ( )

protectedpure virtual

Avp allocator method.

It is recommended to use anna::Recycler for Avps creation/releasing.

See also

anna::Recycler

Implemented in anna::diameter::codec::Engine.

allocateMessage()

virtual Message* anna::diameter::codec::EngineImpl::allocateMessage ( )

protectedpure virtual

Message allocator method.

It is recommended to use anna::Recycler for Message creation/releasing.

See also

anna::Recycler

Implemented in anna::diameter::codec::Engine.

asString()

virtual std::string anna::diameter::codec::EngineImpl::asString ( void  ) const

virtual

Class string representation

Returns

String with class content

Reimplemented from anna::Component.

asXML()

virtual anna::xml::Node* anna::diameter::codec::EngineImpl::asXML ( anna::xml::Node *  parent ) const

virtual

Class XML representation.

Parameters

parent

XML node over which we will put instance information.

Returns

XML documentcon with class content.

Reimplemented from anna::Component.

avpIdForName()

AvpId anna::diameter::codec::EngineImpl::avpIdForName ( const char *  name )

noexcept

Gets the Avp identifier providing its logical name at engine dictionary

Parameters

name	Name of the Avp at engine dictionary

Returns

Avp identifier as pair (code,vendor-id)

commandIdForName()

CommandId anna::diameter::codec::EngineImpl::commandIdForName ( const char *  name )

noexcept

Gets the Command identifier providing its logical name at engine dictionary

Parameters

name	Name of the Command at engine dictionary

Returns

Command identifier as pair (code,request-indicator)

createAvp() [1/3]

Avp* anna::diameter::codec::EngineImpl::createAvp ( const AvpId *  id )

noexcept

createAvp() [2/3]

Avp* anna::diameter::codec::EngineImpl::createAvp ( AvpId  id )

inlinenoexcept

Creates a new diameter avp assigning its identifier, using engine resources to allocate memory (recommended recycler allocation at engine component re-implementation of allocator methods). Obviously, normal objects creation (new) is possible.

Parameters

id	Avp identifier. AVP flags will be established based on active dictionary for known avps, or uninitialized for unknown ones.

Returns

Created avp ready to be used

{ return createAvp(&id); }

Here is the call graph for this function:

createAvp() [3/3]

Avp* anna::diameter::codec::EngineImpl::createAvp ( )

inlinenoexcept

Creates a new diameter avp, using engine resources to allocate memory (recommended recycler allocation at engine component re-implementation of allocator methods). Obviously, normal objects creation (new) is possible.

Returns

Created avp ready to be used

{ return createAvp(NULL); }

Here is the call graph for this function:

createMessage() [1/4]

Message* anna::diameter::codec::EngineImpl::createMessage ( const CommandId *  id )

noexcept

createMessage() [2/4]

Message* anna::diameter::codec::EngineImpl::createMessage ( CommandId  id )

inlinenoexcept

Creates a new diameter Message assigning its identifier, using engine resources to allocate memory (recommended recycler allocation at engine component re-implementation of allocator methods). Obviously, normal objects creation (new) is possible.

Parameters

id	Command identifier. Message flags will be established based on active dictionary for known commands, or uninitialized for unknown ones.

Returns

Created message ready to be used

{ return createMessage(&id); }

Here is the call graph for this function:

createMessage() [3/4]

Message* anna::diameter::codec::EngineImpl::createMessage ( )

inlinenoexcept

Creates a new diameter message, using engine resources to allocate memory (recommended recycler allocation at engine component re-implementation of allocator methods). Obviously, normal objects creation (new) is possible.

Returns

Created message ready to be used

{ return createMessage(NULL); }

Here is the call graph for this function:

createMessage() [4/4]

Message* anna::diameter::codec::EngineImpl::createMessage ( const std::string &  xmlPathFile_or_string, bool  pathfile_or_string = true  )

noexcept

Loads an xml file/string representing a diameter message base in a DTD document (#getDTD)

Parameters

xmlPathFile_or_string	Complete path file or string representation for the xml document which represents the diameter message
pathfile_or_string	boolean about the interpretation of the previous argument

getDictionary()

const stack::Dictionary* anna::diameter::codec::EngineImpl::getDictionary ( ) const

inline

Gets currently configured dictionary. NULL if not configured (manual encode/decode operations).

Returns

Returns currently configured engine dictionary

{ return a_dictionary; }

getFixMode()

FixMode::_v anna::diameter::codec::EngineImpl::getFixMode ( ) const

inline

Returns fix mode.

Returns

Fix mode: before encoding (by default), after decoding, always or never.

{ return a_fixMode; }

getSingleFailedAVP()

bool anna::diameter::codec::EngineImpl::getSingleFailedAVP ( ) const

inline

Returns single Failed-AVP boolean.

Returns

Failed-AVP could be one (true) or more (false) in answer message.

{ return a_singleFailedAVP; }

getValidationDepth()

ValidationDepth::_v anna::diameter::codec::EngineImpl::getValidationDepth ( ) const

inline

Returns behaviour on on validation procedure. For practical purposes, the Failed-AVP would typically refer to the first AVP processing error that a Diameter node encounters (decoding error or validation error in this case). A complete validation depth incurs on multiple-content Failed-AVP and is perhaps useful during integration tasks.

Returns

Behaviour on validation procedure: complete analysis or stop at first validation error over the message (by default).

{ return a_validationDepth; }

getValidationMode()

ValidationMode::_v anna::diameter::codec::EngineImpl::getValidationMode ( ) const

inline

Returns validation mode. Before coding validation mode is perhaps useful during debugging tasks, i.e. to check answer messages built by the application during development phase.

Returns

Validation mode: before encoding, after decoding (by default), always or never.

{ return a_validationMode; }

ignoreFlagsOnValidation() [1/2]

void anna::diameter::codec::EngineImpl::ignoreFlagsOnValidation ( bool  ignoreFlags )

inline

Sets behaviour on validation procedure regarding stack flags. Actually, only AVP flags M & P are affected. The vendor bit is too important to be ignored, and there is no way to check operation flags (as request bit). By default (at engine start), flags are verified.

Parameters

ignoreFlags

Validation will ignore flags.

{ a_ignoreFlags = ignoreFlags; }

ignoreFlagsOnValidation() [2/2]

bool anna::diameter::codec::EngineImpl::ignoreFlagsOnValidation ( ) const

inline

Gets behaviour on validation procedure regarding stack flags. Actually, only AVP flags M & P are affected. The vendor bit is too important to be ignored, and there is no way to check operation flags (as request bit). By default (at engine start), flags are verified.

Returns

Validation ignore flags indicator.

{ return a_ignoreFlags; }

releaseAvp()

virtual void anna::diameter::codec::EngineImpl::releaseAvp ( Avp *  )

pure virtual

Invoked to free Avps.

See also

anna::Recycler

Implemented in anna::diameter::codec::Engine.

releaseMessage()

virtual void anna::diameter::codec::EngineImpl::releaseMessage ( Message *  )

pure virtual

Invoked to free Messages.

See also

anna::Recycler

Implemented in anna::diameter::codec::Engine.

setFixMode()

void anna::diameter::codec::EngineImpl::setFixMode ( const FixMode::_v  fixMode )

inline

Sets fix mode.

Parameters

fixMode

Fix mode: before encoding, after decoding, always or never.

{ a_fixMode = fixMode; }

setSingleFailedAVP()

void anna::diameter::codec::EngineImpl::setSingleFailedAVP ( bool  single = true )

inline

Sets single FailedAVP. True by default. If false, and more than one wrong avp are found during message decoding and or validation, a new Failed-AVP will be added to the dynamic answer provided. The standard talks about only one but it is open to do this.

Parameters

single

Single Failed-AVP boolean.

{ a_singleFailedAVP = single; }

setValidationDepth()

void anna::diameter::codec::EngineImpl::setValidationDepth ( const ValidationDepth::_v  validationDepth )

inline

Sets behaviour on validation procedure.

Parameters

validationDepth

Behaviour on validation procedure: complete analysis or stop at first validation error over the message.

{ a_validationDepth = validationDepth; }

setValidationMode()

void anna::diameter::codec::EngineImpl::setValidationMode ( const ValidationMode::_v  validationMode )

inline

Sets validation mode.

Parameters

validationMode

Validation mode: before encoding, after decoding, always or never.

{ a_validationMode = validationMode; }

validationAnomaly()

void anna::diameter::codec::EngineImpl::validationAnomaly ( const std::string &  description ) const

protectednoexcept

Manages warning trace or exception on validation anomaly depending on ValidationDepth configuration ('complete' and 'first error' reports respectively).

Anomaly description used in trace or exception

See also

setValidationDepth

getValidationDepth

---

The documentation for this class was generated from the following file:

• /tmp/anna/include/anna/diameter/codec/EngineImpl.hpp