Changeset 1392:497d926f5e3d in freeDiameter
- Timestamp:
- Nov 15, 2019, 7:28:11 PM (4 years ago)
- Branch:
- default
- Phase:
- public
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
include/freeDiameter/libfdproto.h
r1343 r1392 139 139 * ... : Same list as printf 140 140 * 141 * DESCRIPTION: 141 * DESCRIPTION: 142 142 * Write information to log. 143 143 * The format and arguments may contain UTF-8 encoded data. The … … 152 152 #endif /* SWIG */ 153 153 154 /* these are internal objects of the debug facility, 154 /* these are internal objects of the debug facility, 155 155 might be useful to control the behavior from outside */ 156 156 extern pthread_mutex_t fd_log_lock; … … 164 164 * name : \0-terminated string containing a name to identify the current thread. 165 165 * 166 * DESCRIPTION: 166 * DESCRIPTION: 167 167 * Name the current thread, useful for debugging multi-threaded problems. 168 168 * … … 186 186 * incl_ms : millisecond value is included in the output 187 187 * 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. 190 190 * 191 191 * RETURN VALUE: … … 246 246 char * function_name(char ** buf, size_t *len, size_t *offset) 247 247 #endif /* SWIG */ 248 248 249 249 250 250 /* Helper functions for the *dump functions that add into a buffer */ … … 313 313 314 314 /* 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: 316 316 */ 317 317 #ifdef DEBUG … … 403 403 * The name "__ret__" is always available in the __fallback__ parameter and contains the error code. 404 404 */ 405 405 406 406 #define CHECK_PRELUDE(__call__) \ 407 407 int __ret__; \ 408 408 TRACE_CALL("Check: %s", #__call__ ); \ 409 409 __ret__ = (__call__) 410 410 411 411 #define DEFAULT_FB return __ret__; 412 412 … … 492 492 #ifndef SWIG 493 493 static __inline__ void fd_log_deprecated( int level, const char *format, ... ) MARK_DEPRECATED 494 { 494 { 495 495 va_list ap; 496 496 va_start(ap, format); … … 558 558 # define CHECK_POSIX( __call__ ) \ 559 559 CHECK_POSIX_DO( (__call__), return __ret__ ) 560 560 561 561 # define CHECK_MALLOC_DO( __call__, __fallback__ ) { \ 562 562 void * __ptr__; \ … … 572 572 # define CHECK_MALLOC( __call__ ) \ 573 573 CHECK_MALLOC_DO( (__call__), return __ret__ ) 574 574 575 575 # define CHECK_PARAMS_DO( __bool__, __fallback__ ) { \ 576 576 TRACE_CALL("Check: %s", #__bool__ ); \ … … 589 589 590 590 #endif /* EXCLUDE_DEPRECATED */ 591 591 592 592 593 593 /*============================================================*/ … … 661 661 662 662 /* Define the value of IP loopback address */ 663 #ifndef INADDR_LOOPBACK 663 #ifndef INADDR_LOOPBACK 664 664 #define INADDR_LOOPBACK inet_addr("127.0.0.1") 665 665 #endif /* INADDR_LOOPBACK */ … … 702 702 # else /* HOST_BIG_ENDIAN */ 703 703 /* 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 ))) 706 706 # endif /* HOST_BIG_ENDIAN */ 707 707 #endif /* HAVE_NTOHLL */ … … 727 727 (tsdiff)->tv_nsec = (tsend)->tv_nsec - (tsstart)->tv_nsec; \ 728 728 }} 729 729 730 730 731 731 /* This gives a good size for buffered reads */ … … 756 756 /*============================================================*/ 757 757 758 /* Compute a hash value of a binary string. 758 /* Compute a hash value of a binary string. 759 759 The hash must remain local to this machine, there is no guarantee that same input 760 760 will give same output on a different system (endianness) */ 761 761 uint32_t fd_os_hash ( uint8_t * string, size_t len ); 762 762 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. 764 764 It means some string operations can be used on it. */ 765 765 typedef uint8_t * os0_t; … … 787 787 int fd_os_is_valid_DiameterIdentity(uint8_t * os, size_t ossz); 788 788 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 790 790 if *inoutsz is != 0 on entry, *id may not be \0-terminated. 791 791 memory has the following meaning: 0: *id can be realloc'd. 1: *id must be malloc'd on output (was static) … … 793 793 int fd_os_validate_DiameterIdentity(char ** id, size_t * inoutsz, int memory); 794 794 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). 796 796 It does NOT mimic strings relationships so that it is more efficient. It is case sensitive. 797 797 (the strings are actually first ordered by their lengh, then by their bytes contents) … … 800 800 #define fd_os_cmp(_o1, _l1, _o2, _l2) fd_os_cmp_int((os0_t)(_o1), _l1, (os0_t)(_o2), _l2) 801 801 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 803 803 -- it does not support locales where a lowercase letter uses more space than upper case, such as ß -> ss 804 804 It is slower than fd_os_cmp. 805 805 Note that the result is NOT the same as strcasecmp !!! 806 806 807 807 This function gives the same order as fd_os_cmp, except when it finds 2 strings to be equal. 808 808 However this is not always sufficient: … … 817 817 #define fd_os_almostcasesrch(_o1, _l1, _o2, _l2, _mb) fd_os_almostcasesrch_int((os0_t)(_o1), _l1, (os0_t)(_o2), _l2, _mb) 818 818 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. 821 821 *diamid is malloc'd on function return and must be freed (it is processed by fd_os_validate_DiameterIdentity). 822 822 *secure is 0 (no security) or 1 (security enabled) on return. … … 835 835 { 836 836 void * th_ret = NULL; 837 837 838 838 CHECK_PARAMS(th); 839 839 840 840 /* Test if it was already terminated */ 841 841 if (*th == (pthread_t)NULL) 842 842 return 0; 843 843 844 844 /* Cancel the thread if it is still running - ignore error if it was already terminated */ 845 845 (void) pthread_cancel(*th); 846 846 847 847 /* Then join the thread */ 848 848 CHECK_POSIX( pthread_join(*th, &th_ret) ); 849 849 850 850 if (th_ret == PTHREAD_CANCELED) { 851 851 TRACE_DEBUG(ANNOYING, "The thread %p was canceled", (void *)*th); … … 853 853 TRACE_DEBUG(CALL, "The thread %p returned %p", (void *)*th, th_ret); 854 854 } 855 855 856 856 /* Clean the location */ 857 857 *th = (pthread_t)NULL; 858 858 859 859 return 0; 860 860 } … … 862 862 863 863 /************* 864 Cancelation cleanup handlers for common objects 864 Cancelation cleanup handlers for common objects 865 865 *************/ 866 866 static __inline__ void fd_cleanup_mutex( void * mutex ) … … 868 868 CHECK_POSIX_DO( pthread_mutex_unlock((pthread_mutex_t *)mutex), /* */); 869 869 } 870 870 871 871 static __inline__ void fd_cleanup_rwlock( void * rwlock ) 872 872 { … … 946 946 #define DICT_TYPE_MAX DICT_RULE 947 947 }; 948 948 949 949 /* Initialize a dictionary */ 950 950 int fd_dict_init(struct dictionary ** dict); … … 958 958 * dict : Pointer to the dictionnary where the object is created 959 959 * 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. 961 961 * type parameter is used to determine the type of data (see below for detail). 962 962 * parent : a reference to a parent object, if needed. 963 963 * ref : upon successful creation, reference to new object is stored here if !null. 964 964 * 965 * DESCRIPTION: 966 * Create a new object in the dictionary. 965 * DESCRIPTION: 966 * Create a new object in the dictionary. 967 967 * See following object sections in this header file for more information on data and parent parameters format. 968 968 * … … 970 970 * 0 : The object is created in the dictionary. 971 971 * 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). 973 973 * If "ref" is not NULL, it points to the existing element on return. 974 974 * (other standard errors may be returned, too, with their standard meaning. Example: … … 988 988 * retval : this value is returned if the object is not found and result is not NULL. 989 989 * 990 * DESCRIPTION: 991 * Perform a search in the dictionary. 990 * DESCRIPTION: 991 * Perform a search in the dictionary. 992 992 * See the object-specific sections below to find how to look for each objects. 993 993 * If the "result" parameter is NULL, the function is used to check if an object is in the dictionary. … … 1013 1013 * The type is the same as "data" parameter in fd_dict_new function. 1014 1014 * 1015 * DESCRIPTION: 1015 * DESCRIPTION: 1016 1016 * Retrieve content of a dictionary object. 1017 1017 * See following object sections in this header file for more information on data and parent parameters format. … … 1040 1040 *************************************************************************** 1041 1041 * 1042 * Vendor object 1042 * Vendor object 1043 1043 * 1044 1044 * These types are used to manage vendors in the dictionary … … 1070 1070 On the other side, when value is retrieved with dict_getval, the string is not copied and MUST NOT be freed. It will 1071 1071 be freed automatically along with the object itself with call to dict_fini later. 1072 1072 1073 1073 - fd_dict_new: 1074 The "parent" parameter is not used for vendors. 1074 The "parent" parameter is not used for vendors. 1075 1075 Sample code to create a vendor: 1076 1076 { … … 1091 1091 ret = fd_dict_search ( dict, DICT_VENDOR, VENDOR_BY_NAME, "my vendor name", &vendor_found, ENOENT); 1092 1092 } 1093 1093 1094 1094 - fd_dict_getval: 1095 1095 Sample code to retrieve the data from a vendor object: … … 1102 1102 printf("my vendor id: %d\n", myvendordata.vendor_id ); 1103 1103 } 1104 1104 1105 1105 */ 1106 1106 1107 1107 /* Special function: */ 1108 1108 uint32_t * fd_dict_get_vendorid_list(struct dictionary * dict); 1109 1109 1110 1110 /* 1111 1111 *************************************************************************** 1112 1112 * 1113 * Application object 1113 * Application object 1114 1114 * 1115 1115 * These types are used to manage Diameter applications in the dictionary … … 1156 1156 "my vendor's application" 1157 1157 }; 1158 1158 1159 1159 ret = fd_dict_new ( dict, DICT_VENDOR, &vendor_data, NULL, &vendor ); 1160 1160 ret = fd_dict_new ( dict, DICT_APPLICATION, &app_data, vendor, &appl ); … … 1166 1166 int ret; 1167 1167 struct dict_object * vendor, * appli; 1168 1168 1169 1169 ret = fd_dict_search ( dict, DICT_APPLICATION, APPLICATION_BY_NAME, "my vendor's application", &appli, ENOENT); 1170 1170 ret = fd_dict_search ( dict, DICT_VENDOR, VENDOR_OF_APPLICATION, appli, &vendor, ENOENT); 1171 1171 } 1172 1172 1173 1173 - fd_dict_getval: 1174 1174 Sample code to retrieve the data from an application object: … … 1187 1187 *************************************************************************** 1188 1188 * 1189 * Type object 1189 * Type object 1190 1190 * 1191 1191 * These types are used to manage AVP data types in the dictionary … … 1194 1194 */ 1195 1195 1196 /* Type to store any AVP value */ 1196 /* Type to store any AVP value */ 1197 1197 union avp_value { 1198 1198 struct { … … 1229 1229 * interpreted : The result of interpretation is stored here. The format and meaning depends on each type. 1230 1230 * 1231 * DESCRIPTION: 1231 * DESCRIPTION: 1232 1232 * This callback can be provided with a derived type in order to facilitate the interpretation of formated data. 1233 1233 * For example, when an AVP of type "Address" is received, it can be used to convert the octetstring into a struct sockaddr. … … 1246 1246 * val : Pointer to the AVP value storage area where the data must be stored. 1247 1247 * 1248 * DESCRIPTION: 1248 * DESCRIPTION: 1249 1249 * This callback can be provided with a derived type in order to facilitate the encoding of formated data. 1250 1250 * For example, it can be used to convert a struct sockaddr in an AVP value of type Address. 1251 1251 * 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 1253 1253 * automatically later. 1254 1254 * … … 1265 1265 * val : Pointer to the AVP value that was received and needs to be sanity checked. 1266 1266 * 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: 1270 1270 * This callback can be provided with a derived type in order to improve the operation of the 1271 1271 * 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 1273 1273 * speccific AVP, the format of an OCTETSTRING value can be further checked, or the 1274 1274 * interger value can be verified. … … 1301 1301 1302 1302 /**** 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. 1304 1304 */ 1305 1305 … … 1328 1328 1329 1329 - 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 1332 1332 Sample code: 1333 1333 { 1334 1334 int ret; 1335 1335 struct dict_object * mytype; 1336 struct dict_type_data mytypedata = 1337 { 1336 struct dict_type_data mytypedata = 1337 { 1338 1338 AVP_TYPE_OCTETSTRING, 1339 1339 "Address", … … 1351 1351 ret = fd_dict_search ( dict, DICT_TYPE, TYPE_BY_NAME, "Address", &address_type, ENOENT); 1352 1352 } 1353 1353 1354 1354 */ 1355 1355 … … 1357 1357 *************************************************************************** 1358 1358 * 1359 * Enumerated values object 1359 * Enumerated values object 1360 1360 * 1361 1361 * These types are used to manage named constants of some AVP, … … 1382 1382 struct dict_object *type_obj; 1383 1383 char * type_name; 1384 1384 1385 1385 /* Search criteria for the constant */ 1386 1386 struct dict_enumval_data search; /* search.enum_value is used only if search.enum_name == NULL */ … … 1391 1391 1392 1392 - 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. 1394 1394 Sample code to create a type "Boolean" with two constants "True" and "False": 1395 1395 { 1396 1396 int ret; 1397 1397 struct dict_object * type_boolean; 1398 struct dict_type_data type_boolean_data = 1399 { 1398 struct dict_type_data type_boolean_data = 1399 { 1400 1400 AVP_TYPE_INTEGER32, 1401 1401 "Boolean", … … 1416 1416 ret = fd_dict_new ( dict, DICT_ENUMVAL, &boolean_false, type_boolean, NULL ); 1417 1417 ret = fd_dict_new ( dict, DICT_ENUMVAL, &boolean_true , type_boolean, NULL ); 1418 1418 1419 1419 } 1420 1420 … … 1430 1430 .search.enum_value.i32 = -1 1431 1431 }; 1432 1432 1433 1433 ret = fd_dict_search ( dict, DICT_ENUMVAL, ENUMVAL_BY_STRUCT, &boolean_by_value, &value_found, ENOENT); 1434 1434 } 1435 1435 1436 1436 - fd_dict_getval: 1437 1437 Sample code to retrieve the data from a constant object: … … 1446 1446 .search.enum_value.i32 = 0 1447 1447 }; 1448 1448 1449 1449 ret = fd_dict_search ( dict, DICT_ENUMVAL, ENUMVAL_BY_STRUCT, &boolean_by_value, &value_found, ENOENT); 1450 1450 ret = fd_dict_getval ( value_found, &boolean_data ); … … 1452 1452 } 1453 1453 */ 1454 1454 1455 1455 /* 1456 1456 *************************************************************************** 1457 1457 * 1458 * AVP object 1458 * AVP object 1459 1459 * 1460 1460 * These objects are used to manage AVP definitions in the dictionary … … 1498 1498 AVP_BY_NAME_ALL_VENDORS,/* "what" points to a string. Might be quite slow... */ 1499 1499 AVP_BY_STRUCT, /* "what" points to a struct dict_avp_request_ex (see below) */ 1500 1500 1501 1501 /* kept for backward compatibility, better use AVP_BY_STRUCT above instead */ 1502 1502 AVP_BY_CODE_AND_VENDOR, /* "what" points to a struct dict_avp_request (see below), where avp_vendor and avp_code are set */ … … 1512 1512 const char * vendor_name; /* set to NULL to ignore */ 1513 1513 } avp_vendor; 1514 1514 1515 1515 struct { 1516 1516 /* Only one of the following fields must be set */ … … 1531 1531 * API usage : 1532 1532 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 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 1535 1535 AVP is automatically interpreted in debug messages, and in message checks. 1536 1536 The derived type of an AVP can be retrieved with: dict_search ( DICT_TYPE, TYPE_OF_AVP, avp, ... ) … … 1561 1561 AVP_TYPE_INTEGER32 // This MUST be the same as parent type's 1562 1562 }; 1563 1563 1564 1564 -- Create an AVP with a base type -- 1565 1565 ret = fd_dict_new ( dict, DICT_AVP, &user_name_data, NULL, &user_name_avp ); 1566 1566 1567 1567 -- Create an AVP with a derived type -- 1568 1568 ret = fd_dict_search ( dict, DICT_TYPE, TYPE_BY_NAME, "Boolean", &boolean_type, ENOENT); 1569 1569 ret = fd_dict_new ( dict, DICT_AVP, &sample_boolean_data , boolean_type, &sample_boolean_avp ); 1570 1570 1571 1571 } 1572 1572 … … 1582 1582 .avp_name = "Sample-Boolean" 1583 1583 }; 1584 1584 1585 1585 ret = fd_dict_search ( dict, DICT_AVP, AVP_BY_NAME, "User-Name", &avp_username, ENOENT); 1586 1586 1587 1587 ret = fd_dict_search ( dict, DICT_AVP, AVP_BY_NAME_AND_VENDOR, &avpvendorboolean, &avp_sampleboolean, ENOENT); 1588 1588 1589 1589 -- this would also work, but be slower, because it has to search all vendor dictionaries -- 1590 1590 ret = fd_dict_search ( dict, DICT_AVP, AVP_BY_NAME_ALL_VENDORS, "Sample-Boolean", &avp_sampleboolean, ENOENT); 1591 1591 1592 1592 } 1593 1593 1594 1594 - fd_dict_getval: 1595 1595 Sample code to retrieve the data from an AVP object: … … 1608 1608 *************************************************************************** 1609 1609 * 1610 * Command object 1610 * Command object 1611 1611 * 1612 1612 * These types are used to manage commands objects in the dictionary … … 1672 1672 CMD_FLAG_REQUEST // value. Only the "R" flag is constrained here, set. 1673 1673 }; 1674 1674 1675 1675 ret = fd_dict_new (dict, DICT_COMMAND, &ce_data, NULL, &cer ); 1676 1676 1677 1677 ce_data.cmd_name = "Capabilities-Exchange-Answer"; 1678 1678 ce_data.cmd_flag_val = 0; // Same constraint on "R" flag, but this time it must be cleared. … … 1690 1690 ret = fd_dict_search ( dict, DICT_COMMAND, CMD_BY_CODE_R, &code, &cer, ENOENT); 1691 1691 } 1692 1692 1693 1693 - fd_dict_getval: 1694 1694 Sample code to retrieve the data from a command object: … … 1764 1764 struct dict_avp_data proxy_host_data = { 280, 0, "Proxy-Host", AVP_FLAG_VENDOR | AVP_FLAG_MANDATORY, AVP_FLAG_MANDATORY, AVP_TYPE_OCTETSTRING }; 1765 1765 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 1767 1767 -- Create the parent AVP 1768 1768 ret = fd_dict_new ( dict, DICT_AVP, &proxy_info_data, NULL, &proxy_info_avp ); 1769 1769 1770 1770 -- Create the first child AVP. 1771 1771 ret = fd_dict_new ( dict, DICT_TYPE, &di_type_data, NULL, &diameteridentity_type ); 1772 1772 ret = fd_dict_new ( dict, DICT_AVP, &proxy_host_data, diameteridentity_type, &proxy_host_avp ); 1773 1773 1774 1774 -- Create the other child AVP 1775 1775 ret = fd_dict_new ( dict, DICT_AVP, &proxy_state_data, NULL, &proxy_state_avp ); 1776 1776 1777 1777 -- Now we can create the rules. Both children AVP are mandatory. 1778 1778 rule_data.rule_position = RULE_REQUIRED; 1779 1779 rule_data.rule_min = -1; 1780 1780 rule_data.rule_max = -1; 1781 1781 1782 1782 rule_data.rule_avp = proxy_host_avp; 1783 1783 ret = fd_dict_new ( dict, DICT_RULE, &rule_data, proxy_info_avp, NULL ); 1784 1784 1785 1785 rule_data.rule_avp = proxy_state_avp; 1786 1786 ret = fd_dict_new ( dict, DICT_RULE, &rule_data, proxy_info_avp, NULL ); … … 1790 1790 1791 1791 */ 1792 1792 1793 1793 /* Define some hard-coded values */ 1794 1794 /* Application */ … … 1841 1841 /* Error codes from Base protocol 1842 1842 (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 1843 Note that currently, rfc3588bis-26 has some different values for some of these 1844 1844 */ 1845 1845 #define ER_DIAMETER_MULTI_ROUND_AUTH 1001 … … 1909 1909 * opaque : A pointer that is passed to the cleanup callback -- the content is never examined by the framework. 1910 1910 * 1911 * DESCRIPTION: 1911 * DESCRIPTION: 1912 1912 * Create a new session handler. This is needed by a module to associate a state with a session object. 1913 1913 * The cleanup handler is called when the session timeout expires, or fd_sess_destroy is called. It must free … … 1921 1921 int 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 ); 1922 1922 1923 1923 1924 1924 /* 1925 1925 * FUNCTION: fd_sess_handler_destroy … … 1929 1929 * opaque : the opaque pointer registered with the callback is restored here (if ! NULL). 1930 1930 * 1931 * DESCRIPTION: 1931 * DESCRIPTION: 1932 1932 * This destroys a session handler (typically called when an application is shutting down). 1933 1933 * If sessions states are registered with this handler, the cleanup callback is called on them. … … 1952 1952 * optlen : if opt is \0-terminated, this can be 0. Otherwise, the length of opt. 1953 1953 * 1954 * DESCRIPTION: 1954 * DESCRIPTION: 1955 1955 * Create a new session object. The Session-Id string associated with this session is generated as follow: 1956 1956 * If diamId parameter is provided, the string is created according to the RFC: <diamId>;<high32>;<low32>[;opt] where … … 1977 1977 * isnew : if not NULL, set to 1 on return if the session object has been created, 0 if it was simply retrieved. 1978 1978 * 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 1981 1981 * id, a new object is silently created (equivalent to fd_sess_new with flag SESSION_NEW_FULL). 1982 1982 * … … 1989 1989 1990 1990 /* 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); 1991 int fd_sess_fromsid_msg ( uint8_t * sid, size_t len, struct session ** session, int * isnew); 1992 1992 int fd_sess_ref_msg ( struct session * session ); 1993 1993 … … 1999 1999 * sid : On success, the location of the sid is stored here. 2000 2000 * 2001 * DESCRIPTION: 2001 * DESCRIPTION: 2002 2002 * Retrieve the session identifier (Session-Id) corresponding to a session object. 2003 2003 * The returned sid is a \0-terminated binary string which might be UTF-8 (but there is no guarantee in the framework). … … 2018 2018 * timeout : The date when the session times out. 2019 2019 * 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 2022 2022 * 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 2025 2025 * session is cleared. 2026 2026 * 2027 2027 * 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 2029 2029 * using data from a session that is about to expire / expired. 2030 2030 * … … 2041 2041 * session : Pointer to a session object. 2042 2042 * 2043 * DESCRIPTION: 2043 * DESCRIPTION: 2044 2044 * Destroys all associated states of a session, if any. 2045 2045 * 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 2047 2047 * by any message anymore. 2048 2048 * … … 2059 2059 * session : Pointer to a session object. 2060 2060 * 2061 * DESCRIPTION: 2061 * DESCRIPTION: 2062 2062 * Equivalent to fd_sess_destroy, only if no session_state is associated with the session. 2063 2063 * Otherwise, this function has no effect (except that it sets *session to NULL). … … 2080 2080 * state : An application state (opaque data) to store with the session. 2081 2081 * 2082 * DESCRIPTION: 2082 * DESCRIPTION: 2083 2083 * Stores an application state with a session. This state can later be retrieved 2084 2084 * with fd_sess_state_retrieve, or implicitly in the cleanup handler when the session … … 2101 2101 * state : Location where the state must be saved if it is found. 2102 2102 * 2103 * DESCRIPTION: 2103 * DESCRIPTION: 2104 2104 * 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 2106 2106 * the session. A new call to fd_sess_state_store must be performed in order to 2107 2107 * store again the data with the session. … … 2111 2111 * EINVAL : A parameter is invalid. 2112 2112 */ 2113 int fd_sess_state_retrieve ( struct session_handler * handler, struct session * session, struct sess_state ** state ); 2113 int fd_sess_state_retrieve ( struct session_handler * handler, struct session * session, struct sess_state ** state ); 2114 2114 2115 2115 … … 2125 2125 /*============================================================*/ 2126 2126 2127 /* The following functions are helpers for the routing module. 2127 /* The following functions are helpers for the routing module. 2128 2128 The routing data is stored in the message itself. */ 2129 2129 … … 2196 2196 #define DIAMETER_VERSION 1 2197 2197 2198 /* In the two following types, some fields are marked (READONLY). 2198 /* In the two following types, some fields are marked (READONLY). 2199 2199 * This means that the content of these fields will be overwritten by the daemon so modifying it is useless. 2200 2200 */ … … 2239 2239 #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) */ 2240 2240 #define AVPFL_MAX AVPFL_SET_RAWDATA_FROM_AVP /* The biggest valid flag value */ 2241 2241 2242 2242 #define MSGFL_ALLOC_ETEID 0x01 /* When creating a message, a new end-to-end ID is allocated and set in the message */ 2243 2243 #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 */ … … 2257 2257 * avp : Upon success, pointer to the new avp is stored here. It points to reference AVP upon function call when flags are used. 2258 2258 * 2259 * DESCRIPTION: 2259 * DESCRIPTION: 2260 2260 * Create a new AVP instance. 2261 2261 * … … 2276 2276 * msg : Upon success, pointer to the new message is stored here. 2277 2277 * 2278 * DESCRIPTION: 2279 * Create a new empty Diameter message. 2278 * DESCRIPTION: 2279 * Create a new empty Diameter message. 2280 2280 * 2281 2281 * RETURN VALUE: … … 2296 2296 * : See other MSGFL_ANSW_* definition above for other flags. 2297 2297 * 2298 * DESCRIPTION: 2298 * DESCRIPTION: 2299 2299 * This function creates the empty answer message corresponding to a request. 2300 2300 * The header is set properly (R flag, ccode, appid, hbhid, eteid) … … 2318 2318 * 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. 2319 2319 * 2320 * DESCRIPTION: 2320 * DESCRIPTION: 2321 2321 * Explore the content of a message object (hierarchy). If "found" is null, only error checking is performed. 2322 2322 * If "depth" is provided, it is updated as follow on successful function return: … … 2329 2329 * 0 : found has been updated (if non NULL). 2330 2330 * 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). 2332 2332 */ 2333 2333 int fd_msg_browse_internal ( msg_or_avp * reference, enum msg_brw_dir dir, msg_or_avp ** found, int * depth ); … … 2345 2345 * avp : pointer to the AVP object that must be inserted. 2346 2346 * 2347 * DESCRIPTION: 2347 * DESCRIPTION: 2348 2348 * 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, 2350 2350 * so it should not be freed after the call to this function. 2351 2351 * … … 2364 2364 * avp : location where the AVP reference is stored if found. 2365 2365 * 2366 * DESCRIPTION: 2366 * DESCRIPTION: 2367 2367 * Search the first top-level AVP of a given model inside a message. 2368 2368 * Note: only the first instance of the AVP is returned by this function. … … 2383 2383 * object : pointer to the message or AVP object that must be unlinked and freed. 2384 2384 * 2385 * DESCRIPTION: 2385 * DESCRIPTION: 2386 2386 * Unlink and free a message or AVP object and its children. 2387 2387 * If the object is an AVP linked into a message, the AVP is removed before being freed. … … 2407 2407 * recurse : allow the function to go through the children objects if any to dump more information. might require parsing. 2408 2408 * 2409 * DESCRIPTION: 2409 * DESCRIPTION: 2410 2410 * These functions dump the content of a message or avp into a buffer 2411 2411 * either recursively or only the object itself. … … 2432 2432 * model : on success, pointer to the dictionary model of this command or AVP. NULL if the model is unknown. 2433 2433 * 2434 * DESCRIPTION: 2434 * DESCRIPTION: 2435 2435 * Retrieve the dictionary object describing this message or avp. If the object is unknown or the fd_msg_parse_dict has not been called, 2436 2436 * *model is set to NULL. … … 2449 2449 * pdata : Upon success, pointer to the msg_hdr structure of this message. The fields may be modified. 2450 2450 * 2451 * DESCRIPTION: 2452 * Retrieve location of modifiable section of a message. 2451 * DESCRIPTION: 2452 * Retrieve location of modifiable section of a message. 2453 2453 * 2454 2454 * RETURN VALUE: … … 2465 2465 * pdata : Upon success, pointer to the avp_hdr structure of this avp. The fields may be modified. 2466 2466 * 2467 * DESCRIPTION: 2468 * Retrieve location of modifiable data of an avp. 2467 * DESCRIPTION: 2468 * Retrieve location of modifiable data of an avp. 2469 2469 * 2470 2470 * RETURN VALUE: … … 2482 2482 * 2483 2483 * 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. 2485 2485 * Query is retrieved with fd_msg_answ_getq. 2486 2486 * If answer message is freed, the query is also freed. … … 2543 2543 * msg : A msg object. 2544 2544 * 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, 2547 2547 * or if it is a local link message only (ex: CER/CEA, DWR/DWA, ...). 2548 2548 * … … 2561 2561 * dict : a dictionary with definition of Route-Record AVP (for fd_msg_source_setrr) 2562 2562 * 2563 * DESCRIPTION: 2563 * DESCRIPTION: 2564 2564 * Store or retrieve the diameted id of the peer from which this message was received. 2565 2565 * Will be used for example by the routing module to add the Route-Record AVP in forwarded requests, … … 2580 2580 * - 2581 2581 * 2582 * DESCRIPTION: 2582 * DESCRIPTION: 2583 2583 * Get a new unique end-to-end id value for the local peer. 2584 2584 * … … 2630 2630 * PARAMETERS: 2631 2631 * 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. 2633 2633 * If data type is an octetstring, the data is also copied. 2634 2634 * If value is a NULL pointer, the previous data is erased and value is unset in the AVP. 2635 2635 * 2636 * DESCRIPTION: 2636 * DESCRIPTION: 2637 2637 * Initialize the avp_value field of an AVP header. 2638 2638 * … … 2651 2651 * This is only valid for AVPs of derived type for which type_data_encode callback is set. (ex: Address type) 2652 2652 * 2653 * DESCRIPTION: 2653 * DESCRIPTION: 2654 2654 * Initialize the avp_value field of an AVP object from formatted data, using the AVP's type "type_data_encode" callback. 2655 2655 * … … 2667 2667 * data : Upon success, formatted interpretation of the AVP value is stored here. 2668 2668 * 2669 * DESCRIPTION: 2669 * DESCRIPTION: 2670 2670 * 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 2672 2672 * of the type. 2673 2673 * … … 2688 2688 * 2689 2689 * 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). 2692 2692 * The buffer may be freed after use. 2693 2693 * len : if not NULL, the size of the buffer is written here. In any case, this size is updated in the msg header. 2694 2694 * 2695 * DESCRIPTION: 2695 * DESCRIPTION: 2696 2696 * Renders a message in memory as a buffer that can be sent over the network to the next peer. 2697 2697 * … … 2707 2707 * 2708 2708 * 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. 2710 2710 * buflen : the size in bytes of the buffer. 2711 2711 * msg : Upon success, this points to a valid msg object. No AVP value is resolved in this object, nor grouped AVP. 2712 2712 * 2713 * DESCRIPTION: 2713 * DESCRIPTION: 2714 2714 * This function parses a buffer an creates a msg object to represent the structure of the message. 2715 2715 * Since no dictionary lookup is performed, the values of the AVPs are not interpreted. To interpret the values, … … 2742 2742 * error_info : If not NULL, will contain the detail about error upon return. May be used to generate an error reply. 2743 2743 * 2744 * DESCRIPTION: 2744 * DESCRIPTION: 2745 2745 * This function looks up for the command and each children AVP definitions in the dictionary. 2746 2746 * If the dictionary definition is found, avp_model is set and the value of the AVP is interpreted accordingly and: 2747 2747 * - for grouped AVPs, the children AVP are created and interpreted also. 2748 2748 * - 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. 2750 2750 * If the dictionary definition is not found, avp_model is set to NULL and 2751 2751 * the content of the AVP is saved as an octetstring in an internal structure. avp_value is NULL. … … 2768 2768 * error_info : If not NULL, the first problem information will be saved here. 2769 2769 * 2770 * DESCRIPTION: 2770 * DESCRIPTION: 2771 2771 * Check that the children of the object do not conflict with the dictionary rules (ABNF compliance). 2772 2772 * … … 2785 2785 * 2786 2786 * 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: 2790 2790 * Update the length field of the object passed as parameter. 2791 2791 * As a side effect, all children objects are also updated. Therefore, all avp_value fields of … … 2889 2889 * DISP_HOW_AVP_ENUMVAL. 2890 2890 * 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. 2892 2892 * 2893 2893 * Here is a sumary of the fields: ( M : must be set; m : may be set; 0 : ignored ) … … 2916 2916 * action : upon return, this tells the daemon what to do next. 2917 2917 * 2918 * DESCRIPTION: 2918 * DESCRIPTION: 2919 2919 * Called when a received message matchs the condition for which the callback was registered. 2920 2920 * This callback may do any kind of processing on the message, including: … … 2923 2923 * - update a routing table or start a connection with a new peer, then forward the message. 2924 2924 * - ... 2925 * 2925 * 2926 2926 * When *action == DISP_ACT_SEND on callback return, the msg pointed by *msg is passed to the routing module for sending. 2927 2927 * When *action == DISP_ACT_CONT, the next registered callback is called. … … 2946 2946 * when : Values that must match, depending on the how argument. 2947 2947 * 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. 2949 2949 * This handler can be used to unregister the cb. 2950 2950 * 2951 * DESCRIPTION: 2951 * DESCRIPTION: 2952 2952 * Register a new callback to handle messages delivered locally. 2953 2953 * … … 2957 2957 * ENOMEM : Not enough memory to complete the operation 2958 2958 */ 2959 int fd_disp_register ( int (*cb)( struct msg **, struct avp *, struct session *, void *, enum disp_action *), 2959 int fd_disp_register ( int (*cb)( struct msg **, struct avp *, struct session *, void *, enum disp_action *), 2960 2960 enum disp_how how, struct disp_when * when, void * opaque, struct disp_hdl ** handle ); 2961 2961 … … 2967 2967 * opaque : If not NULL, the opaque data that was registered is restored here. 2968 2968 * 2969 * DESCRIPTION: 2969 * DESCRIPTION: 2970 2970 * Removes a callback previously registered by fd_disp_register. 2971 2971 * … … 2990 2990 * drop_msg : if drop_reason is set, this points to the message to be freed while *msg is NULL. 2991 2991 * 2992 * DESCRIPTION: 2992 * DESCRIPTION: 2993 2993 * Call all handlers registered for a given message. 2994 2994 * The session must have already been resolved on entry. … … 3022 3022 * blocking operation. Use 0 to disable this maximum. 3023 3023 * 3024 * DESCRIPTION: 3024 * DESCRIPTION: 3025 3025 * Create a new empty queue. 3026 3026 * … … 3028 3028 * 0 : The queue has been initialized successfully. 3029 3029 * EINVAL : The parameter is invalid. 3030 * ENOMEM : Not enough memory to complete the creation. 3030 * ENOMEM : Not enough memory to complete the creation. 3031 3031 */ 3032 3032 int fd_fifo_new ( struct fifo ** queue, int max ); … … 3038 3038 * queue : Pointer to an empty queue to delete. 3039 3039 * 3040 * DESCRIPTION: 3040 * DESCRIPTION: 3041 3041 * Destroys a queue. This is only possible if no thread is waiting for an element, 3042 3042 * and the queue is empty. … … 3056 3056 * loc_update : if non NULL, a place to store the pointer to new FIFO atomically with the move. 3057 3057 * 3058 * DESCRIPTION: 3058 * DESCRIPTION: 3059 3059 * Empties a queue and move its content to another one atomically. 3060 3060 * … … 3077 3077 * blocking : Cumulated time threads trying to post new items were blocked (queue full). 3078 3078 * 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: 3081 3081 * Retrieve the timing information associated with a queue, for monitoring purpose. 3082 3082 * … … 3085 3085 * EINVAL : A parameter is invalid. 3086 3086 */ 3087 int fd_fifo_getstats( struct fifo * queue, int * current_count, int * limit_count, int * highest_count, long long * total_count, 3087 int fd_fifo_getstats( struct fifo * queue, int * current_count, int * limit_count, int * highest_count, long long * total_count, 3088 3088 struct timespec * total, struct timespec * blocking, struct timespec * last); 3089 3089 … … 3094 3094 * queue : The queue from which to retrieve the number of elements. 3095 3095 * 3096 * DESCRIPTION: 3096 * DESCRIPTION: 3097 3097 * Retrieve the number of elements in a queue, without error checking. 3098 3098 * … … 3113 3113 * l_cb : If the number of elements decrease to low, this callback is called. 3114 3114 * 3115 * DESCRIPTION: 3115 * DESCRIPTION: 3116 3116 * This function allows to adjust the number of producer / consumer threads of a queue. 3117 3117 * If the consumer are slower than the producers, the number of elements in the queue increase. … … 3142 3142 * item : The element that is put in the queue. 3143 3143 * 3144 * DESCRIPTION: 3144 * DESCRIPTION: 3145 3145 * An element is added in a queue. Elements are retrieved from the queue in FIFO order 3146 3146 * with the fd_fifo_get, fd_fifo_tryget, or fd_fifo_timedget functions. … … 3166 3166 * item : On return, the first element of the queue is stored here. 3167 3167 * 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 3171 3171 * function does not return). 3172 3172 * … … 3186 3186 * item : On return, the first element of the queue is stored here. 3187 3187 * 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 3190 3190 * the queue is empty, but return EWOULDBLOCK instead. 3191 3191 * … … 3207 3207 * abstime : the absolute time until which we allow waiting for an item. 3208 3208 * 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 3211 3211 * only until the absolute time abstime (see pthread_cond_timedwait for + info). 3212 3212 * If the queue is still empty when the time expires, the function returns ETIMEDOUT … … 3229 3229 * abstime : the absolute time until which we can block waiting for an item. If NULL, the function returns immediatly. 3230 3230 * 3231 * DESCRIPTION: 3231 * DESCRIPTION: 3232 3232 * This function is similar to select(), it waits for data to be available in the queue 3233 3233 * until the abstime is expired.
Note: See TracChangeset
for help on using the changeset viewer.