Navigation


Changeset 1392:497d926f5e3d in freeDiameter


Ignore:
Timestamp:
Nov 15, 2019, 7:28:11 PM (3 years ago)
Author:
Thomas Klausner <tk@giga.or.at>
Branch:
default
Phase:
public
Message:

libfdproto.h: remove trailing whitespace

File:
1 edited

Legend:

Unmodified
Added
Removed
  • include/freeDiameter/libfdproto.h

    r1343 r1392  
    139139 *  ...         : Same list as printf
    140140 *
    141  * DESCRIPTION: 
     141 * DESCRIPTION:
    142142 * Write information to log.
    143143 * The format and arguments may contain UTF-8 encoded data. The
     
    152152#endif /* SWIG */
    153153
    154 /* these are internal objects of the debug facility, 
     154/* these are internal objects of the debug facility,
    155155might be useful to control the behavior from outside */
    156156extern pthread_mutex_t  fd_log_lock;
     
    164164 *  name        : \0-terminated string containing a name to identify the current thread.
    165165 *
    166  * DESCRIPTION: 
     166 * DESCRIPTION:
    167167 *  Name the current thread, useful for debugging multi-threaded problems.
    168168 *
     
    186186 *  incl_ms     : millisecond value is included in the output
    187187 *
    188  * DESCRIPTION: 
    189  *  Writes the timestamp (in human readable format) in a buffer. 
     188 * DESCRIPTION:
     189 *  Writes the timestamp (in human readable format) in a buffer.
    190190 *
    191191 * RETURN VALUE:
     
    246246        char * function_name(char ** buf, size_t *len, size_t *offset)
    247247#endif /* SWIG */
    248        
     248
    249249
    250250/* Helper functions for the *dump functions that add into a buffer */
     
    313313
    314314/*
    315  * Use the following macros in the code to get traces with location & pid in debug mode: 
     315 * Use the following macros in the code to get traces with location & pid in debug mode:
    316316 */
    317317#ifdef DEBUG
     
    403403 * The name "__ret__" is always available in the __fallback__ parameter and contains the error code.
    404404 */
    405  
     405
    406406#define CHECK_PRELUDE(__call__)                         \
    407407                int __ret__;                            \
    408408                TRACE_CALL("Check: %s", #__call__ );    \
    409409                __ret__ = (__call__)
    410        
     410
    411411#define DEFAULT_FB      return __ret__;
    412412
     
    492492#ifndef SWIG
    493493static __inline__ void fd_log_deprecated( int level, const char *format, ... ) MARK_DEPRECATED
    494 { 
     494{
    495495        va_list ap;
    496496        va_start(ap, format);
     
    558558# define CHECK_POSIX( __call__ )        \
    559559                CHECK_POSIX_DO( (__call__), return __ret__ )
    560                
     560
    561561# define CHECK_MALLOC_DO( __call__, __fallback__ ) {                                                   \
    562562               void *  __ptr__;                                                                        \
     
    572572# define CHECK_MALLOC( __call__ )       \
    573573                CHECK_MALLOC_DO( (__call__), return __ret__ )
    574        
     574
    575575# define CHECK_PARAMS_DO( __bool__, __fallback__ ) {                                                   \
    576576               TRACE_CALL("Check: %s", #__bool__ );                                                    \
     
    589589
    590590#endif /* EXCLUDE_DEPRECATED */
    591                
     591
    592592
    593593/*============================================================*/
     
    661661
    662662/* Define the value of IP loopback address */
    663 #ifndef INADDR_LOOPBACK 
     663#ifndef INADDR_LOOPBACK
    664664#define INADDR_LOOPBACK inet_addr("127.0.0.1")
    665665#endif /* INADDR_LOOPBACK */
     
    702702# else /* HOST_BIG_ENDIAN */
    703703    /* For these systems, we must reverse the bytes. Use ntohl and htonl on sub-32 blocs, and inverse these blocs. */
    704 #   define ntohll(x) (typeof (x))( (((uint64_t)ntohl( (uint32_t)(x))) << 32 ) | ((uint64_t) ntohl( ((uint64_t)(x)) >> 32 ))) 
    705 #   define htonll(x) (typeof (x))( (((uint64_t)htonl( (uint32_t)(x))) << 32 ) | ((uint64_t) htonl( ((uint64_t)(x)) >> 32 ))) 
     704#   define ntohll(x) (typeof (x))( (((uint64_t)ntohl( (uint32_t)(x))) << 32 ) | ((uint64_t) ntohl( ((uint64_t)(x)) >> 32 )))
     705#   define htonll(x) (typeof (x))( (((uint64_t)htonl( (uint32_t)(x))) << 32 ) | ((uint64_t) htonl( ((uint64_t)(x)) >> 32 )))
    706706# endif /* HOST_BIG_ENDIAN */
    707707#endif /* HAVE_NTOHLL */
     
    727727                (tsdiff)->tv_nsec = (tsend)->tv_nsec - (tsstart)->tv_nsec;              \
    728728        }}
    729                
     729
    730730
    731731/* This gives a good size for buffered reads */
     
    756756/*============================================================*/
    757757
    758 /* Compute a hash value of a binary string. 
     758/* Compute a hash value of a binary string.
    759759The hash must remain local to this machine, there is no guarantee that same input
    760760will give same output on a different system (endianness) */
    761761uint32_t fd_os_hash ( uint8_t * string, size_t len );
    762762
    763 /* This type used for binary strings that contain no \0 except as their last character. 
     763/* This type used for binary strings that contain no \0 except as their last character.
    764764It means some string operations can be used on it. */
    765765typedef uint8_t * os0_t;
     
    787787int fd_os_is_valid_DiameterIdentity(uint8_t * os, size_t ossz);
    788788
    789 /* The following function validates a string as a Diameter Identity or applies the IDNA transformation on it 
     789/* The following function validates a string as a Diameter Identity or applies the IDNA transformation on it
    790790 if *inoutsz is != 0 on entry, *id may not be \0-terminated.
    791791 memory has the following meaning: 0: *id can be realloc'd. 1: *id must be malloc'd on output (was static)
     
    793793int fd_os_validate_DiameterIdentity(char ** id, size_t * inoutsz, int memory);
    794794
    795 /* Create an order relationship for binary strings (not needed to be \0 terminated). 
     795/* Create an order relationship for binary strings (not needed to be \0 terminated).
    796796   It does NOT mimic strings relationships so that it is more efficient. It is case sensitive.
    797797   (the strings are actually first ordered by their lengh, then by their bytes contents)
     
    800800#define fd_os_cmp(_o1, _l1, _o2, _l2)  fd_os_cmp_int((os0_t)(_o1), _l1, (os0_t)(_o2), _l2)
    801801
    802 /* A roughly case-insensitive variant, which actually only compares ASCII chars (0-127) in a case-insentitive maneer 
     802/* A roughly case-insensitive variant, which actually only compares ASCII chars (0-127) in a case-insentitive maneer
    803803  -- it does not support locales where a lowercase letter uses more space than upper case, such as ß -> ss
    804804 It is slower than fd_os_cmp.
    805805 Note that the result is NOT the same as strcasecmp !!!
    806  
     806
    807807 This function gives the same order as fd_os_cmp, except when it finds 2 strings to be equal.
    808808 However this is not always sufficient:
     
    817817#define fd_os_almostcasesrch(_o1, _l1, _o2, _l2, _mb)  fd_os_almostcasesrch_int((os0_t)(_o1), _l1, (os0_t)(_o2), _l2, _mb)
    818818
    819 /* Analyze a DiameterURI and return its components. 
    820   Return EINVAL if the URI is not valid. 
     819/* Analyze a DiameterURI and return its components.
     820  Return EINVAL if the URI is not valid.
    821821  *diamid is malloc'd on function return and must be freed (it is processed by fd_os_validate_DiameterIdentity).
    822822  *secure is 0 (no security) or 1 (security enabled) on return.
     
    835835{
    836836        void * th_ret = NULL;
    837        
     837
    838838        CHECK_PARAMS(th);
    839        
     839
    840840        /* Test if it was already terminated */
    841841        if (*th == (pthread_t)NULL)
    842842                return 0;
    843        
     843
    844844        /* Cancel the thread if it is still running - ignore error if it was already terminated */
    845845        (void) pthread_cancel(*th);
    846        
     846
    847847        /* Then join the thread */
    848848        CHECK_POSIX( pthread_join(*th, &th_ret) );
    849        
     849
    850850        if (th_ret == PTHREAD_CANCELED) {
    851851                TRACE_DEBUG(ANNOYING, "The thread %p was canceled", (void *)*th);
     
    853853                TRACE_DEBUG(CALL, "The thread %p returned %p", (void *)*th, th_ret);
    854854        }
    855        
     855
    856856        /* Clean the location */
    857857        *th = (pthread_t)NULL;
    858        
     858
    859859        return 0;
    860860}
     
    862862
    863863/*************
    864  Cancelation cleanup handlers for common objects 
     864 Cancelation cleanup handlers for common objects
    865865 *************/
    866866static __inline__ void fd_cleanup_mutex( void * mutex )
     
    868868        CHECK_POSIX_DO( pthread_mutex_unlock((pthread_mutex_t *)mutex), /* */);
    869869}
    870                
     870
    871871static __inline__ void fd_cleanup_rwlock( void * rwlock )
    872872{
     
    946946#define DICT_TYPE_MAX   DICT_RULE
    947947};
    948        
     948
    949949/* Initialize a dictionary */
    950950int fd_dict_init(struct dictionary ** dict);
     
    958958 *  dict        : Pointer to the dictionnary where the object is created
    959959 *  type        : What kind of object must be created
    960  *  data        : pointer to the data for the object. 
     960 *  data        : pointer to the data for the object.
    961961 *               type parameter is used to determine the type of data (see below for detail).
    962962 *  parent      : a reference to a parent object, if needed.
    963963 *  ref         : upon successful creation, reference to new object is stored here if !null.
    964964 *
    965  * DESCRIPTION: 
    966  *  Create a new object in the dictionary. 
     965 * DESCRIPTION:
     966 *  Create a new object in the dictionary.
    967967 *  See following object sections in this header file for more information on data and parent parameters format.
    968968 *
     
    970970 *  0           : The object is created in the dictionary.
    971971 *  EINVAL      : A parameter is invalid.
    972  *  EEXIST      : This object is already defined in the dictionary (with conflicting data). 
     972 *  EEXIST      : This object is already defined in the dictionary (with conflicting data).
    973973 *                If "ref" is not NULL, it points to the existing element on return.
    974974 *  (other standard errors may be returned, too, with their standard meaning. Example:
     
    988988 *  retval      : this value is returned if the object is not found and result is not NULL.
    989989 *
    990  * DESCRIPTION: 
    991  *   Perform a search in the dictionary. 
     990 * DESCRIPTION:
     991 *   Perform a search in the dictionary.
    992992 *   See the object-specific sections below to find how to look for each objects.
    993993 *   If the "result" parameter is NULL, the function is used to check if an object is in the dictionary.
     
    10131013 *                The type is the same as "data" parameter in fd_dict_new function.
    10141014 *
    1015  * DESCRIPTION: 
     1015 * DESCRIPTION:
    10161016 *  Retrieve content of a dictionary object.
    10171017 *  See following object sections in this header file for more information on data and parent parameters format.
     
    10401040 ***************************************************************************
    10411041 *
    1042  * Vendor object 
     1042 * Vendor object
    10431043 *
    10441044 * These types are used to manage vendors in the dictionary
     
    10701070On the other side, when value is retrieved with dict_getval, the string is not copied and MUST NOT be freed. It will
    10711071be freed automatically along with the object itself with call to dict_fini later.
    1072  
     1072
    10731073- fd_dict_new:
    1074  The "parent" parameter is not used for vendors. 
     1074 The "parent" parameter is not used for vendors.
    10751075 Sample code to create a vendor:
    10761076 {
     
    10911091         ret = fd_dict_search ( dict, DICT_VENDOR, VENDOR_BY_NAME, "my vendor name", &vendor_found, ENOENT);
    10921092 }
    1093  
     1093
    10941094 - fd_dict_getval:
    10951095 Sample code to retrieve the data from a vendor object:
     
    11021102         printf("my vendor id: %d\n", myvendordata.vendor_id );
    11031103 }
    1104                  
     1104
    11051105*/
    1106                
     1106
    11071107/* Special function: */
    11081108uint32_t * fd_dict_get_vendorid_list(struct dictionary * dict);
    1109          
     1109
    11101110/*
    11111111 ***************************************************************************
    11121112 *
    1113  * Application object 
     1113 * Application object
    11141114 *
    11151115 * These types are used to manage Diameter applications in the dictionary
     
    11561156                 "my vendor's application"
    11571157         };
    1158        
     1158
    11591159         ret = fd_dict_new ( dict, DICT_VENDOR, &vendor_data, NULL, &vendor );
    11601160         ret = fd_dict_new ( dict, DICT_APPLICATION, &app_data, vendor, &appl );
     
    11661166         int ret;
    11671167         struct dict_object * vendor, * appli;
    1168          
     1168
    11691169         ret = fd_dict_search ( dict, DICT_APPLICATION, APPLICATION_BY_NAME, "my vendor's application", &appli, ENOENT);
    11701170         ret = fd_dict_search ( dict, DICT_VENDOR, VENDOR_OF_APPLICATION, appli, &vendor, ENOENT);
    11711171 }
    1172  
     1172
    11731173 - fd_dict_getval:
    11741174 Sample code to retrieve the data from an application object:
     
    11871187 ***************************************************************************
    11881188 *
    1189  * Type object 
     1189 * Type object
    11901190 *
    11911191 * These types are used to manage AVP data types in the dictionary
     
    11941194 */
    11951195
    1196 /* Type to store any AVP value */ 
     1196/* Type to store any AVP value */
    11971197union avp_value {
    11981198        struct {
     
    12291229 *   interpreted : The result of interpretation is stored here. The format and meaning depends on each type.
    12301230 *
    1231  * DESCRIPTION: 
     1231 * DESCRIPTION:
    12321232 *   This callback can be provided with a derived type in order to facilitate the interpretation of formated data.
    12331233 *  For example, when an AVP of type "Address" is received, it can be used to convert the octetstring into a struct sockaddr.
     
    12461246 *   val        : Pointer to the AVP value storage area where the data must be stored.
    12471247 *
    1248  * DESCRIPTION: 
     1248 * DESCRIPTION:
    12491249 *   This callback can be provided with a derived type in order to facilitate the encoding of formated data.
    12501250 *  For example, it can be used to convert a struct sockaddr in an AVP value of type Address.
    12511251 *  This callback is not called directly, but through the message's API msg_avp_value_encode function.
    1252  *  If the callback is defined for an OctetString based type, the created string must be malloc'd. free will be called 
     1252 *  If the callback is defined for an OctetString based type, the created string must be malloc'd. free will be called
    12531253 *  automatically later.
    12541254 *
     
    12651265 *   val        : Pointer to the AVP value that was received and needs to be sanity checked.
    12661266 *   data      : a parameter stored in the type structure (to enable more generic check functions)
    1267  *   error_msg: upon erroneous value, a string describing the error can be returned here (it will be strcpy by caller). This description will be returned in the error message, if any. 
    1268  *
    1269  * DESCRIPTION: 
     1267 *   error_msg: upon erroneous value, a string describing the error can be returned here (it will be strcpy by caller). This description will be returned in the error message, if any.
     1268 *
     1269 * DESCRIPTION:
    12701270 *   This callback can be provided with a derived type in order to improve the operation of the
    12711271 *  fd_msg_parse_dict function. When this callback is present, the value of the AVP that has
    1272  * been parsed is passed to this function for finer granularity check. For example for some 
     1272 * been parsed is passed to this function for finer granularity check. For example for some
    12731273 * speccific AVP, the format of an OCTETSTRING value can be further checked, or the
    12741274 * interger value can be verified.
     
    13011301
    13021302/****
    1303  Callbacks defined in libfdproto/dictionary_functions.c file -- see that file for usage. 
     1303 Callbacks defined in libfdproto/dictionary_functions.c file -- see that file for usage.
    13041304 */
    13051305
     
    13281328
    13291329- fd_dict_new:
    1330  The "parent" parameter may point to an application object, when a type is defined by a Diameter application. 
    1331  
     1330 The "parent" parameter may point to an application object, when a type is defined by a Diameter application.
     1331
    13321332 Sample code:
    13331333 {
    13341334         int ret;
    13351335         struct dict_object * mytype;
    1336          struct dict_type_data mytypedata = 
    1337                 { 
     1336         struct dict_type_data mytypedata =
     1337                {
    13381338                 AVP_TYPE_OCTETSTRING,
    13391339                 "Address",
     
    13511351         ret = fd_dict_search ( dict, DICT_TYPE, TYPE_BY_NAME, "Address", &address_type, ENOENT);
    13521352 }
    1353  
     1353
    13541354*/
    13551355
     
    13571357 ***************************************************************************
    13581358 *
    1359  * Enumerated values object 
     1359 * Enumerated values object
    13601360 *
    13611361 * These types are used to manage named constants of some AVP,
     
    13821382        struct dict_object      *type_obj;
    13831383        char *                   type_name;
    1384        
     1384
    13851385        /* Search criteria for the constant */
    13861386        struct dict_enumval_data search; /* search.enum_value is used only if search.enum_name == NULL */
     
    13911391
    13921392- fd_dict_new:
    1393  The "parent" parameter must point to a derived type object. 
     1393 The "parent" parameter must point to a derived type object.
    13941394 Sample code to create a type "Boolean" with two constants "True" and "False":
    13951395 {
    13961396         int ret;
    13971397         struct dict_object * type_boolean;
    1398          struct dict_type_data type_boolean_data = 
    1399                 { 
     1398         struct dict_type_data type_boolean_data =
     1399                {
    14001400                 AVP_TYPE_INTEGER32,
    14011401                 "Boolean",
     
    14161416         ret = fd_dict_new ( dict, DICT_ENUMVAL, &boolean_false, type_boolean, NULL );
    14171417         ret = fd_dict_new ( dict, DICT_ENUMVAL, &boolean_true , type_boolean, NULL );
    1418          
     1418
    14191419 }
    14201420
     
    14301430                 .search.enum_value.i32 = -1
    14311431                };
    1432          
     1432
    14331433         ret = fd_dict_search ( dict, DICT_ENUMVAL, ENUMVAL_BY_STRUCT, &boolean_by_value, &value_found, ENOENT);
    14341434 }
    1435  
     1435
    14361436 - fd_dict_getval:
    14371437 Sample code to retrieve the data from a constant object:
     
    14461446                 .search.enum_value.i32 = 0
    14471447                };
    1448          
     1448
    14491449         ret = fd_dict_search ( dict, DICT_ENUMVAL, ENUMVAL_BY_STRUCT, &boolean_by_value, &value_found, ENOENT);
    14501450         ret = fd_dict_getval ( value_found, &boolean_data );
     
    14521452 }
    14531453*/
    1454          
     1454
    14551455/*
    14561456 ***************************************************************************
    14571457 *
    1458  * AVP object 
     1458 * AVP object
    14591459 *
    14601460 * These objects are used to manage AVP definitions in the dictionary
     
    14981498        AVP_BY_NAME_ALL_VENDORS,/* "what" points to a string. Might be quite slow... */
    14991499        AVP_BY_STRUCT,          /* "what" points to a struct dict_avp_request_ex (see below) */
    1500                        
     1500
    15011501        /* kept for backward compatibility, better use AVP_BY_STRUCT above instead */
    15021502        AVP_BY_CODE_AND_VENDOR, /* "what" points to a struct dict_avp_request (see below), where avp_vendor and avp_code are set */
     
    15121512                const char *                    vendor_name;    /* set to NULL to ignore */
    15131513        } avp_vendor;
    1514        
     1514
    15151515        struct {
    15161516                /* Only one of the following fields must be set */
     
    15311531 *  API usage :
    15321532
    1533 If "parent" parameter is not NULL during AVP creation, it must point to a DICT_TYPE object. 
    1534 The extended type is then attached to the AVP. In case where it is an enumerated type, the value of 
     1533If "parent" parameter is not NULL during AVP creation, it must point to a DICT_TYPE object.
     1534The extended type is then attached to the AVP. In case where it is an enumerated type, the value of
    15351535AVP is automatically interpreted in debug messages, and in message checks.
    15361536The derived type of an AVP can be retrieved with: dict_search ( DICT_TYPE, TYPE_OF_AVP, avp, ... )
     
    15611561                 AVP_TYPE_INTEGER32                     // This MUST be the same as parent type's
    15621562         };
    1563        
     1563
    15641564         -- Create an AVP with a base type --
    15651565         ret = fd_dict_new ( dict, DICT_AVP, &user_name_data, NULL, &user_name_avp );
    1566          
     1566
    15671567         -- Create an AVP with a derived type --
    15681568         ret = fd_dict_search ( dict, DICT_TYPE, TYPE_BY_NAME, "Boolean", &boolean_type, ENOENT);
    15691569         ret = fd_dict_new ( dict, DICT_AVP, &sample_boolean_data , boolean_type, &sample_boolean_avp );
    1570          
     1570
    15711571 }
    15721572
     
    15821582                 .avp_name   = "Sample-Boolean"
    15831583                };
    1584          
     1584
    15851585         ret = fd_dict_search ( dict, DICT_AVP, AVP_BY_NAME, "User-Name", &avp_username, ENOENT);
    1586          
     1586
    15871587         ret = fd_dict_search ( dict, DICT_AVP, AVP_BY_NAME_AND_VENDOR, &avpvendorboolean, &avp_sampleboolean, ENOENT);
    15881588
    15891589         -- this would also work, but be slower, because it has to search all vendor dictionaries --
    15901590         ret = fd_dict_search ( dict, DICT_AVP, AVP_BY_NAME_ALL_VENDORS, "Sample-Boolean", &avp_sampleboolean, ENOENT);
    1591          
     1591
    15921592 }
    1593  
     1593
    15941594 - fd_dict_getval:
    15951595 Sample code to retrieve the data from an AVP object:
     
    16081608 ***************************************************************************
    16091609 *
    1610  * Command object 
     1610 * Command object
    16111611 *
    16121612 * These types are used to manage commands objects in the dictionary
     
    16721672                 CMD_FLAG_REQUEST                       // value. Only the "R" flag is constrained here, set.
    16731673         };
    1674        
     1674
    16751675         ret = fd_dict_new (dict,  DICT_COMMAND, &ce_data, NULL, &cer );
    1676          
     1676
    16771677         ce_data.cmd_name = "Capabilities-Exchange-Answer";
    16781678         ce_data.cmd_flag_val = 0;                      // Same constraint on "R" flag, but this time it must be cleared.
     
    16901690         ret = fd_dict_search ( dict, DICT_COMMAND, CMD_BY_CODE_R, &code, &cer, ENOENT);
    16911691 }
    1692  
     1692
    16931693 - fd_dict_getval:
    16941694 Sample code to retrieve the data from a command object:
     
    17641764        struct dict_avp_data proxy_host_data = { 280, 0, "Proxy-Host", AVP_FLAG_VENDOR | AVP_FLAG_MANDATORY, AVP_FLAG_MANDATORY, AVP_TYPE_OCTETSTRING };
    17651765        struct dict_avp_data proxy_state_data = { 33, 0, "Proxy-State",AVP_FLAG_VENDOR | AVP_FLAG_MANDATORY, AVP_FLAG_MANDATORY, AVP_TYPE_OCTETSTRING };
    1766        
     1766
    17671767        -- Create the parent AVP
    17681768        ret = fd_dict_new ( dict, DICT_AVP, &proxy_info_data, NULL, &proxy_info_avp );
    1769        
     1769
    17701770        -- Create the first child AVP.
    17711771        ret = fd_dict_new ( dict, DICT_TYPE, &di_type_data, NULL, &diameteridentity_type );
    17721772        ret = fd_dict_new ( dict, DICT_AVP, &proxy_host_data, diameteridentity_type, &proxy_host_avp );
    1773        
     1773
    17741774        -- Create the other child AVP
    17751775        ret = fd_dict_new ( dict, DICT_AVP, &proxy_state_data, NULL, &proxy_state_avp );
    1776        
     1776
    17771777        -- Now we can create the rules. Both children AVP are mandatory.
    17781778        rule_data.rule_position = RULE_REQUIRED;
    17791779        rule_data.rule_min = -1;
    17801780        rule_data.rule_max = -1;
    1781        
     1781
    17821782        rule_data.rule_avp = proxy_host_avp;
    17831783        ret = fd_dict_new ( dict, DICT_RULE, &rule_data, proxy_info_avp, NULL );
    1784        
     1784
    17851785        rule_data.rule_avp = proxy_state_avp;
    17861786        ret = fd_dict_new ( dict, DICT_RULE, &rule_data, proxy_info_avp, NULL );
     
    17901790
    17911791*/
    1792                
     1792
    17931793/* Define some hard-coded values */
    17941794/* Application */
     
    18411841/* Error codes from Base protocol
    18421842(reference: http://www.iana.org/assignments/aaa-parameters/aaa-parameters.xml#aaa-parameters-4)
    1843 Note that currently, rfc3588bis-26 has some different values for some of these 
     1843Note that currently, rfc3588bis-26 has some different values for some of these
    18441844*/
    18451845#define ER_DIAMETER_MULTI_ROUND_AUTH                    1001
     
    19091909 *  opaque      : A pointer that is passed to the cleanup callback -- the content is never examined by the framework.
    19101910 *
    1911  * DESCRIPTION: 
     1911 * DESCRIPTION:
    19121912 *  Create a new session handler. This is needed by a module to associate a state with a session object.
    19131913 * The cleanup handler is called when the session timeout expires, or fd_sess_destroy is called. It must free
     
    19211921int fd_sess_handler_create ( struct session_handler ** handler, void (*cleanup)(struct sess_state * state, os0_t sid, void * opaque), session_state_dump dumper, void * opaque );
    19221922
    1923        
     1923
    19241924/*
    19251925 * FUNCTION:    fd_sess_handler_destroy
     
    19291929 *  opaque      : the opaque pointer registered with the callback is restored here (if ! NULL).
    19301930 *
    1931  * DESCRIPTION: 
     1931 * DESCRIPTION:
    19321932 *  This destroys a session handler (typically called when an application is shutting down).
    19331933 * If sessions states are registered with this handler, the cleanup callback is called on them.
     
    19521952 *  optlen        : if opt is \0-terminated, this can be 0. Otherwise, the length of opt.
    19531953 *
    1954  * DESCRIPTION: 
     1954 * DESCRIPTION:
    19551955 *   Create a new session object. The Session-Id string associated with this session is generated as follow:
    19561956 *  If diamId parameter is provided, the string is created according to the RFC: <diamId>;<high32>;<low32>[;opt] where
     
    19771977 *  isnew       : if not NULL, set to 1 on return if the session object has been created, 0 if it was simply retrieved.
    19781978 *
    1979  * DESCRIPTION: 
    1980  *   Retrieve a session object from a Session-Id string. In case no session object was previously existing with this 
     1979 * DESCRIPTION:
     1980 *   Retrieve a session object from a Session-Id string. In case no session object was previously existing with this
    19811981 *  id, a new object is silently created (equivalent to fd_sess_new with flag SESSION_NEW_FULL).
    19821982 *
     
    19891989
    19901990/* only use the following in specific situations, e.g. app_radgw extension. They are normally handled by the framework only */
    1991 int fd_sess_fromsid_msg ( uint8_t * sid, size_t len, struct session ** session, int * isnew); 
     1991int fd_sess_fromsid_msg ( uint8_t * sid, size_t len, struct session ** session, int * isnew);
    19921992int fd_sess_ref_msg ( struct session * session );
    19931993
     
    19991999 *  sid         : On success, the location of the sid is stored here.
    20002000 *
    2001  * DESCRIPTION: 
     2001 * DESCRIPTION:
    20022002 *   Retrieve the session identifier (Session-Id) corresponding to a session object.
    20032003 *  The returned sid is a \0-terminated binary string which might be UTF-8 (but there is no guarantee in the framework).
     
    20182018 *  timeout     : The date when the session times out.
    20192019 *
    2020  * DESCRIPTION: 
    2021  *   Set the lifetime for a given session object. This function may be 
     2020 * DESCRIPTION:
     2021 *   Set the lifetime for a given session object. This function may be
    20222022 * called several times on the same object to update the timeout value.
    2023  *   When the timeout date is reached, the cleanup handler of each 
    2024  * module that registered data with this session is called, then the 
     2023 *   When the timeout date is reached, the cleanup handler of each
     2024 * module that registered data with this session is called, then the
    20252025 * session is cleared.
    20262026 *
    20272027 *   There is a possible race condition between cleanup of the session
    2028  * and use of its data; applications should ensure that they are not 
     2028 * and use of its data; applications should ensure that they are not
    20292029 * using data from a session that is about to expire / expired.
    20302030 *
     
    20412041 *  session     : Pointer to a session object.
    20422042 *
    2043  * DESCRIPTION: 
     2043 * DESCRIPTION:
    20442044 *   Destroys all associated states of a session, if any.
    20452045 * Equivalent to a session timeout expired, but the effect is immediate.
    2046  * The session itself is marked as deleted, and will be freed when it is not referenced 
     2046 * The session itself is marked as deleted, and will be freed when it is not referenced
    20472047 * by any message anymore.
    20482048 *
     
    20592059 *  session     : Pointer to a session object.
    20602060 *
    2061  * DESCRIPTION: 
     2061 * DESCRIPTION:
    20622062 *   Equivalent to fd_sess_destroy, only if no session_state is associated with the session.
    20632063 *  Otherwise, this function has no effect (except that it sets *session to NULL).
     
    20802080 *  state       : An application state (opaque data) to store with the session.
    20812081 *
    2082  * DESCRIPTION: 
     2082 * DESCRIPTION:
    20832083 *  Stores an application state with a session. This state can later be retrieved
    20842084 * with fd_sess_state_retrieve, or implicitly in the cleanup handler when the session
     
    21012101 *  state       : Location where the state must be saved if it is found.
    21022102 *
    2103  * DESCRIPTION: 
     2103 * DESCRIPTION:
    21042104 *  Retrieves a state saved by fd_sess_state_store.
    2105  * After this function has been called, the state is no longer associated with 
     2105 * After this function has been called, the state is no longer associated with
    21062106 * the session. A new call to fd_sess_state_store must be performed in order to
    21072107 * store again the data with the session.
     
    21112111 *  EINVAL      : A parameter is invalid.
    21122112 */
    2113 int fd_sess_state_retrieve ( struct session_handler * handler, struct session * session, struct sess_state ** state ); 
     2113int fd_sess_state_retrieve ( struct session_handler * handler, struct session * session, struct sess_state ** state );
    21142114
    21152115
     
    21252125/*============================================================*/
    21262126
    2127 /* The following functions are helpers for the routing module. 
     2127/* The following functions are helpers for the routing module.
    21282128  The routing data is stored in the message itself. */
    21292129
     
    21962196#define DIAMETER_VERSION        1
    21972197
    2198 /* In the two following types, some fields are marked (READONLY). 
     2198/* In the two following types, some fields are marked (READONLY).
    21992199 * This means that the content of these fields will be overwritten by the daemon so modifying it is useless.
    22002200 */
     
    22392239#define AVPFL_SET_RAWDATA_FROM_AVP 0x02 /* When creating an AVP, initialize its rawdata area from an existing AVP -- it is only blank padding (for error reporting) */
    22402240#define AVPFL_MAX                  AVPFL_SET_RAWDATA_FROM_AVP   /* The biggest valid flag value */
    2241        
     2241
    22422242#define MSGFL_ALLOC_ETEID       0x01    /* When creating a message, a new end-to-end ID is allocated and set in the message */
    22432243#define MSGFL_ANSW_ERROR        0x02    /* When creating an answer message, set the 'E' bit and use the generic error ABNF instead of command-specific ABNF */
     
    22572257 *  avp         : Upon success, pointer to the new avp is stored here. It points to reference AVP upon function call when flags are used.
    22582258 *
    2259  * DESCRIPTION: 
     2259 * DESCRIPTION:
    22602260 *   Create a new AVP instance.
    22612261 *
     
    22762276 *  msg         : Upon success, pointer to the new message is stored here.
    22772277 *
    2278  * DESCRIPTION: 
    2279  *   Create a new empty Diameter message. 
     2278 * DESCRIPTION:
     2279 *   Create a new empty Diameter message.
    22802280 *
    22812281 * RETURN VALUE:
     
    22962296 *              : See other MSGFL_ANSW_* definition above for other flags.
    22972297 *
    2298  * DESCRIPTION: 
     2298 * DESCRIPTION:
    22992299 *   This function creates the empty answer message corresponding to a request.
    23002300 *  The header is set properly (R flag, ccode, appid, hbhid, eteid)
     
    23182318 *  depth       : If not NULL, points to an integer representing the "depth" of this object in the tree. This is a relative value, updated on return.
    23192319 *
    2320  * DESCRIPTION: 
     2320 * DESCRIPTION:
    23212321 *   Explore the content of a message object (hierarchy). If "found" is null, only error checking is performed.
    23222322 *  If "depth" is provided, it is updated as follow on successful function return:
     
    23292329 *  0           : found has been updated (if non NULL).
    23302330 *  EINVAL      : A parameter is invalid.
    2331  *  ENOENT      : No element has been found where requested, and "found" was NULL (otherwise, *found is set to NULL and 0 is returned). 
     2331 *  ENOENT      : No element has been found where requested, and "found" was NULL (otherwise, *found is set to NULL and 0 is returned).
    23322332 */
    23332333int fd_msg_browse_internal ( msg_or_avp * reference, enum msg_brw_dir dir, msg_or_avp ** found, int * depth );
     
    23452345 *  avp         : pointer to the AVP object that must be inserted.
    23462346 *
    2347  * DESCRIPTION: 
     2347 * DESCRIPTION:
    23482348 *   Adds an AVP into an object that can contain it: grouped AVP or message.
    2349  * Note that the added AVP will be freed at the same time as the object it is added to, 
     2349 * Note that the added AVP will be freed at the same time as the object it is added to,
    23502350 * so it should not be freed after the call to this function.
    23512351 *
     
    23642364 *  avp         : location where the AVP reference is stored if found.
    23652365 *
    2366  * DESCRIPTION: 
     2366 * DESCRIPTION:
    23672367 *   Search the first top-level AVP of a given model inside a message.
    23682368 * Note: only the first instance of the AVP is returned by this function.
     
    23832383 *  object      : pointer to the message or AVP object that must be unlinked and freed.
    23842384 *
    2385  * DESCRIPTION: 
     2385 * DESCRIPTION:
    23862386 *   Unlink and free a message or AVP object and its children.
    23872387 *  If the object is an AVP linked into a message, the AVP is removed before being freed.
     
    24072407 *  recurse      : allow the function to go through the children objects if any to dump more information. might require parsing.
    24082408 *
    2409  * DESCRIPTION: 
     2409 * DESCRIPTION:
    24102410 *   These functions dump the content of a message or avp into a buffer
    24112411 * either recursively or only the object itself.
     
    24322432 *  model       : on success, pointer to the dictionary model of this command or AVP. NULL if the model is unknown.
    24332433 *
    2434  * DESCRIPTION: 
     2434 * DESCRIPTION:
    24352435 *   Retrieve the dictionary object describing this message or avp. If the object is unknown or the fd_msg_parse_dict has not been called,
    24362436 *  *model is set to NULL.
     
    24492449 *  pdata       : Upon success, pointer to the msg_hdr structure of this message. The fields may be modified.
    24502450 *
    2451  * DESCRIPTION: 
    2452  *   Retrieve location of modifiable section of a message. 
     2451 * DESCRIPTION:
     2452 *   Retrieve location of modifiable section of a message.
    24532453 *
    24542454 * RETURN VALUE:
     
    24652465 *  pdata       : Upon success, pointer to the avp_hdr structure of this avp. The fields may be modified.
    24662466 *
    2467  * DESCRIPTION: 
    2468  *   Retrieve location of modifiable data of an avp. 
     2467 * DESCRIPTION:
     2468 *   Retrieve location of modifiable data of an avp.
    24692469 *
    24702470 * RETURN VALUE:
     
    24822482 *
    24832483 * DESCRIPTION:
    2484  *  fd_msg_answ_associate associates a query msg with the received answer. 
     2484 *  fd_msg_answ_associate associates a query msg with the received answer.
    24852485 * Query is retrieved with fd_msg_answ_getq.
    24862486 * If answer message is freed, the query is also freed.
     
    25432543 *  msg         : A msg object.
    25442544 *
    2545  * DESCRIPTION: 
    2546  *   This function returns a boolean telling if a given message is routable in the Diameter network, 
     2545 * DESCRIPTION:
     2546 *   This function returns a boolean telling if a given message is routable in the Diameter network,
    25472547 *  or if it is a local link message only (ex: CER/CEA, DWR/DWA, ...).
    25482548 *
     
    25612561 *  dict        : a dictionary with definition of Route-Record AVP (for fd_msg_source_setrr)
    25622562 *
    2563  * DESCRIPTION: 
     2563 * DESCRIPTION:
    25642564 *   Store or retrieve the diameted id of the peer from which this message was received.
    25652565 * Will be used for example by the routing module to add the Route-Record AVP in forwarded requests,
     
    25802580 *  -
    25812581 *
    2582  * DESCRIPTION: 
     2582 * DESCRIPTION:
    25832583 *   Get a new unique end-to-end id value for the local peer.
    25842584 *
     
    26302630 * PARAMETERS:
    26312631 *  avp         : Pointer to a valid avp object with a NULL avp_value pointer. The model must be known.
    2632  *  value       : pointer to an avp_value. The content will be COPIED into the internal storage area. 
     2632 *  value       : pointer to an avp_value. The content will be COPIED into the internal storage area.
    26332633 *               If data type is an octetstring, the data is also copied.
    26342634 *               If value is a NULL pointer, the previous data is erased and value is unset in the AVP.
    26352635 *
    2636  * DESCRIPTION: 
     2636 * DESCRIPTION:
    26372637 *   Initialize the avp_value field of an AVP header.
    26382638 *
     
    26512651 *               This is only valid for AVPs of derived type for which type_data_encode callback is set. (ex: Address type)
    26522652 *
    2653  * DESCRIPTION: 
     2653 * DESCRIPTION:
    26542654 *   Initialize the avp_value field of an AVP object from formatted data, using the AVP's type "type_data_encode" callback.
    26552655 *
     
    26672667 *  data        : Upon success, formatted interpretation of the AVP value is stored here.
    26682668 *
    2669  * DESCRIPTION: 
     2669 * DESCRIPTION:
    26702670 *   Interpret the content of an AVP of Derived type and store the result in data pointer. The structure
    2671  * of the data pointer is dependent on the AVP type. This function calls the "type_data_interpret" callback 
     2671 * of the data pointer is dependent on the AVP type. This function calls the "type_data_interpret" callback
    26722672 * of the type.
    26732673 *
     
    26882688 *
    26892689 * PARAMETERS:
    2690  *  msg         : A valid msg object. All AVPs must have a value set. 
    2691  *  buffer      : Upon success, this points to a buffer (malloc'd) containing the message ready for network transmission (or security transformations). 
     2690 *  msg         : A valid msg object. All AVPs must have a value set.
     2691 *  buffer      : Upon success, this points to a buffer (malloc'd) containing the message ready for network transmission (or security transformations).
    26922692 *               The buffer may be freed after use.
    26932693 *  len         : if not NULL, the size of the buffer is written here. In any case, this size is updated in the msg header.
    26942694 *
    2695  * DESCRIPTION: 
     2695 * DESCRIPTION:
    26962696 *   Renders a message in memory as a buffer that can be sent over the network to the next peer.
    26972697 *
     
    27072707 *
    27082708 * PARAMETERS:
    2709  *  buffer      : Pointer to a buffer containing a message received from the network. 
     2709 *  buffer      : Pointer to a buffer containing a message received from the network.
    27102710 *  buflen      : the size in bytes of the buffer.
    27112711 *  msg         : Upon success, this points to a valid msg object. No AVP value is resolved in this object, nor grouped AVP.
    27122712 *
    2713  * DESCRIPTION: 
     2713 * DESCRIPTION:
    27142714 *   This function parses a buffer an creates a msg object to represent the structure of the message.
    27152715 *  Since no dictionary lookup is performed, the values of the AVPs are not interpreted. To interpret the values,
     
    27422742 *  error_info  : If not NULL, will contain the detail about error upon return. May be used to generate an error reply.
    27432743 *
    2744  * DESCRIPTION: 
     2744 * DESCRIPTION:
    27452745 *   This function looks up for the command and each children AVP definitions in the dictionary.
    27462746 *  If the dictionary definition is found, avp_model is set and the value of the AVP is interpreted accordingly and:
    27472747 *   - for grouped AVPs, the children AVP are created and interpreted also.
    27482748 *   - for numerical AVPs, the value is converted to host byte order and saved in the avp_value field.
    2749  *   - for octetstring AVPs, the string is copied into a new buffer and its address is saved in avp_value. 
     2749 *   - for octetstring AVPs, the string is copied into a new buffer and its address is saved in avp_value.
    27502750 *  If the dictionary definition is not found, avp_model is set to NULL and
    27512751 *  the content of the AVP is saved as an octetstring in an internal structure. avp_value is NULL.
     
    27682768 *  error_info  : If not NULL, the first problem information will be saved here.
    27692769 *
    2770  * DESCRIPTION: 
     2770 * DESCRIPTION:
    27712771 *   Check that the children of the object do not conflict with the dictionary rules (ABNF compliance).
    27722772 *
     
    27852785 *
    27862786 * PARAMETERS:
    2787  *  object      : Pointer to a valid msg or avp. 
    2788  *
    2789  * DESCRIPTION: 
     2787 *  object      : Pointer to a valid msg or avp.
     2788 *
     2789 * DESCRIPTION:
    27902790 *   Update the length field of the object passed as parameter.
    27912791 * As a side effect, all children objects are also updated. Therefore, all avp_value fields of
     
    28892889 * DISP_HOW_AVP_ENUMVAL.
    28902890 *  All fields have the same constraints and meaning as in DISP_REG_AVP. In addition, the "value" field must be set
    2891  *  and points to a valid DICT_ENUMVAL object. 
     2891 *  and points to a valid DICT_ENUMVAL object.
    28922892 *
    28932893 * Here is a sumary of the fields: ( M : must be set; m : may be set; 0 : ignored )
     
    29162916 *  action      : upon return, this tells the daemon what to do next.
    29172917 *
    2918  * DESCRIPTION: 
     2918 * DESCRIPTION:
    29192919 *   Called when a received message matchs the condition for which the callback was registered.
    29202920 * This callback may do any kind of processing on the message, including:
     
    29232923 *  - update a routing table or start a connection with a new peer, then forward the message.
    29242924 *  - ...
    2925  * 
     2925 *
    29262926 * When *action == DISP_ACT_SEND on callback return, the msg pointed by *msg is passed to the routing module for sending.
    29272927 * When *action == DISP_ACT_CONT, the next registered callback is called.
     
    29462946 *  when          : Values that must match, depending on the how argument.
    29472947 *  opaque        : A pointer that is passed back to the handler. The content is not interpreted by the framework.
    2948  *  handle        : On success, a handler to the registered callback is stored here if not NULL. 
     2948 *  handle        : On success, a handler to the registered callback is stored here if not NULL.
    29492949 *                 This handler can be used to unregister the cb.
    29502950 *
    2951  * DESCRIPTION: 
     2951 * DESCRIPTION:
    29522952 *   Register a new callback to handle messages delivered locally.
    29532953 *
     
    29572957 *  ENOMEM      : Not enough memory to complete the operation
    29582958 */
    2959 int fd_disp_register ( int (*cb)( struct msg **, struct avp *, struct session *, void *, enum disp_action *), 
     2959int fd_disp_register ( int (*cb)( struct msg **, struct avp *, struct session *, void *, enum disp_action *),
    29602960                        enum disp_how how, struct disp_when * when, void * opaque, struct disp_hdl ** handle );
    29612961
     
    29672967 *  opaque       : If not NULL, the opaque data that was registered is restored here.
    29682968 *
    2969  * DESCRIPTION: 
     2969 * DESCRIPTION:
    29702970 *   Removes a callback previously registered by fd_disp_register.
    29712971 *
     
    29902990 *  drop_msg    : if drop_reason is set, this points to the message to be freed while *msg is NULL.
    29912991 *
    2992  * DESCRIPTION: 
     2992 * DESCRIPTION:
    29932993 *   Call all handlers registered for a given message.
    29942994 *  The session must have already been resolved on entry.
     
    30223022 *                blocking operation. Use 0 to disable this maximum.
    30233023 *
    3024  * DESCRIPTION: 
     3024 * DESCRIPTION:
    30253025 *  Create a new empty queue.
    30263026 *
     
    30283028 *  0           : The queue has been initialized successfully.
    30293029 *  EINVAL      : The parameter is invalid.
    3030  *  ENOMEM      : Not enough memory to complete the creation. 
     3030 *  ENOMEM      : Not enough memory to complete the creation.
    30313031 */
    30323032int fd_fifo_new ( struct fifo ** queue, int max );
     
    30383038 *  queue       : Pointer to an empty queue to delete.
    30393039 *
    3040  * DESCRIPTION: 
     3040 * DESCRIPTION:
    30413041 *  Destroys a queue. This is only possible if no thread is waiting for an element,
    30423042 * and the queue is empty.
     
    30563056 *  loc_update  : if non NULL, a place to store the pointer to new FIFO atomically with the move.
    30573057 *
    3058  * DESCRIPTION: 
     3058 * DESCRIPTION:
    30593059 *  Empties a queue and move its content to another one atomically.
    30603060 *
     
    30773077 *  blocking      : Cumulated time threads trying to post new items were blocked (queue full).
    30783078 *  last          : For the last element retrieved from the queue, how long it take between posting (including blocking) and poping
    3079  * 
    3080  * DESCRIPTION: 
     3079 *
     3080 * DESCRIPTION:
    30813081 *  Retrieve the timing information associated with a queue, for monitoring purpose.
    30823082 *
     
    30853085 *  EINVAL      : A parameter is invalid.
    30863086 */
    3087 int fd_fifo_getstats( struct fifo * queue, int * current_count, int * limit_count, int * highest_count, long long * total_count, 
     3087int fd_fifo_getstats( struct fifo * queue, int * current_count, int * limit_count, int * highest_count, long long * total_count,
    30883088                                           struct timespec * total, struct timespec * blocking, struct timespec * last);
    30893089
     
    30943094 *  queue       : The queue from which to retrieve the number of elements.
    30953095 *
    3096  * DESCRIPTION: 
     3096 * DESCRIPTION:
    30973097 *  Retrieve the number of elements in a queue, without error checking.
    30983098 *
     
    31133113 *  l_cb        : If the number of elements decrease to low, this callback is called.
    31143114 *
    3115  * DESCRIPTION: 
     3115 * DESCRIPTION:
    31163116 *  This function allows to adjust the number of producer / consumer threads of a queue.
    31173117 * If the consumer are slower than the producers, the number of elements in the queue increase.
     
    31423142 *  item        : The element that is put in the queue.
    31433143 *
    3144  * DESCRIPTION: 
     3144 * DESCRIPTION:
    31453145 *  An element is added in a queue. Elements are retrieved from the queue in FIFO order
    31463146 *  with the fd_fifo_get, fd_fifo_tryget, or fd_fifo_timedget functions.
     
    31663166 *  item        : On return, the first element of the queue is stored here.
    31673167 *
    3168  * DESCRIPTION: 
    3169  *  This function retrieves the first element from a queue. If the queue is empty, the function will block the 
    3170  * thread until a new element is posted to the queue, or until the thread is canceled (in which case the 
     3168 * DESCRIPTION:
     3169 *  This function retrieves the first element from a queue. If the queue is empty, the function will block the
     3170 * thread until a new element is posted to the queue, or until the thread is canceled (in which case the
    31713171 * function does not return).
    31723172 *
     
    31863186 *  item        : On return, the first element of the queue is stored here.
    31873187 *
    3188  * DESCRIPTION: 
    3189  *  This function is similar to fd_fifo_get, except that it will not block if 
     3188 * DESCRIPTION:
     3189 *  This function is similar to fd_fifo_get, except that it will not block if
    31903190 * the queue is empty, but return EWOULDBLOCK instead.
    31913191 *
     
    32073207 *  abstime     : the absolute time until which we allow waiting for an item.
    32083208 *
    3209  * DESCRIPTION: 
    3210  *  This function is similar to fd_fifo_get, except that it will block if the queue is empty 
     3209 * DESCRIPTION:
     3210 *  This function is similar to fd_fifo_get, except that it will block if the queue is empty
    32113211 * only until the absolute time abstime (see pthread_cond_timedwait for + info).
    32123212 * If the queue is still empty when the time expires, the function returns ETIMEDOUT
     
    32293229 *  abstime     : the absolute time until which we can block waiting for an item. If NULL, the function returns immediatly.
    32303230 *
    3231  * DESCRIPTION: 
     3231 * DESCRIPTION:
    32323232 *  This function is similar to select(), it waits for data to be available in the queue
    32333233 * until the abstime is expired.
Note: See TracChangeset for help on using the changeset viewer.