diameter-api-1.0.7.txt.svn-base

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

/*! 

\mainpage Open Diameter C++ API 
\author Victor I. Fajardo
\date Jan 4, 2005

This document is a general descripton of the Open Diameter C++ API. 
The C++ API in this release (1.0.7-e) 

\section general Overview

The Open Diameter C++ API is a simple session based API with each
type of diameter session being represented by a C++ class. User
applications derived from these session classes to implement thier
own specific AAA functionality. All events, received messages
processing and message transmissions functionality are provided
by these classes. Generally, the session classes are categorized
into either client or server. The client classes provided AAA client
capabilities and server classes provide AAA server functions. These
two types of classes are further sub-divided into either authentication/
authorization classes and accounting classes. All of these session 
classes derived from a specific AAA state machine framework as 
defined in Sec 8 of RFC3588. Applications can pick and choose which 
AAA functionality they require and derived the appropriate 
session classes. 

The main difference between client and server classes are on the 
way they are instantiated. For application classes based on client 
sessions, it is the responsibility of the AAA client application 
to create and manage the instances of these sessions. For application
classes based on server sessions, the library is responsible in creating 
and deleting instances of these classes. Deletion of server classes are
done by an internal garbage collector when a server session has completed
it's execution as defined by it's state machine. To facilitate the 
instantiation of application derived server session classes, the library
provides a server session factory that an application may instantiate
and register. Once properly registered, these session factories will
create AAA session objects everytime a new auth/accouting request 
arrives. The only criteria for this action is if the local AAA applicaiton
supports the application id advertized in the initial request message.

It is important to note that both client and server session classes 
only provide diameter session management. Diameter peer connectivity
management is provided (contained) within another class called the 
application class. This class manages configuration loading, peer 
connectivity and AAA message routing. Client session classes binds 
to this application class via it's constructor. Server classes are
bounded to an application class via the server session factory class
which is registered in the application class. By binding to the 
application class, a session classes are able to send and receive
messages from the routing platform provided by the application class.
The figure below shows the basic association of the different classes
provided in the Open Diameter C++ API.

\image html api_classes.jpeg
\image latex api_classes.eps
<B>Figure 1. Basic associations of Diameter C++ classes</B>

As shown in the figure, an client accounting session is also required
to implement a record collector object. This class is passed in as a 
template parameter to the client accounting sub-session and must be derived
from AAA_ClientAcctRecCollector interface. The implementation of this
class is application specific. In the same token, the server accounting 
session is also required to implement a record storage object to archive 
records sent by the client (or perhaps sent to a billing system). It is
also passed in as a template parameter to the AAA_ServerAcctSession.

There are also additional utility functions provided by the API to
facilitate a more object oriented approach to message handling (i.e.,
AAA_SessionMsgMux<SESSION>). Further details about these classes and
the API set is explained in the succeeding sections. For sending AAA
messages from any session class, a built-in send function exists in
all session classes. The format of this function is as follows:

\code
       virtual AAAReturnCode Send(std::auto_ptr<AAAMessage> msg);
\endcode

Note that any message that is composed by the application must be
passed in as an auto_ptr<>. This means that the session class will
take over ownership of the AAAMessage object. 

Usage of the API is best described in the sample code of libdiameter.
There are several sample code that came with the distribution and
each describes how to use different aspects of the API. However, the 
succeding sections show all the basic classes necessary to implement 
a diameter AAA application.

\section application Application Class

The application class provides peer connectivity management, route
tables and logic and general configuration databases. All applications
must have an instance of the application class (AAA_Application).
An instance of AAA_Application is synonymous to having a single AAA
diameter entity. So, it is possible for a single program to have multiple
instance of an AAA_Application representing different AAA diameter entities.
The application class also provides registration function for server session 
factories that allow all server sessions to be bounded to to the AAA_Application. 
The following code snipet show the basic usage of AAA_Application

\code   
   // A running AAA_Task must provide execution
   // context to the AAA_Application
   AAA_Application appCore(task);
   if (appCore.Open("my_configuration_file.xml") == AAA_ERR_SUCCESS) {

       diameter_unsigned32_t MyApplicationId = 10000;
       
       /// An application instance can optionally
       // wait for peer connectivity before proceeding
       do {
           ACE_OS::sleep(1);
       } while (appCore.NumActivePeers() == 0);

       // Applications can now register server session factories
       // if this AAA will have some server functionality
       SampleServerAllocator allocator(task, MyApplicationId);
       appCore.RegisterServerSessionFactory(allocator);
       
       // do something here
       // The AAA_Application object must be persistent       
       // within the instances context of all session 
       // classes since all sessions must be bounded to
       // an AAA_Application

       // remove the factory when done       
       appCore.RemoveServerSession(MyApplicationId);
   }
\endcode

\section auth_client Authentication/Authorization Client Session

Diameter client applications should create instances of classes 
AAA_ClientAuthSession 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 answer message is recieved. The following code
snipet shows all of the available virtual functions that can be
implemented by the application. AAA_SampleClient is the application
specific class that derives from AAA_ClientAuthSession. 

\code

class AAA_SampleClient : public AAA_ClientAuthSession {
        // AAA client session derived from AAA_ClientAuthSession.
        // It provides for all the functionality of a diameter 
        // client session. Note that the application is responsible
        // for instantiating this object. Also, the derived class
	// has to provide an instance of an active AAA_Task object
	// and the proper application id of the session
    public:
        AAA_SampleClient(AAA_Task &task,
                         diameter_unsigned32_t id) :
            AAA_ClientAuthSession(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 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";
        }
        virtual void SetSessionTimeout
        (AAA_ScholarAttribute<diameter_unsigned32_t> &timeout)
        {
            // optional override, called by the library so 
            // this client can send a hint to the server 
            // about the session timeout it prefers. 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 client can send a hint to the server 
            // about the auth lifetime it prefers. If not
            // overridden, the value in the config file
            // is used
            timeout = 29;
        }
        virtual AAAReturnCode ReAuthenticate(diameter_unsigned32_t type) {
            // optional override, called by the library so 
            // this client is informed about a re-auth request
            // initiated by the server. Note that the client
            // must return a valid result-code when exiting
            // this function
            return (AAAReturnCode)(AAA_SUCCESS);
        }
        virtual AAAReturnCode RequestMsg(AAAMessage &msg) {
            // all request messages are handled by this function.
            // AAA clients normally should not receive
            // request messags. 
            return (AAA_ERR_SUCCESS);
        }
        virtual AAAReturnCode AnswerMsg(AAAMessage &msg) {

            // all answer 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

            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
            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);