diameter-api-1.0.7.txt.svn-base

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

        }
};

\endcode

\section auth_server Authentication/Authorization Server Session

Diameter server applications should implement the class
AAA_ServerAuthSession or classes that derived from them. This class
provides virtual functions that is called by the library when 
configuration information is being gathered or when incomming 
session specific request message is recieved. 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_ServerAuthSession. 

\code

class AAA_SampleServer : public AAA_ServerAuthSession {
        // AAA serve session derived from AAA_ServerAuthSession.
        // It provides for all the functionality of a diameter 
        // server session. Note that the server session factory
        // is responsible for instantiating this object. Also,
	// any derived class must accept AAA_Task and application
	// id type as constructor parameter and must pass this
	// along to the AAA_ServerAuthSession base class.
    public:
        AAA_SampleServer(AAA_Task &task,
                         diameter_unsigned32_t id,
                         bool endOnSuccess = false) :
           AAA_ServerAuthSession(task, id) {
        }
        virtual void SetAuthSessionState
        (AAA_ScholarAttribute<diameter_unsigned32_t> &authState)
        {
            // optional override, called by the library to set 
            // the auth state. Note that this overrides the 
            // settings in the configuration file or applications 
            // sending an auth session state AVP
	    // Possible values are:
	    //   1. AAA_SESSION_STATE_MAINTAINED
	    //   2. AAA_SESSION_NO_STATE_MAINTAINED
            authState = AAA_SESSION_STATE_MAINTAINED;
        }
        virtual void SetSessionTimeout
        (AAA_ScholarAttribute<diameter_unsigned32_t> &timeout)
        {
            // optional override, called by the library so 
            // this server can dictate the session timeout 
            // to the client. If not overridden, the value 
            // in the config file is used
            timeout = 30;
        }
        virtual void SetAuthLifetimeTimeout
        (AAA_ScholarAttribute<diameter_unsigned32_t> &timeout)
        {
            // optional override, called by the library so 
            // this server can dictate the session timeout 
            // to the client. If not overridden, the value 
            // in the config file is used
            timeout = 2;
        }
        virtual void SetAuthGracePeriodTimeout
        (AAA_ScholarAttribute<diameter_unsigned32_t> &timeout)
        {
            // optional override, called by the library so 
            // this server can dictate the auth grace period
            // to the client. If not overridden, the value 
            // in the config file is used
            timeout = 2;
        }
        virtual AAAReturnCode ReAuthenticate(diameter_unsigned32_t rcode) {
            // optional override, called by the library so 
            // this server is informed that the client has
            // responded to the server initiated re-auth
            // request. The result code from the client
            // is passed as a parameter to this funciton.
            return (AAA_ERR_SUCCESS);
        }
        virtual AAAReturnCode RequestMsg(AAAMessage &msg) {

            // all request messages are handled by this function. 
            // This function can retrun the following values:
            // a. AAA_ERR_SUCCESS - client is successfully authenticated
            // b. AAA_ERR_INCOMPLETE - auth not yet completed, muti-round 
            //                         message trip exchange
            // c. AAA_ERR_FAILURE - client authentication failed

	    // Generally, a server application can send an
	    // application specific answer message from here
            return (AAA_ERR_SUCCESS);
        }
        virtual AAAReturnCode AnswerMsg(AAAMessage &msg) {
            // all answer messages are handled by this function.
            // AAA servers normally should not receive
            // answer messags. 
            return (AAA_ERR_SUCCESS);
        }
        virtual AAAReturnCode ErrorMsg(AAAMessage &msg) {
            // all error messages are handled by this function.
            return (AAA_ERR_SUCCESS);
	}
        virtual AAAReturnCode Success() {
            // notification of successful auth
                // ReAuth(AAA_SESSION_AUTHORIZE_AUTHENTICATE);
	    }
            return (AAA_ERR_SUCCESS);
        }
        virtual AAAReturnCode Disconnect() {
            // notification of completed STR/STA exchange
            return (AAA_ERR_SUCCESS);
        }
        virtual AAAReturnCode SessionTimeout() {
            // notification of session timeout
            return (AAA_ERR_SUCCESS);
        }
        virtual AAAReturnCode AuthorizationTimeout() {
            // notification of auth lifetime timeout
            return (AAA_ERR_SUCCESS);
        }
        virtual AAAReturnCode AbortSession() {
            // notification of completed ASR/ASA exchange
            return (AAA_ERR_SUCCESS);
        }
};

\endcode

Optionally, the server session class also has a built-in function 
to send a Re-Auth-Request message. This would be valid only if
the server session has initiated a stateful session and currently
in it's open state. The format of the re-auth function is as follows:

\code
        AAAReturnCode ReAuth(diameter_unsigned32_t type);
\endcode

As noted in previous sections, the application is not responsible 
for creating instances of server sessions. This is left to a server
session factory discussed in next sections.

\section auth_server_factory Server Session Factory

The server session factory is implemented using the template class
AAA_ServerSessionAllocator<SERVER_SESSION> where SERVER_SESSION
is an application specific class that derives from AAA_ServerAuthSession
or AAA_ServerAcctSession. This class derives from AAA_ServerSessionFactory
which has a pure virtual Create(...) function called by the library
when a new auth/acct request message is received from a new diameter
client. 

An instance of the AAA_ServerSessionAllocator<SERVER_SESSION> must be 
regsitered with an AAA_Application object. Once an AAA_Application
object receives a new request message, it can check the list of locally
registered factories if the application id present in the message is
supported by the diameter application. The code snipet below shows
the basic scenario.

\code

// Server session factory. Unlike AAA clients, server
// sessions need to be created on demand. This factory
// is responsible for creating new server sessions
// based on incomming new request.
typedef AAA_ServerSessionAllocator<AAA_SampleServer> 
        SampleServerAllocator;

int main(int argc, char *argv[])
{
   AAA_Task task;
   task.Start(5);

   diameter_unsigned32_t MyApplicationId = 10000;
   
   // Application core is responsible for providing
   // peer connectivity between AAA entities
   AAA_Application appCore(task, "my_server_configuration.xml");
   SampleServerAllocator allocator(task, MyApplicationId);
   appCore.RegisterServerSessionFactory(allocator);

   // do something here to wait as a deamon

   appCore.Close();
   task.Stop();
   return (0);
}

\endcode


\section acct_client Accounting Client Session

Accounting architecture on the client application is based on
a parent accounting session (AAA_ClientAcctSession) and one or
more sub-session (AAA_ClientAcctSubSession<REC_COLLECTOR>). As
described in RFC3588, a parent session defines the same Session-Id 
for all of it's sub-session. Each sub-session then defines it's own
Accounting-Sub-Session-Id and implements a specific record collection
method. A method maybe an event based record collection wherein record
collection is a one-time event or a sequence based collection where 
there is a start, interim and stop events. Each sub-session implements
the accounting client state machine described in Sec. 8.2 of RFC 3588.
In addition, a record collection mechanism is provided to the sub-session
to allow it to collect data from application specific sources. The record
collector is passed in as a template parameter to the sub-session class
to bind a specific collection scheme to a sub-session. In the similar 
manner, the sub-session instance requires the parent session to be passed
into it's constructor to bind it to a specific accounting session.

Applications are also required to implement thier own specific record
collection schemes and must derived from AAA_ClientAcctRecCollector class.
This class is an abstract class and application must implement all of the
required interfaces. The signature of the class is as follows:

\code
///
/// REC_COLLECTOR MUST implement this class
/// This class provides callback functionality
/// to applications with regards to record
/// collection.
///
class DIAMETERBASEPROTOCOL_EXPORT AAA_ClientAcctRecCollector
{
    public:
        /// Asks the client app to append collected record and other
        /// vendor specific AVP's in message list. The recordType is
	/// describes the current collection scheme (event or sequenced)
	/// and recordNum is the current record count.
        virtual void GenerateRecord(AAAAvpContainerList &avpList,
                                    int recordType,
                                    int recordNum) = 0;

	/// Asks the client app if there are pending records
	/// stored in the application
        virtual bool IsLastRecordInStorage() = 0;

	/// Asks the client app if there is buffer space available
        virtual bool IsStorageSpaceAvailable() = 0;

        /// Asks the client app to store the
        /// record in the message list since
	/// the library is not able to send it
	/// at the moment
        virtual AAAReturnCode StoreLastRecord(int recordType) = 0;

        /// Asks the client app to delete the
        /// last stored record if any
        virtual AAAReturnCode DeleteLastRecord(int recordType) = 0;
};
\endcode
 
Client accounting applications should create instances of classes 
AAA_ClientAcctSubSession<REC_COLLECTOR> or classes that derived from