diameter-api-1.0.7.txt.svn-base

在Diameter3588协议的基础上开发的软件

them. Where REC_COLLECTOR is a class derived from AAA_ClientAcctRecCollector.
The sub-session class provides virtual functions that is called by the 
library when configuration information is being gathered. The following code
snipet shows all of the available virtual functions that can be
implemented by the application. AAA_SampleClientSubSession is the application
specific class that derives from AAA_ClientAcctSubSession. AAA_SampleClientAcctRecCollector
is a sample record collection scheme implemented by the client.

\code
class AAA_SampleClientSubSession : 
    public AAA_ClientAcctSubSession<AAA_SampleClientAcctRecCollector> {
        // AAA client session derived from AAA_ClientAcctSession.
        // It provides for all the functionality of a diameter 
        // client accounting session. The ClientAcctSubSession
        // class is a template function that requires a proper
        // version of a record collector as a paramter. Note 
        // that the application is responsible for instantiating 
        // this object
    public:
        AAA_SampleClientSubSession(AAA_ClientAcctSession &parent) :
            AAA_ClientAcctSubSession<AAA_SampleClientAcctRecCollector>(parent) {
        }
        virtual void SetDestinationHost
        (AAA_ScholarAttribute<diameter_identity_t> &dHost)
        {
            // optional override, called by the library to 
            // set the destination host. Note that this 
            // overrides applications sending a destination
            // host AVP
            dHost = "server.isp.net";
        }
        virtual void SetDestinationRealm
        (AAA_ScholarAttribute<diameter_identity_t> &dRealm)
        {
            // optional override, called by the library 
            // to set the destination realm. Note that 
            // this overrides applications sending a 
            // destination realm AVP
            dRealm = "isp.net";
        }
        /// This function is used for setting realtime required 
        /// AVP as a hint to the server
        virtual void SetRealTimeRequired
        (AAA_ScholarAttribute<diameter_enumerated_t> &rt)
        {
        }
        /// This function is used for setting acct interim 
        /// interval AVP as a hint to the server
        virtual void SetInterimInterval
        (AAA_ScholarAttribute<diameter_unsigned32_t> &timeout)
        {
        }
        /// This function is used for setting RADIUS acct 
        /// session id for RADIUS/DIAMETER translations
        virtual void SetRadiusAcctSessionId
        (AAA_ScholarAttribute<diameter_octetstring_t> &sid)
        {
        }
        /// This function is used for setting multi-session 
        /// id AVP 
        virtual void SetMultiSessionId
        (AAA_ScholarAttribute<diameter_utf8string_t> &sid)
        {
        }
        virtual AAAReturnCode Success() {
            // notification of successful ACR exchange for all record type
            return (AAA_ERR_SUCCESS);
        }
        virtual AAAReturnCode Failed(int recNum) {
            // notification that recNum record was not processed properly
            return (AAA_ERR_SUCCESS);
        }
};
\endcode

The sub-session class also has the following built-in function to control
the beginning and termination of record collection:

\code
        /// This function initializes an AAA recording session
	/// The oneTime parameter determines wether this sub-session
	/// will be a one-time record collection event or a sequenced
	/// collection (start, interim and stop).
        AAAReturnCode Begin(bool oneTime = false);

        /// This function terminates the AAA recording session
        AAAReturnCode End();
\end verobse

Client accounting applications should create instances of classes 
AAA_ClientAcctSession. This provides the accounting parent session
functionality and is passed on to a sub-sessions constructor. The basic
usage of AAA_ClientAcctSession and how it is associated with the 
sub-sessions are show below.

\code
       diameter_unsigned32_t MyApplicationId = 10000;
       AAA_ClientAcctSession parent(task, MyApplicationId);
       for (int x = 0; x < 10; x ++) {
           // A new sub session id is created for each new sub session
           AAA_SampleClientSubSession subSession(parent);

           // shows sequenced record accouting (start/interim/stop)
           subSession.Begin(false);

           /// do something until record collection is completed
           subSession.End();
       }
\endcode

\section acct_server Accounting Server Session

Server accounting applications are similiar to auth server sessions.
The server session factory is responsible for it's creation. The difference
is that the server accounting session takes a record storage class as
a template parameter. The template format is AAA_ServerAcctSession<REC_STORAGE>
where REC_STORAGE is an application specific implementation of AAA_ServerAcctRecStorage.
AAA_ServerAcctRecStorage is an abstract class that is used by the library to
tell the application to store application specific record that has been carried
an Accounting-Request message. The signature of the class is as follows:

\code
///
/// REC_STORAGE MUST implement this class
/// This class provides callback functionality
/// to applications with regards to record
/// storage.
///
class AAA_ServerAcctRecStorage
{
    public:
	/// Asks the server app if there is enough storage space
        virtual bool IsSpaceAvailableOnDevice() = 0;

        /// Asks the server app to store record
	/// recordType indicates whether this is a event
	/// based record or sequenced. recordNum is the
	/// current record number
        virtual void StoreRecord(AAAAvpContainerList &avpList,
                                 int recordType,
                                 int recordNum) = 0;
};
\endcode

The AAA_ServerAcctSession<REC_STORAGE> class also provides virtual functions 
that is called by the library when configuration information is being gathered. 
The following code snipet shows all of the available virtual functions that 
can be implemented by the application. AAA_SampleServer is the application
specific class that derives from AAA_ServerAcctSession<REC_STORAGE>. 

\code
class AAA_SampleServer : 
    public AAA_ServerAcctSession<AAA_SampleRecStorage>
{
        // AAA serve session derived from AAA_ServerAcctSession.
        // It provides for all the functionality of a diameter 
        // accounting server session. Note that the server 
        // session factory is responsible for instantiating 
        // this object. AAA_ServerAcctSession is also a template
        // class that requires an AAA_ServerAcctRecStorage derived
        // class as a parameter.
    public:
        AAA_SampleServer(AAA_Task &task,
                         diameter_unsigned32_t id) :
            AAA_ServerAcctSession<AAA_SampleRecStorage>
                   (task, 
                    id, 
                    true) // dictates whether this session is stateful 
        {             
        }
        /// This function is used for setting realtime required 
        /// AVP as a hint to the server
        virtual void SetRealTimeRequired
        (AAA_ScholarAttribute<diameter_enumerated_t> &rt)
        {
            /// The following are possible values:
            ///   AAA_ACCT_REALTIME_DELIVER_AND_GRANT
            ///   ACCT_REALTIME_GRANT_AND_STORE
            ///   ACCT_REALTIME_GRANT_AND_LOSE
            rt = AAA_ACCT_REALTIME_DELIVER_AND_GRANT;
        }
        /// This function is used for setting acct interim 
        /// interval AVP dictated by the server to client
        virtual void SetInterimInterval
        (AAA_ScholarAttribute<diameter_unsigned32_t> &timeout)
        {
            timeout = 2; // tell client to generate record every 2 sec
        }
        virtual AAAReturnCode Success() {
            // notification of successful ACR exchange for all record type
            return (AAA_ERR_SUCCESS);
        }
        virtual AAAReturnCode Failed(int recNum) {
            // notification that recNum record was not processed properly
            return (AAA_ERR_SUCCESS);
        }
        virtual AAAReturnCode SessionTimeout() {
            // notification of session timeout if this
            // session was stateful
            return (AAA_ERR_SUCCESS);
        }
};

\endcode

\section msg_mux Message Multiplexer Class

The message multiplexer class is an auxillary class that can be used
with sessions that process application specific message. The main purpose
of the message mux is to designate handling or processing of an application
specific request or answer message to it's own class definition. It is 
independent of any session classes and operates soley on the AAAMessage
object passed to it. The message mux is composed of two (2) classes. An
abstract class that applications must implement. This provides the
functions where AAAMessage will be processed (AAA_SessionMsgMuxHandler<ARG>)
on a per-session basis. The second is the actual multiplexer itself 
(AAA_SessionMsgMux<ARG>). Both classes are template classes and has one 
template argument which can be any application specific type. The multiplexer 
allows applications to register a AAA_SessionMsgMuxHandler<ARG> for a message 
code. When a AAAMessage is multiplexed, the AAA_SessionMsgMux<ARG> simply 
checks a matching handler and forwards the message to that handler. The 
multiplexer can be called in RequestMsg(..) or AnswerMsg(..) functions 
in an appropriate session class. The signature of the handlers is as follows:

\code
template<class ARG>
class AAA_SessionMsgMuxHandler
{
    public:
        virtual ~AAA_SessionMsgMuxHandler() {
	}
        /// This function is called when incomming request message is received
        virtual AAAReturnCode RequestMsg(ARG &arg, AAAMessage &msg) = 0;

        /// This function is called when incomming answer message is received
        virtual AAAReturnCode AnswerMsg(ARG &arg, AAAMessage &msg) = 0;

        /// This function is called when incomming error message is received
        virtual AAAReturnCode ErrorMsg(ARG &arg, AAAMessage &msg) = 0;

    protected:
        AAA_SessionMsgMuxHandler() {
	}
};
\endcode

Further details on how to use the message multiplexers can be found in
the sample code.

*/