The Diameter APIToshiba America Research Inc.One Telcordia Drive, #1S222PiscatawayNJ08854+1 908-421-1845vfajardo@tari.toshiba.comCisco Systems, Inc.170 West TasmanSan JoseCA95134+1 408-853-5269pacalhou@cisco.comCisco Systems, Inc.500 Northridge Drive, Suite 800AtlantaGA30350+1 678-352-2764+1 978-334-0249dave@frascone.com
Operations and Management
Diameter Maintenance and Extensions (DIME)The Diameter authentication, authorization,
and accounting (AAA) protocol provides support for peering AAA transactions
across the Internet. This document describes an API for the
Diameter protocol. The API is defined for the C language.
The intent of the API is to foster source code portability across
multiple programming platforms. The Diameter authentication, authorization and accounting (AAA) protocol
provides scale-able AAA support for peering transactions across the Internet
. This document describes an API in C for
applications to access the Diameter protocol.
While an API is not strictly necessary for protocol
interoperability, it does help to promote the
use and deployment of a protocol by reducing the amount of work
necessary to develop and access applications that use the protocol.The Diameter protocol provides a basic attribute/value pair (AVP) data format,
which particular application profiles extend. Processing of the extensions
is handled by code specific to the application profile. Application
profile customizability is reflected into the API as callback functions
for C.The callbacks implement the application profile processing for incoming
messages. For outgoing calls, the C API provides an asynchronous model,
leaving processing of the return message to the callbacks.For the most part, the API hides the details of establishing peering
and redirect connections, parsing and creating Diameter messages, and
other work necessary to set up and maintain a redirect or peering session.
The application profile codes need only be concerned with processing of the
AVPs defined in the application profile. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in .This section discusses a number of implementation considerations for
bindings.The C API is expected to be thread-safe. Access to
data structures shared among threads must be coordinated to
avoid corruption or invalid access. In addition, API implementers
are encouraged to provide the maximum amount of parallel processing
within their library implementations by allowing multiple threads
in the API library at once.The API reports errors resulting from client calls through
language specific mechanisms. All functions in the API return
error codes. API implementers
are additionally encouraged to log errors using the appropriate platform
specific error logging technique, especially for errors that result
from network processing or other causes that are not directly related
to an API function or method call.C API clients are required to format strings as UTF-8 if the string
contains 16 bit characters. Since the ASCII characters and the UTF-8
8 bit characters have the same codes, ASCII can be used for UTF-8 if
no wide characters are in the string.
All strings passed through the C API are standard null-terminated C strings.
Processing to remove the null terminator for transmission on the wire
is done by the library. The API supports making a connection with
an arbitrary Diameter peer. The API allows a client to set
the server address in a message (AAASetServer()).
If a message is not sent to a particular server, the API library is
required to infer the servers by either looking in the configuration files
or dynamically determining the servers that support the extension. The commands that can be parsed by the local Diameter client
library or server are defined in a command dictionary file
containing the command definitions including AVPs. The location
and name of the command dictionary file is platform-specific. This
file is read and parsed to drive creation of
a command dictionary which is used by the library to
parse commands. The syntax
for the command dictionary file is in XML and
a DTD describing it is available in .
XML was selected as the definition language because
support for XML parsing is available as an extension to the standard
Java APIs and as a wide variety of public-domain C libraries,
simplifying implementation. Both APIs also support programmatic
definition of commands, AVPs, and extensions so programs can
add commands not in the dictionary for purposes of experimentation
and implementing the library.Some data structures defined in this document shows only the visible
or public member variables. Other internal or private member variables that maybe
necessary for the correct functioning of an implementation are
left for the implementors to define. Note that this document uses the
C language (see ) so there are no formal ways to guarantee
privacy of internal variables. It would be up to careful documentation and
the implementors discipline to maintain the integrity of the internal
variables privacy. An example of this is shown in
Sec .The C language API is designed around callbacks. An application profile
defines a collection of Diameter commands, and a library of callbacks for
processing those commands. Each command is processed
by a callback. Callbacks can also be defined that handle all commands.
The API provides functions for managing callbacks, including registration
and deregistration. When an incoming Diameter command arrives, the command is parsed and
passed to the appropriate callback. The callback receives as a parameter
the message struct, which contains the AVPs for the command. The
callback code can process the command by stepping through the AVPs.For outgoing requests, the API provides functions for creating messages and
adding AVPs. A collection of functions also provides access to the
AVP dictionary.Unless otherwise noted, parameters to API functions and callbacks
are non-NULL. Some parameters may have other restrictions. If a
parameter fails to satisfy the restrictions on its value, the
function returns AAA_ERR_PARAMETER.typedef struct sockaddr_storage AAA_IP_ADDR;AAA_IP_ADDR provides a way of referring to an IPv4 address,
IPv6 address, and IP port. The default implementation (shown here)
is defined in the Basic Socket Interface Extensions for IPv6
typedef uint32_t AAACommandCode;
AAACommandCode provides a way of referring to the AAA command code
of a command. It is used when registering callbacks, among others.
typedef uint32_t AAAVendorId;
AAAVendorId provides a way of referring to the vendor identification
code. It is used when registering callbacks, among others. Note
that vendor id 0 is reserved and is defined by the preprocessor
constant AAA_NO_VENDOR_ID.
typedef uint32_t AAAExtensionId;
AAAExtensionId provides a way of referring to an application profile
extension, for registering callbacks and other purposes.
typedef uint32_t AAA_AVPCode;
AAA_AVPCode provides a way of referring to the code number of an AVP.
It is used as a parameter to the dictionary functions, and a field
in the AVP struct.
typedef int32_t AAAValue;
AAAValue provides a way of referring to particular dictionary-defined
values. It is used in the dictionary API.
typedef void AAAServer;
AAAServer is an identifier for a particular serving peer. It is used in
the server access functions.
typedef void AAASessionId;
AAASessionId is an identifier for a particular AAA session. It is used in
the session APIs and when a message is created.
typedef uint32_t AAAMsgIdentifier;
AAAMsgIdentifier is a unique identifier for an AAA message. Each individual
message is marked with an identifier.
typedef void AAACallbackHandle;
AAACallbackHandle is a type for representing the callback
handle returned to the client when a callback is
registered.
typedef void* AAAApplicationId;
AAAApplicationId identifies a particular client session
to the API. The application id is passed to AAAStartSession(),
and is attached to incoming messages, to indicate with which
client session the message is associated.
The following status codes are returned by functions in the AAA API:Note that these status codes are separate from the codes returned by
remote AAA servers. The following is a description of the error codes and the reasons why
they can be returned:
This code is returned if a handle or id was
not found.
This code is returned if an unspecified failure
occurred during an AAA operation.
This code is returned if the AAA operation succeeded.
This code is returned if there is not enough memory to execute the operation.
This code is returned if a AAA protocol error occurred.
This code is returned if a security check failed or
another security error occurred.
This code is returned if an invalid parameter was
passed to an AAA function.
This code is returned if an error was encountered
in a configuration file during library initialization.
This code is returned if the library received a
AAA command that is not in the set of registered AAA commands.
This code is returned if a command was received
without a required AVP.
This code is returned if an attempt is made
to initialize the AAA library when it has already been initialized.
This code is returned when a network operation
times out.
This code is returned if the library can't
send a message. It is also of used to application profile extensions
that encounter the same error condition.
This code is returned by the command
registration functions if the command was already registered.
This code is returned by the command
registration functions if the command could not be registered.
This code is returned by any function
in the API except AAAOpen() if the library hasn't been initialized.
This code is returned by any function when an error in
networking occurs.In addition to returning the error code, functions are required to log
errors using the platform dependent logging facility.The following are codes used to indicate where a callback should
be installed in callback chain for processing:Callbacks installed with AAA_APP_INSTALL_FIRST and AAA_APP_INSTALL_LAST
operate on all commands, callbacks installed with AAA_APP_INSTALL_ANYWHERE
just operate on the command for which they are installed.The codes have the following semantics:
Install this callback as the first callback in the
chain. If subsequent callbacks are installed with this code, then
AAA_ERR_ALREADY_REGISTERED is returned.
Install this callback anywhere in the callback
chain.
Install this callback as the last callback in the
chain. If subsequent callbacks are installed with this code, then
AAA_ERR_ALREADY_REGISTERED is returned.The following are AVP data type codes. They correspond directly to the
AVP data types outline in the Diameter specification :The following are used for AVP header flags and for flags
in the AVP wrapper struct and AVP dictionary definitions. The first four
correspond to the AVP flags defined in the Diameter specification .
Some of these are also used in the wrapper struct and dictionary definitions
also. The last four are used only in AAA_AVP and AAADictionaryEntry: The semantics of the flags are as follows:
Indicates that no AVP flags are set.
Represents the 'M' flag in
the Diameter AVP header , meaning the AVP is mandatory.
Represents the 'V' flag in
the Diameter AVP header , meaning that the AVP is vendor specific.
If this flag is set, the header will contain a vendor identifier.
Indicates that the AVP was not located in the
AVP dictionary. This flag is only used
in AAA_AVP.The following domain interconnection types are returned by
AAAGetDomainInterconnectType(). They indicate the type of
domain interconnection:The flags have the following semantics:
The domain name is for the local domain.
The domain name is for a proxy domain. A proxy is a server
that simply forwards the request based on the user's identity or
through some other means. The routing method used for a proxy is
the Proxy-State method, requiring routing through a fixed chain of
proxies .
The domain name is for a broker domain. A broker is
a server that provides redirect services, allowing all servers in a
roaming consortium to interact directly.
The domain name is for a forwarding domain. A forwarding
domain is a proxy that uses Destination-NAI routing. With Destination-NAI
routing, there is no set sequence of proxies through which messages
must be routed .The following type is for the AAA message flags. Currently, there
are no message flags defined in the Diameter protocol :typedef uint8_t AAAMsgFlag;Result codes will be returned by the remote server to indicate the success
or failure of the operation. Result code values are defined in the
Diameter specification. The following type allows the client to specify
which direction to search for an AVP in the AVP
list:The following specifies the type of accounting message:The accounting types have the following semantics:
The event type is used to indicate that a one-time event has occurred.
The accounting start request is used to initiate an accounting session.
Interim messages contains cumulative accounting information for the
existing accounting session (started with an AAA_ACCT_START). Please
refer to for details on the Diameter accounting
mechanisms.
The Accounting stop request terminates a session started with AAA_ACCT_START.The following structure is returned by the dictionary entry lookup
functions. It contains information about a particular AVP in the
dictionary:The following structure contains a message AVP in parsed form:The fields have the following definitions:
Indicates whether the message is for Diameter
or for Radius compatibility. If the AVP is for Radius, then
the code, length, type, and data fields are the only valid fields
in the structure; the other fields are all null. The AVP code. The type of the AVP can be determined
by matching the AVP code with an AVP description from
the dictionary. The length of the AVP's data field. The AVP flags. The data type of the AVP's data. The vendor id, if the AVP is vendor-specific.
If the AVP is standardized, the vendorId field is set to
AAA_NO_VENDOR_ID. The AVP data, in host byte order.The following structure is used for representing
lists of AVPs on the message:AVPs are kept in ordered lists.
The client can use a search direction to indicated
in which direction to search when trying to find an AVP.The following structure contains the full AAA message:The fields have the following definition:
The message flags. Currently this field is always zero, since
there are no flags defined for a Diameter message at this time. The command's message code. The vendor id of the vendor that defined the message. Code indicating the result of the client's request.
This code is sent by the peer over the wire. The IP address of the message's originator. The IP address of the message's previous hop
sender. This is only the same as originator if no
proxy or broker peers are being used. The list of AVPs in the message. The proxy's AVP, if any. Otherwise NULL. The message's unique identifier. Number of seconds until the
message expires. The number of seconds at which the
message was started. An identifier indicating for which
client session the message is.The following definition reserves the vendor id of 0:#define AAA_NO_VENDOR_ID 0This section contains definitions that perform initialization
and configuration of the AAA library.The following function is used to open and configure the AAA library:This function must be called before any other AAA function is called.
Some of the operations that may be performed by AAAOpen() are: opening
and loading the AVP and vendor dictionaries, opening connections with
Diameter peers, loading Diameter extension libraries, and registering
Diameter callbacks. After AAAOpen() returns, the library must
be ready for the client to open a session.The parameters are:
The global configuration file name. If NULL or
the empty string, use the default for this platform. The global
configuration file must contain the vendor and AVP dictionary
file names, and may contain other platform-specific
information needed to initialize and configure the Diameter peer.Return values are:
If initialization succeeded. If the library is already initialized. If the host name can't be determined. If no memory was available. If processing the dictionary or configuration
information failed.The following function closes the AAA library:After this function is called, all other AAA functions are
no longer operative.Return values are:
If finalization succeeded. If AAA was not initialized.The following returns the default configuration file name on the platform:The return value is a pointer to the full pathname for
the file. The pointer value should not be deallocated because
it is constant and does not change.The functions in this section are used to register
callback functions defined in a Diameter application profile extension
library.
The following typedef defines the interface
between callback functions and the
AAA library functions:Authors of Diameter extensions must define command callback
functions having this interface.The parameters are:
The AAAMessage to be processed.The return value is a status code giving
the operation status.The following function is used to register command callbacks
for processing AAA commands:The parameters are:
The code of the command processed by the callback. The vendor id of the command. A pointer to the name of the command. The id of the extension to which this command belongs. The callback function to perform processing. The position of the callback in the chain.The return value is a handle used when deregistering the callback,
or NULL if an error occurred while registering the callback.The following callback registers an AAA callback to process all messages.
The callback is not associated with any command, but rather
will process all messages as they come down the callback chain:The parameters are:
The callback function to perform processing. The position of the callback in the chain.The return value is a handle used when deregistering the callback,
or NULL if an error occurred while registering the callback.The following function deregisters a command callback:The parameters are:
The handle returned when the callback was registered.The return values are:
Returned upon completion. if the callback is not registered.The following function is used to
deregister a noncommand callback:The parameters are:
The handle returned when the callback was registered.Return values are:
Returned upon completion. If the callback is not registered.The following function is used to register a Diameter
extension id. This function is typically called
when registering non-command specific callbacks. Extension ids for
command-specific callbacks are registered when the callback
is registered:The parameters are:
The extension id.The return codes are:
If the registration was successful. if a memory allocation failure occurred.The functions in this section allow the
client to open, close, and register
sessions, and to obtain server identifiers.The following function allows a client to start a session and identify it:The parameters are:
On return, a pointer to the session id for this session. An identifier for the client application starting the
session. This identifier is attached to messages so that the
client callbacks can tell which messages belong to it.- The NAI of the user. A function to be called if this session is aborted
by the server.Return values are:
If the session was successfully started. If a memory allocation failure occurred.The following function allows a client to register
a peer session that it has discovered through
some other means, for example, by receiving
an unsolicited message.The parameters are:
On return, a pointer to the local session id for the session. An identifier for the client application starting the
session. This identifier is attached to messages so that the
client callbacks can tell which messages belong to it. The message from the peer containing the session id.- The NAI of the user. The originator of the Diameter messageReturn values are:
If the session was successfully registered. If a memory allocation failure occurred.The following function, sent by a client, terminates a session:The parameters are:
A pointer to the session id for the session.Return values are:
If the session was successfully closed. If the handle is invalid.The following function, sent by the server, terminates
a session:The parameters are:
A pointer to the session id for the session.Return values are:
If the session was successfully closed. If the handle is invalid.The function looks up the AAA server based on IP address and port number.
Server connections are created from the configuration file:The parameters are:
The IP address/Port/Family of the server.The return value is either a valid server pointer or the
NULL if the server can't be found.The following function sets the timeout, in seconds, for all
AAAMessages in a particular session:The parameters are:
The session id for the session whose timeout should be changed. The session timeout. The default timeout is 120 seconds.The return values are:
If setting the timeout succeeded. If the setting the timeout failed.The following function returns the domain interconnect type for
a particular domain name and type of service:The parameters are:
The name of the domain. The type of service. This must be one of the strings "LOCAL",
"PROXY", or "BROKER".The return values are:
If the domain interconnect type was retrieved. If the command failed.The functions in this section are used to look up AVPs
and commands in the dictionary. The client is responsible
for supplying the structure memory into which the
dictionary information is copied.This function looks up a dictionary entry using a command code and a
vendor id:The parameters are:
The code number of the AVP. The vendor id of the AVP. an AAADictionaryEntry structure for returning the entry.The return value is one of:
If the query succeeded. If no matching dictionary entry was found.This function looks up a dictionary entry using command code
name and vendor id:The parameters are:
The name of the AVP. The vendor id of the AVP. an AAADictionaryEntry structure for returning the entry.The return value is one of:
If the query succeeded. If no matching dictionary entry was found.This function looks up an AVP value using the AVP name and vendor name:The parameters are:
The name of the AVP. The name of the vendor. The name of the value.The return value is the id of the AVP, or AAA_ERR_NOT_FOUND if no
match was found.This function looks up an AVP value using the AVP id and vendor id,
and the value name:The parameters are:
The code of the AVP. The id of the vendor. The name of the value.The return value is id of the AVP, or AAA_ERR_NOT_FOUND if no
match was found.This function returns the AVP value name:The parameters are:
The code of the AVP. The id of the vendor. The value.The value name is returned, or NULL if
no match occurred.This function returns the command code and vendor id based on a string:The parameters are:
A string containing the command name. Pointer that on return holds the
command code if the command was found. Pointer that on return holds the
vendor id if the command was found.The function returns AAA_ERR_SUCCESS when a command has been successfully
retrieved, otherwise AAA_UNKNOWN_CMD is returned.The functions in this section allow the client to
create messages, add AVPs, and traverse AVP lists.This function allocates an AAAMessage and returns a pointer to it.
If a command code is provided, this function adds the command code AVP.
If the session identifier handle is provided,
the Session-Id AVP is also added. Lastly, if this message is
allocated in response to a request, the request's message can be provided,
and the new message is initialized to match the request, for
fields such as the identifier, the server identifier, etc. If this is
a new message, the request parameter is NULL:The parameters are:
The command code. The vendor identifier. Session identifier. The extension identifier. A pointer to a request message, if this message is
being allocated in response to a request.The function returns a pointer to the message or NULL if a
failure occurred.This function frees a message allocated through
AAANewMessage():The parameters are:
A pointer to a pointer to the allocated message.The return value is the AAA status code AAA_ERR_SUCCESS.This function is called to set the AAA Message
to the appropriate values, and to inform the library
that this message is a locally generated response The parameters are:
The AAAMessage to respond to. The command code of the response. The vendor identifier (of the command code). The result code of the response.The function returns AAA_ERR_SUCCESS upon completion, or AAA_ERR_PARAMETER
if a NULL pointer was provided.This function will add a Proxy-State AVP to
a message, that contains the Fully Qualified Domain Name (FQDN)
of the source of the message.The parameters are:
The AAAMessage to add state to.The function returns AAA_ERR_SUCCESS upon completion, or
AAA_ERR_FAILURE if an error occurred.This function creates an AVP and returns a pointer to it. The AVP
is initialized from the arguments:The parameters are:
On return, contains a pointer to the allocated AVP, or NULL if
no AVP was allocated. The AVP's code. Any AVP flags that must be passed. The vendor id of the AVP. If no vendor id, then
AAA_NO_VENDOR_ID. A buffer containing the AVP data. The length of the data buffer.Return values are:
Upon success. If an invalid parameter was passed. If a protocol error occurred. Indicating a memory failure.This function creates an AVP and adds it to an AVP list. It returns
a pointer to the list in the avpList argument. If the avpList is NULL
a new list is created. The new AVP is always added to the end of
the list. The AVP is initialized from the arguments:The parameters are:
The list to which the AVP should be added. The AVP's code. Any AVP flags that must be passed. The vendor id of the AVP. If no vendor id, then
AAA_NO_VENDOR_ID. A buffer containing the AVP data. The length of the data buffer.Return values are:
Upon success. If an invalid parameter was passed. Indicating a memory failure.Insert the AVP avp into this avpList after position. If position is
NULL, the AVP is added to the beginning of the list.If *avpList is NULL, a list will be allocated, and *avpList will point
to it.The parameters are:
Pointer to a pointer for list. If *avpList is NULL, list memory is
allocated. AAA_AVP to add to list. AAA_AVP pointer to add data after, or NULL if the new AVP
should go at the beginning of the list.The return value is one of:
Upon success. If an invalid parameter was passed. Indicates a memory failure.This function finds an AVP with matching code and vendor id. If none match,
the function returns NULL:The parameters are:
A pointer to the head of the AVP list. The code of the sought after AVP. The vendor id of the sought after AVP.The return value is a pointer to the found AVP, or NULL if none
is found.The following function joins together two AVP lists:The parameters are:
The destination list (All of the AVPs in source will be moved here). The source list to be added to dest. The position to add the AVPs to, or NULL for the beginning of the list.The return value is one of:
Upon success. If an invalid parameter was passed.This function removes an AVP from a list:The parameters are:
The head of the list from which to
remove the AVP. Contains a pointer to the AVP to remove. The return value is one of:
Upon success. If an invalid parameter was passed.The function frees an AVP:The parameters are:
Contains a pointer to a pointer to the AVP to free.The return value is one of:
Upon success. If an invalid parameter was passed.This function returns a pointer to the first AVP in the list:The parameters are:
A pointer to the list.The return value is a pointer to the found AVP,
or NULL if none is found.This function returns a pointer to the last AVP in the list:The parameters are:
A pointer to the list.The function returns a pointer to the found AVP,
or NULL if none is found.This function returns a pointer to the next AVP in the list.The parameters are:
A pointer to the AVP prior to the one sought.
It is assumed that AAA_AVP has internal private members that keep track of
the next AAA_AVP element in the list.The return value is the next AVP in the list, or NULL if
the parameter is the last element in the list.This function returns a pointer to the previous AVP in
the list. It is assumed that AAA_AVP has internal private members
that keep track of the previous AAA_AVP element in the list.The parameters are:
A pointer to the AVP after the one sought.The return value is the previous AVP in the list or
NULL if the parameter is the first element in the list.This function frees an AVP list structure including all contained AVPs
if there are any. If the list is empty then only the AVP list data structure
itself is deleted. If successful, the list will point to NULL on return.The parameters are:
The list to be freed.Return values are:
Upon success. If an invalid parameter was passed.This function converts the data in the AVP to a format suitable
for log or display functions.The parameters are:
The AVP to display. A used supplied destination buffer. The length of the user supplied buffer.The return value is the passed in destination buffer.This function decapsulates an encapsulated AVP,
and populates the list with the correct pointers.The parameters are:
A pointer to the allocated message. The AAA Result Code The return value is one of:
Upon success. If an invalid parameter was passed.The following functions allow the client to direct
a message to a particular server, determine
the server for a message, etc.This function sets the server to which the
message is sent:The parameters are:
The message to be sent. The IP address / port / family of the server.The return value is:
If the server was found. If the server was not found.The following function transmitts a message. It will be sent
to the server based on the routing criteria defined in .The parameter is the message to send.The return codes are:
Upon completion. If an error occurred.The following functions allow the client to direct
a message to a particular server, determine
the server for a message, etc.The following function sends an accounting message to an accounting
server.The parameters are:
The session id that this accounting data corresponds to. The extension type associated with this accounting message. A list of AVPs to send in the accounting message. The type of accounting message.The return codes are:
Upon completion. If a parameter is invalid.The following are some implementation notes that library designers
may want to keep in mind.In order to create grouped AVPs, an application creates an AAA_AVP_LIST
that is not attached to an AAAMessage structure (also known as an orphaned
AAA_AVP_LIST). All of the necessary AVPs within the Group are added to
the orphaned AAA_AVP_LIST using the existing list manipulation functions.
Lastly, the grouped AVP is added to the AAAMessage structure.The following is an example that adds a Proxy-State Grouped AVP to an
existing AAAMessage structure.As shown above, the procedures is to create a new AAA_AVP_LIST structure,
adding all of the necessary AVPs that are within the Grouped AVP, then
calling AAACreateAndAddAVPToList() to add the AAA_AVP_LIST as a Grouped
AVP to the AAAMessage.Note that the AAA_AVP_LIST pointed to by orphaned avpList MUST NOT be
accessed by the application after the Grouped avp has been created. The
list will be freed along with the AVP by the AAA Library.In order to parse a Grouped AVP, the AAA_AVP data field contains a
pointer to an AAA_AVP_LIST, as shown below.The AAA_AVP structure that is defined in this specification is
a subset of the structure used by the internal library. The internal
structure, known as the extended AAA_AVP, may contain many private
fields, such as pointers to AAA_AVPs. Applications do not directly
access the next (and previous) AAA_AVP pointers but
instead access them via the AAAGetNextAVP() and AAAGetPreviousAVP()
functions (see ).The following is an example of an extended AAA_AVP structure:Of course, when AAACreateAVP is called, sufficient memory is allocated
for the extended AAA_AVP structure, however the function returns a
pointer to the AAA_AVP.The AAA_AVP struct does not provide an exact mapping to
the Diameter protocol AVP packet format; however, library
implementers can avoid having to copy the AVP data by
putting a pointer to a packet format structure into
a hidden part of the AAA_AVP struct. A pointer to
the AVP data is then deposited into the AAA_AVP
data field. This allows proper deallocation of the
packet format structure when the AAA_AVP structure
is deallocated.The C API allows API clients to register message processors,
or callbacks, that are
invoked before and after the bulk of the processing functions for
a message. Only one pre- or post-processor is allowed for all
incoming messages, regardless of command or extension type. If
the API client adds another, any existing pre- and post-processors
are removed. Message processing can be best explained by the following diagram:In the above diagram, "First", "Any", and "Last" are added by the
API client. The message processor labeled "First" is given
access to the message before any other, the message processor "Last"
after all others are finished. There is no guarantee on ordering
for the other message processors. If the client adds a new "First"
or "Last" message processor, AAA_ERR_ALREADY_REGISTERED error is
returned. There is one "First" and "Last" processor for all commands regardless
of type; whereas, the "Any" processors are command-specific.If one of the "Any" processors completes successfully, the message
is not passed on any further. A successful
completion means the success return code is returned from the
C API callback, but the callback is responsible for freeing the
message before returning.This document describes an API and therefore depends on the security
mechanisms defined in the Diameter protocol . This document has no actions for IANA. The authors would like to thank James Kempf for his input
to this document.Diameter Base ProtocolBasic Socket Interface Extensions for IPv6Key words for use in RFCs to Indicate Requirement LevelsDiameter XML Dictionary