efd.h File Reference

freeDiameter wrapper classes. More...

#include <stddef.h>
#include <string.h>
#include <arpa/inet.h>
#include <time.h>
#include <stdexcept>
#include <string>
#include <list>
#include <map>
#include "freeDiameter/freeDiameter-host.h"
#include "freeDiameter/libfdcore.h"
#include "freeDiameter/libfdproto.h"
#include "ebase.h"
#include "estring.h"
#include "etime.h"
#include "etimer.h"
#include "eutil.h"

Go to the source code of this file.

Classes
class	FDException
	Exception base class used within the freeDiameter wrapper classes. More...
class	FDBuffer< T >
class	FDEngine
	Provides an interface for controlling freeDiameter. More...
class	FDDictionaryEntry
	A class wrapper around a freeDiameter dictionary entry. This base class is not intended to be directly instantiated. More...
class	FDDictionaryEntryApplication
	A dictionary entry object associated with an application. More...
class	FDDictionaryEntryVendor
	A dictionary entry object associated with a vendor. More...
class	FDDictionaryEntryAVP
	A dictionary entry object associated with an AVP. More...
class	FDDictionaryEntryCommand
	A dictionary entry object associated with a command message. More...
class	FDAvp
	A class wrapper around a freeDiameter AVP object. More...
class	FDMessage
	Represents a freeDiameter message. More...
class	FDMessageAnswer
	Represents a Diameter answer message (in rsponse to a request). More...
class	FDMessageRequest
	Represents a Diameter request message. More...
class	FDCommand
	Represents a command, a request or answer, that will be registered with freeDiameter. More...
class	FDCommandRequest
	Represents a command request. More...
class	FDApplication
	Represents a Diameter application. More...
class	FDSession
	Allocates and assigns a Session-Id. More...
class	FDPeer
	Represents a Diameter peer. More...
class	FDPeerList
	A list of FDPeer objects. More...
class	FDExtractorBase
	Extractor base class. An extractor is a wrapper around an AVP that locates and accesses the AVP in the message or grouped AVP. More...
class	FDExtractorKey
	Used as the key to a collection of extractors. More...
class	FDExtractor
	A wrapper around a grouped AVP used to locate and access the AVP's in the parent message or grouped AVP. More...
class	FDExtractorList
	A wrapper around a grouped AVP that can occur multiple times. More...
class	FDExtractorAvp
	An AVP extractor object. More...
class	FDExtractorAvpList
	An extractor for an AVP that can have multiple occurrances. More...
class	FDHook
	Registers, unregisters and process freeDiameter hooks. See "MONITORING" in libfdcore.h in the freeDiameter library. More...
class	FDUtility
	Various Diameter utility functions. More...

Enumerations
enum	DiameterDataType {   DDTUnknown, DDTOctetString, DDTI32, DDTI64,   DDTU32, DDTU64, DDTF32, DDTF64,   DDTGrouped, DDTAddress, DDTTime, DDTUTF8String,   DDTDiameterIdentity, DDTDiameterURI, DDTEnumerated, DDTIPFilterRule }
	The Diameter AVP data types. More...
enum	FDPeerState {   PSInvalid = -1, PSNew = 0, PSOpen, PSClosed,   PSClosing, PSWaitCnxAck, PSWaitCnxAckElec, PSWaitCEA,   PSOpenHandshake, PSSuspect, PSReOpen, PSOpenNew,   PSClosingGrace, PSZombie }
	Peer state enumerations. More...
enum	eFDExtractorType { etAvp, etAvpList, etExtractor, etExtractorList }
	Defines the types of extractors. More...

Detailed Description

freeDiameter wrapper classes.

STARTUP, SHUTDOWN AND ADVERTISING SUPPORT FOR AN APPLICATION

Initialization of the freeDiameter library is achieved by performing the following operations.

1. Create an instance of FDEngine that will exist for the duration of the applciation.
2. Tell the freeDiameter library what configuration file to use by calling FDEngine::setConfigFile().
3. Initialize the freeDiameter library by calling the FDEngine::init() method. This will only initialize the library, it will not actually start communicating with other diameter endpoints until the start() method is called.
4. Call FDEngine::advertiseSupport() for each supported diameter application. To populate the top level Auth-Application-Id or Acct-Application-Id AVP in the Capabilities-Exchagne request or answer, call the FDEngine::advertiseSupport() method that does NOT accept a FDDictionaryEntryVendor object. To populate the the top level Vendor-Specific-Application-Id, use the FDEngine::advertiseSupport() method that does accept a FDDictionaryEntryVendor object.
5. After advertising support for all of the desired applications, start freeDiameter by calling FDEngine::start().
6. At this point, freeDiameter is up and running. The application can wait for the freeDiameter engine to exit by calling FDEngine::waitForShutdown(). This method will block until freeDiameter has completed it's shutdown process. The shutdown process can be triggered by calling FDEngine::uninit() from any thread or from a signal handler.

SENDING A REQUEST AND RECEIVING AN ANSWER

SENDING A REQUEST

Derive new class from FDMessageRequest overriding the processAnswer() virtual method. the processAnswer() method will be called when the answer is received.

If using the interface specific objects generated by fdtool, it may be necessary to derive a new object from the generated message specific request object, ie s6t::COIRreq, in order to add additional data that may be required when processing the answer.

1. "new" the derived FDMessageRequest object
2. Populate the appropriate AVP's
3. Send the request using the send() method *** DO NOT DELETE THE REQUEST OBJECT ***

RECEIVING AN ANSWER

1. The processAnswer() virtual method will be called with the context of the original derived FDMessageRequest object.
2. Inside the processAnswer() virtual method, Create the appropriate FDMessageAnswer (or derived) object and process the answer accordingly.
3. When the FDMessageAnswer object goes out of scope (or is deleted), the underlying freeDiameter message will be freed.
4. After returning from the processAnswer() method, the FDMessageRequest internals will delete the associated FDMessageRequest object.

RECEIVING A REQUEST AND SENDING AN ANSWER

Unlike sending a request and receiving an answer where the answer is processed by virtual method associated with the request object, processAnswer(), to process an incoming request, a command hander needs to be registered using the FDApplication::registerHandler method. If using the fdtool generated interface specific objects, this can be done by uncommenting the appropriate handler in the Application::registerHandlers() method. Then when an incoming request is received the process() method associated with the command object will be called to process the incoming request.

RECEIVING A REQUEST

1. The process() method of the previously registered command object will be called by the framework.
2. Perform whatever processing is required to process the request. If it is necessary to send a request to another application before answering this request, make sure to save the FDMessageRequest*, it will be needed to generate the answer.

SENDING AN ANSWER

1. Construct a FDMessageAnswer object by using the FDMessageRequest* received in the command process() method. The FDMessageAnswer can be allocated on the stack, it does not need to be created on the heap using "new".
2. After adding the necessary AVP's to the answer, send the answer message by calling the FDMessageAnswer::send() method.
3. "delete" the FDMessageAnswer object if it was created using "new".

ADDING AVP'S TO A MESSAGE

AVP's can be added to a message by calling any of the overloaded FDMessage::add() methods. To add an AVP using a basic data type, the FDDictionaryEntryAVP that describes the AVP must also be passed in to the FDMessage::add() method. Additionally, a previously FDAvp object can be added using the FDMessage::add() method. If it is necessary to copy an AVP from one message to another, the FDMessage::add() method will accept any of the FDExtractor objects (FDExtractor, FDExtractorList, FDExtractorAvp or FDExtractorAvpList).

ADDING AVP'S TO A GROUPED AVP

First, create an FDAvp object using the appropriate FDDictionaryEntryAVP object that describes the grouped AVP. Then any AVP can be added to the grouped AVP using the same overloads to the FDAvp::add() method that are available in the FDMessage::add() methods. Once all AVP's have been added to the grouped AVP, add the grouped AVP to it's parent, another grouped AVP or a message, using the add() method on the parent object.

Enumeration Type Documentation

DiameterDataType

enum DiameterDataType

The Diameter AVP data types.

Enumerator
DDTUnknown	unknown/undefined
DDTOctetString	octet string
DDTI32	32-bit integer
DDTI64	64-bit integer
DDTU32	32-bit unsigned integer
DDTU64	64-bit unsigned integer
DDTF32	32-bit floating point
DDTF64	64-bit floating point
DDTGrouped	grouped AVP
DDTAddress	IP address.
DDTTime	time value
DDTUTF8String	UTF-8 string (derived from octet string)
DDTDiameterIdentity	diameter identity (UTF-8 string)
DDTDiameterURI	diameter URI
DDTEnumerated	enumerated type
DDTIPFilterRule	IP filter rule.

eFDExtractorType

enum eFDExtractorType

Defines the types of extractors.

Enumerator
etAvp	represents an AVP extractor
etAvpList	represents an AVP list extractor
etExtractor	represents an extractor (grouped AVP)
etExtractorList	represents an extractor list (grouped AVP)

FDPeerState

enum FDPeerState

Peer state enumerations.

Enumerator
PSInvalid	Invalid or undefined state.
PSNew	The peer has been just been created, PSM thread not started yet.
PSOpen	Connection established.
PSClosed	No connection established, will re-attempt after TcTimer.
PSClosing	The connection is being shutdown (DPR/DPA in progress).
PSWaitCnxAck	Attempting to establish transport-level connection.
PSWaitCnxAckElec	Received a CER from this same peer on an incoming connection (other peer object), while we were waiting for cnx ack.
PSWaitCEA	Connection established, CER sent, waiting for CEA.
PSOpenHandshake	TLS Handshake and validation are in progress in open state – we use it only for debug purpose, it is never displayed.
PSSuspect	A DWR was sent and not answered within TwTime. Failover in progress.
PSReOpen	Connection has been re-established, waiting for 3 DWR/DWA exchanges before putting back to service.
PSOpenNew	After CEA is sent, until a new message is received. Force ordering in this state.
PSClosingGrace	After DPA is sent or received, give a short delay for messages in the pipe to be received.
PSZombie	The PSM thread is not running anymore; it must be re-started or peer should be deleted.