Mercurial > hg > freeDiameter
comparison include/freeDiameter/libfdproto.h @ 1392:497d926f5e3d
libfdproto.h: remove trailing whitespace
author | Thomas Klausner <tk@giga.or.at> |
---|---|
date | Fri, 15 Nov 2019 11:28:11 +0100 |
parents | 0c25bfa3660e |
children | 357e9cec520f |
comparison
equal
deleted
inserted
replaced
1391:a2e760b28cb6 | 1392:497d926f5e3d |
---|---|
136 * PARAMETERS: | 136 * PARAMETERS: |
137 * loglevel : Integer, how important the message is. Valid values are macros FD_LOG_* | 137 * loglevel : Integer, how important the message is. Valid values are macros FD_LOG_* |
138 * format : Same format string as in the printf function | 138 * format : Same format string as in the printf function |
139 * ... : Same list as printf | 139 * ... : Same list as printf |
140 * | 140 * |
141 * DESCRIPTION: | 141 * DESCRIPTION: |
142 * Write information to log. | 142 * Write information to log. |
143 * The format and arguments may contain UTF-8 encoded data. The | 143 * The format and arguments may contain UTF-8 encoded data. The |
144 * output medium is expected to support this encoding. | 144 * output medium is expected to support this encoding. |
145 * | 145 * |
146 * RETURN VALUE: | 146 * RETURN VALUE: |
149 void fd_log ( int, const char *, ... ) _ATTRIBUTE_PRINTFLIKE_(2,3); | 149 void fd_log ( int, const char *, ... ) _ATTRIBUTE_PRINTFLIKE_(2,3); |
150 #ifndef SWIG | 150 #ifndef SWIG |
151 void fd_log_va( int, const char *, va_list); | 151 void fd_log_va( int, const char *, va_list); |
152 #endif /* SWIG */ | 152 #endif /* SWIG */ |
153 | 153 |
154 /* these are internal objects of the debug facility, | 154 /* these are internal objects of the debug facility, |
155 might be useful to control the behavior from outside */ | 155 might be useful to control the behavior from outside */ |
156 extern pthread_mutex_t fd_log_lock; | 156 extern pthread_mutex_t fd_log_lock; |
157 extern char * fd_debug_one_function; | 157 extern char * fd_debug_one_function; |
158 extern char * fd_debug_one_file; | 158 extern char * fd_debug_one_file; |
159 | 159 |
161 * FUNCTION: fd_log_threadname | 161 * FUNCTION: fd_log_threadname |
162 * | 162 * |
163 * PARAMETERS: | 163 * PARAMETERS: |
164 * name : \0-terminated string containing a name to identify the current thread. | 164 * name : \0-terminated string containing a name to identify the current thread. |
165 * | 165 * |
166 * DESCRIPTION: | 166 * DESCRIPTION: |
167 * Name the current thread, useful for debugging multi-threaded problems. | 167 * Name the current thread, useful for debugging multi-threaded problems. |
168 * | 168 * |
169 * This function assumes that a global thread-specific key called "fd_log_thname" exists | 169 * This function assumes that a global thread-specific key called "fd_log_thname" exists |
170 * in the address space of the current process. | 170 * in the address space of the current process. |
171 * | 171 * |
183 * buf : An array where the time must be stored | 183 * buf : An array where the time must be stored |
184 * len : size of the buffer | 184 * len : size of the buffer |
185 * incl_date : The day of year is included in the output | 185 * incl_date : The day of year is included in the output |
186 * incl_ms : millisecond value is included in the output | 186 * incl_ms : millisecond value is included in the output |
187 * | 187 * |
188 * DESCRIPTION: | 188 * DESCRIPTION: |
189 * Writes the timestamp (in human readable format) in a buffer. | 189 * Writes the timestamp (in human readable format) in a buffer. |
190 * | 190 * |
191 * RETURN VALUE: | 191 * RETURN VALUE: |
192 * pointer to buf. | 192 * pointer to buf. |
193 */ | 193 */ |
194 char * fd_log_time ( struct timespec * ts, char * buf, size_t len, int incl_date, int incl_ms ); | 194 char * fd_log_time ( struct timespec * ts, char * buf, size_t len, int incl_date, int incl_ms ); |
243 | 243 |
244 #ifdef SWIG | 244 #ifdef SWIG |
245 #define DECLARE_FD_DUMP_PROTOTYPE_simple( function_name ) \ | 245 #define DECLARE_FD_DUMP_PROTOTYPE_simple( function_name ) \ |
246 char * function_name(char ** buf, size_t *len, size_t *offset) | 246 char * function_name(char ** buf, size_t *len, size_t *offset) |
247 #endif /* SWIG */ | 247 #endif /* SWIG */ |
248 | 248 |
249 | 249 |
250 /* Helper functions for the *dump functions that add into a buffer */ | 250 /* Helper functions for the *dump functions that add into a buffer */ |
251 DECLARE_FD_DUMP_PROTOTYPE( fd_dump_extend, const char * format, ... ) _ATTRIBUTE_PRINTFLIKE_(4,5); | 251 DECLARE_FD_DUMP_PROTOTYPE( fd_dump_extend, const char * format, ... ) _ATTRIBUTE_PRINTFLIKE_(4,5); |
252 DECLARE_FD_DUMP_PROTOTYPE( fd_dump_extend_hexdump, uint8_t *data, size_t datalen, size_t trunc, size_t wrap ); | 252 DECLARE_FD_DUMP_PROTOTYPE( fd_dump_extend_hexdump, uint8_t *data, size_t datalen, size_t trunc, size_t wrap ); |
253 | 253 |
310 *************************/ | 310 *************************/ |
311 #define LOG(printlevel,format,args... ) \ | 311 #define LOG(printlevel,format,args... ) \ |
312 fd_log((printlevel), STD_TRACE_FMT_STRING format STD_TRACE_FMT_ARGS, ## args) | 312 fd_log((printlevel), STD_TRACE_FMT_STRING format STD_TRACE_FMT_ARGS, ## args) |
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 #ifdef DEBUG | 317 #ifdef DEBUG |
318 # define LOG_A(format,args... ) \ | 318 # define LOG_A(format,args... ) \ |
319 do { if ((fd_debug_one_function && !strcmp(fd_debug_one_function, __PRETTY_FUNCTION__)) \ | 319 do { if ((fd_debug_one_function && !strcmp(fd_debug_one_function, __PRETTY_FUNCTION__)) \ |
320 || (fd_debug_one_file && !strcmp(fd_debug_one_file, __STRIPPED_FILE__) ) ) { \ | 320 || (fd_debug_one_file && !strcmp(fd_debug_one_file, __STRIPPED_FILE__) ) ) { \ |
400 /* Macros to check a return value and branch out in case of error. | 400 /* Macros to check a return value and branch out in case of error. |
401 * These macro additionally provide the logging information. | 401 * These macro additionally provide the logging information. |
402 * | 402 * |
403 * The name "__ret__" is always available in the __fallback__ parameter and contains the error code. | 403 * The name "__ret__" is always available in the __fallback__ parameter and contains the error code. |
404 */ | 404 */ |
405 | 405 |
406 #define CHECK_PRELUDE(__call__) \ | 406 #define CHECK_PRELUDE(__call__) \ |
407 int __ret__; \ | 407 int __ret__; \ |
408 TRACE_CALL("Check: %s", #__call__ ); \ | 408 TRACE_CALL("Check: %s", #__call__ ); \ |
409 __ret__ = (__call__) | 409 __ret__ = (__call__) |
410 | 410 |
411 #define DEFAULT_FB return __ret__; | 411 #define DEFAULT_FB return __ret__; |
412 | 412 |
413 /* System check: error case if < 0, error value in errno */ | 413 /* System check: error case if < 0, error value in errno */ |
414 #define CHECK_SYS_GEN( faillevel, __call__, __fallback__ ) { \ | 414 #define CHECK_SYS_GEN( faillevel, __call__, __fallback__ ) { \ |
415 CHECK_PRELUDE(__call__); \ | 415 CHECK_PRELUDE(__call__); \ |
489 } | 489 } |
490 #define TRACE_BOOL(level) old_TRACE_BOOL((level), __STRIPPED_FILE__, __PRETTY_FUNCTION__) | 490 #define TRACE_BOOL(level) old_TRACE_BOOL((level), __STRIPPED_FILE__, __PRETTY_FUNCTION__) |
491 | 491 |
492 #ifndef SWIG | 492 #ifndef SWIG |
493 static __inline__ void fd_log_deprecated( int level, const char *format, ... ) MARK_DEPRECATED | 493 static __inline__ void fd_log_deprecated( int level, const char *format, ... ) MARK_DEPRECATED |
494 { | 494 { |
495 va_list ap; | 495 va_list ap; |
496 va_start(ap, format); | 496 va_start(ap, format); |
497 fd_log_va(level, format, ap); | 497 fd_log_va(level, format, ap); |
498 va_end(ap); | 498 va_end(ap); |
499 } | 499 } |
555 # define CHECK_POSIX_DO( __call__, __fallback__ ) \ | 555 # define CHECK_POSIX_DO( __call__, __fallback__ ) \ |
556 CHECK_POSIX_DO2( (__call__), 0, , __fallback__ ) | 556 CHECK_POSIX_DO2( (__call__), 0, , __fallback__ ) |
557 | 557 |
558 # define CHECK_POSIX( __call__ ) \ | 558 # define CHECK_POSIX( __call__ ) \ |
559 CHECK_POSIX_DO( (__call__), return __ret__ ) | 559 CHECK_POSIX_DO( (__call__), return __ret__ ) |
560 | 560 |
561 # define CHECK_MALLOC_DO( __call__, __fallback__ ) { \ | 561 # define CHECK_MALLOC_DO( __call__, __fallback__ ) { \ |
562 void * __ptr__; \ | 562 void * __ptr__; \ |
563 TRACE_CALL("Check: %s", #__call__ ); \ | 563 TRACE_CALL("Check: %s", #__call__ ); \ |
564 __ptr__ = (void *)(__call__); \ | 564 __ptr__ = (void *)(__call__); \ |
565 if (__ptr__ == NULL) { \ | 565 if (__ptr__ == NULL) { \ |
569 } \ | 569 } \ |
570 } | 570 } |
571 | 571 |
572 # define CHECK_MALLOC( __call__ ) \ | 572 # define CHECK_MALLOC( __call__ ) \ |
573 CHECK_MALLOC_DO( (__call__), return __ret__ ) | 573 CHECK_MALLOC_DO( (__call__), return __ret__ ) |
574 | 574 |
575 # define CHECK_PARAMS_DO( __bool__, __fallback__ ) { \ | 575 # define CHECK_PARAMS_DO( __bool__, __fallback__ ) { \ |
576 TRACE_CALL("Check: %s", #__bool__ ); \ | 576 TRACE_CALL("Check: %s", #__bool__ ); \ |
577 if ( ! (__bool__) ) { \ | 577 if ( ! (__bool__) ) { \ |
578 int __ret__ = EINVAL; \ | 578 int __ret__ = EINVAL; \ |
579 TRACE_ERROR("ERROR: Invalid parameter '%s', %d", #__bool__, __ret__ ); \ | 579 TRACE_ERROR("ERROR: Invalid parameter '%s', %d", #__bool__, __ret__ ); \ |
586 | 586 |
587 # define CHECK_FCT_DO CHECK_POSIX_DO | 587 # define CHECK_FCT_DO CHECK_POSIX_DO |
588 # define CHECK_FCT CHECK_POSIX | 588 # define CHECK_FCT CHECK_POSIX |
589 | 589 |
590 #endif /* EXCLUDE_DEPRECATED */ | 590 #endif /* EXCLUDE_DEPRECATED */ |
591 | 591 |
592 | 592 |
593 /*============================================================*/ | 593 /*============================================================*/ |
594 /* Optimized code: remove all debugging code */ | 594 /* Optimized code: remove all debugging code */ |
595 /*============================================================*/ | 595 /*============================================================*/ |
596 #ifdef STRIP_DEBUG_CODE | 596 #ifdef STRIP_DEBUG_CODE |
658 (((_proto) == IPPROTO_SCTP) ? "SCTP" : \ | 658 (((_proto) == IPPROTO_SCTP) ? "SCTP" : \ |
659 "Unknown")) | 659 "Unknown")) |
660 #endif /* DISABLE_SCTP */ | 660 #endif /* DISABLE_SCTP */ |
661 | 661 |
662 /* Define the value of IP loopback address */ | 662 /* Define the value of IP loopback address */ |
663 #ifndef INADDR_LOOPBACK | 663 #ifndef INADDR_LOOPBACK |
664 #define INADDR_LOOPBACK inet_addr("127.0.0.1") | 664 #define INADDR_LOOPBACK inet_addr("127.0.0.1") |
665 #endif /* INADDR_LOOPBACK */ | 665 #endif /* INADDR_LOOPBACK */ |
666 | 666 |
667 #ifndef INADDR_BROADCAST | 667 #ifndef INADDR_BROADCAST |
668 #define INADDR_BROADCAST ((in_addr_t) 0xffffffff) | 668 #define INADDR_BROADCAST ((in_addr_t) 0xffffffff) |
699 /* In big-endian systems, we don't have to change the values, since the order is the same as network */ | 699 /* In big-endian systems, we don't have to change the values, since the order is the same as network */ |
700 # define ntohll(x) (x) | 700 # define ntohll(x) (x) |
701 # define htonll(x) (x) | 701 # define htonll(x) (x) |
702 # else /* HOST_BIG_ENDIAN */ | 702 # else /* HOST_BIG_ENDIAN */ |
703 /* For these systems, we must reverse the bytes. Use ntohl and htonl on sub-32 blocs, and inverse these blocs. */ | 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 ))) | 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 ))) | 705 # define htonll(x) (typeof (x))( (((uint64_t)htonl( (uint32_t)(x))) << 32 ) | ((uint64_t) htonl( ((uint64_t)(x)) >> 32 ))) |
706 # endif /* HOST_BIG_ENDIAN */ | 706 # endif /* HOST_BIG_ENDIAN */ |
707 #endif /* HAVE_NTOHLL */ | 707 #endif /* HAVE_NTOHLL */ |
708 | 708 |
709 /* This macro will give the next multiple of 4 for an integer (used for padding sizes of AVP). */ | 709 /* This macro will give the next multiple of 4 for an integer (used for padding sizes of AVP). */ |
710 #define PAD4(_x) ((_x) + ( (4 - (_x)) & 3 ) ) | 710 #define PAD4(_x) ((_x) + ( (4 - (_x)) & 3 ) ) |
724 (tsdiff)->tv_nsec = (tsend)->tv_nsec + 1000000000 - (tsstart)->tv_nsec; \ | 724 (tsdiff)->tv_nsec = (tsend)->tv_nsec + 1000000000 - (tsstart)->tv_nsec; \ |
725 } else { \ | 725 } else { \ |
726 (tsdiff)->tv_sec = (tsend)->tv_sec - (tsstart)->tv_sec; \ | 726 (tsdiff)->tv_sec = (tsend)->tv_sec - (tsstart)->tv_sec; \ |
727 (tsdiff)->tv_nsec = (tsend)->tv_nsec - (tsstart)->tv_nsec; \ | 727 (tsdiff)->tv_nsec = (tsend)->tv_nsec - (tsstart)->tv_nsec; \ |
728 }} | 728 }} |
729 | 729 |
730 | 730 |
731 /* This gives a good size for buffered reads */ | 731 /* This gives a good size for buffered reads */ |
732 #ifndef BUFSIZ | 732 #ifndef BUFSIZ |
733 #define BUFSIZ 96 | 733 #define BUFSIZ 96 |
734 #endif /* BUFSIZ */ | 734 #endif /* BUFSIZ */ |
753 | 753 |
754 /*============================================================*/ | 754 /*============================================================*/ |
755 /* BINARY STRINGS */ | 755 /* BINARY STRINGS */ |
756 /*============================================================*/ | 756 /*============================================================*/ |
757 | 757 |
758 /* Compute a hash value of a binary string. | 758 /* Compute a hash value of a binary string. |
759 The hash must remain local to this machine, there is no guarantee that same input | 759 The hash must remain local to this machine, there is no guarantee that same input |
760 will give same output on a different system (endianness) */ | 760 will give same output on a different system (endianness) */ |
761 uint32_t fd_os_hash ( uint8_t * string, size_t len ); | 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 It means some string operations can be used on it. */ | 764 It means some string operations can be used on it. */ |
765 typedef uint8_t * os0_t; | 765 typedef uint8_t * os0_t; |
766 | 766 |
767 /* Same as strdup but for os0_t strings */ | 767 /* Same as strdup but for os0_t strings */ |
768 os0_t os0dup_int(os0_t s, size_t l); | 768 os0_t os0dup_int(os0_t s, size_t l); |
784 | 784 |
785 /* Check if a binary string contains a valid Diameter Identity value. | 785 /* Check if a binary string contains a valid Diameter Identity value. |
786 rfc3588 states explicitely that such a Diameter Identity consists only of ASCII characters. */ | 786 rfc3588 states explicitely that such a Diameter Identity consists only of ASCII characters. */ |
787 int fd_os_is_valid_DiameterIdentity(uint8_t * os, size_t ossz); | 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 if *inoutsz is != 0 on entry, *id may not be \0-terminated. | 790 if *inoutsz is != 0 on entry, *id may not be \0-terminated. |
791 memory has the following meaning: 0: *id can be realloc'd. 1: *id must be malloc'd on output (was static) | 791 memory has the following meaning: 0: *id can be realloc'd. 1: *id must be malloc'd on output (was static) |
792 */ | 792 */ |
793 int fd_os_validate_DiameterIdentity(char ** id, size_t * inoutsz, int memory); | 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 It does NOT mimic strings relationships so that it is more efficient. It is case sensitive. | 796 It does NOT mimic strings relationships so that it is more efficient. It is case sensitive. |
797 (the strings are actually first ordered by their lengh, then by their bytes contents) | 797 (the strings are actually first ordered by their lengh, then by their bytes contents) |
798 returns: -1 if os1 < os2; +1 if os1 > os2; 0 if they are equal */ | 798 returns: -1 if os1 < os2; +1 if os1 > os2; 0 if they are equal */ |
799 int fd_os_cmp_int(os0_t os1, size_t os1sz, os0_t os2, size_t os2sz); | 799 int fd_os_cmp_int(os0_t os1, size_t os1sz, os0_t os2, size_t os2sz); |
800 #define fd_os_cmp(_o1, _l1, _o2, _l2) fd_os_cmp_int((os0_t)(_o1), _l1, (os0_t)(_o2), _l2) | 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 -- it does not support locales where a lowercase letter uses more space than upper case, such as ß -> ss | 803 -- it does not support locales where a lowercase letter uses more space than upper case, such as ß -> ss |
804 It is slower than fd_os_cmp. | 804 It is slower than fd_os_cmp. |
805 Note that the result is NOT the same as strcasecmp !!! | 805 Note that the result is NOT the same as strcasecmp !!! |
806 | 806 |
807 This function gives the same order as fd_os_cmp, except when it finds 2 strings to be equal. | 807 This function gives the same order as fd_os_cmp, except when it finds 2 strings to be equal. |
808 However this is not always sufficient: | 808 However this is not always sufficient: |
809 for example fd_os_cmp gives: "Ac" < "aB" < "aa" | 809 for example fd_os_cmp gives: "Ac" < "aB" < "aa" |
810 if you attempt to fd_os_almostcasesrch "Aa" you will actually have to go past "aB" which is > "Aa". | 810 if you attempt to fd_os_almostcasesrch "Aa" you will actually have to go past "aB" which is > "Aa". |
811 Therefore you can use the maybefurther parameter. | 811 Therefore you can use the maybefurther parameter. |
814 When looping through a list of fd_os_cmp classified values, this parameter must be used to stop looping, in addition to the comp result. | 814 When looping through a list of fd_os_cmp classified values, this parameter must be used to stop looping, in addition to the comp result. |
815 */ | 815 */ |
816 int fd_os_almostcasesrch_int(uint8_t * os1, size_t os1sz, uint8_t * os2, size_t os2sz, int * maybefurther); | 816 int fd_os_almostcasesrch_int(uint8_t * os1, size_t os1sz, uint8_t * os2, size_t os2sz, int * maybefurther); |
817 #define fd_os_almostcasesrch(_o1, _l1, _o2, _l2, _mb) fd_os_almostcasesrch_int((os0_t)(_o1), _l1, (os0_t)(_o2), _l2, _mb) | 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. | 819 /* Analyze a DiameterURI and return its components. |
820 Return EINVAL if the URI is not valid. | 820 Return EINVAL if the URI is not valid. |
821 *diamid is malloc'd on function return and must be freed (it is processed by fd_os_validate_DiameterIdentity). | 821 *diamid is malloc'd on function return and must be freed (it is processed by fd_os_validate_DiameterIdentity). |
822 *secure is 0 (no security) or 1 (security enabled) on return. | 822 *secure is 0 (no security) or 1 (security enabled) on return. |
823 *port is 0 (default) or a value in host byte order on return. | 823 *port is 0 (default) or a value in host byte order on return. |
824 *transport is 0 (default) or IPPROTO_* on return. | 824 *transport is 0 (default) or IPPROTO_* on return. |
825 *proto is 0 (default) or 'd' (diameter), 'r' (radius), or 't' (tacacs+) on return. | 825 *proto is 0 (default) or 'd' (diameter), 'r' (radius), or 't' (tacacs+) on return. |
832 | 832 |
833 /* Terminate a thread */ | 833 /* Terminate a thread */ |
834 static __inline__ int fd_thr_term(pthread_t * th) | 834 static __inline__ int fd_thr_term(pthread_t * th) |
835 { | 835 { |
836 void * th_ret = NULL; | 836 void * th_ret = NULL; |
837 | 837 |
838 CHECK_PARAMS(th); | 838 CHECK_PARAMS(th); |
839 | 839 |
840 /* Test if it was already terminated */ | 840 /* Test if it was already terminated */ |
841 if (*th == (pthread_t)NULL) | 841 if (*th == (pthread_t)NULL) |
842 return 0; | 842 return 0; |
843 | 843 |
844 /* Cancel the thread if it is still running - ignore error if it was already terminated */ | 844 /* Cancel the thread if it is still running - ignore error if it was already terminated */ |
845 (void) pthread_cancel(*th); | 845 (void) pthread_cancel(*th); |
846 | 846 |
847 /* Then join the thread */ | 847 /* Then join the thread */ |
848 CHECK_POSIX( pthread_join(*th, &th_ret) ); | 848 CHECK_POSIX( pthread_join(*th, &th_ret) ); |
849 | 849 |
850 if (th_ret == PTHREAD_CANCELED) { | 850 if (th_ret == PTHREAD_CANCELED) { |
851 TRACE_DEBUG(ANNOYING, "The thread %p was canceled", (void *)*th); | 851 TRACE_DEBUG(ANNOYING, "The thread %p was canceled", (void *)*th); |
852 } else { | 852 } else { |
853 TRACE_DEBUG(CALL, "The thread %p returned %p", (void *)*th, th_ret); | 853 TRACE_DEBUG(CALL, "The thread %p returned %p", (void *)*th, th_ret); |
854 } | 854 } |
855 | 855 |
856 /* Clean the location */ | 856 /* Clean the location */ |
857 *th = (pthread_t)NULL; | 857 *th = (pthread_t)NULL; |
858 | 858 |
859 return 0; | 859 return 0; |
860 } | 860 } |
861 | 861 |
862 | 862 |
863 /************* | 863 /************* |
864 Cancelation cleanup handlers for common objects | 864 Cancelation cleanup handlers for common objects |
865 *************/ | 865 *************/ |
866 static __inline__ void fd_cleanup_mutex( void * mutex ) | 866 static __inline__ void fd_cleanup_mutex( void * mutex ) |
867 { | 867 { |
868 CHECK_POSIX_DO( pthread_mutex_unlock((pthread_mutex_t *)mutex), /* */); | 868 CHECK_POSIX_DO( pthread_mutex_unlock((pthread_mutex_t *)mutex), /* */); |
869 } | 869 } |
870 | 870 |
871 static __inline__ void fd_cleanup_rwlock( void * rwlock ) | 871 static __inline__ void fd_cleanup_rwlock( void * rwlock ) |
872 { | 872 { |
873 CHECK_POSIX_DO( pthread_rwlock_unlock((pthread_rwlock_t *)rwlock), /* */); | 873 CHECK_POSIX_DO( pthread_rwlock_unlock((pthread_rwlock_t *)rwlock), /* */); |
874 } | 874 } |
875 | 875 |
943 DICT_AVP, /* AVP */ | 943 DICT_AVP, /* AVP */ |
944 DICT_COMMAND, /* Diameter Command */ | 944 DICT_COMMAND, /* Diameter Command */ |
945 DICT_RULE /* a Rule for AVP in command or grouped AVP */ | 945 DICT_RULE /* a Rule for AVP in command or grouped AVP */ |
946 #define DICT_TYPE_MAX DICT_RULE | 946 #define DICT_TYPE_MAX DICT_RULE |
947 }; | 947 }; |
948 | 948 |
949 /* Initialize a dictionary */ | 949 /* Initialize a dictionary */ |
950 int fd_dict_init(struct dictionary ** dict); | 950 int fd_dict_init(struct dictionary ** dict); |
951 /* Destroy a dictionary */ | 951 /* Destroy a dictionary */ |
952 int fd_dict_fini(struct dictionary ** dict); | 952 int fd_dict_fini(struct dictionary ** dict); |
953 | 953 |
955 * FUNCTION: fd_dict_new | 955 * FUNCTION: fd_dict_new |
956 * | 956 * |
957 * PARAMETERS: | 957 * PARAMETERS: |
958 * dict : Pointer to the dictionnary where the object is created | 958 * dict : Pointer to the dictionnary where the object is created |
959 * type : What kind of object must be created | 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 * type parameter is used to determine the type of data (see below for detail). | 961 * type parameter is used to determine the type of data (see below for detail). |
962 * parent : a reference to a parent object, if needed. | 962 * parent : a reference to a parent object, if needed. |
963 * ref : upon successful creation, reference to new object is stored here if !null. | 963 * ref : upon successful creation, reference to new object is stored here if !null. |
964 * | 964 * |
965 * DESCRIPTION: | 965 * DESCRIPTION: |
966 * Create a new object in the dictionary. | 966 * Create a new object in the dictionary. |
967 * See following object sections in this header file for more information on data and parent parameters format. | 967 * See following object sections in this header file for more information on data and parent parameters format. |
968 * | 968 * |
969 * RETURN VALUE: | 969 * RETURN VALUE: |
970 * 0 : The object is created in the dictionary. | 970 * 0 : The object is created in the dictionary. |
971 * EINVAL : A parameter is invalid. | 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 * If "ref" is not NULL, it points to the existing element on return. | 973 * If "ref" is not NULL, it points to the existing element on return. |
974 * (other standard errors may be returned, too, with their standard meaning. Example: | 974 * (other standard errors may be returned, too, with their standard meaning. Example: |
975 * ENOMEM : Memory allocation for the new object element failed.) | 975 * ENOMEM : Memory allocation for the new object element failed.) |
976 */ | 976 */ |
977 int fd_dict_new ( struct dictionary * dict, enum dict_object_type type, void * data, struct dict_object * parent, struct dict_object ** ref ); | 977 int fd_dict_new ( struct dictionary * dict, enum dict_object_type type, void * data, struct dict_object * parent, struct dict_object ** ref ); |
985 * criteria : how the object must be searched. See object-related sections below for more information. | 985 * criteria : how the object must be searched. See object-related sections below for more information. |
986 * what : depending on criteria, the data that must be searched. | 986 * what : depending on criteria, the data that must be searched. |
987 * result : On successful return, pointer to the object is stored here. | 987 * result : On successful return, pointer to the object is stored here. |
988 * retval : this value is returned if the object is not found and result is not NULL. | 988 * retval : this value is returned if the object is not found and result is not NULL. |
989 * | 989 * |
990 * DESCRIPTION: | 990 * DESCRIPTION: |
991 * Perform a search in the dictionary. | 991 * Perform a search in the dictionary. |
992 * See the object-specific sections below to find how to look for each objects. | 992 * See the object-specific sections below to find how to look for each objects. |
993 * If the "result" parameter is NULL, the function is used to check if an object is in the dictionary. | 993 * If the "result" parameter is NULL, the function is used to check if an object is in the dictionary. |
994 * Otherwise, a reference to the object is stored in result if found. | 994 * Otherwise, a reference to the object is stored in result if found. |
995 * If result is not NULL and the object is not found, retval is returned (should be 0 or ENOENT usually) | 995 * If result is not NULL and the object is not found, retval is returned (should be 0 or ENOENT usually) |
996 * | 996 * |
1010 * PARAMETERS: | 1010 * PARAMETERS: |
1011 * object : Pointer to a dictionary object. | 1011 * object : Pointer to a dictionary object. |
1012 * data : pointer to a structure to hold the data for the object. | 1012 * data : pointer to a structure to hold the data for the object. |
1013 * The type is the same as "data" parameter in fd_dict_new function. | 1013 * The type is the same as "data" parameter in fd_dict_new function. |
1014 * | 1014 * |
1015 * DESCRIPTION: | 1015 * DESCRIPTION: |
1016 * Retrieve content of a dictionary object. | 1016 * Retrieve content of a dictionary object. |
1017 * See following object sections in this header file for more information on data and parent parameters format. | 1017 * See following object sections in this header file for more information on data and parent parameters format. |
1018 * | 1018 * |
1019 * RETURN VALUE: | 1019 * RETURN VALUE: |
1020 * 0 : The content of the object has been retrieved. | 1020 * 0 : The content of the object has been retrieved. |
1037 int fd_dict_delete(struct dict_object * obj); | 1037 int fd_dict_delete(struct dict_object * obj); |
1038 | 1038 |
1039 /* | 1039 /* |
1040 *************************************************************************** | 1040 *************************************************************************** |
1041 * | 1041 * |
1042 * Vendor object | 1042 * Vendor object |
1043 * | 1043 * |
1044 * These types are used to manage vendors in the dictionary | 1044 * These types are used to manage vendors in the dictionary |
1045 * | 1045 * |
1046 *************************************************************************** | 1046 *************************************************************************** |
1047 */ | 1047 */ |
1067 * API usage : | 1067 * API usage : |
1068 | 1068 |
1069 Note: the value of "vendor_name" is copied when the object is created, and the string may be disposed afterwards. | 1069 Note: the value of "vendor_name" is copied when the object is created, and the string may be disposed afterwards. |
1070 On the other side, when value is retrieved with dict_getval, the string is not copied and MUST NOT be freed. It will | 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 be freed automatically along with the object itself with call to dict_fini later. | 1071 be freed automatically along with the object itself with call to dict_fini later. |
1072 | 1072 |
1073 - fd_dict_new: | 1073 - fd_dict_new: |
1074 The "parent" parameter is not used for vendors. | 1074 The "parent" parameter is not used for vendors. |
1075 Sample code to create a vendor: | 1075 Sample code to create a vendor: |
1076 { | 1076 { |
1077 int ret; | 1077 int ret; |
1078 struct dict_object * myvendor; | 1078 struct dict_object * myvendor; |
1079 struct dict_vendor_data myvendordata = { 23455, "my vendor name" }; -- just an example... | 1079 struct dict_vendor_data myvendordata = { 23455, "my vendor name" }; -- just an example... |
1088 vendor_id_t vendorid = 23455; | 1088 vendor_id_t vendorid = 23455; |
1089 ret = fd_dict_search ( dict, DICT_VENDOR, VENDOR_BY_ID, &vendorid, &vendor_found, ENOENT); | 1089 ret = fd_dict_search ( dict, DICT_VENDOR, VENDOR_BY_ID, &vendorid, &vendor_found, ENOENT); |
1090 - or - | 1090 - or - |
1091 ret = fd_dict_search ( dict, DICT_VENDOR, VENDOR_BY_NAME, "my vendor name", &vendor_found, ENOENT); | 1091 ret = fd_dict_search ( dict, DICT_VENDOR, VENDOR_BY_NAME, "my vendor name", &vendor_found, ENOENT); |
1092 } | 1092 } |
1093 | 1093 |
1094 - fd_dict_getval: | 1094 - fd_dict_getval: |
1095 Sample code to retrieve the data from a vendor object: | 1095 Sample code to retrieve the data from a vendor object: |
1096 { | 1096 { |
1097 int ret; | 1097 int ret; |
1098 struct dict_object * myvendor; | 1098 struct dict_object * myvendor; |
1099 struct dict_vendor_data myvendordata; | 1099 struct dict_vendor_data myvendordata; |
1100 ret = fd_dict_search ( dict, DICT_VENDOR, VENDOR_BY_NAME, "my vendor name", &myvendor, ENOENT); | 1100 ret = fd_dict_search ( dict, DICT_VENDOR, VENDOR_BY_NAME, "my vendor name", &myvendor, ENOENT); |
1101 ret = fd_dict_getval ( myvendor, &myvendordata ); | 1101 ret = fd_dict_getval ( myvendor, &myvendordata ); |
1102 printf("my vendor id: %d\n", myvendordata.vendor_id ); | 1102 printf("my vendor id: %d\n", myvendordata.vendor_id ); |
1103 } | 1103 } |
1104 | 1104 |
1105 */ | 1105 */ |
1106 | 1106 |
1107 /* Special function: */ | 1107 /* Special function: */ |
1108 uint32_t * fd_dict_get_vendorid_list(struct dictionary * dict); | 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 * These types are used to manage Diameter applications in the dictionary | 1115 * These types are used to manage Diameter applications in the dictionary |
1116 * | 1116 * |
1117 *************************************************************************** | 1117 *************************************************************************** |
1118 */ | 1118 */ |
1153 }; | 1153 }; |
1154 struct dict_application_data app_data = { | 1154 struct dict_application_data app_data = { |
1155 9789, | 1155 9789, |
1156 "my vendor's application" | 1156 "my vendor's application" |
1157 }; | 1157 }; |
1158 | 1158 |
1159 ret = fd_dict_new ( dict, DICT_VENDOR, &vendor_data, NULL, &vendor ); | 1159 ret = fd_dict_new ( dict, DICT_VENDOR, &vendor_data, NULL, &vendor ); |
1160 ret = fd_dict_new ( dict, DICT_APPLICATION, &app_data, vendor, &appl ); | 1160 ret = fd_dict_new ( dict, DICT_APPLICATION, &app_data, vendor, &appl ); |
1161 } | 1161 } |
1162 | 1162 |
1163 - fd_dict_search: | 1163 - fd_dict_search: |
1164 Sample code to retrieve the vendor of an application | 1164 Sample code to retrieve the vendor of an application |
1165 { | 1165 { |
1166 int ret; | 1166 int ret; |
1167 struct dict_object * vendor, * appli; | 1167 struct dict_object * vendor, * appli; |
1168 | 1168 |
1169 ret = fd_dict_search ( dict, DICT_APPLICATION, APPLICATION_BY_NAME, "my vendor's application", &appli, ENOENT); | 1169 ret = fd_dict_search ( dict, DICT_APPLICATION, APPLICATION_BY_NAME, "my vendor's application", &appli, ENOENT); |
1170 ret = fd_dict_search ( dict, DICT_VENDOR, VENDOR_OF_APPLICATION, appli, &vendor, ENOENT); | 1170 ret = fd_dict_search ( dict, DICT_VENDOR, VENDOR_OF_APPLICATION, appli, &vendor, ENOENT); |
1171 } | 1171 } |
1172 | 1172 |
1173 - fd_dict_getval: | 1173 - fd_dict_getval: |
1174 Sample code to retrieve the data from an application object: | 1174 Sample code to retrieve the data from an application object: |
1175 { | 1175 { |
1176 int ret; | 1176 int ret; |
1177 struct dict_object * appli; | 1177 struct dict_object * appli; |
1184 */ | 1184 */ |
1185 | 1185 |
1186 /* | 1186 /* |
1187 *************************************************************************** | 1187 *************************************************************************** |
1188 * | 1188 * |
1189 * Type object | 1189 * Type object |
1190 * | 1190 * |
1191 * These types are used to manage AVP data types in the dictionary | 1191 * These types are used to manage AVP data types in the dictionary |
1192 * | 1192 * |
1193 *************************************************************************** | 1193 *************************************************************************** |
1194 */ | 1194 */ |
1195 | 1195 |
1196 /* Type to store any AVP value */ | 1196 /* Type to store any AVP value */ |
1197 union avp_value { | 1197 union avp_value { |
1198 struct { | 1198 struct { |
1199 uint8_t *data; /* bytes buffer */ | 1199 uint8_t *data; /* bytes buffer */ |
1200 size_t len; /* length of the data buffer */ | 1200 size_t len; /* length of the data buffer */ |
1201 } os; /* Storage for an octet string */ | 1201 } os; /* Storage for an octet string */ |
1226 * | 1226 * |
1227 * PARAMETERS: | 1227 * PARAMETERS: |
1228 * val : Pointer to the AVP value that must be interpreted. | 1228 * val : Pointer to the AVP value that must be interpreted. |
1229 * interpreted : The result of interpretation is stored here. The format and meaning depends on each type. | 1229 * interpreted : The result of interpretation is stored here. The format and meaning depends on each type. |
1230 * | 1230 * |
1231 * DESCRIPTION: | 1231 * DESCRIPTION: |
1232 * This callback can be provided with a derived type in order to facilitate the interpretation of formated data. | 1232 * This callback can be provided with a derived type in order to facilitate the interpretation of formated data. |
1233 * For example, when an AVP of type "Address" is received, it can be used to convert the octetstring into a struct sockaddr. | 1233 * For example, when an AVP of type "Address" is received, it can be used to convert the octetstring into a struct sockaddr. |
1234 * This callback is not called directly, but through the message's API msg_avp_value_interpret function. | 1234 * This callback is not called directly, but through the message's API msg_avp_value_interpret function. |
1235 * | 1235 * |
1236 * RETURN VALUE: | 1236 * RETURN VALUE: |
1243 * | 1243 * |
1244 * PARAMETERS: | 1244 * PARAMETERS: |
1245 * data : The formated data that must be stored in the AVP value. | 1245 * data : The formated data that must be stored in the AVP value. |
1246 * val : Pointer to the AVP value storage area where the data must be stored. | 1246 * val : Pointer to the AVP value storage area where the data must be stored. |
1247 * | 1247 * |
1248 * DESCRIPTION: | 1248 * DESCRIPTION: |
1249 * This callback can be provided with a derived type in order to facilitate the encoding of formated data. | 1249 * This callback can be provided with a derived type in order to facilitate the encoding of formated data. |
1250 * For example, it can be used to convert a struct sockaddr in an AVP value of type Address. | 1250 * For example, it can be used to convert a struct sockaddr in an AVP value of type Address. |
1251 * This callback is not called directly, but through the message's API msg_avp_value_encode function. | 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 * automatically later. | 1253 * automatically later. |
1254 * | 1254 * |
1255 * RETURN VALUE: | 1255 * RETURN VALUE: |
1256 * 0 : Operation complete. | 1256 * 0 : Operation complete. |
1257 * !0 : An error occurred, the error code is returned. | 1257 * !0 : An error occurred, the error code is returned. |
1262 * CALLBACK: dict_avpdata_check | 1262 * CALLBACK: dict_avpdata_check |
1263 * | 1263 * |
1264 * PARAMETERS: | 1264 * PARAMETERS: |
1265 * val : Pointer to the AVP value that was received and needs to be sanity checked. | 1265 * val : Pointer to the AVP value that was received and needs to be sanity checked. |
1266 * data : a parameter stored in the type structure (to enable more generic check functions) | 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. | 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 * | 1268 * |
1269 * DESCRIPTION: | 1269 * DESCRIPTION: |
1270 * This callback can be provided with a derived type in order to improve the operation of the | 1270 * This callback can be provided with a derived type in order to improve the operation of the |
1271 * fd_msg_parse_dict function. When this callback is present, the value of the AVP that has | 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 * speccific AVP, the format of an OCTETSTRING value can be further checked, or the | 1273 * speccific AVP, the format of an OCTETSTRING value can be further checked, or the |
1274 * interger value can be verified. | 1274 * interger value can be verified. |
1275 * | 1275 * |
1276 * RETURN VALUE: | 1276 * RETURN VALUE: |
1277 * 0 : The value is valid. | 1277 * 0 : The value is valid. |
1298 TYPE_OF_ENUMVAL, /* "what" points to a struct dict_object containing an enumerated constant (DICT_ENUMVAL, see below). */ | 1298 TYPE_OF_ENUMVAL, /* "what" points to a struct dict_object containing an enumerated constant (DICT_ENUMVAL, see below). */ |
1299 TYPE_OF_AVP /* "what" points to a struct dict_object containing an AVP object. */ | 1299 TYPE_OF_AVP /* "what" points to a struct dict_object containing an AVP object. */ |
1300 }; | 1300 }; |
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 |
1306 /* Convert an Address type AVP into a struct sockaddr_storage */ | 1306 /* Convert an Address type AVP into a struct sockaddr_storage */ |
1307 int fd_dictfct_Address_encode(void * data, union avp_value * avp_value); | 1307 int fd_dictfct_Address_encode(void * data, union avp_value * avp_value); |
1308 int fd_dictfct_Address_interpret(union avp_value * avp_value, void * interpreted); | 1308 int fd_dictfct_Address_interpret(union avp_value * avp_value, void * interpreted); |
1325 | 1325 |
1326 /*** | 1326 /*** |
1327 * API usage : | 1327 * API usage : |
1328 | 1328 |
1329 - fd_dict_new: | 1329 - fd_dict_new: |
1330 The "parent" parameter may point to an application object, when a type is defined by a Diameter application. | 1330 The "parent" parameter may point to an application object, when a type is defined by a Diameter application. |
1331 | 1331 |
1332 Sample code: | 1332 Sample code: |
1333 { | 1333 { |
1334 int ret; | 1334 int ret; |
1335 struct dict_object * mytype; | 1335 struct dict_object * mytype; |
1336 struct dict_type_data mytypedata = | 1336 struct dict_type_data mytypedata = |
1337 { | 1337 { |
1338 AVP_TYPE_OCTETSTRING, | 1338 AVP_TYPE_OCTETSTRING, |
1339 "Address", | 1339 "Address", |
1340 NULL, | 1340 NULL, |
1341 NULL | 1341 NULL |
1342 }; | 1342 }; |
1348 { | 1348 { |
1349 int ret; | 1349 int ret; |
1350 struct dict_object * address_type; | 1350 struct dict_object * address_type; |
1351 ret = fd_dict_search ( dict, DICT_TYPE, TYPE_BY_NAME, "Address", &address_type, ENOENT); | 1351 ret = fd_dict_search ( dict, DICT_TYPE, TYPE_BY_NAME, "Address", &address_type, ENOENT); |
1352 } | 1352 } |
1353 | 1353 |
1354 */ | 1354 */ |
1355 | 1355 |
1356 /* | 1356 /* |
1357 *************************************************************************** | 1357 *************************************************************************** |
1358 * | 1358 * |
1359 * Enumerated values object | 1359 * Enumerated values object |
1360 * | 1360 * |
1361 * These types are used to manage named constants of some AVP, | 1361 * These types are used to manage named constants of some AVP, |
1362 * for enumerated types. freeDiameter allows constants for types others than Unsigned32 | 1362 * for enumerated types. freeDiameter allows constants for types others than Unsigned32 |
1363 * | 1363 * |
1364 *************************************************************************** | 1364 *************************************************************************** |
1379 | 1379 |
1380 struct dict_enumval_request { | 1380 struct dict_enumval_request { |
1381 /* Identifier of the parent type, one of the following must not be NULL */ | 1381 /* Identifier of the parent type, one of the following must not be NULL */ |
1382 struct dict_object *type_obj; | 1382 struct dict_object *type_obj; |
1383 char * type_name; | 1383 char * type_name; |
1384 | 1384 |
1385 /* Search criteria for the constant */ | 1385 /* Search criteria for the constant */ |
1386 struct dict_enumval_data search; /* search.enum_value is used only if search.enum_name == NULL */ | 1386 struct dict_enumval_data search; /* search.enum_value is used only if search.enum_name == NULL */ |
1387 }; | 1387 }; |
1388 | 1388 |
1389 /*** | 1389 /*** |
1390 * API usage : | 1390 * API usage : |
1391 | 1391 |
1392 - fd_dict_new: | 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 Sample code to create a type "Boolean" with two constants "True" and "False": | 1394 Sample code to create a type "Boolean" with two constants "True" and "False": |
1395 { | 1395 { |
1396 int ret; | 1396 int ret; |
1397 struct dict_object * type_boolean; | 1397 struct dict_object * type_boolean; |
1398 struct dict_type_data type_boolean_data = | 1398 struct dict_type_data type_boolean_data = |
1399 { | 1399 { |
1400 AVP_TYPE_INTEGER32, | 1400 AVP_TYPE_INTEGER32, |
1401 "Boolean", | 1401 "Boolean", |
1402 NULL, | 1402 NULL, |
1403 NULL | 1403 NULL |
1404 }; | 1404 }; |
1413 .enum_value.i32 = -1 | 1413 .enum_value.i32 = -1 |
1414 }; | 1414 }; |
1415 ret = fd_dict_new ( dict, DICT_TYPE, &type_boolean_data, NULL, &type_boolean ); | 1415 ret = fd_dict_new ( dict, DICT_TYPE, &type_boolean_data, NULL, &type_boolean ); |
1416 ret = fd_dict_new ( dict, DICT_ENUMVAL, &boolean_false, type_boolean, NULL ); | 1416 ret = fd_dict_new ( dict, DICT_ENUMVAL, &boolean_false, type_boolean, NULL ); |
1417 ret = fd_dict_new ( dict, DICT_ENUMVAL, &boolean_true , type_boolean, NULL ); | 1417 ret = fd_dict_new ( dict, DICT_ENUMVAL, &boolean_true , type_boolean, NULL ); |
1418 | 1418 |
1419 } | 1419 } |
1420 | 1420 |
1421 - fd_dict_search: | 1421 - fd_dict_search: |
1422 Sample code to look for a constant name, by its value: | 1422 Sample code to look for a constant name, by its value: |
1423 { | 1423 { |
1427 { | 1427 { |
1428 .type_name = "Boolean", | 1428 .type_name = "Boolean", |
1429 .search.enum_name=NULL, | 1429 .search.enum_name=NULL, |
1430 .search.enum_value.i32 = -1 | 1430 .search.enum_value.i32 = -1 |
1431 }; | 1431 }; |
1432 | 1432 |
1433 ret = fd_dict_search ( dict, DICT_ENUMVAL, ENUMVAL_BY_STRUCT, &boolean_by_value, &value_found, ENOENT); | 1433 ret = fd_dict_search ( dict, DICT_ENUMVAL, ENUMVAL_BY_STRUCT, &boolean_by_value, &value_found, ENOENT); |
1434 } | 1434 } |
1435 | 1435 |
1436 - fd_dict_getval: | 1436 - fd_dict_getval: |
1437 Sample code to retrieve the data from a constant object: | 1437 Sample code to retrieve the data from a constant object: |
1438 { | 1438 { |
1439 int ret; | 1439 int ret; |
1440 struct dict_object * value_found; | 1440 struct dict_object * value_found; |
1443 { | 1443 { |
1444 .type_name = "Boolean", | 1444 .type_name = "Boolean", |
1445 .search.enum_name=NULL, | 1445 .search.enum_name=NULL, |
1446 .search.enum_value.i32 = 0 | 1446 .search.enum_value.i32 = 0 |
1447 }; | 1447 }; |
1448 | 1448 |
1449 ret = fd_dict_search ( dict, DICT_ENUMVAL, ENUMVAL_BY_STRUCT, &boolean_by_value, &value_found, ENOENT); | 1449 ret = fd_dict_search ( dict, DICT_ENUMVAL, ENUMVAL_BY_STRUCT, &boolean_by_value, &value_found, ENOENT); |
1450 ret = fd_dict_getval ( value_found, &boolean_data ); | 1450 ret = fd_dict_getval ( value_found, &boolean_data ); |
1451 printf(" Boolean with value 0: %s", boolean_data.enum_name ); | 1451 printf(" Boolean with value 0: %s", boolean_data.enum_name ); |
1452 } | 1452 } |
1453 */ | 1453 */ |
1454 | 1454 |
1455 /* | 1455 /* |
1456 *************************************************************************** | 1456 *************************************************************************** |
1457 * | 1457 * |
1458 * AVP object | 1458 * AVP object |
1459 * | 1459 * |
1460 * These objects are used to manage AVP definitions in the dictionary | 1460 * These objects are used to manage AVP definitions in the dictionary |
1461 * | 1461 * |
1462 *************************************************************************** | 1462 *************************************************************************** |
1463 */ | 1463 */ |
1495 enum { | 1495 enum { |
1496 AVP_BY_CODE = 50, /* "what" points to an avp_code_t, vendor is always 0 */ | 1496 AVP_BY_CODE = 50, /* "what" points to an avp_code_t, vendor is always 0 */ |
1497 AVP_BY_NAME, /* "what" points to a char *, vendor is always 0 */ | 1497 AVP_BY_NAME, /* "what" points to a char *, vendor is always 0 */ |
1498 AVP_BY_NAME_ALL_VENDORS,/* "what" points to a string. Might be quite slow... */ | 1498 AVP_BY_NAME_ALL_VENDORS,/* "what" points to a string. Might be quite slow... */ |
1499 AVP_BY_STRUCT, /* "what" points to a struct dict_avp_request_ex (see below) */ | 1499 AVP_BY_STRUCT, /* "what" points to a struct dict_avp_request_ex (see below) */ |
1500 | 1500 |
1501 /* kept for backward compatibility, better use AVP_BY_STRUCT above instead */ | 1501 /* kept for backward compatibility, better use AVP_BY_STRUCT above instead */ |
1502 AVP_BY_CODE_AND_VENDOR, /* "what" points to a struct dict_avp_request (see below), where avp_vendor and avp_code are set */ | 1502 AVP_BY_CODE_AND_VENDOR, /* "what" points to a struct dict_avp_request (see below), where avp_vendor and avp_code are set */ |
1503 AVP_BY_NAME_AND_VENDOR /* "what" points to a struct dict_avp_request (see below), where avp_vendor and avp_name are set */ | 1503 AVP_BY_NAME_AND_VENDOR /* "what" points to a struct dict_avp_request (see below), where avp_vendor and avp_name are set */ |
1504 }; | 1504 }; |
1505 | 1505 |
1509 /* Only one of the following fields must be set. */ | 1509 /* Only one of the following fields must be set. */ |
1510 struct dict_object * vendor; /* most efficient if already known, set to NULL to ignore */ | 1510 struct dict_object * vendor; /* most efficient if already known, set to NULL to ignore */ |
1511 vendor_id_t vendor_id; /* set to 0 to ignore -- prefer AVP_BY_CODE or AVP_BY_NAME for vendor 0 */ | 1511 vendor_id_t vendor_id; /* set to 0 to ignore -- prefer AVP_BY_CODE or AVP_BY_NAME for vendor 0 */ |
1512 const char * vendor_name; /* set to NULL to ignore */ | 1512 const char * vendor_name; /* set to NULL to ignore */ |
1513 } avp_vendor; | 1513 } avp_vendor; |
1514 | 1514 |
1515 struct { | 1515 struct { |
1516 /* Only one of the following fields must be set */ | 1516 /* Only one of the following fields must be set */ |
1517 avp_code_t avp_code; /* set to 0 to ignore */ | 1517 avp_code_t avp_code; /* set to 0 to ignore */ |
1518 const char * avp_name; /* set to NULL to ignore */ | 1518 const char * avp_name; /* set to NULL to ignore */ |
1519 } avp_data; | 1519 } avp_data; |
1528 | 1528 |
1529 | 1529 |
1530 /*** | 1530 /*** |
1531 * API usage : | 1531 * API usage : |
1532 | 1532 |
1533 If "parent" parameter is not NULL during AVP creation, it must point to a DICT_TYPE object. | 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 | 1534 The extended type is then attached to the AVP. In case where it is an enumerated type, the value of |
1535 AVP is automatically interpreted in debug messages, and in message checks. | 1535 AVP is automatically interpreted in debug messages, and in message checks. |
1536 The derived type of an AVP can be retrieved with: dict_search ( DICT_TYPE, TYPE_OF_AVP, avp, ... ) | 1536 The derived type of an AVP can be retrieved with: dict_search ( DICT_TYPE, TYPE_OF_AVP, avp, ... ) |
1537 | 1537 |
1538 To create the rules (ABNF) for children of Grouped AVP, see the DICT_RULE related part. | 1538 To create the rules (ABNF) for children of Grouped AVP, see the DICT_RULE related part. |
1539 | 1539 |
1558 "Sample-Boolean", | 1558 "Sample-Boolean", |
1559 AVP_FLAG_VENDOR | AVP_FLAG_MANDATORY, | 1559 AVP_FLAG_VENDOR | AVP_FLAG_MANDATORY, |
1560 AVP_FLAG_VENDOR, | 1560 AVP_FLAG_VENDOR, |
1561 AVP_TYPE_INTEGER32 // This MUST be the same as parent type's | 1561 AVP_TYPE_INTEGER32 // This MUST be the same as parent type's |
1562 }; | 1562 }; |
1563 | 1563 |
1564 -- Create an AVP with a base type -- | 1564 -- Create an AVP with a base type -- |
1565 ret = fd_dict_new ( dict, DICT_AVP, &user_name_data, NULL, &user_name_avp ); | 1565 ret = fd_dict_new ( dict, DICT_AVP, &user_name_data, NULL, &user_name_avp ); |
1566 | 1566 |
1567 -- Create an AVP with a derived type -- | 1567 -- Create an AVP with a derived type -- |
1568 ret = fd_dict_search ( dict, DICT_TYPE, TYPE_BY_NAME, "Boolean", &boolean_type, ENOENT); | 1568 ret = fd_dict_search ( dict, DICT_TYPE, TYPE_BY_NAME, "Boolean", &boolean_type, ENOENT); |
1569 ret = fd_dict_new ( dict, DICT_AVP, &sample_boolean_data , boolean_type, &sample_boolean_avp ); | 1569 ret = fd_dict_new ( dict, DICT_AVP, &sample_boolean_data , boolean_type, &sample_boolean_avp ); |
1570 | 1570 |
1571 } | 1571 } |
1572 | 1572 |
1573 - fd_dict_search: | 1573 - fd_dict_search: |
1574 Sample code to look for an AVP | 1574 Sample code to look for an AVP |
1575 { | 1575 { |
1579 struct dict_avp_request avpvendorboolean = | 1579 struct dict_avp_request avpvendorboolean = |
1580 { | 1580 { |
1581 .avp_vendor = 23455, | 1581 .avp_vendor = 23455, |
1582 .avp_name = "Sample-Boolean" | 1582 .avp_name = "Sample-Boolean" |
1583 }; | 1583 }; |
1584 | 1584 |
1585 ret = fd_dict_search ( dict, DICT_AVP, AVP_BY_NAME, "User-Name", &avp_username, ENOENT); | 1585 ret = fd_dict_search ( dict, DICT_AVP, AVP_BY_NAME, "User-Name", &avp_username, ENOENT); |
1586 | 1586 |
1587 ret = fd_dict_search ( dict, DICT_AVP, AVP_BY_NAME_AND_VENDOR, &avpvendorboolean, &avp_sampleboolean, ENOENT); | 1587 ret = fd_dict_search ( dict, DICT_AVP, AVP_BY_NAME_AND_VENDOR, &avpvendorboolean, &avp_sampleboolean, ENOENT); |
1588 | 1588 |
1589 -- this would also work, but be slower, because it has to search all vendor dictionaries -- | 1589 -- this would also work, but be slower, because it has to search all vendor dictionaries -- |
1590 ret = fd_dict_search ( dict, DICT_AVP, AVP_BY_NAME_ALL_VENDORS, "Sample-Boolean", &avp_sampleboolean, ENOENT); | 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 - fd_dict_getval: | 1594 - fd_dict_getval: |
1595 Sample code to retrieve the data from an AVP object: | 1595 Sample code to retrieve the data from an AVP object: |
1596 { | 1596 { |
1597 int ret; | 1597 int ret; |
1598 struct dict_object * avp_username; | 1598 struct dict_object * avp_username; |
1605 */ | 1605 */ |
1606 | 1606 |
1607 /* | 1607 /* |
1608 *************************************************************************** | 1608 *************************************************************************** |
1609 * | 1609 * |
1610 * Command object | 1610 * Command object |
1611 * | 1611 * |
1612 * These types are used to manage commands objects in the dictionary | 1612 * These types are used to manage commands objects in the dictionary |
1613 * | 1613 * |
1614 *************************************************************************** | 1614 *************************************************************************** |
1615 */ | 1615 */ |
1669 257, // code | 1669 257, // code |
1670 "Capabilities-Exchange-Request", // name | 1670 "Capabilities-Exchange-Request", // name |
1671 CMD_FLAG_REQUEST, // mask | 1671 CMD_FLAG_REQUEST, // mask |
1672 CMD_FLAG_REQUEST // value. Only the "R" flag is constrained here, set. | 1672 CMD_FLAG_REQUEST // value. Only the "R" flag is constrained here, set. |
1673 }; | 1673 }; |
1674 | 1674 |
1675 ret = fd_dict_new (dict, DICT_COMMAND, &ce_data, NULL, &cer ); | 1675 ret = fd_dict_new (dict, DICT_COMMAND, &ce_data, NULL, &cer ); |
1676 | 1676 |
1677 ce_data.cmd_name = "Capabilities-Exchange-Answer"; | 1677 ce_data.cmd_name = "Capabilities-Exchange-Answer"; |
1678 ce_data.cmd_flag_val = 0; // Same constraint on "R" flag, but this time it must be cleared. | 1678 ce_data.cmd_flag_val = 0; // Same constraint on "R" flag, but this time it must be cleared. |
1679 | 1679 |
1680 ret = fd_dict_new ( dict, DICT_COMMAND, &ce_data, NULL, &cea ); | 1680 ret = fd_dict_new ( dict, DICT_COMMAND, &ce_data, NULL, &cea ); |
1681 } | 1681 } |
1687 struct dict_object * cer, * cea; | 1687 struct dict_object * cer, * cea; |
1688 command_code_t code = 257; | 1688 command_code_t code = 257; |
1689 ret = fd_dict_search ( dict, DICT_COMMAND, CMD_BY_NAME, "Capabilities-Exchange-Request", &cer, ENOENT); | 1689 ret = fd_dict_search ( dict, DICT_COMMAND, CMD_BY_NAME, "Capabilities-Exchange-Request", &cer, ENOENT); |
1690 ret = fd_dict_search ( dict, DICT_COMMAND, CMD_BY_CODE_R, &code, &cer, ENOENT); | 1690 ret = fd_dict_search ( dict, DICT_COMMAND, CMD_BY_CODE_R, &code, &cer, ENOENT); |
1691 } | 1691 } |
1692 | 1692 |
1693 - fd_dict_getval: | 1693 - fd_dict_getval: |
1694 Sample code to retrieve the data from a command object: | 1694 Sample code to retrieve the data from a command object: |
1695 { | 1695 { |
1696 int ret; | 1696 int ret; |
1697 struct dict_object * cer; | 1697 struct dict_object * cer; |
1761 struct dict_rule_data rule_data; | 1761 struct dict_rule_data rule_data; |
1762 struct dict_type_data di_type_data = { AVP_TYPE_OCTETSTRING, "DiameterIdentity", NULL, NULL }; | 1762 struct dict_type_data di_type_data = { AVP_TYPE_OCTETSTRING, "DiameterIdentity", NULL, NULL }; |
1763 struct dict_avp_data proxy_info_data = { 284, 0, "Proxy-Info", AVP_FLAG_VENDOR | AVP_FLAG_MANDATORY, AVP_FLAG_MANDATORY, AVP_TYPE_GROUPED }; | 1763 struct dict_avp_data proxy_info_data = { 284, 0, "Proxy-Info", AVP_FLAG_VENDOR | AVP_FLAG_MANDATORY, AVP_FLAG_MANDATORY, AVP_TYPE_GROUPED }; |
1764 struct dict_avp_data proxy_host_data = { 280, 0, "Proxy-Host", AVP_FLAG_VENDOR | AVP_FLAG_MANDATORY, AVP_FLAG_MANDATORY, AVP_TYPE_OCTETSTRING }; | 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 struct dict_avp_data proxy_state_data = { 33, 0, "Proxy-State",AVP_FLAG_VENDOR | AVP_FLAG_MANDATORY, AVP_FLAG_MANDATORY, AVP_TYPE_OCTETSTRING }; | 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 -- Create the parent AVP | 1767 -- Create the parent AVP |
1768 ret = fd_dict_new ( dict, DICT_AVP, &proxy_info_data, NULL, &proxy_info_avp ); | 1768 ret = fd_dict_new ( dict, DICT_AVP, &proxy_info_data, NULL, &proxy_info_avp ); |
1769 | 1769 |
1770 -- Create the first child AVP. | 1770 -- Create the first child AVP. |
1771 ret = fd_dict_new ( dict, DICT_TYPE, &di_type_data, NULL, &diameteridentity_type ); | 1771 ret = fd_dict_new ( dict, DICT_TYPE, &di_type_data, NULL, &diameteridentity_type ); |
1772 ret = fd_dict_new ( dict, DICT_AVP, &proxy_host_data, diameteridentity_type, &proxy_host_avp ); | 1772 ret = fd_dict_new ( dict, DICT_AVP, &proxy_host_data, diameteridentity_type, &proxy_host_avp ); |
1773 | 1773 |
1774 -- Create the other child AVP | 1774 -- Create the other child AVP |
1775 ret = fd_dict_new ( dict, DICT_AVP, &proxy_state_data, NULL, &proxy_state_avp ); | 1775 ret = fd_dict_new ( dict, DICT_AVP, &proxy_state_data, NULL, &proxy_state_avp ); |
1776 | 1776 |
1777 -- Now we can create the rules. Both children AVP are mandatory. | 1777 -- Now we can create the rules. Both children AVP are mandatory. |
1778 rule_data.rule_position = RULE_REQUIRED; | 1778 rule_data.rule_position = RULE_REQUIRED; |
1779 rule_data.rule_min = -1; | 1779 rule_data.rule_min = -1; |
1780 rule_data.rule_max = -1; | 1780 rule_data.rule_max = -1; |
1781 | 1781 |
1782 rule_data.rule_avp = proxy_host_avp; | 1782 rule_data.rule_avp = proxy_host_avp; |
1783 ret = fd_dict_new ( dict, DICT_RULE, &rule_data, proxy_info_avp, NULL ); | 1783 ret = fd_dict_new ( dict, DICT_RULE, &rule_data, proxy_info_avp, NULL ); |
1784 | 1784 |
1785 rule_data.rule_avp = proxy_state_avp; | 1785 rule_data.rule_avp = proxy_state_avp; |
1786 ret = fd_dict_new ( dict, DICT_RULE, &rule_data, proxy_info_avp, NULL ); | 1786 ret = fd_dict_new ( dict, DICT_RULE, &rule_data, proxy_info_avp, NULL ); |
1787 } | 1787 } |
1788 | 1788 |
1789 - fd_dict_search and fd_dict_getval are similar to previous examples. | 1789 - fd_dict_search and fd_dict_getval are similar to previous examples. |
1790 | 1790 |
1791 */ | 1791 */ |
1792 | 1792 |
1793 /* Define some hard-coded values */ | 1793 /* Define some hard-coded values */ |
1794 /* Application */ | 1794 /* Application */ |
1795 #define AI_RELAY 0xffffffff | 1795 #define AI_RELAY 0xffffffff |
1796 | 1796 |
1797 /* Commands Codes */ | 1797 /* Commands Codes */ |
1838 #define ACV_ISI_NO_INBAND_SECURITY 0 | 1838 #define ACV_ISI_NO_INBAND_SECURITY 0 |
1839 #define ACV_ISI_TLS 1 | 1839 #define ACV_ISI_TLS 1 |
1840 | 1840 |
1841 /* Error codes from Base protocol | 1841 /* Error codes from Base protocol |
1842 (reference: http://www.iana.org/assignments/aaa-parameters/aaa-parameters.xml#aaa-parameters-4) | 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 #define ER_DIAMETER_MULTI_ROUND_AUTH 1001 | 1845 #define ER_DIAMETER_MULTI_ROUND_AUTH 1001 |
1846 | 1846 |
1847 #define ER_DIAMETER_SUCCESS 2001 | 1847 #define ER_DIAMETER_SUCCESS 2001 |
1848 #define ER_DIAMETER_LIMITED_SUCCESS 2002 | 1848 #define ER_DIAMETER_LIMITED_SUCCESS 2002 |
1906 * handler : location where the new handler must be stored. | 1906 * handler : location where the new handler must be stored. |
1907 * cleanup : a callback function that must be called when the session with associated data is destroyed. | 1907 * cleanup : a callback function that must be called when the session with associated data is destroyed. |
1908 * dumper : if not NULL, will be called during fd_sess_dump to display the data associated with a session. NULL otherwise. | 1908 * dumper : if not NULL, will be called during fd_sess_dump to display the data associated with a session. NULL otherwise. |
1909 * opaque : A pointer that is passed to the cleanup callback -- the content is never examined by the framework. | 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 * Create a new session handler. This is needed by a module to associate a state with a session object. | 1912 * Create a new session handler. This is needed by a module to associate a state with a session object. |
1913 * The cleanup handler is called when the session timeout expires, or fd_sess_destroy is called. It must free | 1913 * The cleanup handler is called when the session timeout expires, or fd_sess_destroy is called. It must free |
1914 * the state associated with the session, and eventually trig other actions (send a STR, ...). | 1914 * the state associated with the session, and eventually trig other actions (send a STR, ...). |
1915 * | 1915 * |
1916 * RETURN VALUE: | 1916 * RETURN VALUE: |
1918 * EINVAL : A parameter is invalid. | 1918 * EINVAL : A parameter is invalid. |
1919 * ENOMEM : Not enough memory to complete the operation | 1919 * ENOMEM : Not enough memory to complete the operation |
1920 */ | 1920 */ |
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 ); | 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 * FUNCTION: fd_sess_handler_destroy | 1925 * FUNCTION: fd_sess_handler_destroy |
1926 * | 1926 * |
1927 * PARAMETERS: | 1927 * PARAMETERS: |
1928 * handler : location of an handler created by fd_sess_handler_create. | 1928 * handler : location of an handler created by fd_sess_handler_create. |
1929 * opaque : the opaque pointer registered with the callback is restored here (if ! NULL). | 1929 * opaque : the opaque pointer registered with the callback is restored here (if ! NULL). |
1930 * | 1930 * |
1931 * DESCRIPTION: | 1931 * DESCRIPTION: |
1932 * This destroys a session handler (typically called when an application is shutting down). | 1932 * This destroys a session handler (typically called when an application is shutting down). |
1933 * If sessions states are registered with this handler, the cleanup callback is called on them. | 1933 * If sessions states are registered with this handler, the cleanup callback is called on them. |
1934 * | 1934 * |
1935 * RETURN VALUE: | 1935 * RETURN VALUE: |
1936 * 0 : The handler was destroyed. | 1936 * 0 : The handler was destroyed. |
1949 * diamid : a Diameter Identity, or NULL. | 1949 * diamid : a Diameter Identity, or NULL. |
1950 * diamidlen : if diamid is \0-terminated, this can be 0. Otherwise, the length of diamid. | 1950 * diamidlen : if diamid is \0-terminated, this can be 0. Otherwise, the length of diamid. |
1951 * opt : Additional string, or NULL. Usage is described below. | 1951 * opt : Additional string, or NULL. Usage is described below. |
1952 * optlen : if opt is \0-terminated, this can be 0. Otherwise, the length of opt. | 1952 * optlen : if opt is \0-terminated, this can be 0. Otherwise, the length of opt. |
1953 * | 1953 * |
1954 * DESCRIPTION: | 1954 * DESCRIPTION: |
1955 * Create a new session object. The Session-Id string associated with this session is generated as follow: | 1955 * Create a new session object. The Session-Id string associated with this session is generated as follow: |
1956 * If diamId parameter is provided, the string is created according to the RFC: <diamId>;<high32>;<low32>[;opt] where | 1956 * If diamId parameter is provided, the string is created according to the RFC: <diamId>;<high32>;<low32>[;opt] where |
1957 * diamId is a Diameter Identity. | 1957 * diamId is a Diameter Identity. |
1958 * high32 and low32 are the parts of a monotonic 64 bits counter initialized to (time, 0) at startup. | 1958 * high32 and low32 are the parts of a monotonic 64 bits counter initialized to (time, 0) at startup. |
1959 * opt is an optional string that can be concatenated to the identifier. | 1959 * opt is an optional string that can be concatenated to the identifier. |
1974 * sid : pointer to a string containing a Session-Id (should be UTF-8). | 1974 * sid : pointer to a string containing a Session-Id (should be UTF-8). |
1975 * len : length of the sid string (which does not need to be '\0'-terminated) | 1975 * len : length of the sid string (which does not need to be '\0'-terminated) |
1976 * session : On success, pointer to the session object created / retrieved. | 1976 * session : On success, pointer to the session object created / retrieved. |
1977 * isnew : if not NULL, set to 1 on return if the session object has been created, 0 if it was simply retrieved. | 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: | 1979 * DESCRIPTION: |
1980 * Retrieve a session object from a Session-Id string. In case no session object was previously existing with this | 1980 * Retrieve a session object from a Session-Id string. In case no session object was previously existing with this |
1981 * id, a new object is silently created (equivalent to fd_sess_new with flag SESSION_NEW_FULL). | 1981 * id, a new object is silently created (equivalent to fd_sess_new with flag SESSION_NEW_FULL). |
1982 * | 1982 * |
1983 * RETURN VALUE: | 1983 * RETURN VALUE: |
1984 * 0 : The session parameter has been updated. | 1984 * 0 : The session parameter has been updated. |
1985 * EINVAL : A parameter is invalid. | 1985 * EINVAL : A parameter is invalid. |
1986 * ENOMEM : Not enough memory to complete the operation | 1986 * ENOMEM : Not enough memory to complete the operation |
1987 */ | 1987 */ |
1988 int fd_sess_fromsid ( uint8_t * sid, size_t len, struct session ** session, int * isnew); | 1988 int fd_sess_fromsid ( uint8_t * sid, size_t len, struct session ** session, int * isnew); |
1989 | 1989 |
1990 /* only use the following in specific situations, e.g. app_radgw extension. They are normally handled by the framework only */ | 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 int fd_sess_ref_msg ( struct session * session ); | 1992 int fd_sess_ref_msg ( struct session * session ); |
1993 | 1993 |
1994 /* | 1994 /* |
1995 * FUNCTION: fd_sess_getsid | 1995 * FUNCTION: fd_sess_getsid |
1996 * | 1996 * |
1997 * PARAMETERS: | 1997 * PARAMETERS: |
1998 * session : Pointer to a session object. | 1998 * session : Pointer to a session object. |
1999 * sid : On success, the location of the sid is stored here. | 1999 * sid : On success, the location of the sid is stored here. |
2000 * | 2000 * |
2001 * DESCRIPTION: | 2001 * DESCRIPTION: |
2002 * Retrieve the session identifier (Session-Id) corresponding to a session object. | 2002 * Retrieve the session identifier (Session-Id) corresponding to a session object. |
2003 * The returned sid is a \0-terminated binary string which might be UTF-8 (but there is no guarantee in the framework). | 2003 * The returned sid is a \0-terminated binary string which might be UTF-8 (but there is no guarantee in the framework). |
2004 * It may be used for example to set the value of an AVP. | 2004 * It may be used for example to set the value of an AVP. |
2005 * Note that the sid string is not copied, just its reference... do not free it! | 2005 * Note that the sid string is not copied, just its reference... do not free it! |
2006 * | 2006 * |
2015 * | 2015 * |
2016 * PARAMETERS: | 2016 * PARAMETERS: |
2017 * session : The session for which to set the timeout. | 2017 * session : The session for which to set the timeout. |
2018 * timeout : The date when the session times out. | 2018 * timeout : The date when the session times out. |
2019 * | 2019 * |
2020 * DESCRIPTION: | 2020 * DESCRIPTION: |
2021 * Set the lifetime for a given session object. This function may be | 2021 * Set the lifetime for a given session object. This function may be |
2022 * called several times on the same object to update the timeout value. | 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 | 2023 * When the timeout date is reached, the cleanup handler of each |
2024 * module that registered data with this session is called, then the | 2024 * module that registered data with this session is called, then the |
2025 * session is cleared. | 2025 * session is cleared. |
2026 * | 2026 * |
2027 * There is a possible race condition between cleanup of the session | 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 * using data from a session that is about to expire / expired. | 2029 * using data from a session that is about to expire / expired. |
2030 * | 2030 * |
2031 * RETURN VALUE: | 2031 * RETURN VALUE: |
2032 * 0 : The session timeout has been updated. | 2032 * 0 : The session timeout has been updated. |
2033 * EINVAL : A parameter is invalid. | 2033 * EINVAL : A parameter is invalid. |
2038 * FUNCTION: fd_sess_destroy | 2038 * FUNCTION: fd_sess_destroy |
2039 * | 2039 * |
2040 * PARAMETERS: | 2040 * PARAMETERS: |
2041 * session : Pointer to a session object. | 2041 * session : Pointer to a session object. |
2042 * | 2042 * |
2043 * DESCRIPTION: | 2043 * DESCRIPTION: |
2044 * Destroys all associated states of a session, if any. | 2044 * Destroys all associated states of a session, if any. |
2045 * Equivalent to a session timeout expired, but the effect is immediate. | 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 * by any message anymore. | 2047 * by any message anymore. |
2048 * | 2048 * |
2049 * RETURN VALUE: | 2049 * RETURN VALUE: |
2050 * 0 : The session no longer exists. | 2050 * 0 : The session no longer exists. |
2051 * EINVAL : A parameter is invalid. | 2051 * EINVAL : A parameter is invalid. |
2056 * FUNCTION: fd_sess_reclaim | 2056 * FUNCTION: fd_sess_reclaim |
2057 * | 2057 * |
2058 * PARAMETERS: | 2058 * PARAMETERS: |
2059 * session : Pointer to a session object. | 2059 * session : Pointer to a session object. |
2060 * | 2060 * |
2061 * DESCRIPTION: | 2061 * DESCRIPTION: |
2062 * Equivalent to fd_sess_destroy, only if no session_state is associated with the session. | 2062 * Equivalent to fd_sess_destroy, only if no session_state is associated with the session. |
2063 * Otherwise, this function has no effect (except that it sets *session to NULL). | 2063 * Otherwise, this function has no effect (except that it sets *session to NULL). |
2064 * | 2064 * |
2065 * RETURN VALUE: | 2065 * RETURN VALUE: |
2066 * 0 : The session was reclaimed. | 2066 * 0 : The session was reclaimed. |
2077 * PARAMETERS: | 2077 * PARAMETERS: |
2078 * handler : The handler with which the state is registered. | 2078 * handler : The handler with which the state is registered. |
2079 * session : The session object with which the state is registered. | 2079 * session : The session object with which the state is registered. |
2080 * state : An application state (opaque data) to store with the session. | 2080 * state : An application state (opaque data) to store with the session. |
2081 * | 2081 * |
2082 * DESCRIPTION: | 2082 * DESCRIPTION: |
2083 * Stores an application state with a session. This state can later be retrieved | 2083 * Stores an application state with a session. This state can later be retrieved |
2084 * with fd_sess_state_retrieve, or implicitly in the cleanup handler when the session | 2084 * with fd_sess_state_retrieve, or implicitly in the cleanup handler when the session |
2085 * is destroyed. | 2085 * is destroyed. |
2086 * | 2086 * |
2087 * RETURN VALUE: | 2087 * RETURN VALUE: |
2098 * PARAMETERS: | 2098 * PARAMETERS: |
2099 * handler : The handler with which the state was registered. | 2099 * handler : The handler with which the state was registered. |
2100 * session : The session object with which the state was registered. | 2100 * session : The session object with which the state was registered. |
2101 * state : Location where the state must be saved if it is found. | 2101 * state : Location where the state must be saved if it is found. |
2102 * | 2102 * |
2103 * DESCRIPTION: | 2103 * DESCRIPTION: |
2104 * Retrieves a state saved by fd_sess_state_store. | 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 * the session. A new call to fd_sess_state_store must be performed in order to | 2106 * the session. A new call to fd_sess_state_store must be performed in order to |
2107 * store again the data with the session. | 2107 * store again the data with the session. |
2108 * | 2108 * |
2109 * RETURN VALUE: | 2109 * RETURN VALUE: |
2110 * 0 : *state is updated (NULL or points to the state if it was found). | 2110 * 0 : *state is updated (NULL or points to the state if it was found). |
2111 * EINVAL : A parameter is invalid. | 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 |
2116 /* For debug */ | 2116 /* For debug */ |
2117 DECLARE_FD_DUMP_PROTOTYPE(fd_sess_dump, struct session * session, int with_states); | 2117 DECLARE_FD_DUMP_PROTOTYPE(fd_sess_dump, struct session * session, int with_states); |
2118 DECLARE_FD_DUMP_PROTOTYPE(fd_sess_dump_hdl, struct session_handler * handler); | 2118 DECLARE_FD_DUMP_PROTOTYPE(fd_sess_dump_hdl, struct session_handler * handler); |
2122 | 2122 |
2123 /*============================================================*/ | 2123 /*============================================================*/ |
2124 /* ROUTING */ | 2124 /* ROUTING */ |
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 The routing data is stored in the message itself. */ | 2128 The routing data is stored in the message itself. */ |
2129 | 2129 |
2130 /* Structure that contains the routing data for a message */ | 2130 /* Structure that contains the routing data for a message */ |
2131 struct rt_data; | 2131 struct rt_data; |
2132 | 2132 |
2193 typedef void msg_or_avp; | 2193 typedef void msg_or_avp; |
2194 | 2194 |
2195 /* The Diameter protocol version */ | 2195 /* The Diameter protocol version */ |
2196 #define DIAMETER_VERSION 1 | 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 * This means that the content of these fields will be overwritten by the daemon so modifying it is useless. | 2199 * This means that the content of these fields will be overwritten by the daemon so modifying it is useless. |
2200 */ | 2200 */ |
2201 | 2201 |
2202 /* The following structure represents the header of a message. All data is in host byte order. */ | 2202 /* The following structure represents the header of a message. All data is in host byte order. */ |
2203 struct msg_hdr { | 2203 struct msg_hdr { |
2236 | 2236 |
2237 /* Some flags used in the functions below */ | 2237 /* Some flags used in the functions below */ |
2238 #define AVPFL_SET_BLANK_VALUE 0x01 /* When creating an AVP, initialize its value to a blank area */ | 2238 #define AVPFL_SET_BLANK_VALUE 0x01 /* When creating an AVP, initialize its value to a blank area */ |
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) */ | 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 #define AVPFL_MAX AVPFL_SET_RAWDATA_FROM_AVP /* The biggest valid flag value */ | 2240 #define AVPFL_MAX AVPFL_SET_RAWDATA_FROM_AVP /* The biggest valid flag value */ |
2241 | 2241 |
2242 #define MSGFL_ALLOC_ETEID 0x01 /* When creating a message, a new end-to-end ID is allocated and set in the message */ | 2242 #define MSGFL_ALLOC_ETEID 0x01 /* When creating a message, a new end-to-end ID is allocated and set in the message */ |
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 */ | 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 */ |
2244 #define MSGFL_ANSW_NOSID 0x04 /* When creating an answer message, do not add the Session-Id even if present in request */ | 2244 #define MSGFL_ANSW_NOSID 0x04 /* When creating an answer message, do not add the Session-Id even if present in request */ |
2245 #define MSGFL_ANSW_NOPROXYINFO 0x08 /* When creating an answer message, do not add the Proxy-Info AVPs presents in request */ | 2245 #define MSGFL_ANSW_NOPROXYINFO 0x08 /* When creating an answer message, do not add the Proxy-Info AVPs presents in request */ |
2246 #define MSGFL_MAX MSGFL_ANSW_NOPROXYINFO /* The biggest valid flag value */ | 2246 #define MSGFL_MAX MSGFL_ANSW_NOPROXYINFO /* The biggest valid flag value */ |
2254 * PARAMETERS: | 2254 * PARAMETERS: |
2255 * model : Pointer to a DICT_AVP dictionary object describing the avp to create, or NULL if flags are used. | 2255 * model : Pointer to a DICT_AVP dictionary object describing the avp to create, or NULL if flags are used. |
2256 * flags : Flags to use in creation (AVPFL_*, see above). | 2256 * flags : Flags to use in creation (AVPFL_*, see above). |
2257 * avp : Upon success, pointer to the new avp is stored here. It points to reference AVP upon function call when flags are used. | 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 * Create a new AVP instance. | 2260 * Create a new AVP instance. |
2261 * | 2261 * |
2262 * RETURN VALUE: | 2262 * RETURN VALUE: |
2263 * 0 : The AVP is created. | 2263 * 0 : The AVP is created. |
2264 * EINVAL : A parameter is invalid. | 2264 * EINVAL : A parameter is invalid. |
2273 * PARAMETERS: | 2273 * PARAMETERS: |
2274 * model : Pointer to a DICT_COMMAND dictionary object describing the message to create, or NULL. | 2274 * model : Pointer to a DICT_COMMAND dictionary object describing the message to create, or NULL. |
2275 * flags : combination of MSGFL_* flags. | 2275 * flags : combination of MSGFL_* flags. |
2276 * msg : Upon success, pointer to the new message is stored here. | 2276 * msg : Upon success, pointer to the new message is stored here. |
2277 * | 2277 * |
2278 * DESCRIPTION: | 2278 * DESCRIPTION: |
2279 * Create a new empty Diameter message. | 2279 * Create a new empty Diameter message. |
2280 * | 2280 * |
2281 * RETURN VALUE: | 2281 * RETURN VALUE: |
2282 * 0 : The message is created. | 2282 * 0 : The message is created. |
2283 * EINVAL : A parameter is invalid. | 2283 * EINVAL : A parameter is invalid. |
2284 * (other standard errors may be returned, too, with their standard meaning. Example: | 2284 * (other standard errors may be returned, too, with their standard meaning. Example: |
2293 * dict : Pointer to the dictionary containing the model of the query. | 2293 * dict : Pointer to the dictionary containing the model of the query. |
2294 * msg : The location of the query on function call. Updated by the location of answer message on return. | 2294 * msg : The location of the query on function call. Updated by the location of answer message on return. |
2295 * flag : Pass MSGFL_ANSW_ERROR to indicate if the answer is an error message (will set the 'E' bit) | 2295 * flag : Pass MSGFL_ANSW_ERROR to indicate if the answer is an error message (will set the 'E' bit) |
2296 * : See other MSGFL_ANSW_* definition above for other flags. | 2296 * : See other MSGFL_ANSW_* definition above for other flags. |
2297 * | 2297 * |
2298 * DESCRIPTION: | 2298 * DESCRIPTION: |
2299 * This function creates the empty answer message corresponding to a request. | 2299 * This function creates the empty answer message corresponding to a request. |
2300 * The header is set properly (R flag, ccode, appid, hbhid, eteid) | 2300 * The header is set properly (R flag, ccode, appid, hbhid, eteid) |
2301 * The Session-Id AVP is copied if present. | 2301 * The Session-Id AVP is copied if present. |
2302 * The calling code should usually call fd_msg_rescode_set function on the answer. | 2302 * The calling code should usually call fd_msg_rescode_set function on the answer. |
2303 * Upon return, the original query may be retrieved by calling fd_msg_answ_getq on the message. | 2303 * Upon return, the original query may be retrieved by calling fd_msg_answ_getq on the message. |
2315 * reference : Pointer to a struct msg or struct avp. | 2315 * reference : Pointer to a struct msg or struct avp. |
2316 * dir : Direction for browsing | 2316 * dir : Direction for browsing |
2317 * found : If not NULL, updated with the element that has been found, if any, or NULL if no element was found / an error occurred. | 2317 * found : If not NULL, updated with the element that has been found, if any, or NULL if no element was found / an error occurred. |
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. | 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 * Explore the content of a message object (hierarchy). If "found" is null, only error checking is performed. | 2321 * Explore the content of a message object (hierarchy). If "found" is null, only error checking is performed. |
2322 * If "depth" is provided, it is updated as follow on successful function return: | 2322 * If "depth" is provided, it is updated as follow on successful function return: |
2323 * - not modified for MSG_BRW_NEXT and MSG_BRW_PREV. | 2323 * - not modified for MSG_BRW_NEXT and MSG_BRW_PREV. |
2324 * - *depth = *depth + 1 for MSG_BRW_FIRST_CHILD and MSG_BRW_LAST_CHILD. | 2324 * - *depth = *depth + 1 for MSG_BRW_FIRST_CHILD and MSG_BRW_LAST_CHILD. |
2325 * - *depth = *depth - 1 for MSG_BRW_PARENT. | 2325 * - *depth = *depth - 1 for MSG_BRW_PARENT. |
2326 * - *depth = *depth + X for MSG_BRW_WALK, with X between 1 (returned the 1st child) and -N (returned the Nth parent's next). | 2326 * - *depth = *depth + X for MSG_BRW_WALK, with X between 1 (returned the 1st child) and -N (returned the Nth parent's next). |
2327 * | 2327 * |
2328 * RETURN VALUE: | 2328 * RETURN VALUE: |
2329 * 0 : found has been updated (if non NULL). | 2329 * 0 : found has been updated (if non NULL). |
2330 * EINVAL : A parameter is invalid. | 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 int fd_msg_browse_internal ( msg_or_avp * reference, enum msg_brw_dir dir, msg_or_avp ** found, int * depth ); | 2333 int fd_msg_browse_internal ( msg_or_avp * reference, enum msg_brw_dir dir, msg_or_avp ** found, int * depth ); |
2334 /* Macro to avoid having to cast the third parameter everywhere */ | 2334 /* Macro to avoid having to cast the third parameter everywhere */ |
2335 #define fd_msg_browse( ref, dir, found, depth ) \ | 2335 #define fd_msg_browse( ref, dir, found, depth ) \ |
2336 fd_msg_browse_internal( (ref), (dir), (void *)(found), (depth) ) | 2336 fd_msg_browse_internal( (ref), (dir), (void *)(found), (depth) ) |
2342 * PARAMETERS: | 2342 * PARAMETERS: |
2343 * reference : Pointer to a valid msg or avp. | 2343 * reference : Pointer to a valid msg or avp. |
2344 * dir : location where the new AVP should be inserted, relative to the reference. MSG_BRW_PARENT and MSG_BRW_WALK are not valid. | 2344 * dir : location where the new AVP should be inserted, relative to the reference. MSG_BRW_PARENT and MSG_BRW_WALK are not valid. |
2345 * avp : pointer to the AVP object that must be inserted. | 2345 * avp : pointer to the AVP object that must be inserted. |
2346 * | 2346 * |
2347 * DESCRIPTION: | 2347 * DESCRIPTION: |
2348 * Adds an AVP into an object that can contain it: grouped AVP or message. | 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 * so it should not be freed after the call to this function. | 2350 * so it should not be freed after the call to this function. |
2351 * | 2351 * |
2352 * RETURN VALUE: | 2352 * RETURN VALUE: |
2353 * 0 : The AVP has been added. | 2353 * 0 : The AVP has been added. |
2354 * EINVAL : A parameter is invalid. | 2354 * EINVAL : A parameter is invalid. |
2361 * PARAMETERS: | 2361 * PARAMETERS: |
2362 * msg : The message structure in which to search the AVP. | 2362 * msg : The message structure in which to search the AVP. |
2363 * what : The dictionary model of the AVP to search. | 2363 * what : The dictionary model of the AVP to search. |
2364 * avp : location where the AVP reference is stored if found. | 2364 * avp : location where the AVP reference is stored if found. |
2365 * | 2365 * |
2366 * DESCRIPTION: | 2366 * DESCRIPTION: |
2367 * Search the first top-level AVP of a given model inside a message. | 2367 * Search the first top-level AVP of a given model inside a message. |
2368 * Note: only the first instance of the AVP is returned by this function. | 2368 * Note: only the first instance of the AVP is returned by this function. |
2369 * Note: only top-level AVPs are searched, not inside grouped AVPs. | 2369 * Note: only top-level AVPs are searched, not inside grouped AVPs. |
2370 * Use msg_browse if you need more advanced research features. | 2370 * Use msg_browse if you need more advanced research features. |
2371 * | 2371 * |
2380 * FUNCTION: fd_msg_free | 2380 * FUNCTION: fd_msg_free |
2381 * | 2381 * |
2382 * PARAMETERS: | 2382 * PARAMETERS: |
2383 * object : pointer to the message or AVP object that must be unlinked and freed. | 2383 * object : pointer to the message or AVP object that must be unlinked and freed. |
2384 * | 2384 * |
2385 * DESCRIPTION: | 2385 * DESCRIPTION: |
2386 * Unlink and free a message or AVP object and its children. | 2386 * Unlink and free a message or AVP object and its children. |
2387 * If the object is an AVP linked into a message, the AVP is removed before being freed. | 2387 * If the object is an AVP linked into a message, the AVP is removed before being freed. |
2388 * | 2388 * |
2389 * RETURN VALUE: | 2389 * RETURN VALUE: |
2390 * 0 : The message has been freed. | 2390 * 0 : The message has been freed. |
2404 * dict : the dictionary to use if parsing is requested (optional) | 2404 * dict : the dictionary to use if parsing is requested (optional) |
2405 * force_parsing: by default these functions do not parse the object but dump hexa values in that case. | 2405 * force_parsing: by default these functions do not parse the object but dump hexa values in that case. |
2406 * use !0 to force parsing. If parsing fails, the hexa dump is still provided. | 2406 * use !0 to force parsing. If parsing fails, the hexa dump is still provided. |
2407 * recurse : allow the function to go through the children objects if any to dump more information. might require parsing. | 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 * These functions dump the content of a message or avp into a buffer | 2410 * These functions dump the content of a message or avp into a buffer |
2411 * either recursively or only the object itself. | 2411 * either recursively or only the object itself. |
2412 * | 2412 * |
2413 * RETURN VALUE: | 2413 * RETURN VALUE: |
2414 * - see DECLARE_FD_DUMP_PROTOTYPE, | 2414 * - see DECLARE_FD_DUMP_PROTOTYPE, |
2429 * | 2429 * |
2430 * PARAMETERS: | 2430 * PARAMETERS: |
2431 * reference : Pointer to a valid msg or avp. | 2431 * reference : Pointer to a valid msg or avp. |
2432 * model : on success, pointer to the dictionary model of this command or AVP. NULL if the model is unknown. | 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 * Retrieve the dictionary object describing this message or avp. If the object is unknown or the fd_msg_parse_dict has not been called, | 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 * *model is set to NULL. | 2436 * *model is set to NULL. |
2437 * | 2437 * |
2438 * RETURN VALUE: | 2438 * RETURN VALUE: |
2439 * 0 : The model has been set. | 2439 * 0 : The model has been set. |
2446 * | 2446 * |
2447 * PARAMETERS: | 2447 * PARAMETERS: |
2448 * msg : Pointer to a valid message object. | 2448 * msg : Pointer to a valid message object. |
2449 * pdata : Upon success, pointer to the msg_hdr structure of this message. The fields may be modified. | 2449 * pdata : Upon success, pointer to the msg_hdr structure of this message. The fields may be modified. |
2450 * | 2450 * |
2451 * DESCRIPTION: | 2451 * DESCRIPTION: |
2452 * Retrieve location of modifiable section of a message. | 2452 * Retrieve location of modifiable section of a message. |
2453 * | 2453 * |
2454 * RETURN VALUE: | 2454 * RETURN VALUE: |
2455 * 0 : The location has been written. | 2455 * 0 : The location has been written. |
2456 * EINVAL : A parameter is invalid. | 2456 * EINVAL : A parameter is invalid. |
2457 */ | 2457 */ |
2462 * | 2462 * |
2463 * PARAMETERS: | 2463 * PARAMETERS: |
2464 * avp : Pointer to a valid avp object. | 2464 * avp : Pointer to a valid avp object. |
2465 * pdata : Upon success, pointer to the avp_hdr structure of this avp. The fields may be modified. | 2465 * pdata : Upon success, pointer to the avp_hdr structure of this avp. The fields may be modified. |
2466 * | 2466 * |
2467 * DESCRIPTION: | 2467 * DESCRIPTION: |
2468 * Retrieve location of modifiable data of an avp. | 2468 * Retrieve location of modifiable data of an avp. |
2469 * | 2469 * |
2470 * RETURN VALUE: | 2470 * RETURN VALUE: |
2471 * 0 : The location has been written. | 2471 * 0 : The location has been written. |
2472 * EINVAL : A parameter is invalid. | 2472 * EINVAL : A parameter is invalid. |
2473 */ | 2473 */ |
2479 * PARAMETERS: | 2479 * PARAMETERS: |
2480 * answer : the received answer message | 2480 * answer : the received answer message |
2481 * query : the corresponding query that had been sent | 2481 * query : the corresponding query that had been sent |
2482 * | 2482 * |
2483 * DESCRIPTION: | 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 * Query is retrieved with fd_msg_answ_getq. | 2485 * Query is retrieved with fd_msg_answ_getq. |
2486 * If answer message is freed, the query is also freed. | 2486 * If answer message is freed, the query is also freed. |
2487 * If the msg_answ_detach function is called, the association is removed. | 2487 * If the msg_answ_detach function is called, the association is removed. |
2488 * This is meant to be called from the daemon only. | 2488 * This is meant to be called from the daemon only. |
2489 * | 2489 * |
2540 * FUNCTION: fd_msg_is_routable | 2540 * FUNCTION: fd_msg_is_routable |
2541 * | 2541 * |
2542 * PARAMETERS: | 2542 * PARAMETERS: |
2543 * msg : A msg object. | 2543 * msg : A msg object. |
2544 * | 2544 * |
2545 * DESCRIPTION: | 2545 * DESCRIPTION: |
2546 * This function returns a boolean telling if a given message is routable in the Diameter network, | 2546 * This function returns a boolean telling if a given message is routable in the Diameter network, |
2547 * or if it is a local link message only (ex: CER/CEA, DWR/DWA, ...). | 2547 * or if it is a local link message only (ex: CER/CEA, DWR/DWA, ...). |
2548 * | 2548 * |
2549 * RETURN VALUE: | 2549 * RETURN VALUE: |
2550 * 0 : The message is not routable / an error occurred. | 2550 * 0 : The message is not routable / an error occurred. |
2551 * 1 : The message is routable. | 2551 * 1 : The message is routable. |
2558 * PARAMETERS: | 2558 * PARAMETERS: |
2559 * msg : A msg object. | 2559 * msg : A msg object. |
2560 * diamid,len : The diameter id of the peer from which this message was received. | 2560 * diamid,len : The diameter id of the peer from which this message was received. |
2561 * dict : a dictionary with definition of Route-Record AVP (for fd_msg_source_setrr) | 2561 * dict : a dictionary with definition of Route-Record AVP (for fd_msg_source_setrr) |
2562 * | 2562 * |
2563 * DESCRIPTION: | 2563 * DESCRIPTION: |
2564 * Store or retrieve the diameted id of the peer from which this message was received. | 2564 * Store or retrieve the diameted id of the peer from which this message was received. |
2565 * Will be used for example by the routing module to add the Route-Record AVP in forwarded requests, | 2565 * Will be used for example by the routing module to add the Route-Record AVP in forwarded requests, |
2566 * or to direct answers to the appropriate peer. | 2566 * or to direct answers to the appropriate peer. |
2567 * | 2567 * |
2568 * RETURN VALUE: | 2568 * RETURN VALUE: |
2577 * FUNCTION: fd_msg_eteid_get | 2577 * FUNCTION: fd_msg_eteid_get |
2578 * | 2578 * |
2579 * PARAMETERS: | 2579 * PARAMETERS: |
2580 * - | 2580 * - |
2581 * | 2581 * |
2582 * DESCRIPTION: | 2582 * DESCRIPTION: |
2583 * Get a new unique end-to-end id value for the local peer. | 2583 * Get a new unique end-to-end id value for the local peer. |
2584 * | 2584 * |
2585 * RETURN VALUE: | 2585 * RETURN VALUE: |
2586 * The new assigned value. No error code is defined. | 2586 * The new assigned value. No error code is defined. |
2587 */ | 2587 */ |
2627 /* | 2627 /* |
2628 * FUNCTION: fd_msg_avp_setvalue | 2628 * FUNCTION: fd_msg_avp_setvalue |
2629 * | 2629 * |
2630 * PARAMETERS: | 2630 * PARAMETERS: |
2631 * avp : Pointer to a valid avp object with a NULL avp_value pointer. The model must be known. | 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 * If data type is an octetstring, the data is also copied. | 2633 * If data type is an octetstring, the data is also copied. |
2634 * If value is a NULL pointer, the previous data is erased and value is unset in the AVP. | 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 * Initialize the avp_value field of an AVP header. | 2637 * Initialize the avp_value field of an AVP header. |
2638 * | 2638 * |
2639 * RETURN VALUE: | 2639 * RETURN VALUE: |
2640 * 0 : The avp_value pointer has been set. | 2640 * 0 : The avp_value pointer has been set. |
2641 * EINVAL : A parameter is invalid. | 2641 * EINVAL : A parameter is invalid. |
2648 * PARAMETERS: | 2648 * PARAMETERS: |
2649 * avp : Pointer to a valid avp object with a NULL avp_value. The model must be known. | 2649 * avp : Pointer to a valid avp object with a NULL avp_value. The model must be known. |
2650 * data : Pointer to the data that must be encoded as AVP value and stored in the AVP. | 2650 * data : Pointer to the data that must be encoded as AVP value and stored in the AVP. |
2651 * This is only valid for AVPs of derived type for which type_data_encode callback is set. (ex: Address type) | 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 * Initialize the avp_value field of an AVP object from formatted data, using the AVP's type "type_data_encode" callback. | 2654 * Initialize the avp_value field of an AVP object from formatted data, using the AVP's type "type_data_encode" callback. |
2655 * | 2655 * |
2656 * RETURN VALUE: | 2656 * RETURN VALUE: |
2657 * 0 : The avp_value has been set. | 2657 * 0 : The avp_value has been set. |
2658 * EINVAL : A parameter is invalid. | 2658 * EINVAL : A parameter is invalid. |
2664 * | 2664 * |
2665 * PARAMETERS: | 2665 * PARAMETERS: |
2666 * avp : Pointer to a valid avp object with a non-NULL avp_value value. | 2666 * avp : Pointer to a valid avp object with a non-NULL avp_value value. |
2667 * data : Upon success, formatted interpretation of the AVP value is stored here. | 2667 * data : Upon success, formatted interpretation of the AVP value is stored here. |
2668 * | 2668 * |
2669 * DESCRIPTION: | 2669 * DESCRIPTION: |
2670 * Interpret the content of an AVP of Derived type and store the result in data pointer. The structure | 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 * of the type. | 2672 * of the type. |
2673 * | 2673 * |
2674 * RETURN VALUE: | 2674 * RETURN VALUE: |
2675 * 0 : The avp_value has been set. | 2675 * 0 : The avp_value has been set. |
2676 * EINVAL : A parameter is invalid. | 2676 * EINVAL : A parameter is invalid. |
2685 | 2685 |
2686 /* | 2686 /* |
2687 * FUNCTION: fd_msg_bufferize | 2687 * FUNCTION: fd_msg_bufferize |
2688 * | 2688 * |
2689 * PARAMETERS: | 2689 * PARAMETERS: |
2690 * msg : A valid msg object. All AVPs must have a value set. | 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). | 2691 * buffer : Upon success, this points to a buffer (malloc'd) containing the message ready for network transmission (or security transformations). |
2692 * The buffer may be freed after use. | 2692 * The buffer may be freed after use. |
2693 * len : if not NULL, the size of the buffer is written here. In any case, this size is updated in the msg header. | 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 * Renders a message in memory as a buffer that can be sent over the network to the next peer. | 2696 * Renders a message in memory as a buffer that can be sent over the network to the next peer. |
2697 * | 2697 * |
2698 * RETURN VALUE: | 2698 * RETURN VALUE: |
2699 * 0 : The location has been written. | 2699 * 0 : The location has been written. |
2700 * EINVAL : The buffer does not contain a valid Diameter message. | 2700 * EINVAL : The buffer does not contain a valid Diameter message. |
2704 | 2704 |
2705 /* | 2705 /* |
2706 * FUNCTION: fd_msg_parse_buffer | 2706 * FUNCTION: fd_msg_parse_buffer |
2707 * | 2707 * |
2708 * PARAMETERS: | 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 * buflen : the size in bytes of the buffer. | 2710 * buflen : the size in bytes of the buffer. |
2711 * msg : Upon success, this points to a valid msg object. No AVP value is resolved in this object, nor grouped AVP. | 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 * This function parses a buffer an creates a msg object to represent the structure of the message. | 2714 * This function parses a buffer an creates a msg object to represent the structure of the message. |
2715 * Since no dictionary lookup is performed, the values of the AVPs are not interpreted. To interpret the values, | 2715 * Since no dictionary lookup is performed, the values of the AVPs are not interpreted. To interpret the values, |
2716 * the returned message object must be passed to fd_msg_parse_dict function. | 2716 * the returned message object must be passed to fd_msg_parse_dict function. |
2717 * The buffer pointer is saved inside the message and will be freed when not needed anymore. | 2717 * The buffer pointer is saved inside the message and will be freed when not needed anymore. |
2718 * | 2718 * |
2739 * PARAMETERS: | 2739 * PARAMETERS: |
2740 * object : A msg or AVP object as returned by fd_msg_parse_buffer. | 2740 * object : A msg or AVP object as returned by fd_msg_parse_buffer. |
2741 * dict : the dictionary containing the objects definitions to use for resolving all AVPs. | 2741 * dict : the dictionary containing the objects definitions to use for resolving all AVPs. |
2742 * error_info : If not NULL, will contain the detail about error upon return. May be used to generate an error reply. | 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 * This function looks up for the command and each children AVP definitions in the dictionary. | 2745 * This function looks up for the command and each children AVP definitions in the dictionary. |
2746 * If the dictionary definition is found, avp_model is set and the value of the AVP is interpreted accordingly and: | 2746 * If the dictionary definition is found, avp_model is set and the value of the AVP is interpreted accordingly and: |
2747 * - for grouped AVPs, the children AVP are created and interpreted also. | 2747 * - for grouped AVPs, the children AVP are created and interpreted also. |
2748 * - for numerical AVPs, the value is converted to host byte order and saved in the avp_value field. | 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 * If the dictionary definition is not found, avp_model is set to NULL and | 2750 * If the dictionary definition is not found, avp_model is set to NULL and |
2751 * the content of the AVP is saved as an octetstring in an internal structure. avp_value is NULL. | 2751 * the content of the AVP is saved as an octetstring in an internal structure. avp_value is NULL. |
2752 * As a result, after this function has been called, there is no more dependency of the msg object to the message buffer, that is freed. | 2752 * As a result, after this function has been called, there is no more dependency of the msg object to the message buffer, that is freed. |
2753 * | 2753 * |
2754 * RETURN VALUE: | 2754 * RETURN VALUE: |
2765 * PARAMETERS: | 2765 * PARAMETERS: |
2766 * object : A msg or grouped avp object that must be verified. | 2766 * object : A msg or grouped avp object that must be verified. |
2767 * dict : The dictionary containing the rules definitions. | 2767 * dict : The dictionary containing the rules definitions. |
2768 * error_info : If not NULL, the first problem information will be saved here. | 2768 * error_info : If not NULL, the first problem information will be saved here. |
2769 * | 2769 * |
2770 * DESCRIPTION: | 2770 * DESCRIPTION: |
2771 * Check that the children of the object do not conflict with the dictionary rules (ABNF compliance). | 2771 * Check that the children of the object do not conflict with the dictionary rules (ABNF compliance). |
2772 * | 2772 * |
2773 * RETURN VALUE: | 2773 * RETURN VALUE: |
2774 * 0 : The message has been fully parsed and complies to the defined rules. | 2774 * 0 : The message has been fully parsed and complies to the defined rules. |
2775 * EBADMSG : A conflict was detected, or a mandatory AVP is unknown in the dictionary. | 2775 * EBADMSG : A conflict was detected, or a mandatory AVP is unknown in the dictionary. |
2782 | 2782 |
2783 /* | 2783 /* |
2784 * FUNCTION: fd_msg_update_length | 2784 * FUNCTION: fd_msg_update_length |
2785 * | 2785 * |
2786 * PARAMETERS: | 2786 * PARAMETERS: |
2787 * object : Pointer to a valid msg or avp. | 2787 * object : Pointer to a valid msg or avp. |
2788 * | 2788 * |
2789 * DESCRIPTION: | 2789 * DESCRIPTION: |
2790 * Update the length field of the object passed as parameter. | 2790 * Update the length field of the object passed as parameter. |
2791 * As a side effect, all children objects are also updated. Therefore, all avp_value fields of | 2791 * As a side effect, all children objects are also updated. Therefore, all avp_value fields of |
2792 * the children AVPs must be set, or an error will occur. | 2792 * the children AVPs must be set, or an error will occur. |
2793 * | 2793 * |
2794 * RETURN VALUE: | 2794 * RETURN VALUE: |
2886 * The "command" field may also be set to a valid DICT_COMMAND object. | 2886 * The "command" field may also be set to a valid DICT_COMMAND object. |
2887 * The content of the "value" field is ignored. | 2887 * The content of the "value" field is ignored. |
2888 * | 2888 * |
2889 * DISP_HOW_AVP_ENUMVAL. | 2889 * DISP_HOW_AVP_ENUMVAL. |
2890 * All fields have the same constraints and meaning as in DISP_REG_AVP. In addition, the "value" field must be set | 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 * Here is a sumary of the fields: ( M : must be set; m : may be set; 0 : ignored ) | 2893 * Here is a sumary of the fields: ( M : must be set; m : may be set; 0 : ignored ) |
2894 * field: app_id command avp value | 2894 * field: app_id command avp value |
2895 * APPID : M 0 0 0 | 2895 * APPID : M 0 0 0 |
2896 * CC : m M 0 0 | 2896 * CC : m M 0 0 |
2913 * avp : for callbacks registered with DISP_HOW_AVP or DISP_HOW_AVP_ENUMVAL, direct link to the triggering AVP. | 2913 * avp : for callbacks registered with DISP_HOW_AVP or DISP_HOW_AVP_ENUMVAL, direct link to the triggering AVP. |
2914 * session : if the message contains a Session-Id AVP, the corresponding session object, NULL otherwise. | 2914 * session : if the message contains a Session-Id AVP, the corresponding session object, NULL otherwise. |
2915 * opaque : An opaque pointer that is registered along the session handler. | 2915 * opaque : An opaque pointer that is registered along the session handler. |
2916 * action : upon return, this tells the daemon what to do next. | 2916 * action : upon return, this tells the daemon what to do next. |
2917 * | 2917 * |
2918 * DESCRIPTION: | 2918 * DESCRIPTION: |
2919 * Called when a received message matchs the condition for which the callback was registered. | 2919 * Called when a received message matchs the condition for which the callback was registered. |
2920 * This callback may do any kind of processing on the message, including: | 2920 * This callback may do any kind of processing on the message, including: |
2921 * - create an answer for a request. | 2921 * - create an answer for a request. |
2922 * - proxy a request or message, add / remove the Proxy-Info AVP, then forward the message. | 2922 * - proxy a request or message, add / remove the Proxy-Info AVP, then forward the message. |
2923 * - update a routing table or start a connection with a new peer, then forward the message. | 2923 * - update a routing table or start a connection with a new peer, then forward the message. |
2924 * - ... | 2924 * - ... |
2925 * | 2925 * |
2926 * When *action == DISP_ACT_SEND on callback return, the msg pointed by *msg is passed to the routing module for sending. | 2926 * When *action == DISP_ACT_SEND on callback return, the msg pointed by *msg is passed to the routing module for sending. |
2927 * When *action == DISP_ACT_CONT, the next registered callback is called. | 2927 * When *action == DISP_ACT_CONT, the next registered callback is called. |
2928 * When the last callback gives also DISP_ACT_CONT action value, a default handler is called. It's behavior is as follow: | 2928 * When the last callback gives also DISP_ACT_CONT action value, a default handler is called. It's behavior is as follow: |
2929 * - if the message is an answer, it is discarded. | 2929 * - if the message is an answer, it is discarded. |
2930 * - if the message is a request, it is passed again to the routing stack, and marked as non-local handling. | 2930 * - if the message is a request, it is passed again to the routing stack, and marked as non-local handling. |
2943 * PARAMETERS: | 2943 * PARAMETERS: |
2944 * cb : The callback function to register (see dispatch_callback description above). | 2944 * cb : The callback function to register (see dispatch_callback description above). |
2945 * how : How the callback must be registered. | 2945 * how : How the callback must be registered. |
2946 * when : Values that must match, depending on the how argument. | 2946 * when : Values that must match, depending on the how argument. |
2947 * opaque : A pointer that is passed back to the handler. The content is not interpreted by the framework. | 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 * This handler can be used to unregister the cb. | 2949 * This handler can be used to unregister the cb. |
2950 * | 2950 * |
2951 * DESCRIPTION: | 2951 * DESCRIPTION: |
2952 * Register a new callback to handle messages delivered locally. | 2952 * Register a new callback to handle messages delivered locally. |
2953 * | 2953 * |
2954 * RETURN VALUE: | 2954 * RETURN VALUE: |
2955 * 0 : The callback is registered. | 2955 * 0 : The callback is registered. |
2956 * EINVAL : A parameter is invalid. | 2956 * EINVAL : A parameter is invalid. |
2957 * ENOMEM : Not enough memory to complete the operation | 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 enum disp_how how, struct disp_when * when, void * opaque, struct disp_hdl ** handle ); | 2960 enum disp_how how, struct disp_when * when, void * opaque, struct disp_hdl ** handle ); |
2961 | 2961 |
2962 /* | 2962 /* |
2963 * FUNCTION: fd_disp_unregister | 2963 * FUNCTION: fd_disp_unregister |
2964 * | 2964 * |
2965 * PARAMETERS: | 2965 * PARAMETERS: |
2966 * handle : Location of the handle of the callback that must be unregistered. | 2966 * handle : Location of the handle of the callback that must be unregistered. |
2967 * opaque : If not NULL, the opaque data that was registered is restored here. | 2967 * opaque : If not NULL, the opaque data that was registered is restored here. |
2968 * | 2968 * |
2969 * DESCRIPTION: | 2969 * DESCRIPTION: |
2970 * Removes a callback previously registered by fd_disp_register. | 2970 * Removes a callback previously registered by fd_disp_register. |
2971 * | 2971 * |
2972 * RETURN VALUE: | 2972 * RETURN VALUE: |
2973 * 0 : The callback is unregistered. | 2973 * 0 : The callback is unregistered. |
2974 * EINVAL : A parameter is invalid. | 2974 * EINVAL : A parameter is invalid. |
2987 * action : Upon return, the action that must be taken on the message | 2987 * action : Upon return, the action that must be taken on the message |
2988 * error_code : Upon return with action == DISP_ACT_ERROR, contains the error (such as "DIAMETER_UNABLE_TO_COMPLY") | 2988 * error_code : Upon return with action == DISP_ACT_ERROR, contains the error (such as "DIAMETER_UNABLE_TO_COMPLY") |
2989 * drop_reason : if set on return, the message must be freed for this reason. | 2989 * drop_reason : if set on return, the message must be freed for this reason. |
2990 * drop_msg : if drop_reason is set, this points to the message to be freed while *msg is NULL. | 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 * Call all handlers registered for a given message. | 2993 * Call all handlers registered for a given message. |
2994 * The session must have already been resolved on entry. | 2994 * The session must have already been resolved on entry. |
2995 * The msg pointed may be updated during this process. | 2995 * The msg pointed may be updated during this process. |
2996 * Upon return, the action parameter points to what must be done next. | 2996 * Upon return, the action parameter points to what must be done next. |
2997 * | 2997 * |
3019 * PARAMETERS: | 3019 * PARAMETERS: |
3020 * queue : Upon success, a pointer to the new queue is saved here. | 3020 * queue : Upon success, a pointer to the new queue is saved here. |
3021 * max : max number of items in the queue. Above this number, adding a new item becomes a | 3021 * max : max number of items in the queue. Above this number, adding a new item becomes a |
3022 * blocking operation. Use 0 to disable this maximum. | 3022 * blocking operation. Use 0 to disable this maximum. |
3023 * | 3023 * |
3024 * DESCRIPTION: | 3024 * DESCRIPTION: |
3025 * Create a new empty queue. | 3025 * Create a new empty queue. |
3026 * | 3026 * |
3027 * RETURN VALUE : | 3027 * RETURN VALUE : |
3028 * 0 : The queue has been initialized successfully. | 3028 * 0 : The queue has been initialized successfully. |
3029 * EINVAL : The parameter is invalid. | 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 int fd_fifo_new ( struct fifo ** queue, int max ); | 3032 int fd_fifo_new ( struct fifo ** queue, int max ); |
3033 | 3033 |
3034 /* | 3034 /* |
3035 * FUNCTION: fd_fifo_del | 3035 * FUNCTION: fd_fifo_del |
3036 * | 3036 * |
3037 * PARAMETERS: | 3037 * PARAMETERS: |
3038 * queue : Pointer to an empty queue to delete. | 3038 * queue : Pointer to an empty queue to delete. |
3039 * | 3039 * |
3040 * DESCRIPTION: | 3040 * DESCRIPTION: |
3041 * Destroys a queue. This is only possible if no thread is waiting for an element, | 3041 * Destroys a queue. This is only possible if no thread is waiting for an element, |
3042 * and the queue is empty. | 3042 * and the queue is empty. |
3043 * | 3043 * |
3044 * RETURN VALUE: | 3044 * RETURN VALUE: |
3045 * 0 : The queue has been destroyed successfully. | 3045 * 0 : The queue has been destroyed successfully. |
3053 * PARAMETERS: | 3053 * PARAMETERS: |
3054 * oldq : Location of a FIFO that is to be emptied. | 3054 * oldq : Location of a FIFO that is to be emptied. |
3055 * newq : A FIFO that will receive the old data. | 3055 * newq : A FIFO that will receive the old data. |
3056 * loc_update : if non NULL, a place to store the pointer to new FIFO atomically with the move. | 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 * Empties a queue and move its content to another one atomically. | 3059 * Empties a queue and move its content to another one atomically. |
3060 * | 3060 * |
3061 * RETURN VALUE: | 3061 * RETURN VALUE: |
3062 * 0 : The queue has been destroyed successfully. | 3062 * 0 : The queue has been destroyed successfully. |
3063 * EINVAL : A parameter is invalid. | 3063 * EINVAL : A parameter is invalid. |
3074 * highest_count : The maximum number of items this queue has contained. This enables to see if limit_count count was reached. | 3074 * highest_count : The maximum number of items this queue has contained. This enables to see if limit_count count was reached. |
3075 * total_count : the total number of items that went through the queue (already pop'd). Always increasing. | 3075 * total_count : the total number of items that went through the queue (already pop'd). Always increasing. |
3076 * total : Cumulated time all items spent in this queue, including blocking time (always growing, use deltas for monitoring) | 3076 * total : Cumulated time all items spent in this queue, including blocking time (always growing, use deltas for monitoring) |
3077 * blocking : Cumulated time threads trying to post new items were blocked (queue full). | 3077 * blocking : Cumulated time threads trying to post new items were blocked (queue full). |
3078 * last : For the last element retrieved from the queue, how long it take between posting (including blocking) and poping | 3078 * last : For the last element retrieved from the queue, how long it take between posting (including blocking) and poping |
3079 * | 3079 * |
3080 * DESCRIPTION: | 3080 * DESCRIPTION: |
3081 * Retrieve the timing information associated with a queue, for monitoring purpose. | 3081 * Retrieve the timing information associated with a queue, for monitoring purpose. |
3082 * | 3082 * |
3083 * RETURN VALUE: | 3083 * RETURN VALUE: |
3084 * 0 : The statistics have been updated. | 3084 * 0 : The statistics have been updated. |
3085 * EINVAL : A parameter is invalid. | 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 struct timespec * total, struct timespec * blocking, struct timespec * last); | 3088 struct timespec * total, struct timespec * blocking, struct timespec * last); |
3089 | 3089 |
3090 /* | 3090 /* |
3091 * FUNCTION: fd_fifo_length | 3091 * FUNCTION: fd_fifo_length |
3092 * | 3092 * |
3093 * PARAMETERS: | 3093 * PARAMETERS: |
3094 * queue : The queue from which to retrieve the number of elements. | 3094 * queue : The queue from which to retrieve the number of elements. |
3095 * | 3095 * |
3096 * DESCRIPTION: | 3096 * DESCRIPTION: |
3097 * Retrieve the number of elements in a queue, without error checking. | 3097 * Retrieve the number of elements in a queue, without error checking. |
3098 * | 3098 * |
3099 * RETURN VALUE: | 3099 * RETURN VALUE: |
3100 * The number of items currently queued. | 3100 * The number of items currently queued. |
3101 */ | 3101 */ |
3110 * high : The high-level threshold. If the number of elements in the queue increase to this value, h_cb is called. | 3110 * high : The high-level threshold. If the number of elements in the queue increase to this value, h_cb is called. |
3111 * h_cb : if not NULL, a callback to call when the queue lengh is bigger than "high". | 3111 * h_cb : if not NULL, a callback to call when the queue lengh is bigger than "high". |
3112 * low : The low-level threshold. Must be < high. | 3112 * low : The low-level threshold. Must be < high. |
3113 * l_cb : If the number of elements decrease to low, this callback is called. | 3113 * l_cb : If the number of elements decrease to low, this callback is called. |
3114 * | 3114 * |
3115 * DESCRIPTION: | 3115 * DESCRIPTION: |
3116 * This function allows to adjust the number of producer / consumer threads of a queue. | 3116 * This function allows to adjust the number of producer / consumer threads of a queue. |
3117 * If the consumer are slower than the producers, the number of elements in the queue increase. | 3117 * If the consumer are slower than the producers, the number of elements in the queue increase. |
3118 * By setting a "high" value, we allow a callback to be called when this number is too high. | 3118 * By setting a "high" value, we allow a callback to be called when this number is too high. |
3119 * The typical use would be to create an additional consumer thread in this callback. | 3119 * The typical use would be to create an additional consumer thread in this callback. |
3120 * If the queue continues to grow, the callback will be called again when the length is 2 * high, then 3*high, ... N * high | 3120 * If the queue continues to grow, the callback will be called again when the length is 2 * high, then 3*high, ... N * high |
3139 * | 3139 * |
3140 * PARAMETERS: | 3140 * PARAMETERS: |
3141 * queue : The queue in which the element must be posted. | 3141 * queue : The queue in which the element must be posted. |
3142 * item : The element that is put in the queue. | 3142 * item : The element that is put in the queue. |
3143 * | 3143 * |
3144 * DESCRIPTION: | 3144 * DESCRIPTION: |
3145 * An element is added in a queue. Elements are retrieved from the queue in FIFO order | 3145 * An element is added in a queue. Elements are retrieved from the queue in FIFO order |
3146 * with the fd_fifo_get, fd_fifo_tryget, or fd_fifo_timedget functions. | 3146 * with the fd_fifo_get, fd_fifo_tryget, or fd_fifo_timedget functions. |
3147 * | 3147 * |
3148 * RETURN VALUE: | 3148 * RETURN VALUE: |
3149 * 0 : The element is queued. | 3149 * 0 : The element is queued. |
3163 * | 3163 * |
3164 * PARAMETERS: | 3164 * PARAMETERS: |
3165 * queue : The queue from which the first element must be retrieved. | 3165 * queue : The queue from which the first element must be retrieved. |
3166 * item : On return, the first element of the queue is stored here. | 3166 * item : On return, the first element of the queue is stored here. |
3167 * | 3167 * |
3168 * DESCRIPTION: | 3168 * DESCRIPTION: |
3169 * This function retrieves the first element from a queue. If the queue is empty, the function will block the | 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 | 3170 * thread until a new element is posted to the queue, or until the thread is canceled (in which case the |
3171 * function does not return). | 3171 * function does not return). |
3172 * | 3172 * |
3173 * RETURN VALUE: | 3173 * RETURN VALUE: |
3174 * 0 : A new element has been retrieved. | 3174 * 0 : A new element has been retrieved. |
3175 * EINVAL : A parameter is invalid. | 3175 * EINVAL : A parameter is invalid. |
3183 * | 3183 * |
3184 * PARAMETERS: | 3184 * PARAMETERS: |
3185 * queue : The queue from which the element must be retrieved. | 3185 * queue : The queue from which the element must be retrieved. |
3186 * item : On return, the first element of the queue is stored here. | 3186 * item : On return, the first element of the queue is stored here. |
3187 * | 3187 * |
3188 * DESCRIPTION: | 3188 * DESCRIPTION: |
3189 * This function is similar to fd_fifo_get, except that it will not block if | 3189 * This function is similar to fd_fifo_get, except that it will not block if |
3190 * the queue is empty, but return EWOULDBLOCK instead. | 3190 * the queue is empty, but return EWOULDBLOCK instead. |
3191 * | 3191 * |
3192 * RETURN VALUE: | 3192 * RETURN VALUE: |
3193 * 0 : A new element has been retrieved. | 3193 * 0 : A new element has been retrieved. |
3194 * EINVAL : A parameter is invalid. | 3194 * EINVAL : A parameter is invalid. |
3204 * PARAMETERS: | 3204 * PARAMETERS: |
3205 * queue : The queue from which the element must be retrieved. | 3205 * queue : The queue from which the element must be retrieved. |
3206 * item : On return, the element is stored here. | 3206 * item : On return, the element is stored here. |
3207 * abstime : the absolute time until which we allow waiting for an item. | 3207 * abstime : the absolute time until which we allow waiting for an item. |
3208 * | 3208 * |
3209 * DESCRIPTION: | 3209 * DESCRIPTION: |
3210 * This function is similar to fd_fifo_get, except that it will block if the queue is empty | 3210 * This function is similar to fd_fifo_get, except that it will block if the queue is empty |
3211 * only until the absolute time abstime (see pthread_cond_timedwait for + info). | 3211 * only until the absolute time abstime (see pthread_cond_timedwait for + info). |
3212 * If the queue is still empty when the time expires, the function returns ETIMEDOUT | 3212 * If the queue is still empty when the time expires, the function returns ETIMEDOUT |
3213 * | 3213 * |
3214 * RETURN VALUE: | 3214 * RETURN VALUE: |
3215 * 0 : A new item has been retrieved. | 3215 * 0 : A new item has been retrieved. |
3226 * | 3226 * |
3227 * PARAMETERS: | 3227 * PARAMETERS: |
3228 * queue : The queue to test. | 3228 * queue : The queue to test. |
3229 * abstime : the absolute time until which we can block waiting for an item. If NULL, the function returns immediatly. | 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 * This function is similar to select(), it waits for data to be available in the queue | 3232 * This function is similar to select(), it waits for data to be available in the queue |
3233 * until the abstime is expired. | 3233 * until the abstime is expired. |
3234 * Upon function entry, even if abstime is already expired the data availability is tested. | 3234 * Upon function entry, even if abstime is already expired the data availability is tested. |
3235 * | 3235 * |
3236 * RETURN VALUE: | 3236 * RETURN VALUE: |