The CDP Module

Dragos Vingarzan

   Fraunhofer

Edited by

Jason Penton

Richard Good

Carsten Bock

   ng-voice GmbH

   Copyright © 2006 FhG Fokus

   Copyright © 2012 Smile Communications

   Copyright © 2017 ng-voice GmbH
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. How it works
        3. Dependencies

              3.1. Kamailio Modules
              3.2. External Libraries or Applications

        4. Parameters

              4.1. config_file (string)
              4.2. latency_threshold (int)
              4.3. workerq_latency_threshold (int)
              4.4. workerq_length_threshold_percentage (int)
              4.5. debug_heavy (int)
              4.6. enable_tls (int)
              4.7. tls_method (string)
              4.8. private_key (string)
              4.9. certificate (string)
              4.10. ca_list (string)

        5. Functions

              5.1. cdp_check_peer(fqdn)
              5.2. cdp_has_app([vendorid, ]application)

        6. RPC Commands

              6.1. States
              6.2. cdp.disable_peer
              6.3. cdp.enable_peer
              6.4. cdp.list_peers

        7. Configuration Examples

              7.1. DiameterPeer.xml example

   2. Developer Guide

        1. Available Functions

              1.1. load_cdp(struct cdp_binds *cdpb)
              1.2. AAACreateRequest(AAAApplicationId app_id,
                      AAACommandCode command_code, AAAMsgFlag flags,
                      AAASession *session)

              1.3. AAACreateResponse(AAAMessage *request)
              1.4. AAAReturnCode AAAFreeMessage(AAAMessage **msg)
              1.5. AAAReturnCode AAASendMessage(AAAMessage *message,
                      AAATransactionCallback_f *callback_f, void
                      *callback_param)

              1.6. AAAReturnCode AAASendMessageToPeer(AAAMessage *message,
                      str *peer_id, AAATransactionCallback_f *callback_f,
                      void *callback_param)

              1.7. AAAMessage* AAASendRecvMessage(AAAMessage *message)
              1.8. AAAMessage* AAASendRecvMessageToPeer(AAAMessage
                      *message, str *peer_id)

              1.9. AAASession* AAACreateSession(void *generic_data)
              1.10. AAASession* AAAMakeSession(int app_id,int type,str
                      session_id)

              1.11. AAASession* AAAGetSession(str id)
              1.12. AAADropSession(AAASession *s)
              1.13. AAASessionLock(unsigned int hash)
              1.14. AAASessionUnLock(unsigned int hash)
              1.15. AAASession* AAACreateClientAuthSession(int
                      is_statefull,AAASessionCallback_f *cb,void
                      *generic_data)

              1.16. AAASession* AAACreateServerAuthSession(AAMessage
                      *msg,int is_statefull,AAASessionCallback_f *cb,void
                      *generic_data)

              1.17. AAASession* AAAGetAuthSession(str id)
              1.18. AAADropAuthSession(AAASession *s)
              1.19. AAATerminateAuthSession(AAASession *s)
              1.20. AAATransaction* AAACreateTransaction(AAAApplicationId
                      app_id,AAACommandCode cmd_code)

              1.21. int AAADropTransaction(AAATransaction *trans)
              1.22. AAA_AVP* AAACreateAVP(AAA_AVPCode code, AAA_AVPFlag
                      flags, AAAVendorId vendorId, char *data, size_t
                      length, AVPDataStatus data_status)

              1.23. AAAReturnCode AAAAddAVPToMessage(AAAMessage *msg,
                      AAA_AVP *avp, AAA_AVP *position)

              1.24. AAA_AVP* AAAFindMatchingAVP(AAAMessage *msg, AAA_AVP
                      *startAvp, AAA_AVPCode avpCode, AAAVendorId
                      vendorId, AAASearchType searchType)

              1.25. AAA_AVP * AAAGetNextAVP(AAA_AVP *avp)
              1.26. AAAReturnCode AAAFreeAVP(AAA_AVP **avp)
              1.27. str AAAGroupAVPS(AAA_AVP_LIST avps)
              1.28. AAA_AVP_LIST AAAUnGroupAVPS(str buf)
              1.29. AAA_AVP* AAAFindMatchingAVPList(AAA_AVP_LIST avpList,
                      AAA_AVP *startAvp, AAA_AVPCode avpCode, AAAVendorId
                      vendorId, AAASearchType searchType)

              1.30. AAAFreeAVPList(AAA_AVP_LIST *avpList)
              1.31. int AAAAddRequestHandler(AAARequestHandler_f *f,void
                      *param)

              1.32. int AAAAddResponseHandler(AAAResponseHandler_f *f,void
                      *param)

   3. Frequently Asked Questions

   List of Examples

   1.1. Set config_file parameter
   1.2. Set latency_threshold parameter
   1.3. Set workerq_latency_threshold parameter
   1.4. Set workerq_length_threshold_percentage parameter
   1.5. Set debug_heavy parameter
   1.6. Set enable_tls parameter
   1.7. Set tls_method parameter
   1.8. Set private_key parameter
   1.9. Set certificate parameter
   1.10. Set ca_list parameter
   1.11. cdp_check_peer usage
   1.12. cdp_has_app usage
   1.13. cdp_has_app usage
   1.14. DiameterPeer.xml example

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. How it works
   3. Dependencies

        3.1. Kamailio Modules
        3.2. External Libraries or Applications

   4. Parameters

        4.1. config_file (string)
        4.2. latency_threshold (int)
        4.3. workerq_latency_threshold (int)
        4.4. workerq_length_threshold_percentage (int)
        4.5. debug_heavy (int)
        4.6. enable_tls (int)
        4.7. tls_method (string)
        4.8. private_key (string)
        4.9. certificate (string)
        4.10. ca_list (string)

   5. Functions

        5.1. cdp_check_peer(fqdn)
        5.2. cdp_has_app([vendorid, ]application)

   6. RPC Commands

        6.1. States
        6.2. cdp.disable_peer
        6.3. cdp.enable_peer
        6.4. cdp.list_peers

   7. Configuration Examples

        7.1. DiameterPeer.xml example

1. Overview

   CDP (C Diameter Peer) allows Diameter communication to and from
   Kamailio. Most of the code is inherited from DISC
   http://developer.berlios.de/projects/disc/ and OpenIMS and modified for
   use within Kamailio. A few improvements and new functionality has been
   added along the way, for example, threshold reporting on Diameter calls
   that are serviced above a certain threshold.

2. How it works

   CDP forks the following processes:
     * 1 x Timer
     * 1 x Acceptor
     * k x Workers (k configurable through configuration)
     * i x Receivers (one for each peer plus one for unknown peers)

   CDP is really only an API and offers all of its methods to other
   modules. No commands are made available to the main Kamailio
   configuration file. The exported API can be seen in mod.c. The Full
   Diameter API is in diameter.h and diameter_api.h. IMS-specific
   constants can be found in diameter_ims.h. The protocol coding is
   implemented in diameter_avp.c and diameter_msg.c. The diameter state
   machine is implemented in peerstatemachine.c - there is one of these
   for each peer which maintains all protocol/application state for each
   peer. peermanager.c is responsible for peer administration. Diameter
   transactions are implemented in transaction.c.

   There are 2 configuration areas for CDP. Firstly it must be loaded and
   configured in the Kamailio.cfg file (this is the normal task associated
   with Kamailio modules). Then, an XML file is required to configure
   various Diameter parameters and all related peers and the associated
   routes.

3. Dependencies

   3.1. Kamailio Modules
   3.2. External Libraries or Applications

3.1. Kamailio Modules

   The following modules must be loaded before this module:
     * None.

3.2. External Libraries or Applications

   The following libraries or applications must be installed before
   running Kamailio with this module loaded:
     * libxml,
     * openssl.

4. Parameters

   4.1. config_file (string)
   4.2. latency_threshold (int)
   4.3. workerq_latency_threshold (int)
   4.4. workerq_length_threshold_percentage (int)
   4.5. debug_heavy (int)
   4.6. enable_tls (int)
   4.7. tls_method (string)
   4.8. private_key (string)
   4.9. certificate (string)
   4.10. ca_list (string)

4.1. config_file (string)

   This is the location of the XML configuration file.

   Default value is “DiameterPeer.xml”.

   Example 1.1. Set config_file parameter
...
modparam("cdp", "config_file", "/etc/kamailio/diametercfg.xml")
...

4.2. latency_threshold (int)

   The time in ms above which a log error is written to log file for long
   CDP transactions.

   Default value is “500”.

   Example 1.2. Set latency_threshold parameter
...
modparam("cdp", "latency_threshold", 1000)
...

4.3. workerq_latency_threshold (int)

   The time in ms above which a log error is written to log file for
   putting tasks into task queue.

   Default value is “100”.

   Example 1.3. Set workerq_latency_threshold parameter
...
modparam("cdp", "workerq_latency_threshold", 250)
...

4.4. workerq_length_threshold_percentage (int)

   The threshold of the length of the worker queue as a percentage of the
   maximum queue size - when exceeded a warning is written to the log
   file. 0 means disabled

   Default value is “0”.

   Example 1.4. Set workerq_length_threshold_percentage parameter
...
modparam("cdp", "workerq_length_threshold_percentage", 25)
...

4.5. debug_heavy (int)

   Flag to enable a more verbose log, which tells you more details about
   peers. This is disabled by default because it brings to a log too much
   verbose in DBG mode Can be enabled upon needs

   Default value is “0”.

   Example 1.5. Set debug_heavy parameter
...
modparam("cdp", "debug_heavy", 1)
...

4.6. enable_tls (int)

   Flag to enable TLS for communication with all the peers.

   Default value is “0”.

   Example 1.6. Set enable_tls parameter
...
modparam("cdp", "enable_tls", 1)
...

4.7. tls_method (string)

   Sets the TLS protocol method. Possible values are:
     * TLSv1.3+ - TLSv1.3 or newer connections are accepted (available
       starting with openssl/libssl v1.1.1)
     * TLSv1.3 - only TLSv1.3 connections are accepted (available starting
       with openssl/libssl v1.1.1)
     * TLSv1.2+ - TLSv1.2 or newer (TLSv1.3, ...) connections are accepted
       (available starting with openssl/libssl v1.1.1)
     * TLSv1.2 - only TLSv1.2 connections are accepted (available starting
       with openssl/libssl v1.0.1e)
     * TLSv1.1+ - TLSv1.1 or newer (TLSv1.2, ...) connections are accepted
       (available starting with openssl/libssl v1.0.1)
     * TLSv1.1 - only TLSv1.1 connections are accepted (available starting
       with openssl/libssl v1.0.1)
     * TLSv1+ - TLSv1.0 or newer (TLSv1.1, TLSv1.2, ...) connections are
       accepted.
     * TLSv1 - only TLSv1 (TLSv1.0) connections are accepted. This is the
       default value.

   Default value is “TLSv1.2”.

   Example 1.7. Set tls_method parameter
...
modparam("tls", "tls_method", "TLSv1")
...

4.8. private_key (string)

   Sets the private key file name.

   Example 1.8. Set private_key parameter
...
modparam("cdp", "private_key", "/usr/local/etc/kamailio/my_pkey.pem")
...

4.9. certificate (string)

   Sets the certificate file name. Must be in PEM format.

   Example 1.9. Set certificate parameter
...
modparam("cdp", "certificate", "/usr/local/etc/kamailio/my_certificate.pem")
...

4.10. ca_list (string)

   Sets the CA list file name. This file contains a list of all the
   trusted CAs certificates used when connecting to other SIP
   implementations. If a signature in a certificate chain belongs to one
   of the listed CAs, the verification of that certificate will succeed.
   If not set, the PCRF sent certificate is not checked.

   The parameter must contain an absolute path. Only PEM files are
   accepted.

   By default this parameter is not set.

   An easy way to create the CA list is to append each trusted trusted CA
   certificate in the PEM format to one file.

   Example 1.10. Set ca_list parameter
...
modparam("cdp", "ca_list", "/usr/local/etc/kamailio/ca_list.pem")
...

5. Functions

   5.1. cdp_check_peer(fqdn)
   5.2. cdp_has_app([vendorid, ]application)

5.1.  cdp_check_peer(fqdn)

   The method checks, if a specific peer is connected and ready.

   Meaning of the parameter is as follows:
     * fqdn - the Fully qualified domain name of the peer, that should be
       checked. The parameter may contain pseudovariables.

   Example 1.11. cdp_check_peer usage
...
if(!cdp_check_peer("hss.mnc001.mcc001.3gppnetwork.org")) {
        send_reply("503", "HSS not ready");
        exit;
}
...

5.2.  cdp_has_app([vendorid, ]application)

   The method checks, if any peer with this specific application has
   connected.

   Meaning of the parameters are as follows:
     * vendorid - The Vendor ID of the App
       application - The Application ID

   Example 1.12. cdp_has_app usage
...
if(!cdp_has_app("10415", "4")) {
        send_reply("503", "Charging Server not ready");
        exit;
}
...

   Example 1.13. cdp_has_app usage
...
if(!cdp_has_app("16777216")) {
        send_reply("503", "Cx/Dx Interface not ready");
        exit;
}
...

6. RPC Commands

   6.1. States
   6.2. cdp.disable_peer
   6.3. cdp.enable_peer
   6.4. cdp.list_peers

6.1. States

     * Closed (0) - Not connected
     * Wait_Conn_Ack (1) - Connecting - waiting for Ack
     * Wait_I_CEA (2) - Connecting - waiting for Capabilities Exchange
       Answer
     * Wait_Conn_Ack_Elect (3) - Connecting - Acknowledged and going for
       Election
     * Wait_Returns (4) - Connecting - done
     * R_Open (5) - Connected as receiver
     * I_Open (6) - Connected as initiator
     * Closing (7) - Closing the connection

   Exported RPC commands.

6.2. cdp.disable_peer

   instantly disable a particular diameter peer.

6.3. cdp.enable_peer

   enable/re-enable a diameter peer

6.4. cdp.list_peers

   list all configured diameter peers

   State details can be found in the list above (Section 6.1, “States”)

7. Configuration Examples

   7.1. DiameterPeer.xml example

7.1. DiameterPeer.xml example

   This is an example CDP configuration file. The location of this file is
   configured as a CDP parameter (config_file) - See section 4.1 Above

   Example 1.14. DiameterPeer.xml example
<?xml version="1.0" encoding="UTF-8"?>
<!--

 DiameterPeer Parameters
  - FQDN - FQDN of this peer, as it should appear in the Origin-Host AVP
  - Realm - Realm of this peer, as it should appear in the Origin-Realm AVP
  - Vendor_Id - Default Vendor-Id to appear in the Capabilities Exchange
  - Product_Name - Product Name to appear in the Capabilities Exchange
  - AcceptUnknownPeers - Whether to accept (1) or deny (0) connections from peer
s with FQDN
    not configured below
  - DropUnknownOnDisconnect - Whether to drop (1) or keep (0) and retry connecti
ons (until restart)
    unknown peers in the list of peers after a disconnection.
  - Tc - Value for the RFC3588 Tc timer - default 30 seconds
  - Workers - Number of incoming messages processing workers forked processes.
  - Queue - Length of queue of tasks for the workers:
     - too small and the incoming messages will be blocked too often;
     - too large and the senders of incoming messages will have a longer feedbac
k loop to notice that
     this Diameter peer is overloaded in processing incoming requests;
     - a good choice is to have it about 2 times the number of workers. This wil
l mean that each worker
     will have about 2 tasks in the queue to process before new incoming message
s will start to block.
  - ConnectTimeout - time in seconds to wait for an outbound TCP connection to b
e established.
  - TransactionTimeout - time in seconds after which the transaction timeout cal
lback will be fired,
    when using transactional processing.
  - SessionsHashSize - size of the hash-table to use for the Diameter sessions.
When searching for a
    session, the time required for this operation will be that of sequential sea
rching in a list of
    NumberOfActiveSessions/SessionsHashSize. So higher the better, yet each hash
slot will consume an
    extra 2xsizeof(void*) bytes (typically 8 or 16 bytes extra).
  - DefaultAuthSessionTimeout - default value to use when there is no Authorizat
ion Session Timeout
  AVP present.
  - MaxAuthSessionTimeout - maximum Authorization Session Timeout as a cut-out m
easure meant to
  enforce session refreshes.

 -->
<DiameterPeer
        FQDN="pcscf.ims.smilecoms.com"
        Realm="ims.smilecoms.com"
        Vendor_Id="10415"
        Product_Name="CDiameterPeer"
        AcceptUnknownPeers="0"
        DropUnknownOnDisconnect="1"
        Tc="30"
        Workers="4"
        QueueLength="32"
        ConnectTimeout="5"
        TransactionTimeout="5"
        SessionsHashSize="128"
        DefaultAuthSessionTimeout="60"
        MaxAuthSessionTimeout="300"
>

        <!--
                Definition of peers to connect to and accept connections from. F
or each peer found in here
                a dedicated receiver process will be forked. All other unknown p
eers will share a single
                receiver. NB: You must have a peer definition for each peer list
ed in the realm routing section
        -->
        <Peer FQDN="pcrf1.ims.smilecoms.com" Realm="ims.smilecoms.com" port="386
8"/>
        <Peer FQDN="pcrf2.ims.smilecoms.com" Realm="ims.smilecoms.com" port="386
8"/>
        <Peer FQDN="pcrf3.ims.smilecoms.com" Realm="ims.smilecoms.com" port="386
8"/>
        <Peer FQDN="pcrf4.ims.smilecoms.com" Realm="ims.smilecoms.com" port="386
8"/>
        <Peer FQDN="pcrf5.ims.smilecoms.com" Realm="ims.smilecoms.com" port="386
8"/>
        <Peer FQDN="pcrf6.ims.smilecoms.com" Realm="ims.smilecoms.com" port="386
8"/>

        <!--
                Definition of incoming connection acceptors. If no bind is speci
fied, the acceptor will bind
                on all available interfaces.
        -->
        <Acceptor port="3868"  />
        <Acceptor port="3869" bind="127.0.0.1" />
        <Acceptor port="3870" bind="192.168.1.1" />

        <!--
                Definition of Auth (authorization) and Acct (accounting) support
ed applications. This
                information is sent as part of the Capabilities Exchange procedu
res on connecting to
                peers. If no common application is found, the peers will disconn
ect. Messages will only
                be sent to a peer if that peer actually has declared support for
 the application id of
                the message.
        -->
        <Acct id="16777216" vendor="10415" />
        <Acct id="16777216" vendor="0" />
        <Auth id="16777216" vendor="10415"/>
        <Auth id="16777216" vendor="0" />

        <!--
                Supported Vendor IDs - list of values which will be sent in the
CER/CEA in the
                Supported-Vendor-ID AVPs
        -->
        <SupportedVendor vendor="10415" />

        <!--
                Realm routing definition.
                Each Realm can have a different table of peers to route towards.
 In case the Destination
                Realm AVP contains a Realm not defined here, the DefaultRoute en
tries will be used.

                Note: In case a message already contains a Destination-Host AVP,
 Realm Routing will not be
                applied.
                Note: Routing will only happen towards connected and application
 id supporting peers.

                The metric is used to order the list of preferred peers, while l
ooking for a connected and
                application id supporting peer. In the end, of course, just one
peer will be selected.
        -->
        <Realm name="ims.smilecoms.com">
                <Route FQDN="pcrf1.ims.smilecoms.com" metric="3"/>
                <Route FQDN="pcrf2.ims.smilecoms.com" metric="5"/>
        </Realm>

        <Realm name="temp.ims.smilecoms.com">
                <Route FQDN="pcrf3.ims.smilecoms.com" metric="7"/>
                <Route FQDN="pcrf4.ims.smilecoms.com" metric="11"/>
        </Realm>
        <DefaultRoute FQDN="pcrf5.ims.smilecoms.com" metric="15"/>
        <DefaultRoute FQDN="pcrf6.ims.smilecoms.com" metric="13"/>


</DiameterPeer>

Chapter 2. Developer Guide

   Table of Contents

   1. Available Functions

        1.1. load_cdp(struct cdp_binds *cdpb)
        1.2. AAACreateRequest(AAAApplicationId app_id, AAACommandCode
                command_code, AAAMsgFlag flags, AAASession *session)

        1.3. AAACreateResponse(AAAMessage *request)
        1.4. AAAReturnCode AAAFreeMessage(AAAMessage **msg)
        1.5. AAAReturnCode AAASendMessage(AAAMessage *message,
                AAATransactionCallback_f *callback_f, void
                *callback_param)

        1.6. AAAReturnCode AAASendMessageToPeer(AAAMessage *message, str
                *peer_id, AAATransactionCallback_f *callback_f, void
                *callback_param)

        1.7. AAAMessage* AAASendRecvMessage(AAAMessage *message)
        1.8. AAAMessage* AAASendRecvMessageToPeer(AAAMessage *message, str
                *peer_id)

        1.9. AAASession* AAACreateSession(void *generic_data)
        1.10. AAASession* AAAMakeSession(int app_id,int type,str
                session_id)

        1.11. AAASession* AAAGetSession(str id)
        1.12. AAADropSession(AAASession *s)
        1.13. AAASessionLock(unsigned int hash)
        1.14. AAASessionUnLock(unsigned int hash)
        1.15. AAASession* AAACreateClientAuthSession(int
                is_statefull,AAASessionCallback_f *cb,void *generic_data)

        1.16. AAASession* AAACreateServerAuthSession(AAMessage *msg,int
                is_statefull,AAASessionCallback_f *cb,void *generic_data)

        1.17. AAASession* AAAGetAuthSession(str id)
        1.18. AAADropAuthSession(AAASession *s)
        1.19. AAATerminateAuthSession(AAASession *s)
        1.20. AAATransaction* AAACreateTransaction(AAAApplicationId
                app_id,AAACommandCode cmd_code)

        1.21. int AAADropTransaction(AAATransaction *trans)
        1.22. AAA_AVP* AAACreateAVP(AAA_AVPCode code, AAA_AVPFlag flags,
                AAAVendorId vendorId, char *data, size_t length,
                AVPDataStatus data_status)

        1.23. AAAReturnCode AAAAddAVPToMessage(AAAMessage *msg, AAA_AVP
                *avp, AAA_AVP *position)

        1.24. AAA_AVP* AAAFindMatchingAVP(AAAMessage *msg, AAA_AVP
                *startAvp, AAA_AVPCode avpCode, AAAVendorId vendorId,
                AAASearchType searchType)

        1.25. AAA_AVP * AAAGetNextAVP(AAA_AVP *avp)
        1.26. AAAReturnCode AAAFreeAVP(AAA_AVP **avp)
        1.27. str AAAGroupAVPS(AAA_AVP_LIST avps)
        1.28. AAA_AVP_LIST AAAUnGroupAVPS(str buf)
        1.29. AAA_AVP* AAAFindMatchingAVPList(AAA_AVP_LIST avpList,
                AAA_AVP *startAvp, AAA_AVPCode avpCode, AAAVendorId
                vendorId, AAASearchType searchType)

        1.30. AAAFreeAVPList(AAA_AVP_LIST *avpList)
        1.31. int AAAAddRequestHandler(AAARequestHandler_f *f,void *param)
        1.32. int AAAAddResponseHandler(AAAResponseHandler_f *f,void
                *param)

1. Available Functions

   1.1. load_cdp(struct cdp_binds *cdpb)
   1.2. AAACreateRequest(AAAApplicationId app_id, AAACommandCode
          command_code, AAAMsgFlag flags, AAASession *session)

   1.3. AAACreateResponse(AAAMessage *request)
   1.4. AAAReturnCode AAAFreeMessage(AAAMessage **msg)
   1.5. AAAReturnCode AAASendMessage(AAAMessage *message,
          AAATransactionCallback_f *callback_f, void *callback_param)

   1.6. AAAReturnCode AAASendMessageToPeer(AAAMessage *message, str
          *peer_id, AAATransactionCallback_f *callback_f, void
          *callback_param)

   1.7. AAAMessage* AAASendRecvMessage(AAAMessage *message)
   1.8. AAAMessage* AAASendRecvMessageToPeer(AAAMessage *message, str
          *peer_id)

   1.9. AAASession* AAACreateSession(void *generic_data)
   1.10. AAASession* AAAMakeSession(int app_id,int type,str session_id)
   1.11. AAASession* AAAGetSession(str id)
   1.12. AAADropSession(AAASession *s)
   1.13. AAASessionLock(unsigned int hash)
   1.14. AAASessionUnLock(unsigned int hash)
   1.15. AAASession* AAACreateClientAuthSession(int
          is_statefull,AAASessionCallback_f *cb,void *generic_data)

   1.16. AAASession* AAACreateServerAuthSession(AAMessage *msg,int
          is_statefull,AAASessionCallback_f *cb,void *generic_data)

   1.17. AAASession* AAAGetAuthSession(str id)
   1.18. AAADropAuthSession(AAASession *s)
   1.19. AAATerminateAuthSession(AAASession *s)
   1.20. AAATransaction* AAACreateTransaction(AAAApplicationId
          app_id,AAACommandCode cmd_code)

   1.21. int AAADropTransaction(AAATransaction *trans)
   1.22. AAA_AVP* AAACreateAVP(AAA_AVPCode code, AAA_AVPFlag flags,
          AAAVendorId vendorId, char *data, size_t length, AVPDataStatus
          data_status)

   1.23. AAAReturnCode AAAAddAVPToMessage(AAAMessage *msg, AAA_AVP *avp,
          AAA_AVP *position)

   1.24. AAA_AVP* AAAFindMatchingAVP(AAAMessage *msg, AAA_AVP *startAvp,
          AAA_AVPCode avpCode, AAAVendorId vendorId, AAASearchType
          searchType)

   1.25. AAA_AVP * AAAGetNextAVP(AAA_AVP *avp)
   1.26. AAAReturnCode AAAFreeAVP(AAA_AVP **avp)
   1.27. str AAAGroupAVPS(AAA_AVP_LIST avps)
   1.28. AAA_AVP_LIST AAAUnGroupAVPS(str buf)
   1.29. AAA_AVP* AAAFindMatchingAVPList(AAA_AVP_LIST avpList, AAA_AVP
          *startAvp, AAA_AVPCode avpCode, AAAVendorId vendorId,
          AAASearchType searchType)

   1.30. AAAFreeAVPList(AAA_AVP_LIST *avpList)
   1.31. int AAAAddRequestHandler(AAARequestHandler_f *f,void *param)
   1.32. int AAAAddResponseHandler(AAAResponseHandler_f *f,void *param)

1.1. load_cdp(struct cdp_binds *cdpb)

   Find and load the CDiameterPeer function bindings

   Meaning of the parameters is as follows:
     * struct cdp_binds *cdpb - structure holding function pointers

1.2. AAACreateRequest(AAAApplicationId app_id, AAACommandCode command_code,
AAAMsgFlag flags, AAASession *session)

   Create a Diameter request

   Meaning of the parameters is as follows:
     * AAAApplicationId app_id - structure holding function pointers
     * AAACommandCode command_code - command code for the message
     * AAAMsgFlag flags - flags to be set
     * AAASession *session - session id to be set

1.3. AAACreateResponse(AAAMessage *request)

   Create a Diameter response to a give request

   Meaning of the parameters is as follows:
     * AAAMessage *request - request that this response is for

1.4. AAAReturnCode AAAFreeMessage(AAAMessage **msg)

   Free up memory used by Diameter message

   Meaning of the parameters is as follows:
     * AAAMessage **msg - pointer to the pointer containing the message

1.5. AAAReturnCode AAASendMessage(AAAMessage *message,
AAATransactionCallback_f *callback_f, void *callback_param)

   Send Diameter message asynchronously

   Meaning of the parameters is as follows:
     * AAAMessage *message - request message to be sent
     * AAATransactionCallback_f *callback_f - When the response is
       received, the callback_f(callback_param,...) is called
     * void *callback_param - generic param for callback

1.6. AAAReturnCode AAASendMessageToPeer(AAAMessage *message, str *peer_id,
AAATransactionCallback_f *callback_f, void *callback_param)

   Send Diameter message to specific peer asynchronously

   Meaning of the parameters is as follows:
     * AAAMessage *message - request message to send
     * str *peer_id - FQDN of peer to send to
     * AAATransactionCallback_f *callback_f - When the response is
       received, the callback_f(callback_param,...) is called
     * void *callback_param - generic param for callback

1.7. AAAMessage* AAASendRecvMessage(AAAMessage *message)

   Send Diameter message synchronously. This blocks until a response is
   received or a transactional time-out happens.

   Meaning of the parameters is as follows:
     * AAAMessage *message - request message to be sent

1.8. AAAMessage* AAASendRecvMessageToPeer(AAAMessage *message, str *peer_id)

   Send Diameter message to specific peer synchronously. This blocks until
   a response is received or a transactional time-out happens.

   Meaning of the parameters is as follows:
     * AAAMessage *message - request message to send
     * str *peer_id - FQDN of peer to send to.

1.9. AAASession* AAACreateSession(void *generic_data)

   Create a generic Diameter session

   Meaning of the parameters is as follows:
     * void *generic_data - data to be save to session, useful for
       attaching app specific data to the session

1.10. AAASession* AAAMakeSession(int app_id,int type,str session_id)

   Create a Diameter session using already known params

   Meaning of the parameters is as follows:
     * int app_id - app id to use
     * int type - type of session
     * str session_id - session ID

1.11. AAASession* AAAGetSession(str id)

   Retrieve a Diameter session. Returns with a lock on AAASession->hash -
   Unlock when done working with result

   Meaning of the parameters is as follows:
     * str id - Diameter session ID to search for

1.12. AAADropSession(AAASession *s)

   Drop a Diameter session - deallocating all memory

   Meaning of the parameters is as follows:
     * AAASession *s - session to drop

1.13. AAASessionLock(unsigned int hash)

   Lock a Diameter session (hash table row)

   Meaning of the parameters is as follows:
     * unsigned int hash - hash to lock

1.14. AAASessionUnLock(unsigned int hash)

   Unlock a Diameter session (hash table row)

   Meaning of the parameters is as follows:
     * unsigned int hash - hash to unlock

1.15. AAASession* AAACreateClientAuthSession(int
is_statefull,AAASessionCallback_f *cb,void *generic_data)

   Creates an Authorisation session for the Client. It generate a new ID
   and adds to the list of CDP sessions. Returns with a lock on
   AAASession->hash

   Meaning of the parameters is as follows:
     * int is_statefull - is session stateful or not
     * AAASessionCallback_f *cb - callback function on session state
       change
     * void *generic_data - generic callback data

1.16. AAASession* AAACreateServerAuthSession(AAMessage *msg,int
is_statefull,AAASessionCallback_f *cb,void *generic_data)

   Create authorisation session for the Server. Generates a new ID and add
   to CDP list of sessions. Returns with a lock on AAASession->hash.

   Meaning of the parameters is as follows:
     * AAMessage *msg - request message from which to create server
       session
     * int is_statefull - is session stateful or not
     * AAASessionCallback_f *cb - callback function on session state
       change
     * void *generic_data - generic callback data

1.17. AAASession* AAAGetAuthSession(str id)

   Look for an authorisation session. Returns with lock on
   AAASession->hash

   Meaning of the parameters is as follows:
     * str id - ID of Auth session to search for

1.18. AAADropAuthSession(AAASession *s)

   Deallocates the memory taken by an Authorisation session

   Meaning of the parameters is as follows:
     * AAASession *s - Session to drop and deallocate memory for

1.19. AAATerminateAuthSession(AAASession *s)

   Sends a service terminated event to the session

   Meaning of the parameters is as follows:
     * AAASession *s - authhorisation session to terminate

1.20. AAATransaction* AAACreateTransaction(AAAApplicationId
app_id,AAACommandCode cmd_code)

   Create an AAATransaction for the given request

   Meaning of the parameters is as follows:
     * AAAApplicationId app_id - ID of the request's application
     * AAACommandCode cmd_code - request's code

1.21. int AAADropTransaction(AAATransaction *trans)

   Deallocates the memory taken by AAA transaction

   Meaning of the parameters is as follows:
     * AAATransaction *trans - transaction to free

1.22. AAA_AVP* AAACreateAVP(AAA_AVPCode code, AAA_AVPFlag flags, AAAVendorId
vendorId, char *data, size_t length, AVPDataStatus data_status)

   Create new AVP and return pointer to it

   Meaning of the parameters is as follows:
     * AAA_AVPCode code - code for new AVP
     * AAA_AVPFlag flags - flags to set
     * AAAVendorId vendorId - vendor ID for AVP
     * char *data - generic payload data
     * size_t length - length of payload data
     * AVPDataStatus data_status - what to do with the payload, duplicate,
       free with message, etc

1.23. AAAReturnCode AAAAddAVPToMessage(AAAMessage *msg, AAA_AVP *avp, AAA_AVP
*position)

   Find and load the CDiameterPeer function bindings

   Meaning of the parameters is as follows:
     * AAAMessage *msg - the message to add to
     * AAA_AVP *avp - the AVP to add
     * AAA_AVP *position - AVP to add after. if NULL, we add at beginning

1.24. AAA_AVP* AAAFindMatchingAVP(AAAMessage *msg, AAA_AVP *startAvp,
AAA_AVPCode avpCode, AAAVendorId vendorId, AAASearchType searchType)

   Find and load the CDiameterPeer function bindings

   Meaning of the parameters is as follows:
     * AAAMessage *msg - the message to search in
     * AAA_AVP *startAvp - at which AVP to start the search. Useful for
       looking for more of the same name
     * AAA_AVPCode avpCode - AVP code to match
     * AAAVendorId vendorId - AVP vendor ID to match
     * AAASearchType searchType - look forward or backward

1.25. AAA_AVP * AAAGetNextAVP(AAA_AVP *avp)

   Find and load the CDiameterPeer function bindings

   Meaning of the parameters is as follows:
     * AAA_AVP *avp - reference AVP

1.26. AAAReturnCode AAAFreeAVP(AAA_AVP **avp)

   Find and load the CDiameterPeer function bindings

   Meaning of the parameters is as follows:
     * AAA_AVP **avp - pointer memory to be freed

1.27. str AAAGroupAVPS(AAA_AVP_LIST avps)

   Groups a list of AVPS into a data buffer

   Meaning of the parameters is as follows:
     * AAA_AVP_LIST avps - list of AVPS to group

1.28. AAA_AVP_LIST AAAUnGroupAVPS(str buf)

   Ungroup a data buffer into a list of AVPs

   Meaning of the parameters is as follows:
     * str buf - payload to ungroup list from

1.29. AAA_AVP* AAAFindMatchingAVPList(AAA_AVP_LIST avpList, AAA_AVP
*startAvp, AAA_AVPCode avpCode, AAAVendorId vendorId, AAASearchType
searchType)

   Find an AVP in an AVP list

   Meaning of the parameters is as follows:
     * AAA_AVP_LIST avpList - AVP list to search
     * AAA_AVP *startAvp - where to start the search
     * AAA_AVPCode avpCode - AVP code to match
     * AAAVendorId vendorId - vendor ID to match
     * AAASearchType searchType - forwards or backwards

1.30. AAAFreeAVPList(AAA_AVP_LIST *avpList)

   Free AVP list and all its members

   Meaning of the parameters is as follows:
     * AAA_AVP_LIST *avpList - list to be freed

1.31. int AAAAddRequestHandler(AAARequestHandler_f *f,void *param)

   add a #AAARequestHandler_f callback to request being received

   Meaning of the parameters is as follows:
     * AAARequestHandler_f *f - callback function to be called on incoming
       requests
     * void *param - generic data passed to callback function

1.32. int AAAAddResponseHandler(AAAResponseHandler_f *f,void *param)

   add a #AAAResponseHandler_f callback to responses being received

   Meaning of the parameters is as follows:
     * AAAResponseHandler_f *f - callback function to be called on
       incoming responses
     * void *param - generic data to be passed to callback function

Chapter 3. Frequently Asked Questions

   3.1. Where can I find more about Kamailio?
   3.2. Where can I post a question about this module?
   3.3. How can I report a bug?

   3.1.

   Where can I find more about Kamailio?

   Take a look at https://www.kamailio.org/.

   3.2.

   Where can I post a question about this module?

   First at all check if your question was already answered on one of our
   mailing lists:
     * User Mailing List -
       https://lists.kamailio.org/mailman3/postorius/lists/sr-users.lists.
       kamailio.org/
     * Developer Mailing List -
       https://lists.kamailio.org/mailman3/postorius/lists/sr-dev.lists.ka
       mailio.org/

   E-mails regarding any stable Kamailio release should be sent to
   <sr-users@lists.kamailio.org> and e-mails regarding development
   versions should be sent to <sr-dev@lists.kamailio.org>.

   3.3.

   How can I report a bug?

   Please follow the guidelines provided at:
   https://github.com/kamailio/kamailio/issues.
