1 /*********************************************************************************************************
2 * Software License Agreement (BSD License) *
3 * Author: Sebastien Decugis <sdecugis@freediameter.net> *
4 * *
5 * Copyright (c) 2020, WIDE Project and NICT *
6 * All rights reserved. *
7 * *
8 * Redistribution and use of this software in source and binary forms, with or without modification, are *
9 * permitted provided that the following conditions are met: *
10 * *
11 * * Redistributions of source code must retain the above *
12 * copyright notice, this list of conditions and the *
13 * following disclaimer. *
14 * *
15 * * Redistributions in binary form must reproduce the above *
16 * copyright notice, this list of conditions and the *
17 * following disclaimer in the documentation and/or other *
18 * materials provided with the distribution. *
19 * *
20 * * Neither the name of the WIDE Project or NICT nor the *
21 * names of its contributors may be used to endorse or *
22 * promote products derived from this software without *
23 * specific prior written permission of WIDE Project and *
24 * NICT. *
25 * *
26 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED *
27 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A *
28 * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR *
29 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT *
30 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS *
31 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR *
32 * TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY S_OUT OF THE USE OF THIS SOFTWARE, EVEN IF *
33 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. *
34 *********************************************************************************************************/
35
36 /* This file contains the definitions of functions and types used by the libfreeDiameter library.
37 *
38 * This library is meant to be used by both the freeDiameter daemon and its extensions.
39 * It provides the tools to manipulate Diameter messages and related data.
40 * This file should always be included as #include <freeDiameter/libfreeDiameter.h>
41 *
42 * If any change is made to this file, you must increment the FD_PROJECT_VERSION_API version.
43 *
44 * The file contains the following parts:
45 * DEBUG
46 * MACROS
47 * OCTET STRINGS
48 * THREADS
49 * LISTS
50 * DICTIONARY
51 * SESSIONS
52 * MESSAGES
53 * DISPATCH
54 * QUEUES
55 */
56
57 #ifndef _LIBFDPROTO_H
58 #define _LIBFDPROTO_H
59
60 #ifdef __cplusplus
61 extern "C" {
62 #endif
63
64 #ifndef FD_IS_CONFIG
65 #error "You must include 'freeDiameter-host.h' before this file."
66 #endif /* FD_IS_CONFIG */
67
68 #include <pthread.h>
69 #include <sched.h>
70 #include <string.h>
71 #include <assert.h>
72 #include <errno.h>
73 #include <netinet/in.h>
74 #include <arpa/inet.h>
75 #include <sys/socket.h>
76 #include <netdb.h>
77 #include <stdio.h>
78 #include <stdlib.h>
79 #include <unistd.h>
80 #include <stdarg.h>
81
82 #include <libgen.h> /* for basename */
83
84 #ifdef SWIG
85 #define _ATTRIBUTE_PRINTFLIKE_(_f,_v)
86 #else
87 #define _ATTRIBUTE_PRINTFLIKE_(_f,_v) __attribute__ ((format (printf, _f, _v)))
88 #endif /* SWIG */
89
90 /* Remove some deprecated warnings from some gnutls versions, when possible */
91 #if defined(__GNUC__)
92 # define GCC_DIAG_DO_PRAGMA(x) _Pragma (#x)
93 # define GCC_DIAG_PRAGMA(x) GCC_DIAG_DO_PRAGMA(GCC diagnostic x)
94 # if ((__GNUC__ * 100) + __GNUC_MINOR__) >= 406 /* 4.6.x */
95 # define GCC_DIAG_OFF(x) GCC_DIAG_PRAGMA(push) \
96 GCC_DIAG_PRAGMA(ignored x)
97 # define GCC_DIAG_ON(x) GCC_DIAG_PRAGMA(pop)
98 # else /* older */
99 # define GCC_DIAG_OFF(x) GCC_DIAG_PRAGMA(ignored x)
100 # define GCC_DIAG_ON(x) GCC_DIAG_PRAGMA(warning x)
101 # endif
102 #else
103 # define GCC_DIAG_OFF(x)
104 # define GCC_DIAG_ON(x)
105 #endif
106
107 /*============================================================*/
108 /* CONSTANTS */
109 /*============================================================*/
110
111 #define DIAMETER_PORT 3868
112 #define DIAMETER_SECURE_PORT 5868
113
114
115 /*============================================================*/
116 /* INIT */
117 /*============================================================*/
118
119 /* This function must be called first, before any call to another library function */
120 int fd_libproto_init(void); /* note if you are using libfdcore, it handles this already */
121
122 /* Call this one when the application terminates, to destroy internal threads */
123 void fd_libproto_fini(void);
124
125 /* Retrieve the version of the binary */
126 extern const char fd_libproto_version[];
127
128 /*============================================================*/
129 /* DEBUG */
130 /*============================================================*/
131
132
133 /*
134 * FUNCTION: fd_log
135 *
136 * PARAMETERS:
137 * loglevel : Integer, how important the message is. Valid values are macros FD_LOG_*
138 * format : Same format string as in the printf function
139 * ... : Same list as printf
140 *
141 * DESCRIPTION:
142 * Write information to log.
143 * The format and arguments may contain UTF-8 encoded data. The
144 * output medium is expected to support this encoding.
145 *
146 * RETURN VALUE:
147 * None.
148 */
149 void fd_log ( int, const char *, ... ) _ATTRIBUTE_PRINTFLIKE_(2,3);
150 #ifndef SWIG
151 void fd_log_va( int, const char *, va_list);
152 #endif /* SWIG */
153
154 /* these are internal objects of the debug facility,
155 might be useful to control the behavior from outside */
156 extern pthread_mutex_t fd_log_lock;
157 extern char * fd_debug_one_function;
158 extern char * fd_debug_one_file;
159
160 /*
161 * FUNCTION: fd_log_threadname
162 *
163 * PARAMETERS:
164 * name : \0-terminated string containing a name to identify the current thread.
165 *
166 * DESCRIPTION:
167 * Name the current thread, useful for debugging multi-threaded problems.
168 *
169 * This function assumes that a global thread-specific key called "fd_log_thname" exists
170 * in the address space of the current process.
171 *
172 * RETURN VALUE:
173 * None.
174 */
175 void fd_log_threadname ( const char * name );
176 extern pthread_key_t fd_log_thname;
177
178 /*
179 * FUNCTION: fd_log_time
180 *
181 * PARAMETERS:
182 * ts : The timestamp to log, or NULL for "now"
183 * buf : An array where the time must be stored
184 * len : size of the buffer
185 * incl_date : The day of year is included in the output
186 * incl_ms : millisecond value is included in the output
187 *
188 * DESCRIPTION:
189 * Writes the timestamp (in human readable format) in a buffer.
190 *
191 * RETURN VALUE:
192 * pointer to buf.
193 */
194 char * fd_log_time ( struct timespec * ts, char * buf, size_t len, int incl_date, int incl_ms );
195
196 /*
197 * FUNCTION: fd_log_handler_register
198 * MACRO:
199 *
200 * PARAMETERS:
201 * loglevel : priority of the message
202 * format : Same format string as in the printf function
203 * va_list : Argument list
204 *
205 * DESCRIPTION:
206 * Register an external method for logging purposes.
207 *
208 * RETURN VALUE:
209 * int : Success or failure
210 */
211 int fd_log_handler_register ( void (*logger)(int loglevel, const char * format, va_list args) );
212
213 /*
214 * FUNCTION: fd_log_handler_unregister
215 * MACRO:
216 *
217 * PARAMETERS:
218 *
219 * DESCRIPTION:
220 * Unregister the external logging function.
221 *
222 * RETURN VALUE:
223 * int : Success or failure
224 */
225 int fd_log_handler_unregister ( void );
226
227
228 /* All dump functions follow this same prototype:
229 * PARAMETERS:
230 * buf : *buf can be NULL on entry, it will be malloc'd. Otherwise it is realloc'd if needed.
231 * len : the current size of the buffer (in/out)
232 * offset: (optional) if provided, starts writing dump at offset in the buffer, and updated upon exit. if NULL, starts at offset O.
233 *
234 * RETURN VALUE:
235 * *buf upon success, NULL upon failure.
236 *
237 * REMARKS:
238 * - After the buffer has been used, it should be freed.
239 * - Depending on the function, the created string may be multi-line. However, it should never be terminated with a '\n'.
240 */
241 #define DECLARE_FD_DUMP_PROTOTYPE( function_name, args... ) \
242 char * function_name(char ** buf, size_t *len, size_t *offset, ##args)
243
244 #ifdef SWIG
245 #define DECLARE_FD_DUMP_PROTOTYPE_simple( function_name ) \
246 char * function_name(char ** buf, size_t *len, size_t *offset)
247 #endif /* SWIG */
248
249
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);
252 DECLARE_FD_DUMP_PROTOTYPE( fd_dump_extend_hexdump, uint8_t *data, size_t datalen, size_t trunc, size_t wrap );
253
254
255 /* Some helpers macro for writing such *_dump routine */
256 #define FD_DUMP_STD_PARAMS buf, len, offset
257 #define FD_DUMP_HANDLE_OFFSET() size_t o = 0; if (!offset) offset = &o; if (buf && (*buf) && !(*offset)) **buf='\0'
258 #define FD_DUMP_HANDLE_TRAIL() while ((*buf) && (*offset > 0) && ((*buf)[*offset - 1] == '\n')) { *offset -= 1; (*buf)[*offset] = '\0'; }
259
260
261
262 /*============================================================*/
263 /* DEBUG MACROS */
264 /*============================================================*/
265
266 #ifndef ASSERT
267 #define ASSERT(x) assert(x)
268 #endif /* ASSERT */
269
270 /* log levels definitions, that are passed to the logger */
271 #define FD_LOG_ANNOYING 0 /* very verbose loops and such "overkill" traces. Only active when the framework is compiled in DEBUG mode. */
272 #define FD_LOG_DEBUG 1 /* Get a detailed sense of what is going on in the framework. Use this level for normal debug */
273 #define FD_LOG_INFO 2 /* Informational execution states */
274 #define FD_LOG_NOTICE 3 /* Normal execution states worth noting */
275 #define FD_LOG_ERROR 5 /* Recoverable or expected error conditions */
276 #define FD_LOG_FATAL 6 /* Unrecoverable error, e.g. malloc fail, etc. that requires the framework to shutdown */
277
278 /* The level used by the default logger, can be changed by command-line arguments. Ignored for other loggers. */
279 extern int fd_g_debug_lvl;
280
281 /* Some portability code to get nice function name in __PRETTY_FUNCTION__ */
282 #if (!defined( __func__)) && (__STDC_VERSION__ < 199901L)
283 # if __GNUC__ >= 2
284 # define __func__ __FUNCTION__
285 # else /* __GNUC__ >= 2 */
286 # define __func__ "<unknown>"
287 # endif /* __GNUC__ >= 2 */
288 #endif /*(!defined( __func__)) && (__STDC_VERSION__ < 199901L) */
289 #ifndef __PRETTY_FUNCTION__
290 #define __PRETTY_FUNCTION__ __func__
291 #endif /* __PRETTY_FUNCTION__ */
292
293 /* A version of __FILE__ without the full path. This is specific to each C file being compiled */
294 static char * file_bname = NULL;
file_bname_init(const char * full)295 static char * file_bname_init(const char * full) {
296 /* Since FreeBSD 12.0, basename() modifies the provided
297 * input buffer, so we must strdup() the input string,
298 * otherwise we'd segfault on __FILE__ which is const. */
299 file_bname = basename(strdup(full));
300 return file_bname; }
301 #define __STRIPPED_FILE__ (file_bname ?: file_bname_init(__FILE__))
302
303
304
305 /* In DEBUG mode, we add meta-information along each trace. This makes multi-threading problems easier to debug. */
306 #if (defined(DEBUG) && defined(DEBUG_WITH_META))
307 # define STD_TRACE_FMT_STRING "pid:%s in %s@%s:%d: "
308 # define STD_TRACE_FMT_ARGS , ((char *)pthread_getspecific(fd_log_thname) ?: "unnamed"), __PRETTY_FUNCTION__, __STRIPPED_FILE__, __LINE__
309 #else /* DEBUG && DEBUG_WITH_META */
310 # define STD_TRACE_FMT_STRING ""
311 # define STD_TRACE_FMT_ARGS
312 #endif /* DEBUG && DEBUG_WITH_META */
313
314 /*************************
315 The general debug macro
316 *************************/
317 #define LOG(printlevel,format,args... ) \
318 fd_log((printlevel), STD_TRACE_FMT_STRING format STD_TRACE_FMT_ARGS, ## args)
319
320 /*
321 * Use the following macros in the code to get traces with location & pid in debug mode:
322 */
323 #ifdef DEBUG
324 # define LOG_A(format,args... ) \
325 do { if ((fd_debug_one_function && !strcmp(fd_debug_one_function, __PRETTY_FUNCTION__)) \
326 || (fd_debug_one_file && !strcmp(fd_debug_one_file, __STRIPPED_FILE__) ) ) { \
327 LOG(FD_LOG_DEBUG,"[DBG_MATCH] " format,##args); \
328 } else { \
329 LOG(FD_LOG_ANNOYING,format,##args); \
330 } } while (0)
331 #else /* DEBUG */
332 # define LOG_A(format,args... ) /* not defined in release */
333 #endif /* DEBUG */
334
335 /* Debug information useful to follow in detail what is going on */
336 #define LOG_D(format,args... ) \
337 LOG(FD_LOG_DEBUG, format, ##args)
338
339 /* Report an info message */
340 #define LOG_I(format,args... ) \
341 LOG(FD_LOG_INFO, format,##args)
342
343 /* Report a normal message that is useful for normal admin monitoring */
344 #define LOG_N(format,args... ) \
345 LOG(FD_LOG_NOTICE, format,##args)
346
347 /* Report an error */
348 #define LOG_E(format,args... ) \
349 LOG(FD_LOG_ERROR, format, ##args)
350
351 /* Report a fatal error */
352 #define LOG_F(format,args... ) \
353 LOG(FD_LOG_FATAL, format, ##args)
354
355
356 /*************
357 Derivatives
358 ************/
359 /* Trace a binary buffer content */
360 #define LOG_BUFFER(printlevel, prefix, buf, bufsz, suffix ) { \
361 int __i; \
362 size_t __sz = (size_t)(bufsz); \
363 uint8_t * __buf = (uint8_t *)(buf); \
364 char __strbuf[1024+1]; \
365 for (__i = 0; (__i < __sz) && (__i<(sizeof(__strbuf)/2)); __i++) { \
366 sprintf(__strbuf + (2 * __i), "%02hhx", __buf[__i]); \
367 } \
368 fd_log(printlevel, STD_TRACE_FMT_STRING "%s%s%s" STD_TRACE_FMT_ARGS, \
369 (prefix), __strbuf, (suffix)); \
370 }
371
372 /* Split a multi-line buffer into separate calls to the LOG function. */
373 #define LOG_SPLIT(printlevel, per_line_prefix, mlbuf, per_line_suffix ) { \
374 char * __line = (mlbuf), *__next; \
375 char * __p = (per_line_prefix), *__s = (per_line_suffix); \
376 while ((__next = strchr(__line, '\n')) != NULL) { \
377 LOG(printlevel, "%s%.*s%s", __p ?:"", (int)(__next - __line), __line, __s ?:""); \
378 __line = __next + 1; \
379 } \
380 LOG(printlevel, "%s%s%s", __p ?:"", __line, __s ?:""); \
381 }
382
383 /* Helper for function entry -- for very detailed trace of the execution */
384 #define TRACE_ENTRY(_format,_args... ) \
385 LOG_A("[enter] %s(" _format ") {" #_args "}", __PRETTY_FUNCTION__, ##_args );
386
387 /* Helper for debugging by adding traces -- for debuging a specific location of the code */
388 #define TRACE_HERE() \
389 LOG_F(" -- debug checkpoint %d -- ", fd_breakhere());
390 int fd_breakhere(void);
391
392 /* Helper for tracing the CHECK_* macros below -- very very verbose code execution! */
393 #define TRACE_CALL( str... ) \
394 LOG_A( str )
395
396 /* For development only, to keep track of TODO locations in the code */
397 #ifndef ERRORS_ON_TODO
398 # define TODO( _msg, _args... ) \
399 LOG_F( "TODO: " _msg , ##_args);
400 #else /* ERRORS_ON_TODO */
401 # define TODO( _msg, _args... ) \
402 "TODO" = _msg ## _args; /* just a stupid compilation error to spot the todo */
403 #endif /* ERRORS_ON_TODO */
404
405
406 /*============================================================*/
407 /* ERROR CHECKING MACRO */
408 /*============================================================*/
409
410 /* Macros to check a return value and branch out in case of error.
411 * These macro additionally provide the logging information.
412 *
413 * The name "__ret__" is always available in the __fallback__ parameter and contains the error code.
414 */
415
416 #define CHECK_PRELUDE(__call__) \
417 int __ret__; \
418 TRACE_CALL("Check: %s", #__call__ ); \
419 __ret__ = (__call__)
420
421 #define DEFAULT_FB return __ret__;
422
423 /* System check: error case if < 0, error value in errno */
424 #define CHECK_SYS_GEN( faillevel, __call__, __fallback__ ) { \
425 CHECK_PRELUDE(__call__); \
426 if (__ret__ < 0) { \
427 __ret__ = errno; \
428 LOG(faillevel, "ERROR: in '%s' :\t%s", #__call__ , strerror(__ret__)); \
429 __fallback__; \
430 } \
431 }
432
433
434 /* Check the return value of a function and execute fallback in case of error or special value */
435 #define CHECK_FCT_GEN2( faillevel, __call__, __speval__, __fallback1__, __fallback2__ ) { \
436 CHECK_PRELUDE(__call__); \
437 if (__ret__ != 0) { \
438 if (__ret__ == (__speval__)) { \
439 __fallback1__; \
440 } else { \
441 LOG(faillevel, "ERROR: in '%s' :\t%s", #__call__ , strerror(__ret__)); \
442 __fallback2__; \
443 } \
444 } \
445 }
446
447 /* Check the return value of a function and execute fallback in case of error (return value different from 0) */
448 #define CHECK_FCT_GEN( faillevel, __call__, __fallback__) \
449 CHECK_FCT_GEN2( faillevel, (__call__), 0, , (__fallback__) )
450
451 /* Check that a memory allocator did not return NULL, otherwise log an error and execute fallback */
452 #define CHECK_MALLOC_GEN( faillevel, __call__, __fallback__ ) { \
453 void * __ptr__; \
454 TRACE_CALL("Check: %s", #__call__ ); \
455 __ptr__ = (void *)(__call__); \
456 if (__ptr__ == NULL) { \
457 int __ret__ = errno; \
458 LOG(faillevel, "ERROR: in '%s' :\t%s", #__call__ , strerror(__ret__)); \
459 __fallback__; \
460 } \
461 }
462
463 /* Check parameters at function entry, execute fallback on error */
464 #define CHECK_PARAMS_GEN( faillevel, __bool__, __fallback__ ) { \
465 TRACE_CALL("Check: %s", #__bool__ ); \
466 if ( ! (__bool__) ) { \
467 int __ret__ = EINVAL; \
468 LOG(faillevel, "ERROR: invalid parameter '%s'", #__bool__ ); \
469 __fallback__; \
470 } \
471 }
472
473
474 /*============================================================*/
475 /* COMPATIBILITY MACROS, TO BE REMOVED */
476 /*============================================================*/
477 /* Redefine the old macros for transition of the code */
478 #ifndef EXCLUDE_DEPRECATED
479
480 #define MARK_DEPRECATED /* __attribute__ ((deprecated)) */
481
482 enum old_levels {
483 NONE = 0,
484 INFO = 1,
485 FULL = 2,
486 ANNOYING = 4,
487 FCTS = 6,
488 CALL = 9
489 } MARK_DEPRECATED;
490
old_TRACE_BOOL(enum old_levels level,const char * file,const char * func)491 static __inline__ int old_TRACE_BOOL( enum old_levels level, const char * file, const char * func ) MARK_DEPRECATED
492 {
493 if ((fd_debug_one_function && !strcmp(fd_debug_one_function, func))
494 || (fd_debug_one_file && !strcmp(fd_debug_one_file, file) ))
495 return 2; /* Level override */
496 if ((int)level <= fd_g_debug_lvl)
497 return 1; /* Normal level */
498 return 0; /* No trace */
499 }
500 #define TRACE_BOOL(level) old_TRACE_BOOL((level), __STRIPPED_FILE__, __PRETTY_FUNCTION__)
501
502 #ifndef SWIG
fd_log_deprecated(int level,const char * format,...)503 static __inline__ void fd_log_deprecated( int level, const char *format, ... ) MARK_DEPRECATED
504 {
505 va_list ap;
506 va_start(ap, format);
507 fd_log_va(level, format, ap);
508 va_end(ap);
509 }
510 #else /* SWIG */
511 void fd_log_deprecated( int level, const char *format, ... );
512 #endif /* SWIG */
replace_me()513 static __inline__ void replace_me() MARK_DEPRECATED { }
514
515 #define TRACE_BUFFER(...) replace_me();
516 #define TRACE_NOTICE(...) replace_me();
517
518
519 /* Use the LOG_* instead, or use the new *_dump functions when dumping an object */
520 #define fd_log_debug(format,args...) fd_log_deprecated(FD_LOG_DEBUG, format, ## args)
521 #define fd_log_notice(format,args...) fd_log_deprecated(FD_LOG_NOTICE, format, ## args)
522 #define fd_log_error(format,args...) fd_log_deprecated(FD_LOG_ERROR, format, ## args)
523
524 /* old macro for traces. To be replaced by appropriate LOG_* macros. */
525 # define TRACE_DEBUG(oldlevel, format,args... ) { \
526 int __l__; \
527 if ((__l__ = TRACE_BOOL(oldlevel))) { \
528 if (oldlevel <= NONE) { LOG_E(format,##args); } \
529 else if (oldlevel <= INFO) { LOG_I(format,##args); } \
530 else if (__l__ == 2) { LOG_N(format,##args); } \
531 else if (oldlevel <= FULL) { LOG_D(format,##args); } \
532 else { LOG_A(format,##args); } \
533 } }
534
535 /* the following macro must be replaced with LOG_E or LOG_F */
536 # define TRACE_ERROR LOG_E
537
538
539 /* The following macros are missing the faillevel information, which indicates at what log level the error case should be displayed. */
540 # define CHECK_SYS_DO( __call__, __fallback__ ) { \
541 CHECK_PRELUDE(__call__); \
542 if (__ret__ < 0) { \
543 __ret__ = errno; \
544 TRACE_ERROR("ERROR: in '%s' :\t%s", #__call__ , strerror(__ret__)); \
545 __fallback__; \
546 } \
547 }
548
549 # define CHECK_SYS( __call__ ) \
550 CHECK_SYS_DO( (__call__), return __ret__ )
551
552
553 # define CHECK_POSIX_DO2( __call__, __speval__, __fallback1__, __fallback2__ ) { \
554 CHECK_PRELUDE(__call__); \
555 if (__ret__ != 0) { \
556 if (__ret__ == (__speval__)) { \
557 __fallback1__; \
558 } else { \
559 TRACE_ERROR("ERROR: in '%s' :\t%s", #__call__ , strerror(__ret__)); \
560 __fallback2__; \
561 } \
562 } \
563 }
564
565 # define CHECK_POSIX_DO( __call__, __fallback__ ) \
566 CHECK_POSIX_DO2( (__call__), 0, , __fallback__ )
567
568 # define CHECK_POSIX( __call__ ) \
569 CHECK_POSIX_DO( (__call__), return __ret__ )
570
571 # define CHECK_MALLOC_DO( __call__, __fallback__ ) { \
572 void * __ptr__; \
573 TRACE_CALL("Check: %s", #__call__ ); \
574 __ptr__ = (void *)(__call__); \
575 if (__ptr__ == NULL) { \
576 int __ret__ = errno; \
577 TRACE_ERROR("ERROR: in '%s' :\t%s", #__call__ , strerror(__ret__)); \
578 __fallback__; \
579 } \
580 }
581
582 # define CHECK_MALLOC( __call__ ) \
583 CHECK_MALLOC_DO( (__call__), return __ret__ )
584
585 # define CHECK_PARAMS_DO( __bool__, __fallback__ ) { \
586 TRACE_CALL("Check: %s", #__bool__ ); \
587 if ( ! (__bool__) ) { \
588 int __ret__ = EINVAL; \
589 TRACE_ERROR("ERROR: Invalid parameter '%s', %d", #__bool__, __ret__ ); \
590 __fallback__; \
591 } \
592 }
593
594 # define CHECK_PARAMS( __bool__ ) \
595 CHECK_PARAMS_DO( (__bool__), return __ret__ )
596
597 # define CHECK_FCT_DO CHECK_POSIX_DO
598 # define CHECK_FCT CHECK_POSIX
599
600 #endif /* EXCLUDE_DEPRECATED */
601
602
603 /*============================================================*/
604 /* Optimized code: remove all debugging code */
605 /*============================================================*/
606 #ifdef STRIP_DEBUG_CODE
607 #undef LOG_D
608 #undef LOG_I
609 #undef LOG_N
610 #undef LOG_E
611 #undef LOG_F
612 #undef LOG_BUFFER
613
614 #define LOG_D(format,args... ) /* noop */
615 #define LOG_I(format,args...) fd_log(FD_LOG_INFO, format, ## args)
616 #define LOG_N(format,args...) fd_log(FD_LOG_NOTICE, format, ## args)
617 #define LOG_E(format,args...) fd_log(FD_LOG_ERROR, format, ## args)
618 #define LOG_F(format,args...) fd_log(FD_LOG_FATAL, format, ## args)
619 #define LOG_BUFFER(printlevel, level, prefix, buf, bufsz, suffix ) { \
620 if (printlevel > FD_LOG_DEBUG) { \
621 int __i; \
622 size_t __sz = (size_t)(bufsz); \
623 uint8_t * __buf = (uint8_t *)(buf); \
624 char * __strbuf[1024+1]; \
625 for (__i = 0; (__i < __sz) && (__i<(sizeof(__strbuf)/2); __i++) { \
626 sprintf(__strbuf + (2 * __i), "%02.2hhx", __buf[__i]); \
627 } \
628 fd_log(printlevel, prefix"%s"suffix, __strbuf); \
629 }
630 #endif /* STRIP_DEBUG_CODE */
631
632 /*============================================================*/
633 /* OTHER MACROS */
634 /*============================================================*/
635 /* helper macros (pre-processor hacks to allow macro arguments) */
636 #define __tostr( arg ) #arg
637 #define _stringize( arg ) __tostr( arg )
638 #define __agr( arg1, arg2 ) arg1 ## arg2
639 #define _aggregate( arg1, arg2 ) __agr( arg1, arg2 )
640
641 /* Some aliases to socket addresses structures */
642 #define sSS struct sockaddr_storage
643 #define sSA struct sockaddr
644 #define sSA4 struct sockaddr_in
645 #define sSA6 struct sockaddr_in6
646
647 /* The sockaddr length of a sSS structure */
648 #define sSAlen( _sa_ ) \
649 ( (socklen_t) ( (((sSA *)_sa_)->sa_family == AF_INET) ? (sizeof(sSA4)) : \
650 ((((sSA *)_sa_)->sa_family == AF_INET6) ? (sizeof(sSA6)) : \
651 0 ) ) )
652 #define sSAport( _sa_ ) \
653 ( (socklen_t) ( (((sSA *)_sa_)->sa_family == AF_INET) ? (((sSA4 *)(_sa_))->sin_port) : \
654 ((((sSA *)_sa_)->sa_family == AF_INET6) ? (((sSA6 *)(_sa_))->sin6_port) : \
655 0 ) ) )
656
657 DECLARE_FD_DUMP_PROTOTYPE(fd_sa_dump, sSA * sa, int flags);
658 #define sSA_DUMP_STRLEN (INET6_ADDRSTRLEN + 1 + 32 + 2)
659 void fd_sa_sdump_numeric(char * buf /* must be at least sSA_DUMP_STRLEN */, sSA * sa);
660
661
662 /* A l4 protocol name (TCP / SCTP) */
663 #ifdef DISABLE_SCTP
664 #define IPPROTO_NAME( _proto ) \
665 (((_proto) == IPPROTO_TCP) ? "TCP" : \
666 "Unknown")
667 #else /* DISABLE_SCTP */
668 #define IPPROTO_NAME( _proto ) \
669 ( ((_proto) == IPPROTO_TCP) ? "TCP" : \
670 (((_proto) == IPPROTO_SCTP) ? "SCTP" : \
671 "Unknown"))
672 #endif /* DISABLE_SCTP */
673
674 /* Define the value of IP loopback address */
675 #ifndef INADDR_LOOPBACK
676 #define INADDR_LOOPBACK inet_addr("127.0.0.1")
677 #endif /* INADDR_LOOPBACK */
678
679 #ifndef INADDR_BROADCAST
680 #define INADDR_BROADCAST ((in_addr_t) 0xffffffff)
681 #endif /* INADDR_BROADCAST */
682
683 /* An IP equivalent to IN6_IS_ADDR_LOOPBACK */
684 #ifndef IN_IS_ADDR_LOOPBACK
685 #define IN_IS_ADDR_LOOPBACK(a) \
686 ((((long int) (a)->s_addr) & ntohl(0xff000000)) == ntohl(0x7f000000))
687 #endif /* IN_IS_ADDR_LOOPBACK */
688
689 /* An IP equivalent to IN6_IS_ADDR_UNSPECIFIED */
690 #ifndef IN_IS_ADDR_UNSPECIFIED
691 #define IN_IS_ADDR_UNSPECIFIED(a) \
692 (((long int) (a)->s_addr) == 0x00000000)
693 #endif /* IN_IS_ADDR_UNSPECIFIED */
694
695 /* create a V4MAPPED address */
696 #define IN6_ADDR_V4MAP( a6, a4 ) { \
697 memset(&(*a6)[0], 0, 10); \
698 (*a6)[10] = 0xff; \
699 (*a6)[11] = 0xff; \
700 memcpy(&(*a6)[12], &a4, 4); \
701 }
702
703 /* Retrieve a v4 value from V4MAPPED address ( takes a s6_addr as param) */
704 #define IN6_ADDR_V4UNMAP( a6 ) \
705 (((in_addr_t *)(a6))[3])
706
707
708 /* We provide macros to convert 64 bit values to and from network byte-order, on systems where it is not already provided. */
709 #ifndef HAVE_NTOHLL /* Defined by the cmake step, if the ntohll symbol is defined on the system */
710 # if HOST_BIG_ENDIAN
711 /* In big-endian systems, we don't have to change the values, since the order is the same as network */
712 # define ntohll(x) (x)
713 # define htonll(x) (x)
714 # else /* HOST_BIG_ENDIAN */
715 /* For these systems, we must reverse the bytes. Use ntohl and htonl on sub-32 blocs, and inverse these blocs. */
716 # define ntohll(x) (typeof (x))( (((uint64_t)ntohl( (uint32_t)(x))) << 32 ) | ((uint64_t) ntohl( ((uint64_t)(x)) >> 32 )))
717 # define htonll(x) (typeof (x))( (((uint64_t)htonl( (uint32_t)(x))) << 32 ) | ((uint64_t) htonl( ((uint64_t)(x)) >> 32 )))
718 # endif /* HOST_BIG_ENDIAN */
719 #endif /* HAVE_NTOHLL */
720
721 /* This macro will give the next multiple of 4 for an integer (used for padding sizes of AVP). */
722 #define PAD4(_x) ((_x) + ( (4 - (_x)) & 3 ) )
723
724 /* Useful to display any value as (safe) ASCII (will garbage UTF-8 output...) */
725 #define ASCII(_c) ( ((_c < 32) || (_c > 127)) ? ( _c ? '?' : ' ' ) : _c )
726
727 /* Compare timespec structures */
728 #define TS_IS_INFERIOR( ts1, ts2 ) \
729 ( ((ts1)->tv_sec < (ts2)->tv_sec ) \
730 || (((ts1)->tv_sec == (ts2)->tv_sec ) && ((ts1)->tv_nsec < (ts2)->tv_nsec) ))
731
732 /* Compute diff between two timespecs (pointers) */
733 #define TS_DIFFERENCE( tsdiff, tsstart, tsend ) { \
734 if ((tsend)->tv_nsec < (tsstart)->tv_nsec ) { \
735 (tsdiff)->tv_sec = (tsend)->tv_sec - (tsstart)->tv_sec - 1; \
736 (tsdiff)->tv_nsec = (tsend)->tv_nsec + 1000000000 - (tsstart)->tv_nsec; \
737 } else { \
738 (tsdiff)->tv_sec = (tsend)->tv_sec - (tsstart)->tv_sec; \
739 (tsdiff)->tv_nsec = (tsend)->tv_nsec - (tsstart)->tv_nsec; \
740 }}
741
742
743 /* This gives a good size for buffered reads */
744 #ifndef BUFSIZ
745 #define BUFSIZ 96
746 #endif /* BUFSIZ */
747
748 /* This gives the length of a const string */
749 #define CONSTSTRLEN( str ) (sizeof(str) - 1)
750
751
752 /*============================================================*/
753 /* PORTABILITY */
754 /*============================================================*/
755 #ifndef HAVE_CLOCK_GETTIME
756 #define CLOCK_REALTIME 0
757 #include <sys/time.h>
758 int clock_gettime(int clk_id, struct timespec* ts);
759 #endif /* HAVE_CLOCK_GETTIME */
760
761 #ifndef HAVE_STRNDUP
762 char * strndup (char *str, size_t len);
763 #endif /* HAVE_STRNDUP */
764
765
766 /*============================================================*/
767 /* BINARY STRINGS */
768 /*============================================================*/
769
770 /* Compute a hash value of a binary string.
771 The hash must remain local to this machine, there is no guarantee that same input
772 will give same output on a different system (endianness) */
773 uint32_t fd_os_hash ( uint8_t * string, size_t len );
774
775 /* This type used for binary strings that contain no \0 except as their last character.
776 It means some string operations can be used on it. */
777 typedef uint8_t * os0_t;
778
779 /* Same as strdup but for os0_t strings */
780 os0_t os0dup_int(os0_t s, size_t l);
781 #define os0dup( _s, _l) (void *)os0dup_int((os0_t)(_s), _l)
782
783 /* Check that an octet string value can be used as os0_t */
fd_os_is_valid_os0(uint8_t * os,size_t oslen)784 static __inline__ int fd_os_is_valid_os0(uint8_t * os, size_t oslen) {
785 /* The only situation where it is not valid is when it contains a \0 inside the octet string */
786 return (memchr(os, '\0', oslen) == NULL);
787 }
788
789 /* The following type denotes a verified DiameterIdentity value (that contains only pure letters, digits, hyphen, dot) */
790 typedef char * DiamId_t;
791
792 /* Maximum length of a hostname we accept */
793 #ifndef HOST_NAME_MAX
794 #define HOST_NAME_MAX 512
795 #endif /* HOST_NAME_MAX */
796
797 /* Check if a binary string contains a valid Diameter Identity value.
798 rfc3588 states explicitely that such a Diameter Identity consists only of ASCII characters. */
799 int fd_os_is_valid_DiameterIdentity(uint8_t * os, size_t ossz);
800
801 /* The following function validates a string as a Diameter Identity or applies the IDNA transformation on it
802 if *inoutsz is != 0 on entry, *id may not be \0-terminated.
803 memory has the following meaning: 0: *id can be realloc'd. 1: *id must be malloc'd on output (was static)
804 */
805 int fd_os_validate_DiameterIdentity(char ** id, size_t * inoutsz, int memory);
806
807 /* Create an order relationship for binary strings (not needed to be \0 terminated).
808 It does NOT mimic strings relationships so that it is more efficient. It is case sensitive.
809 (the strings are actually first ordered by their lengh, then by their bytes contents)
810 returns: -1 if os1 < os2; +1 if os1 > os2; 0 if they are equal */
811 int fd_os_cmp_int(os0_t os1, size_t os1sz, os0_t os2, size_t os2sz);
812 #define fd_os_cmp(_o1, _l1, _o2, _l2) fd_os_cmp_int((os0_t)(_o1), _l1, (os0_t)(_o2), _l2)
813
814 /* A roughly case-insensitive variant, which actually only compares ASCII chars (0-127) in a case-insentitive maneer
815 -- it does not support locales where a lowercase letter uses more space than upper case, such as ß -> ss
816 It is slower than fd_os_cmp.
817 Note that the result is NOT the same as strcasecmp !!!
818
819 This function gives the same order as fd_os_cmp, except when it finds 2 strings to be equal.
820 However this is not always sufficient:
821 for example fd_os_cmp gives: "Ac" < "aB" < "aa"
822 if you attempt to fd_os_almostcasesrch "Aa" you will actually have to go past "aB" which is > "Aa".
823 Therefore you can use the maybefurther parameter.
824 This parameter is 1 on return if os1 may have been stored further that os2 (assuming os2 values are ordered by fd_os_cmp)
825 and 0 if we are sure that it is not the case.
826 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.
827 */
828 int fd_os_almostcasesrch_int(uint8_t * os1, size_t os1sz, uint8_t * os2, size_t os2sz, int * maybefurther);
829 #define fd_os_almostcasesrch(_o1, _l1, _o2, _l2, _mb) fd_os_almostcasesrch_int((os0_t)(_o1), _l1, (os0_t)(_o2), _l2, _mb)
830
831 /* Analyze a DiameterURI and return its components.
832 Return EINVAL if the URI is not valid.
833 *diamid is malloc'd on function return and must be freed (it is processed by fd_os_validate_DiameterIdentity).
834 *secure is 0 (no security) or 1 (security enabled) on return.
835 *port is 0 (default) or a value in host byte order on return.
836 *transport is 0 (default) or IPPROTO_* on return.
837 *proto is 0 (default) or 'd' (diameter), 'r' (radius), or 't' (tacacs+) on return.
838 */
839 int fd_os_parse_DiameterURI(uint8_t * uri, size_t urisz, DiamId_t * diamid, size_t * diamidlen, int * secure, uint16_t * port, int * transport, char *proto);
840
841 /*============================================================*/
842 /* THREADS */
843 /*============================================================*/
844
845 /* Terminate a thread */
fd_thr_term(pthread_t * th)846 static __inline__ int fd_thr_term(pthread_t * th)
847 {
848 void * th_ret = NULL;
849
850 CHECK_PARAMS(th);
851
852 /* Test if it was already terminated */
853 if (*th == (pthread_t)NULL)
854 return 0;
855
856 /* Cancel the thread if it is still running - ignore error if it was already terminated */
857 (void) pthread_cancel(*th);
858
859 /* Then join the thread */
860 CHECK_POSIX( pthread_join(*th, &th_ret) );
861
862 if (th_ret == PTHREAD_CANCELED) {
863 TRACE_DEBUG(ANNOYING, "The thread %p was canceled", (void *)*th);
864 } else {
865 TRACE_DEBUG(CALL, "The thread %p returned %p", (void *)*th, th_ret);
866 }
867
868 /* Clean the location */
869 *th = (pthread_t)NULL;
870
871 return 0;
872 }
873
874
875 /*************
876 Cancelation cleanup handlers for common objects
877 *************/
fd_cleanup_mutex(void * mutex)878 static __inline__ void fd_cleanup_mutex( void * mutex )
879 {
880 CHECK_POSIX_DO( pthread_mutex_unlock((pthread_mutex_t *)mutex), /* */);
881 }
882
fd_cleanup_rwlock(void * rwlock)883 static __inline__ void fd_cleanup_rwlock( void * rwlock )
884 {
885 CHECK_POSIX_DO( pthread_rwlock_unlock((pthread_rwlock_t *)rwlock), /* */);
886 }
887
fd_cleanup_buffer(void * buffer)888 static __inline__ void fd_cleanup_buffer( void * buffer )
889 {
890 free(buffer);
891 }
fd_cleanup_socket(void * sockptr)892 static __inline__ void fd_cleanup_socket(void * sockptr)
893 {
894 if (sockptr && (*(int *)sockptr > 0)) {
895 CHECK_SYS_DO( close(*(int *)sockptr), /* ignore */ );
896 *(int *)sockptr = -1;
897 }
898 }
899
900
901 /*============================================================*/
902 /* LISTS */
903 /*============================================================*/
904
905 /* The following structure represents a chained list element */
906 struct fd_list {
907 struct fd_list *next; /* next element in the list */
908 struct fd_list *prev; /* previous element in the list */
909 struct fd_list *head; /* head of the list */
910 void *o; /* additional pointer, used for any purpose (ex: start of the parent object) */
911 };
912
913 /* Initialize a list element */
914 #define FD_LIST_INITIALIZER( _list_name ) \
915 { .next = & _list_name, .prev = & _list_name, .head = & _list_name, .o = NULL }
916 #define FD_LIST_INITIALIZER_O( _list_name, _obj ) \
917 { .next = & _list_name, .prev = & _list_name, .head = & _list_name, .o = _obj }
918 void fd_list_init ( struct fd_list * list, void * obj );
919
920 /* Return boolean, true if the list is empty */
921 #define FD_IS_LIST_EMPTY( _list ) ((((struct fd_list *)(_list))->head == (_list)) && (((struct fd_list *)(_list))->next == (_list)))
922
923 /* Insert an item in a list at known position */
924 void fd_list_insert_after ( struct fd_list * ref, struct fd_list * item );
925 void fd_list_insert_before ( struct fd_list * ref, struct fd_list * item );
926
927 /* Move all elements from a list at the end of another */
928 void fd_list_move_end(struct fd_list * ref, struct fd_list * senti);
929
930 /* Insert an item in an ordered list -- ordering function must be provided. If duplicate object found, EEXIST and it is returned in ref_duplicate */
931 int fd_list_insert_ordered( struct fd_list * head, struct fd_list * item, int (*cmp_fct)(void *, void *), void ** ref_duplicate);
932
933 /* Unlink an item from a list */
934 void fd_list_unlink ( struct fd_list * item );
935
936
937
938
939 /*============================================================*/
940 /* DICTIONARY */
941 /*============================================================*/
942
943 /* Structure that contains the complete dictionary definitions */
944 struct dictionary;
945
946 /* Structure that contains a dictionary object */
947 struct dict_object;
948
949 /* Types of object in the dictionary. */
950 enum dict_object_type {
951 DICT_VENDOR = 1, /* Vendor */
952 DICT_APPLICATION, /* Diameter Application */
953 DICT_TYPE, /* AVP data type */
954 DICT_ENUMVAL, /* Named constant (value of an enumerated AVP type) */
955 DICT_AVP, /* AVP */
956 DICT_COMMAND, /* Diameter Command */
957 DICT_RULE /* a Rule for AVP in command or grouped AVP */
958 #define DICT_TYPE_MAX DICT_RULE
959 };
960
961 /* Initialize a dictionary */
962 int fd_dict_init(struct dictionary ** dict);
963 /* Destroy a dictionary */
964 int fd_dict_fini(struct dictionary ** dict);
965
966 /*
967 * FUNCTION: fd_dict_new
968 *
969 * PARAMETERS:
970 * dict : Pointer to the dictionary where the object is created
971 * type : What kind of object must be created
972 * data : pointer to the data for the object.
973 * type parameter is used to determine the type of data (see below for detail).
974 * parent : a reference to a parent object, if needed.
975 * ref : upon successful creation, reference to new object is stored here if !null.
976 *
977 * DESCRIPTION:
978 * Create a new object in the dictionary.
979 * See following object sections in this header file for more information on data and parent parameters format.
980 *
981 * RETURN VALUE:
982 * 0 : The object is created in the dictionary.
983 * EINVAL : A parameter is invalid.
984 * EEXIST : This object is already defined in the dictionary (with conflicting data).
985 * If "ref" is not NULL, it points to the existing element on return.
986 * (other standard errors may be returned, too, with their standard meaning. Example:
987 * ENOMEM : Memory allocation for the new object element failed.)
988 */
989 int fd_dict_new ( struct dictionary * dict, enum dict_object_type type, void * data, struct dict_object * parent, struct dict_object ** ref );
990
991 /*
992 * FUNCTION: fd_dict_search
993 *
994 * PARAMETERS:
995 * dict : Pointer to the dictionary where the object is searched
996 * type : type of object that is being searched
997 * criteria : how the object must be searched. See object-related sections below for more information.
998 * what : depending on criteria, the data that must be searched.
999 * result : On successful return, pointer to the object is stored here.
1000 * retval : this value is returned if the object is not found and result is not NULL.
1001 *
1002 * DESCRIPTION:
1003 * Perform a search in the dictionary.
1004 * See the object-specific sections below to find how to look for each objects.
1005 * If the "result" parameter is NULL, the function is used to check if an object is in the dictionary.
1006 * Otherwise, a reference to the object is stored in result if found.
1007 * If result is not NULL and the object is not found, retval is returned (should be 0 or ENOENT usually)
1008 *
1009 * RETURN VALUE:
1010 * 0 : The object has been found in the dictionary, or *result is NULL.
1011 * EINVAL : A parameter is invalid.
1012 * ENOENT : No matching object has been found, and result was NULL.
1013 */
1014 int fd_dict_search ( struct dictionary * dict, enum dict_object_type type, int criteria, const void * what, struct dict_object ** result, int retval );
1015
1016 /* Special case: get the generic error command object */
1017 int fd_dict_get_error_cmd(struct dictionary * dict, struct dict_object ** obj);
1018
1019 /*
1020 * FUNCTION: fd_dict_getval
1021 *
1022 * PARAMETERS:
1023 * object : Pointer to a dictionary object.
1024 * data : pointer to a structure to hold the data for the object.
1025 * The type is the same as "data" parameter in fd_dict_new function.
1026 *
1027 * DESCRIPTION:
1028 * Retrieve content of a dictionary object.
1029 * See following object sections in this header file for more information on data and parent parameters format.
1030 *
1031 * RETURN VALUE:
1032 * 0 : The content of the object has been retrieved.
1033 * EINVAL : A parameter is invalid.
1034 */
1035 int fd_dict_getval ( struct dict_object * object, void * val);
1036 int fd_dict_gettype ( struct dict_object * object, enum dict_object_type * type);
1037 int fd_dict_getdict ( struct dict_object * object, struct dictionary ** dict);
1038
1039 /* Debug functions */
1040 DECLARE_FD_DUMP_PROTOTYPE(fd_dict_dump_object, struct dict_object * obj);
1041 DECLARE_FD_DUMP_PROTOTYPE(fd_dict_dump, struct dictionary * dict);
1042
1043 /* Function to access full contents of the dictionary, see doc in dictionary.c */
1044 int fd_dict_getlistof(int criteria, void * parent, struct fd_list ** sentinel);
1045
1046 /* Function to remove an entry from the dictionary.
1047 This cannot be used if the object has children (for example a vendor with vendor-specific AVPs).
1048 In such case, the children must be removed first. */
1049 int fd_dict_delete(struct dict_object * obj);
1050
1051 /*
1052 ***************************************************************************
1053 *
1054 * Vendor object
1055 *
1056 * These types are used to manage vendors in the dictionary
1057 *
1058 ***************************************************************************
1059 */
1060
1061 /* Type to hold a Vendor ID: "SMI Network Management Private Enterprise Codes" (RFC3232) */
1062 typedef uint32_t vendor_id_t;
1063
1064 /* Type to hold data associated to a vendor */
1065 struct dict_vendor_data {
1066 vendor_id_t vendor_id; /* ID of a vendor */
1067 char * vendor_name; /* The name of this vendor */
1068 };
1069
1070 /* The criteria for searching a vendor object in the dictionary */
1071 enum {
1072 VENDOR_BY_ID = 10, /* "what" points to a vendor_id_t */
1073 VENDOR_BY_NAME, /* "what" points to a char * */
1074 VENDOR_OF_APPLICATION, /* "what" points to a struct dict_object containing an application (see below) */
1075 VENDOR_OF_AVP, /* "what" points to a struct dict_object containing an avp (see below) */
1076 };
1077
1078 /***
1079 * API usage :
1080
1081 Note: the value of "vendor_name" is copied when the object is created, and the string may be disposed afterwards.
1082 On the other side, when value is retrieved with dict_getval, the string is not copied and MUST NOT be freed. It will
1083 be freed automatically along with the object itself with call to dict_fini later.
1084
1085 - fd_dict_new:
1086 The "parent" parameter is not used for vendors.
1087 Sample code to create a vendor:
1088 {
1089 int ret;
1090 struct dict_object * myvendor;
1091 struct dict_vendor_data myvendordata = { 23455, "my vendor name" }; -- just an example...
1092 ret = fd_dict_new ( dict, DICT_VENDOR, &myvendordata, NULL, &myvendor );
1093 }
1094
1095 - fd_dict_search:
1096 Sample codes to look for a vendor object, by its id or name:
1097 {
1098 int ret;
1099 struct dict_object * vendor_found;
1100 vendor_id_t vendorid = 23455;
1101 ret = fd_dict_search ( dict, DICT_VENDOR, VENDOR_BY_ID, &vendorid, &vendor_found, ENOENT);
1102 - or -
1103 ret = fd_dict_search ( dict, DICT_VENDOR, VENDOR_BY_NAME, "my vendor name", &vendor_found, ENOENT);
1104 }
1105
1106 - fd_dict_getval:
1107 Sample code to retrieve the data from a vendor object:
1108 {
1109 int ret;
1110 struct dict_object * myvendor;
1111 struct dict_vendor_data myvendordata;
1112 ret = fd_dict_search ( dict, DICT_VENDOR, VENDOR_BY_NAME, "my vendor name", &myvendor, ENOENT);
1113 ret = fd_dict_getval ( myvendor, &myvendordata );
1114 printf("my vendor id: %d\n", myvendordata.vendor_id );
1115 }
1116
1117 */
1118
1119 /* Special function: */
1120 uint32_t * fd_dict_get_vendorid_list(struct dictionary * dict);
1121
1122 /*
1123 ***************************************************************************
1124 *
1125 * Application object
1126 *
1127 * These types are used to manage Diameter applications in the dictionary
1128 *
1129 ***************************************************************************
1130 */
1131
1132 /* Type to hold a Diameter application ID: IANA assigned value for this application. */
1133 typedef uint32_t application_id_t;
1134
1135 /* Type to hold data associated to an application */
1136 struct dict_application_data {
1137 application_id_t application_id; /* ID of the application */
1138 char * application_name; /* The name of this application */
1139 };
1140
1141 /* The criteria for searching an application object in the dictionary */
1142 enum {
1143 APPLICATION_BY_ID = 20, /* "what" points to a application_id_t */
1144 APPLICATION_BY_NAME, /* "what" points to a char * */
1145 APPLICATION_OF_TYPE, /* "what" points to a struct dict_object containing a type object (see below) */
1146 APPLICATION_OF_COMMAND /* "what" points to a struct dict_object containing a command (see below) */
1147 };
1148
1149 /***
1150 * API usage :
1151
1152 The "parent" parameter of dict_new may point to a vendor object to inform of what vendor defines the application.
1153 for standard-track applications, the "parent" parameter should be NULL.
1154 The vendor associated to an application is retrieved with VENDOR_OF_APPLICATION search criteria on vendors.
1155
1156 - fd_dict_new:
1157 Sample code for application creation:
1158 {
1159 int ret;
1160 struct dict_object * vendor;
1161 struct dict_object * appl;
1162 struct dict_vendor_data vendor_data = {
1163 23455,
1164 "my vendor name"
1165 };
1166 struct dict_application_data app_data = {
1167 9789,
1168 "my vendor's application"
1169 };
1170
1171 ret = fd_dict_new ( dict, DICT_VENDOR, &vendor_data, NULL, &vendor );
1172 ret = fd_dict_new ( dict, DICT_APPLICATION, &app_data, vendor, &appl );
1173 }
1174
1175 - fd_dict_search:
1176 Sample code to retrieve the vendor of an application
1177 {
1178 int ret;
1179 struct dict_object * vendor, * appli;
1180
1181 ret = fd_dict_search ( dict, DICT_APPLICATION, APPLICATION_BY_NAME, "my vendor's application", &appli, ENOENT);
1182 ret = fd_dict_search ( dict, DICT_VENDOR, VENDOR_OF_APPLICATION, appli, &vendor, ENOENT);
1183 }
1184
1185 - fd_dict_getval:
1186 Sample code to retrieve the data from an application object:
1187 {
1188 int ret;
1189 struct dict_object * appli;
1190 struct dict_application_data appl_data;
1191 ret = fd_dict_search ( dict, DICT_APPLICATION, APPLICATION_BY_NAME, "my vendor's application", &appli, ENOENT);
1192 ret = fd_dict_getval ( appli, &appl_data );
1193 printf("my application id: %s\n", appl_data.application_id );
1194 }
1195
1196 */
1197
1198 /*
1199 ***************************************************************************
1200 *
1201 * Type object
1202 *
1203 * These types are used to manage AVP data types in the dictionary
1204 *
1205 ***************************************************************************
1206 */
1207
1208 /* Type to store any AVP value */
1209 union avp_value {
1210 struct {
1211 uint8_t *data; /* bytes buffer */
1212 size_t len; /* length of the data buffer */
1213 } os; /* Storage for an octet string */
1214 int32_t i32; /* integer 32 */
1215 int64_t i64; /* integer 64 */
1216 uint32_t u32; /* unsigned 32 */
1217 uint64_t u64; /* unsigned 64 */
1218 float f32; /* float 32 */
1219 double f64; /* float 64 */
1220 };
1221
1222 /* These are the basic AVP types defined in RFC3588bis */
1223 enum dict_avp_basetype {
1224 AVP_TYPE_GROUPED,
1225 AVP_TYPE_OCTETSTRING,
1226 AVP_TYPE_INTEGER32,
1227 AVP_TYPE_INTEGER64,
1228 AVP_TYPE_UNSIGNED32,
1229 AVP_TYPE_UNSIGNED64,
1230 AVP_TYPE_FLOAT32,
1231 AVP_TYPE_FLOAT64
1232 #define AVP_TYPE_MAX AVP_TYPE_FLOAT64
1233 };
1234
1235 /* Callbacks that can be associated with a derived type to easily interpret the AVP value. */
1236 /*
1237 * CALLBACK: dict_avpdata_interpret
1238 *
1239 * PARAMETERS:
1240 * val : Pointer to the AVP value that must be interpreted.
1241 * interpreted : The result of interpretation is stored here. The format and meaning depends on each type.
1242 *
1243 * DESCRIPTION:
1244 * This callback can be provided with a derived type in order to facilitate the interpretation of formated data.
1245 * For example, when an AVP of type "Address" is received, it can be used to convert the octetstring into a struct sockaddr.
1246 * This callback is not called directly, but through the message's API msg_avp_value_interpret function.
1247 *
1248 * RETURN VALUE:
1249 * 0 : Operation complete.
1250 * !0 : An error occurred, the error code is returned.
1251 */
1252 typedef int (*dict_avpdata_interpret) (union avp_value * value, void * interpreted);
1253 /*
1254 * CALLBACK: dict_avpdata_encode
1255 *
1256 * PARAMETERS:
1257 * data : The formated data that must be stored in the AVP value.
1258 * val : Pointer to the AVP value storage area where the data must be stored.
1259 *
1260 * DESCRIPTION:
1261 * This callback can be provided with a derived type in order to facilitate the encoding of formated data.
1262 * For example, it can be used to convert a struct sockaddr in an AVP value of type Address.
1263 * This callback is not called directly, but through the message's API msg_avp_value_encode function.
1264 * If the callback is defined for an OctetString based type, the created string must be malloc'd. free will be called
1265 * automatically later.
1266 *
1267 * RETURN VALUE:
1268 * 0 : Operation complete.
1269 * !0 : An error occurred, the error code is returned.
1270 */
1271 typedef int (*dict_avpdata_encode) (void * data, union avp_value * val);
1272
1273 /*
1274 * CALLBACK: dict_avpdata_check
1275 *
1276 * PARAMETERS:
1277 * val : Pointer to the AVP value that was received and needs to be sanity checked.
1278 * data : a parameter stored in the type structure (to enable more generic check functions)
1279 * 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.
1280 *
1281 * DESCRIPTION:
1282 * This callback can be provided with a derived type in order to improve the operation of the
1283 * fd_msg_parse_dict function. When this callback is present, the value of the AVP that has
1284 * been parsed is passed to this function for finer granularity check. For example for some
1285 * speccific AVP, the format of an OCTETSTRING value can be further checked, or the
1286 * interger value can be verified.
1287 *
1288 * RETURN VALUE:
1289 * 0 : The value is valid.
1290 * !0 : An error occurred, the error code is returned. It is advised to return EINVAL on incorrect val
1291 */
1292 typedef int (*dict_avpdata_check) (void * data, union avp_value * val, char ** error_msg);
1293
1294
1295
1296 /* Type to hold data associated to a derived AVP data type */
1297 struct dict_type_data {
1298 enum dict_avp_basetype type_base; /* How the data of such AVP must be interpreted */
1299 char * type_name; /* The name of this type */
1300 dict_avpdata_interpret type_interpret;/* cb to convert the AVP value in more comprehensive format (or NULL) */
1301 dict_avpdata_encode type_encode; /* cb to convert formatted data into an AVP value (or NULL) */
1302 DECLARE_FD_DUMP_PROTOTYPE((*type_dump), union avp_value * val); /* cb called by fd_msg_dump_* for this type of data (if != NULL). Returned string must be freed. */
1303 dict_avpdata_check type_check;
1304 void * type_check_param;
1305 };
1306
1307 /* The criteria for searching a type object in the dictionary */
1308 enum {
1309 TYPE_BY_NAME = 30, /* "what" points to a char * */
1310 TYPE_OF_ENUMVAL, /* "what" points to a struct dict_object containing an enumerated constant (DICT_ENUMVAL, see below). */
1311 TYPE_OF_AVP /* "what" points to a struct dict_object containing an AVP object. */
1312 };
1313
1314 /****
1315 Callbacks defined in libfdproto/dictionary_functions.c file -- see that file for usage.
1316 */
1317
1318 /* Convert an Address type AVP into a struct sockaddr_storage */
1319 int fd_dictfct_Address_encode(void * data, union avp_value * avp_value);
1320 int fd_dictfct_Address_interpret(union avp_value * avp_value, void * interpreted);
1321 DECLARE_FD_DUMP_PROTOTYPE(fd_dictfct_Address_dump, union avp_value * avp_value);
1322
1323 /* Display the content of an AVP of type UTF8String in the log file */
1324 DECLARE_FD_DUMP_PROTOTYPE(fd_dictfct_UTF8String_dump, union avp_value * avp_value);
1325
1326 /* For Time AVPs, map with time_t value directly */
1327 int fd_dictfct_Time_encode(void * data, union avp_value * avp_value);
1328 int fd_dictfct_Time_interpret(union avp_value * avp_value, void * interpreted);
1329 DECLARE_FD_DUMP_PROTOTYPE(fd_dictfct_Time_dump, union avp_value * avp_value);
1330
1331
1332 /* For string AVP, the following type_check function provides simple basic check for specific characters presence, e.g. use "@." for trivial email address check */
1333 int fd_dictfct_CharInOS_check(void * data, union avp_value * val, char ** error_msg);
1334
1335
1336 /****/
1337
1338 /***
1339 * API usage :
1340
1341 - fd_dict_new:
1342 The "parent" parameter may point to an application object, when a type is defined by a Diameter application.
1343
1344 Sample code:
1345 {
1346 int ret;
1347 struct dict_object * mytype;
1348 struct dict_type_data mytypedata =
1349 {
1350 AVP_TYPE_OCTETSTRING,
1351 "Address",
1352 NULL,
1353 NULL
1354 };
1355 ret = fd_dict_new ( dict, DICT_TYPE, &mytypedata, NULL, &mytype );
1356 }
1357
1358 - fd_dict_search:
1359 Sample code:
1360 {
1361 int ret;
1362 struct dict_object * address_type;
1363 ret = fd_dict_search ( dict, DICT_TYPE, TYPE_BY_NAME, "Address", &address_type, ENOENT);
1364 }
1365
1366 */
1367
1368 /*
1369 ***************************************************************************
1370 *
1371 * Enumerated values object
1372 *
1373 * These types are used to manage named constants of some AVP,
1374 * for enumerated types. freeDiameter allows constants for types others than Unsigned32
1375 *
1376 ***************************************************************************
1377 */
1378
1379 /* Type to hold data of named constants for AVP */
1380 struct dict_enumval_data {
1381 char * enum_name; /* The name of this constant */
1382 union avp_value enum_value; /* Value of the constant. Union term depends on parent type's base type. */
1383 };
1384
1385 /* The criteria for searching a constant in the dictionary */
1386 enum {
1387 ENUMVAL_BY_STRUCT = 40, /* "what" points to a struct dict_enumval_request as defined below */
1388 ENUMVAL_BY_NAME, /* This cannot be used for searches */
1389 ENUMVAL_BY_VALUE /* This cannot be used for searches */
1390 };
1391
1392 struct dict_enumval_request {
1393 /* Identifier of the parent type, one of the following must not be NULL */
1394 struct dict_object *type_obj;
1395 char * type_name;
1396
1397 /* Search criteria for the constant */
1398 struct dict_enumval_data search; /* search.enum_value is used only if search.enum_name == NULL */
1399 };
1400
1401 /***
1402 * API usage :
1403
1404 - fd_dict_new:
1405 The "parent" parameter must point to a derived type object.
1406 Sample code to create a type "Boolean" with two constants "True" and "False":
1407 {
1408 int ret;
1409 struct dict_object * type_boolean;
1410 struct dict_type_data type_boolean_data =
1411 {
1412 AVP_TYPE_INTEGER32,
1413 "Boolean",
1414 NULL,
1415 NULL
1416 };
1417 struct dict_enumval_data boolean_false =
1418 {
1419 .enum_name="False",
1420 .enum_value.i32 = 0
1421 };
1422 struct dict_enumval_data boolean_true =
1423 {
1424 .enum_name="True",
1425 .enum_value.i32 = -1
1426 };
1427 ret = fd_dict_new ( dict, DICT_TYPE, &type_boolean_data, NULL, &type_boolean );
1428 ret = fd_dict_new ( dict, DICT_ENUMVAL, &boolean_false, type_boolean, NULL );
1429 ret = fd_dict_new ( dict, DICT_ENUMVAL, &boolean_true , type_boolean, NULL );
1430
1431 }
1432
1433 - fd_dict_search:
1434 Sample code to look for a constant name, by its value:
1435 {
1436 int ret;
1437 struct dict_object * value_found;
1438 struct dict_enumval_request boolean_by_value =
1439 {
1440 .type_name = "Boolean",
1441 .search.enum_name=NULL,
1442 .search.enum_value.i32 = -1
1443 };
1444
1445 ret = fd_dict_search ( dict, DICT_ENUMVAL, ENUMVAL_BY_STRUCT, &boolean_by_value, &value_found, ENOENT);
1446 }
1447
1448 - fd_dict_getval:
1449 Sample code to retrieve the data from a constant object:
1450 {
1451 int ret;
1452 struct dict_object * value_found;
1453 struct dict_enumval_data boolean_data = NULL;
1454 struct dict_enumval_request boolean_by_value =
1455 {
1456 .type_name = "Boolean",
1457 .search.enum_name=NULL,
1458 .search.enum_value.i32 = 0
1459 };
1460
1461 ret = fd_dict_search ( dict, DICT_ENUMVAL, ENUMVAL_BY_STRUCT, &boolean_by_value, &value_found, ENOENT);
1462 ret = fd_dict_getval ( value_found, &boolean_data );
1463 printf(" Boolean with value 0: %s", boolean_data.enum_name );
1464 }
1465 */
1466
1467 /*
1468 ***************************************************************************
1469 *
1470 * AVP object
1471 *
1472 * These objects are used to manage AVP definitions in the dictionary
1473 *
1474 ***************************************************************************
1475 */
1476
1477 /* Type to hold an AVP code. For vendor 0, these codes are assigned by IANA. Otherwise, it is managed by the vendor */
1478 typedef uint32_t avp_code_t;
1479
1480 /* Values of AVP flags */
1481 #define AVP_FLAG_VENDOR 0x80
1482 #define AVP_FLAG_MANDATORY 0x40
1483 #define AVP_FLAG_RESERVED3 0x20
1484 #define AVP_FLAG_RESERVED4 0x10
1485 #define AVP_FLAG_RESERVED5 0x08
1486 #define AVP_FLAG_RESERVED6 0x04
1487 #define AVP_FLAG_RESERVED7 0x02
1488 #define AVP_FLAG_RESERVED8 0x01
1489
1490 /* For dumping flags and values */
1491 #define DUMP_AVPFL_str "%c%c%s%s%s%s%s%s"
1492 #define DUMP_AVPFL_val(_val) (_val & AVP_FLAG_VENDOR)?'V':'-' , (_val & AVP_FLAG_MANDATORY)?'M':'-', \
1493 (_val & AVP_FLAG_RESERVED3)?"3":"", (_val & AVP_FLAG_RESERVED4)?"4":"", \
1494 (_val & AVP_FLAG_RESERVED5)?"5":"", (_val & AVP_FLAG_RESERVED6)?"6":"", (_val & AVP_FLAG_RESERVED7)?"7":"", (_val & AVP_FLAG_RESERVED8)?"8":""
1495
1496 /* Type to hold data associated to an avp */
1497 struct dict_avp_data {
1498 avp_code_t avp_code; /* Code of the avp */
1499 vendor_id_t avp_vendor; /* Vendor of the AVP, or 0 */
1500 char * avp_name; /* Name of this AVP */
1501 uint8_t avp_flag_mask; /* Mask of fixed AVP flags */
1502 uint8_t avp_flag_val; /* Values of the fixed flags */
1503 enum dict_avp_basetype avp_basetype; /* Basic type of data found in the AVP */
1504 };
1505
1506 /* The criteria for searching an avp object in the dictionary */
1507 enum {
1508 AVP_BY_CODE = 50, /* "what" points to an avp_code_t, vendor is always 0 */
1509 AVP_BY_NAME, /* "what" points to a char *, vendor is always 0 */
1510 AVP_BY_NAME_ALL_VENDORS,/* "what" points to a string. Might be quite slow... */
1511 AVP_BY_STRUCT, /* "what" points to a struct dict_avp_request_ex (see below) */
1512
1513 /* kept for backward compatibility, better use AVP_BY_STRUCT above instead */
1514 AVP_BY_CODE_AND_VENDOR, /* "what" points to a struct dict_avp_request (see below), where avp_vendor and avp_code are set */
1515 AVP_BY_NAME_AND_VENDOR /* "what" points to a struct dict_avp_request (see below), where avp_vendor and avp_name are set */
1516 };
1517
1518 /* Struct used for some searches */
1519 struct dict_avp_request_ex {
1520 struct {
1521 /* Only one of the following fields must be set. */
1522 struct dict_object * vendor; /* most efficient if already known, set to NULL to ignore */
1523 vendor_id_t vendor_id; /* set to 0 to ignore -- prefer AVP_BY_CODE or AVP_BY_NAME for vendor 0 */
1524 const char * vendor_name; /* set to NULL to ignore */
1525 } avp_vendor;
1526
1527 struct {
1528 /* Only one of the following fields must be set */
1529 avp_code_t avp_code; /* set to 0 to ignore */
1530 const char * avp_name; /* set to NULL to ignore */
1531 } avp_data;
1532 };
1533
1534 struct dict_avp_request {
1535 vendor_id_t avp_vendor;
1536 avp_code_t avp_code;
1537 char * avp_name;
1538 };
1539
1540
1541
1542 /***
1543 * API usage :
1544
1545 If "parent" parameter is not NULL during AVP creation, it must point to a DICT_TYPE object.
1546 The extended type is then attached to the AVP. In case where it is an enumerated type, the value of
1547 AVP is automatically interpreted in debug messages, and in message checks.
1548 The derived type of an AVP can be retrieved with: dict_search ( DICT_TYPE, TYPE_OF_AVP, avp, ... )
1549
1550 To create the rules (ABNF) for children of Grouped AVP, see the DICT_RULE related part.
1551
1552 - fd_dict_new:
1553 Sample code for AVP creation:
1554 {
1555 int ret;
1556 struct dict_object * user_name_avp;
1557 struct dict_object * boolean_type;
1558 struct dict_object * sample_boolean_avp;
1559 struct dict_avp_data user_name_data = {
1560 1, // code
1561 0, // vendor
1562 "User-Name", // name
1563 AVP_FLAG_VENDOR | AVP_FLAG_MANDATORY, // fixed mask: V and M values must always be defined as follow. other flags can be set or cleared
1564 AVP_FLAG_MANDATORY, // the V flag must be cleared, the M flag must be set.
1565 AVP_TYPE_OCTETSTRING // User-Name AVP contains OctetString data (further precision such as UTF8String can be given with a parent derived type)
1566 };
1567 struct dict_avp_data sample_boolean_data = {
1568 31337,
1569 23455,
1570 "Sample-Boolean",
1571 AVP_FLAG_VENDOR | AVP_FLAG_MANDATORY,
1572 AVP_FLAG_VENDOR,
1573 AVP_TYPE_INTEGER32 // This MUST be the same as parent type's
1574 };
1575
1576 -- Create an AVP with a base type --
1577 ret = fd_dict_new ( dict, DICT_AVP, &user_name_data, NULL, &user_name_avp );
1578
1579 -- Create an AVP with a derived type --
1580 ret = fd_dict_search ( dict, DICT_TYPE, TYPE_BY_NAME, "Boolean", &boolean_type, ENOENT);
1581 ret = fd_dict_new ( dict, DICT_AVP, &sample_boolean_data , boolean_type, &sample_boolean_avp );
1582
1583 }
1584
1585 - fd_dict_search:
1586 Sample code to look for an AVP
1587 {
1588 int ret;
1589 struct dict_object * avp_username;
1590 struct dict_object * avp_sampleboolean;
1591 struct dict_avp_request avpvendorboolean =
1592 {
1593 .avp_vendor = 23455,
1594 .avp_name = "Sample-Boolean"
1595 };
1596
1597 ret = fd_dict_search ( dict, DICT_AVP, AVP_BY_NAME, "User-Name", &avp_username, ENOENT);
1598
1599 ret = fd_dict_search ( dict, DICT_AVP, AVP_BY_NAME_AND_VENDOR, &avpvendorboolean, &avp_sampleboolean, ENOENT);
1600
1601 -- this would also work, but be slower, because it has to search all vendor dictionaries --
1602 ret = fd_dict_search ( dict, DICT_AVP, AVP_BY_NAME_ALL_VENDORS, "Sample-Boolean", &avp_sampleboolean, ENOENT);
1603
1604 }
1605
1606 - fd_dict_getval:
1607 Sample code to retrieve the data from an AVP object:
1608 {
1609 int ret;
1610 struct dict_object * avp_username;
1611 struct dict_avp_data user_name_data;
1612 ret = fd_dict_search ( dict, DICT_AVP, AVP_BY_NAME, "User-Name", &avp_username, ENOENT);
1613 ret = fd_dict_getval ( avp_username, &user_name_data );
1614 printf("User-Name code: %d\n", user_name_data.avp_code );
1615 }
1616
1617 */
1618
1619 /*
1620 ***************************************************************************
1621 *
1622 * Command object
1623 *
1624 * These types are used to manage commands objects in the dictionary
1625 *
1626 ***************************************************************************
1627 */
1628
1629 /* Type to hold a Diameter command code: IANA assigned values. 0x0-0x7fffff=standard, 0x800000-0xfffffd=vendors, 0xfffffe-0xffffff=experimental */
1630 typedef uint32_t command_code_t;
1631
1632 /* Values of command flags */
1633 #define CMD_FLAG_REQUEST 0x80
1634 #define CMD_FLAG_PROXIABLE 0x40
1635 #define CMD_FLAG_ERROR 0x20
1636 #define CMD_FLAG_RETRANSMIT 0x10
1637 #define CMD_FLAG_RESERVED5 0x08
1638 #define CMD_FLAG_RESERVED6 0x04
1639 #define CMD_FLAG_RESERVED7 0x02
1640 #define CMD_FLAG_RESERVED8 0x01
1641
1642 /* For dumping flags and values */
1643 #define DUMP_CMDFL_str "%c%c%c%c%s%s%s%s"
1644 #define DUMP_CMDFL_val(_val) (_val & CMD_FLAG_REQUEST)?'R':'-' , (_val & CMD_FLAG_PROXIABLE)?'P':'-' , (_val & CMD_FLAG_ERROR)?'E':'-' , (_val & CMD_FLAG_RETRANSMIT)?'T':'-', \
1645 (_val & CMD_FLAG_RESERVED5)?"5":"", (_val & CMD_FLAG_RESERVED6)?"6":"", (_val & CMD_FLAG_RESERVED7)?"7":"", (_val & CMD_FLAG_RESERVED8)?"8":""
1646
1647 /* Type to hold data associated to a command */
1648 struct dict_cmd_data {
1649 command_code_t cmd_code; /* code of the command */
1650 char * cmd_name; /* Name of the command */
1651 uint8_t cmd_flag_mask; /* Mask of fixed-value flags */
1652 uint8_t cmd_flag_val; /* values of the fixed flags */
1653 };
1654
1655 /* The criteria for searching an avp object in the dictionary */
1656 enum {
1657 CMD_BY_NAME = 60, /* "what" points to a char * */
1658 CMD_BY_CODE_R, /* "what" points to a command_code_t. The "Request" command is returned. */
1659 CMD_BY_CODE_A, /* "what" points to a command_code_t. The "Answer" command is returned. */
1660 CMD_ANSWER /* "what" points to a struct dict_object of a request command. The corresponding "Answer" command is returned. */
1661 };
1662
1663
1664 /***
1665 * API usage :
1666
1667 The "parent" parameter of dict_new may point to an application object to inform of what application defines the command.
1668 The application associated to a command is retrieved with APPLICATION_OF_COMMAND search criteria on applications.
1669
1670 To create the rules for children of commands, see the DICT_RULE related part.
1671
1672 Note that the "Request" and "Answer" commands are two independant objects. This allows to have different rules for each.
1673
1674 - fd_dict_new:
1675 Sample code for command creation:
1676 {
1677 int ret;
1678 struct dict_object * cer;
1679 struct dict_object * cea;
1680 struct dict_cmd_data ce_data = {
1681 257, // code
1682 "Capabilities-Exchange-Request", // name
1683 CMD_FLAG_REQUEST, // mask
1684 CMD_FLAG_REQUEST // value. Only the "R" flag is constrained here, set.
1685 };
1686
1687 ret = fd_dict_new (dict, DICT_COMMAND, &ce_data, NULL, &cer );
1688
1689 ce_data.cmd_name = "Capabilities-Exchange-Answer";
1690 ce_data.cmd_flag_val = 0; // Same constraint on "R" flag, but this time it must be cleared.
1691
1692 ret = fd_dict_new ( dict, DICT_COMMAND, &ce_data, NULL, &cea );
1693 }
1694
1695 - fd_dict_search:
1696 Sample code to look for a command
1697 {
1698 int ret;
1699 struct dict_object * cer, * cea;
1700 command_code_t code = 257;
1701 ret = fd_dict_search ( dict, DICT_COMMAND, CMD_BY_NAME, "Capabilities-Exchange-Request", &cer, ENOENT);
1702 ret = fd_dict_search ( dict, DICT_COMMAND, CMD_BY_CODE_R, &code, &cer, ENOENT);
1703 }
1704
1705 - fd_dict_getval:
1706 Sample code to retrieve the data from a command object:
1707 {
1708 int ret;
1709 struct dict_object * cer;
1710 struct dict_object * cea;
1711 struct dict_cmd_data cea_data;
1712 ret = fd_dict_search ( dict, DICT_COMMAND, CMD_BY_NAME, "Capabilities-Exchange-Request", &cer, ENOENT);
1713 ret = fd_dict_search ( dict, DICT_COMMAND, CMD_ANSWER, cer, &cea, ENOENT);
1714 ret = fd_dict_getval ( cea, &cea_data );
1715 printf("Answer to CER: %s\n", cea_data.cmd_name );
1716 }
1717
1718 */
1719
1720 /*
1721 ***************************************************************************
1722 *
1723 * Rule object
1724 *
1725 * These objects are used to manage rules in the dictionary (ABNF implementation)
1726 * This is used for checking messages validity (more powerful than a DTD)
1727 *
1728 ***************************************************************************
1729 */
1730
1731 /* This defines the kind of rule that is defined */
1732 enum rule_position {
1733 RULE_FIXED_HEAD = 1, /* The AVP must be at the head of the group. The rule_order field is used to specify the position. */
1734 RULE_REQUIRED, /* The AVP must be present in the parent, but its position is not defined. */
1735 RULE_OPTIONAL, /* The AVP may be present in the message. Used to specify a max number of occurences for example */
1736 RULE_FIXED_TAIL /* The AVP must be at the end of the group. The rule_order field is used to specify the position. */
1737 };
1738
1739 /* Content of a RULE object data */
1740 struct dict_rule_data {
1741 struct dict_object *rule_avp; /* Pointer to the AVP object that is concerned by this rule */
1742 enum rule_position rule_position; /* The position in which the rule_avp must appear in the parent */
1743 unsigned rule_order; /* for RULE_FIXED_* rules, the place. 1,2,3.. for HEAD rules; ...,3,2,1 for TAIL rules. */
1744 int rule_min; /* Minimum number of occurences. -1 means "default": 0 for optional rules, 1 for other rules */
1745 int rule_max; /* Maximum number of occurences. -1 means no maximum. 0 means the AVP is forbidden. */
1746 };
1747
1748 /* The criteria for searching a rule in the dictionary */
1749 enum {
1750 RULE_BY_AVP_AND_PARENT = 70 /* "what" points to a struct dict_rule_request -- see below. This is used to query "what is the rule for this AVP in this group?" */
1751 };
1752
1753 /* Structure for querying the dictionary about a rule */
1754 struct dict_rule_request {
1755 struct dict_object *rule_parent; /* The grouped avp or command to which the rule apply */
1756 struct dict_object *rule_avp; /* The AVP concerned by this rule */
1757 };
1758
1759
1760 /***
1761 * API usage :
1762
1763 The "parent" parameter can not be NULL. It points to the object (grouped avp or command) to which this rule apply (i.e. for which the ABNF is defined).
1764
1765 - fd_dict_new:
1766 Sample code for rule creation. Let's create the Proxy-Info grouped AVP for example.
1767 {
1768 int ret;
1769 struct dict_object * proxy_info_avp;
1770 struct dict_object * proxy_host_avp;
1771 struct dict_object * proxy_state_avp;
1772 struct dict_object * diameteridentity_type;
1773 struct dict_rule_data rule_data;
1774 struct dict_type_data di_type_data = { AVP_TYPE_OCTETSTRING, "DiameterIdentity", NULL, NULL };
1775 struct dict_avp_data proxy_info_data = { 284, 0, "Proxy-Info", AVP_FLAG_VENDOR | AVP_FLAG_MANDATORY, AVP_FLAG_MANDATORY, AVP_TYPE_GROUPED };
1776 struct dict_avp_data proxy_host_data = { 280, 0, "Proxy-Host", AVP_FLAG_VENDOR | AVP_FLAG_MANDATORY, AVP_FLAG_MANDATORY, AVP_TYPE_OCTETSTRING };
1777 struct dict_avp_data proxy_state_data = { 33, 0, "Proxy-State",AVP_FLAG_VENDOR | AVP_FLAG_MANDATORY, AVP_FLAG_MANDATORY, AVP_TYPE_OCTETSTRING };
1778
1779 -- Create the parent AVP
1780 ret = fd_dict_new ( dict, DICT_AVP, &proxy_info_data, NULL, &proxy_info_avp );
1781
1782 -- Create the first child AVP.
1783 ret = fd_dict_new ( dict, DICT_TYPE, &di_type_data, NULL, &diameteridentity_type );
1784 ret = fd_dict_new ( dict, DICT_AVP, &proxy_host_data, diameteridentity_type, &proxy_host_avp );
1785
1786 -- Create the other child AVP
1787 ret = fd_dict_new ( dict, DICT_AVP, &proxy_state_data, NULL, &proxy_state_avp );
1788
1789 -- Now we can create the rules. Both children AVP are mandatory.
1790 rule_data.rule_position = RULE_REQUIRED;
1791 rule_data.rule_min = -1;
1792 rule_data.rule_max = -1;
1793
1794 rule_data.rule_avp = proxy_host_avp;
1795 ret = fd_dict_new ( dict, DICT_RULE, &rule_data, proxy_info_avp, NULL );
1796
1797 rule_data.rule_avp = proxy_state_avp;
1798 ret = fd_dict_new ( dict, DICT_RULE, &rule_data, proxy_info_avp, NULL );
1799 }
1800
1801 - fd_dict_search and fd_dict_getval are similar to previous examples.
1802
1803 */
1804
1805 /* Define some hard-coded values */
1806 /* Application */
1807 #define AI_RELAY 0xffffffff
1808
1809 /* Commands Codes */
1810 #define CC_CAPABILITIES_EXCHANGE 257
1811 #define CC_RE_AUTH 258
1812 #define CC_ACCOUNTING 271
1813 #define CC_ABORT_SESSION 274
1814 #define CC_SESSION_TERMINATION 275
1815 #define CC_DEVICE_WATCHDOG 280
1816 #define CC_DISCONNECT_PEER 282
1817
1818 /* AVPs (Vendor 0) */
1819 #define AC_USER_NAME 1
1820 #define AC_PROXY_STATE 33
1821 #define AC_HOST_IP_ADDRESS 257
1822 #define AC_AUTH_APPLICATION_ID 258
1823 #define AC_ACCT_APPLICATION_ID 259
1824 #define AC_VENDOR_SPECIFIC_APPLICATION_ID 260
1825 #define AC_REDIRECT_HOST_USAGE 261
1826 #define AC_REDIRECT_MAX_CACHE_TIME 262
1827 #define AC_SESSION_ID 263
1828 #define AC_ORIGIN_HOST 264
1829 #define AC_SUPPORTED_VENDOR_ID 265
1830 #define AC_VENDOR_ID 266
1831 #define AC_FIRMWARE_REVISION 267
1832 #define AC_RESULT_CODE 268
1833 #define AC_PRODUCT_NAME 269
1834 #define AC_DISCONNECT_CAUSE 273
1835 #define ACV_DC_REBOOTING 0
1836 #define ACV_DC_BUSY 1
1837 #define ACV_DC_NOT_FRIEND 2
1838 #define AC_ORIGIN_STATE_ID 278
1839 #define AC_FAILED_AVP 279
1840 #define AC_PROXY_HOST 280
1841 #define AC_ERROR_MESSAGE 281
1842 #define AC_ROUTE_RECORD 282
1843 #define AC_DESTINATION_REALM 283
1844 #define AC_PROXY_INFO 284
1845 #define AC_REDIRECT_HOST 292
1846 #define AC_DESTINATION_HOST 293
1847 #define AC_ERROR_REPORTING_HOST 294
1848 #define AC_ORIGIN_REALM 296
1849 #define AC_INBAND_SECURITY_ID 299
1850 #define ACV_ISI_NO_INBAND_SECURITY 0
1851 #define ACV_ISI_TLS 1
1852
1853 /* Error codes from Base protocol
1854 (reference: http://www.iana.org/assignments/aaa-parameters/aaa-parameters.xml#aaa-parameters-4)
1855 Note that currently, rfc3588bis-26 has some different values for some of these
1856 */
1857 #define ER_DIAMETER_MULTI_ROUND_AUTH 1001
1858
1859 #define ER_DIAMETER_SUCCESS 2001
1860 #define ER_DIAMETER_LIMITED_SUCCESS 2002
1861
1862 #define ER_DIAMETER_COMMAND_UNSUPPORTED 3001 /* 5019 ? */
1863 #define ER_DIAMETER_UNABLE_TO_DELIVER 3002
1864 #define ER_DIAMETER_REALM_NOT_SERVED 3003
1865 #define ER_DIAMETER_TOO_BUSY 3004
1866 #define ER_DIAMETER_LOOP_DETECTED 3005
1867 #define ER_DIAMETER_REDIRECT_INDICATION 3006
1868 #define ER_DIAMETER_APPLICATION_UNSUPPORTED 3007
1869 #define ER_DIAMETER_INVALID_HDR_BITS 3008 /* 5020 ? */
1870 #define ER_DIAMETER_INVALID_AVP_BITS 3009 /* 5021 ? */
1871 #define ER_DIAMETER_UNKNOWN_PEER 3010 /* 5018 ? */
1872
1873 #define ER_DIAMETER_AUTHENTICATION_REJECTED 4001
1874 #define ER_DIAMETER_OUT_OF_SPACE 4002
1875 #define ER_ELECTION_LOST 4003
1876
1877 #define ER_DIAMETER_AVP_UNSUPPORTED 5001
1878 #define ER_DIAMETER_UNKNOWN_SESSION_ID 5002
1879 #define ER_DIAMETER_AUTHORIZATION_REJECTED 5003
1880 #define ER_DIAMETER_INVALID_AVP_VALUE 5004
1881 #define ER_DIAMETER_MISSING_AVP 5005
1882 #define ER_DIAMETER_RESOURCES_EXCEEDED 5006
1883 #define ER_DIAMETER_CONTRADICTING_AVPS 5007
1884 #define ER_DIAMETER_AVP_NOT_ALLOWED 5008
1885 #define ER_DIAMETER_AVP_OCCURS_TOO_MANY_TIMES 5009
1886 #define ER_DIAMETER_NO_COMMON_APPLICATION 5010
1887 #define ER_DIAMETER_UNSUPPORTED_VERSION 5011
1888 #define ER_DIAMETER_UNABLE_TO_COMPLY 5012
1889 #define ER_DIAMETER_INVALID_BIT_IN_HEADER 5013 /* 3011 ? */
1890 #define ER_DIAMETER_INVALID_AVP_LENGTH 5014
1891 #define ER_DIAMETER_INVALID_MESSAGE_LENGTH 5015 /* 3012 ? */
1892 #define ER_DIAMETER_INVALID_AVP_BIT_COMBO 5016 /* deprecated? */
1893 #define ER_DIAMETER_NO_COMMON_SECURITY 5017
1894
1895
1896 /*============================================================*/
1897 /* SESSIONS */
1898 /*============================================================*/
1899
1900 /* Modules that want to associate a state with a Session-Id must first register a handler of this type */
1901 struct session_handler;
1902
1903 /* This opaque structure represents a session associated with a Session-Id */
1904 struct session;
1905
1906 /* The state information that a module associate with a session -- each module defines its own data format */
1907 struct sess_state; /* declare this in your own extension */
1908
1909 typedef DECLARE_FD_DUMP_PROTOTYPE((*session_state_dump), struct sess_state * st);
1910
1911 /* The following function must be called to activate the session expiry mechanism */
1912 int fd_sess_start(void);
1913
1914 /*
1915 * FUNCTION: fd_sess_handler_create
1916 *
1917 * PARAMETERS:
1918 * handler : location where the new handler must be stored.
1919 * cleanup : a callback function that must be called when the session with associated data is destroyed.
1920 * dumper : if not NULL, will be called during fd_sess_dump to display the data associated with a session. NULL otherwise.
1921 * opaque : A pointer that is passed to the cleanup callback -- the content is never examined by the framework.
1922 *
1923 * DESCRIPTION:
1924 * Create a new session handler. This is needed by a module to associate a state with a session object.
1925 * The cleanup handler is called when the session timeout expires, or fd_sess_destroy is called. It must free
1926 * the state associated with the session, and eventually trig other actions (send a STR, ...).
1927 *
1928 * RETURN VALUE:
1929 * 0 : The new handler has been created.
1930 * EINVAL : A parameter is invalid.
1931 * ENOMEM : Not enough memory to complete the operation
1932 */
1933 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 );
1934
1935
1936 /*
1937 * FUNCTION: fd_sess_handler_destroy
1938 *
1939 * PARAMETERS:
1940 * handler : location of an handler created by fd_sess_handler_create.
1941 * opaque : the opaque pointer registered with the callback is restored here (if ! NULL).
1942 *
1943 * DESCRIPTION:
1944 * This destroys a session handler (typically called when an application is shutting down).
1945 * If sessions states are registered with this handler, the cleanup callback is called on them.
1946 *
1947 * RETURN VALUE:
1948 * 0 : The handler was destroyed.
1949 * EINVAL : A parameter is invalid.
1950 * ENOMEM : Not enough memory to complete the operation
1951 */
1952 int fd_sess_handler_destroy ( struct session_handler ** handler, void **opaque );
1953
1954
1955
1956 /*
1957 * FUNCTION: fd_sess_new
1958 *
1959 * PARAMETERS:
1960 * session : The location where the session object will be created upon success.
1961 * diamid : a Diameter Identity, or NULL.
1962 * diamidlen : if diamid is \0-terminated, this can be 0. Otherwise, the length of diamid.
1963 * opt : Additional string, or NULL. Usage is described below.
1964 * optlen : if opt is \0-terminated, this can be 0. Otherwise, the length of opt.
1965 *
1966 * DESCRIPTION:
1967 * Create a new session object. The Session-Id string associated with this session is generated as follow:
1968 * If diamId parameter is provided, the string is created according to the RFC: <diamId>;<high32>;<low32>[;opt] where
1969 * diamId is a Diameter Identity.
1970 * high32 and low32 are the parts of a monotonic 64 bits counter initialized to (time, 0) at startup.
1971 * opt is an optional string that can be concatenated to the identifier.
1972 * If diamId is NULL, the string is exactly the content of opt.
1973 *
1974 * RETURN VALUE:
1975 * 0 : The session is created, the initial msg refcount is 1.
1976 * EINVAL : A parameter is invalid.
1977 * EALREADY : A session with the same name already exists (returned in *session), the msg refcount is increased.
1978 * ENOMEM : Not enough memory to complete the operation
1979 */
1980 int fd_sess_new ( struct session ** session, DiamId_t diamid, size_t diamidlen, uint8_t * opt, size_t optlen );
1981
1982 /*
1983 * FUNCTION: fd_sess_fromsid
1984 *
1985 * PARAMETERS:
1986 * sid : pointer to a string containing a Session-Id (should be UTF-8).
1987 * len : length of the sid string (which does not need to be '\0'-terminated)
1988 * session : On success, pointer to the session object created / retrieved.
1989 * isnew : if not NULL, set to 1 on return if the session object has been created, 0 if it was simply retrieved.
1990 *
1991 * DESCRIPTION:
1992 * Retrieve a session object from a Session-Id string. In case no session object was previously existing with this
1993 * id, a new object is silently created (equivalent to fd_sess_new with flag SESSION_NEW_FULL).
1994 *
1995 * RETURN VALUE:
1996 * 0 : The session parameter has been updated.
1997 * EINVAL : A parameter is invalid.
1998 * ENOMEM : Not enough memory to complete the operation
1999 */
2000 int fd_sess_fromsid ( uint8_t * sid, size_t len, struct session ** session, int * isnew);
2001
2002 /* only use the following in specific situations, e.g. app_radgw extension. They are normally handled by the framework only */
2003 int fd_sess_fromsid_msg ( uint8_t * sid, size_t len, struct session ** session, int * isnew);
2004 int fd_sess_ref_msg ( struct session * session );
2005
2006 /*
2007 * FUNCTION: fd_sess_getsid
2008 *
2009 * PARAMETERS:
2010 * session : Pointer to a session object.
2011 * sid : On success, the location of the sid is stored here.
2012 *
2013 * DESCRIPTION:
2014 * Retrieve the session identifier (Session-Id) corresponding to a session object.
2015 * The returned sid is a \0-terminated binary string which might be UTF-8 (but there is no guarantee in the framework).
2016 * It may be used for example to set the value of an AVP.
2017 * Note that the sid string is not copied, just its reference... do not free it!
2018 *
2019 * RETURN VALUE:
2020 * 0 : The sid & len parameters have been updated.
2021 * EINVAL : A parameter is invalid.
2022 */
2023 int fd_sess_getsid ( struct session * session, os0_t * sid, size_t * sidlen );
2024
2025 /*
2026 * FUNCTION: fd_sess_settimeout
2027 *
2028 * PARAMETERS:
2029 * session : The session for which to set the timeout.
2030 * timeout : The date when the session times out.
2031 *
2032 * DESCRIPTION:
2033 * Set the lifetime for a given session object. This function may be
2034 * called several times on the same object to update the timeout value.
2035 * When the timeout date is reached, the cleanup handler of each
2036 * module that registered data with this session is called, then the
2037 * session is cleared.
2038 *
2039 * There is a possible race condition between cleanup of the session
2040 * and use of its data; applications should ensure that they are not
2041 * using data from a session that is about to expire / expired.
2042 *
2043 * RETURN VALUE:
2044 * 0 : The session timeout has been updated.
2045 * EINVAL : A parameter is invalid.
2046 */
2047 int fd_sess_settimeout( struct session * session, const struct timespec * timeout );
2048
2049 /*
2050 * FUNCTION: fd_sess_destroy
2051 *
2052 * PARAMETERS:
2053 * session : Pointer to a session object.
2054 *
2055 * DESCRIPTION:
2056 * Destroys all associated states of a session, if any.
2057 * Equivalent to a session timeout expired, but the effect is immediate.
2058 * The session itself is marked as deleted, and will be freed when it is not referenced
2059 * by any message anymore.
2060 *
2061 * RETURN VALUE:
2062 * 0 : The session no longer exists.
2063 * EINVAL : A parameter is invalid.
2064 */
2065 int fd_sess_destroy ( struct session ** session );
2066
2067 /*
2068 * FUNCTION: fd_sess_reclaim
2069 *
2070 * PARAMETERS:
2071 * session : Pointer to a session object.
2072 *
2073 * DESCRIPTION:
2074 * Equivalent to fd_sess_destroy, only if no session_state is associated with the session.
2075 * Otherwise, this function has no effect (except that it sets *session to NULL).
2076 *
2077 * RETURN VALUE:
2078 * 0 : The session was reclaimed.
2079 * EINVAL : A parameter is invalid.
2080 */
2081 int fd_sess_reclaim ( struct session ** session );
2082
2083
2084
2085
2086 /*
2087 * FUNCTION: fd_sess_state_store
2088 *
2089 * PARAMETERS:
2090 * handler : The handler with which the state is registered.
2091 * session : The session object with which the state is registered.
2092 * state : An application state (opaque data) to store with the session.
2093 *
2094 * DESCRIPTION:
2095 * Stores an application state with a session. This state can later be retrieved
2096 * with fd_sess_state_retrieve, or implicitly in the cleanup handler when the session
2097 * is destroyed.
2098 *
2099 * RETURN VALUE:
2100 * 0 : The state has been stored.
2101 * EINVAL : A parameter is invalid.
2102 * EALREADY : Data was already associated with this session and client.
2103 * ENOMEM : Not enough memory to complete the operation
2104 */
2105 int fd_sess_state_store ( struct session_handler * handler, struct session * session, struct sess_state ** state );
2106
2107 /*
2108 * FUNCTION: fd_sess_state_retrieve
2109 *
2110 * PARAMETERS:
2111 * handler : The handler with which the state was registered.
2112 * session : The session object with which the state was registered.
2113 * state : Location where the state must be saved if it is found.
2114 *
2115 * DESCRIPTION:
2116 * Retrieves a state saved by fd_sess_state_store.
2117 * After this function has been called, the state is no longer associated with
2118 * the session. A new call to fd_sess_state_store must be performed in order to
2119 * store again the data with the session.
2120 *
2121 * RETURN VALUE:
2122 * 0 : *state is updated (NULL or points to the state if it was found).
2123 * EINVAL : A parameter is invalid.
2124 */
2125 int fd_sess_state_retrieve ( struct session_handler * handler, struct session * session, struct sess_state ** state );
2126
2127
2128 /* For debug */
2129 DECLARE_FD_DUMP_PROTOTYPE(fd_sess_dump, struct session * session, int with_states);
2130 DECLARE_FD_DUMP_PROTOTYPE(fd_sess_dump_hdl, struct session_handler * handler);
2131
2132 /* For statistics / monitoring: get the number of struct session in memory */
2133 int fd_sess_getcount(uint32_t *cnt);
2134
2135 /*============================================================*/
2136 /* ROUTING */
2137 /*============================================================*/
2138
2139 /* The following functions are helpers for the routing module.
2140 The routing data is stored in the message itself. */
2141
2142 /* Structure that contains the routing data for a message */
2143 struct rt_data;
2144
2145 /* Following functions are helpers to create the routing data of a message */
2146 int fd_rtd_init(struct rt_data ** rtd);
2147 void fd_rtd_free(struct rt_data ** rtd);
2148
2149 /* Add a peer to the candidates list. */
2150 int fd_rtd_candidate_add(struct rt_data * rtd, DiamId_t peerid, size_t peeridlen, DiamId_t realm, size_t realmlen);
2151
2152 /* Remove a peer from the candidates (if it is found). The search is case-insensitive. */
2153 void fd_rtd_candidate_del(struct rt_data * rtd, uint8_t * id, size_t idsz);
2154
2155 /* Extract the list of valid candidates, and initialize their scores to 0 */
2156 void fd_rtd_candidate_extract(struct rt_data * rtd, struct fd_list ** candidates, int ini_score);
2157
2158 /* If a peer returned a protocol error for this message, save it so that we don't try to send it there again. Optionally retrieve the current list of candidates. */
2159 int fd_rtd_error_add(struct rt_data * rtd, DiamId_t sentto, size_t senttolen, uint8_t * origin, size_t originsz, uint32_t rcode, struct fd_list ** candidates, int * sendingattemtps);
2160
2161 /* Only retrieve the number of times this message has been processed by the routing-out mechanism (i.e. number of times it was failed over) */
2162 int fd_rtd_get_nb_attempts(struct rt_data * rtd, int * sendingattemtps);
2163
2164 /* The extracted list items have the following structure: */
2165 struct rtd_candidate {
2166 struct fd_list chain; /* link in the list returned by the previous fcts */
2167 DiamId_t diamid; /* the diameter Id of the peer */
2168 size_t diamidlen; /* cached size of the diamid string */
2169 DiamId_t realm; /* the diameter realm of the peer */
2170 size_t realmlen; /* cached size of realm */
2171 int score; /* the current routing score for this peer, see fd_rt_out_register definition for details */
2172 };
2173
2174 /* Reorder the list of peers by score */
2175 int fd_rtd_candidate_reorder(struct fd_list * candidates);
2176
2177 /* Note : it is fine for a callback to add a new entry in the candidates list after the list has been extracted. The diamid must then be malloc'd. */
2178 /* Beware that this could lead to routing loops */
2179
2180 /*============================================================*/
2181 /* MESSAGES */
2182 /*============================================================*/
2183
2184 /* The following types are opaque */
2185 struct msg; /* A message: command with children AVPs (possibly grand children) */
2186 struct avp; /* AVP object */
2187
2188 /* Some details about chaining:
2189 *
2190 * A message is made of a header ( msg ) and 0 or more AVPs ( avp ).
2191 * The structure is a kind of tree, where some AVPs (grouped AVPs) can contain other AVPs.
2192 * Example:
2193 * msg
2194 * |-avp
2195 * |-gavp
2196 * | |-avp
2197 * | |-avp
2198 * | \-avp
2199 * |-avp
2200 * \-avp
2201 *
2202 */
2203
2204 /* The following type is used to point to either a msg or an AVP */
2205 typedef void msg_or_avp;
2206
2207 /* The Diameter protocol version */
2208 #define DIAMETER_VERSION 1
2209
2210 /* In the two following types, some fields are marked (READONLY).
2211 * This means that the content of these fields will be overwritten by the daemon so modifying it is useless.
2212 */
2213
2214 /* The following structure represents the header of a message. All data is in host byte order. */
2215 struct msg_hdr {
2216 uint8_t msg_version; /* (READONLY) Version of Diameter: must be DIAMETER_VERSION. */
2217 uint32_t msg_length; /* (READONLY)(3 bytes) indicates the length of the message */
2218 uint8_t msg_flags; /* Message flags: CMD_FLAG_* */
2219 command_code_t msg_code; /* (3 bytes) the command-code. See dictionary-api.h for more detail */
2220 application_id_t msg_appl; /* The application issuing this message */
2221 uint32_t msg_hbhid; /* The Hop-by-Hop identifier of the message */
2222 uint32_t msg_eteid; /* The End-to-End identifier of the message */
2223 };
2224
2225 /* The following structure represents the visible content of an AVP. All data is in host byte order. */
2226 struct avp_hdr {
2227 avp_code_t avp_code; /* the AVP Code */
2228 uint8_t avp_flags; /* AVP_FLAG_* flags */
2229 uint32_t avp_len; /* (READONLY)(Only 3 bytes are used) the length of the AVP as described in the RFC */
2230 vendor_id_t avp_vendor; /* Only used if AVP_FLAG_VENDOR is present */
2231 union avp_value *avp_value; /* pointer to the value of the AVP. NULL means that the value is not set / not understood.
2232 One should not directly change this value. Use the msg_avp_setvalue function instead.
2233 The content of the pointed structure can be changed directly, with this restriction:
2234 if the AVP is an OctetString, and you change the value of the pointer avp_value->os.data, then
2235 you must call free() on the previous value, and the new one must be free()-able.
2236 */
2237 };
2238
2239 /* The following enum is used to browse inside message hierarchy (msg, gavp, avp) */
2240 enum msg_brw_dir {
2241 MSG_BRW_NEXT = 1, /* Get the next element at the same level, or NULL if this is the last element. */
2242 MSG_BRW_PREV, /* Get the previous element at the same level, or NULL if this is the first element. */
2243 MSG_BRW_FIRST_CHILD, /* Get the first child AVP of this element, if any. */
2244 MSG_BRW_LAST_CHILD, /* Get the last child AVP of this element, if any. */
2245 MSG_BRW_PARENT, /* Get the parent element of this element, if any. Only the msg_t object has no parent. */
2246 MSG_BRW_WALK /* This is equivalent to FIRST_CHILD or NEXT or PARENT->next, first that is not NULL. Use this to walk inside all AVPs. */
2247 };
2248
2249 /* Some flags used in the functions below */
2250 #define AVPFL_SET_BLANK_VALUE 0x01 /* When creating an AVP, initialize its value to a blank area */
2251 #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) */
2252 #define AVPFL_MAX AVPFL_SET_RAWDATA_FROM_AVP /* The biggest valid flag value */
2253
2254 #define MSGFL_ALLOC_ETEID 0x01 /* When creating a message, a new end-to-end ID is allocated and set in the message */
2255 #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 */
2256 #define MSGFL_ANSW_NOSID 0x04 /* When creating an answer message, do not add the Session-Id even if present in request */
2257 #define MSGFL_ANSW_NOPROXYINFO 0x08 /* When creating an answer message, do not add the Proxy-Info AVPs presents in request */
2258 #define MSGFL_MAX MSGFL_ANSW_NOPROXYINFO /* The biggest valid flag value */
2259
2260 /**************************************************/
2261 /* Message creation, manipulation, disposal */
2262 /**************************************************/
2263 /*
2264 * FUNCTION: fd_msg_avp_new
2265 *
2266 * PARAMETERS:
2267 * model : Pointer to a DICT_AVP dictionary object describing the avp to create, or NULL if flags are used.
2268 * flags : Flags to use in creation (AVPFL_*, see above).
2269 * avp : Upon success, pointer to the new avp is stored here. It points to reference AVP upon function call when flags are used.
2270 *
2271 * DESCRIPTION:
2272 * Create a new AVP instance.
2273 *
2274 * RETURN VALUE:
2275 * 0 : The AVP is created.
2276 * EINVAL : A parameter is invalid.
2277 * (other standard errors may be returned, too, with their standard meaning. Example:
2278 * ENOMEM : Memory allocation for the new avp failed.)
2279 */
2280 int fd_msg_avp_new ( struct dict_object * model, int flags, struct avp ** avp );
2281
2282 /*
2283 * FUNCTION: fd_msg_new
2284 *
2285 * PARAMETERS:
2286 * model : Pointer to a DICT_COMMAND dictionary object describing the message to create, or NULL.
2287 * flags : combination of MSGFL_* flags.
2288 * msg : Upon success, pointer to the new message is stored here.
2289 *
2290 * DESCRIPTION:
2291 * Create a new empty Diameter message.
2292 *
2293 * RETURN VALUE:
2294 * 0 : The message is created.
2295 * EINVAL : A parameter is invalid.
2296 * (other standard errors may be returned, too, with their standard meaning. Example:
2297 * ENOMEM : Memory allocation for the new message failed.)
2298 */
2299 int fd_msg_new ( struct dict_object * model, int flags, struct msg ** msg );
2300
2301 /*
2302 * FUNCTION: msg_new_answer_from_req
2303 *
2304 * PARAMETERS:
2305 * dict : Pointer to the dictionary containing the model of the query.
2306 * msg : The location of the query on function call. Updated by the location of answer message on return.
2307 * flag : Pass MSGFL_ANSW_ERROR to indicate if the answer is an error message (will set the 'E' bit)
2308 * : See other MSGFL_ANSW_* definition above for other flags.
2309 *
2310 * DESCRIPTION:
2311 * This function creates the empty answer message corresponding to a request.
2312 * The header is set properly (R flag, ccode, appid, hbhid, eteid)
2313 * The Session-Id AVP is copied if present.
2314 * The calling code should usually call fd_msg_rescode_set function on the answer.
2315 * Upon return, the original query may be retrieved by calling fd_msg_answ_getq on the message.
2316 *
2317 * RETURN VALUE:
2318 * 0 : Operation complete.
2319 * !0 : an error occurred.
2320 */
2321 int fd_msg_new_answer_from_req ( struct dictionary * dict, struct msg ** msg, int flag );
2322
2323 /*
2324 * FUNCTION: fd_msg_browse
2325 *
2326 * PARAMETERS:
2327 * reference : Pointer to a struct msg or struct avp.
2328 * dir : Direction for browsing
2329 * found : If not NULL, updated with the element that has been found, if any, or NULL if no element was found / an error occurred.
2330 * 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.
2331 *
2332 * DESCRIPTION:
2333 * Explore the content of a message object (hierarchy). If "found" is null, only error checking is performed.
2334 * If "depth" is provided, it is updated as follow on successful function return:
2335 * - not modified for MSG_BRW_NEXT and MSG_BRW_PREV.
2336 * - *depth = *depth + 1 for MSG_BRW_FIRST_CHILD and MSG_BRW_LAST_CHILD.
2337 * - *depth = *depth - 1 for MSG_BRW_PARENT.
2338 * - *depth = *depth + X for MSG_BRW_WALK, with X between 1 (returned the 1st child) and -N (returned the Nth parent's next).
2339 *
2340 * RETURN VALUE:
2341 * 0 : found has been updated (if non NULL).
2342 * EINVAL : A parameter is invalid.
2343 * ENOENT : No element has been found where requested, and "found" was NULL (otherwise, *found is set to NULL and 0 is returned).
2344 */
2345 int fd_msg_browse_internal ( msg_or_avp * reference, enum msg_brw_dir dir, msg_or_avp ** found, int * depth );
2346 /* Macro to avoid having to cast the third parameter everywhere */
2347 #define fd_msg_browse( ref, dir, found, depth ) \
2348 fd_msg_browse_internal( (ref), (dir), (void *)(found), (depth) )
2349
2350
2351 /*
2352 * FUNCTION: fd_msg_avp_add
2353 *
2354 * PARAMETERS:
2355 * reference : Pointer to a valid msg or avp.
2356 * dir : location where the new AVP should be inserted, relative to the reference. MSG_BRW_PARENT and MSG_BRW_WALK are not valid.
2357 * avp : pointer to the AVP object that must be inserted.
2358 *
2359 * DESCRIPTION:
2360 * Adds an AVP into an object that can contain it: grouped AVP or message.
2361 * Note that the added AVP will be freed at the same time as the object it is added to,
2362 * so it should not be freed after the call to this function.
2363 *
2364 * RETURN VALUE:
2365 * 0 : The AVP has been added.
2366 * EINVAL : A parameter is invalid.
2367 */
2368 int fd_msg_avp_add ( msg_or_avp * reference, enum msg_brw_dir dir, struct avp *avp);
2369
2370 /*
2371 * FUNCTION: fd_msg_search_avp
2372 *
2373 * PARAMETERS:
2374 * reference : Pointer to a valid msg or avp in which to search the AVP.
2375 * what : The dictionary model of the AVP to search.
2376 * avp : location where the AVP reference is stored if found.
2377 *
2378 * DESCRIPTION:
2379 * Search for the first top-level AVP of a given model inside a message or AVP.
2380 * Note: only the first instance of the AVP is returned by this function.
2381 * Note: only top-level AVPs are searched, not inside grouped AVPs.
2382 * Use msg_browse if you need more advanced search features.
2383 *
2384 * RETURN VALUE:
2385 * 0 : The AVP has been found.
2386 * EINVAL : A parameter is invalid.
2387 * ENOENT : No AVP has been found, and "avp" was NULL (otherwise, *avp is set to NULL and 0 returned).
2388 */
2389 int fd_msg_search_avp ( msg_or_avp * reference, struct dict_object * what, struct avp ** avp );
2390
2391 /*
2392 * FUNCTION: fd_msg_free
2393 *
2394 * PARAMETERS:
2395 * object : pointer to the message or AVP object that must be unlinked and freed.
2396 *
2397 * DESCRIPTION:
2398 * Unlink and free a message or AVP object and its children.
2399 * If the object is an AVP linked into a message, the AVP is removed before being freed.
2400 *
2401 * RETURN VALUE:
2402 * 0 : The message has been freed.
2403 * EINVAL : A parameter is invalid.
2404 */
2405 int fd_msg_free ( msg_or_avp * object );
2406
2407 /***************************************/
2408 /* Dump functions */
2409 /***************************************/
2410 /*
2411 * FUNCTION: fd_msg_dump_*
2412 *
2413 * PARAMETERS:
2414 * see definition of DECLARE_FD_DUMP_PROTOTYPE,
2415 * obj : A msg or avp object to dump.
2416 * dict : the dictionary to use if parsing is requested (optional)
2417 * force_parsing: by default these functions do not parse the object but dump hexa values in that case.
2418 * use !0 to force parsing. If parsing fails, the hexa dump is still provided.
2419 * recurse : allow the function to go through the children objects if any to dump more information. might require parsing.
2420 *
2421 * DESCRIPTION:
2422 * These functions dump the content of a message or avp into a buffer
2423 * either recursively or only the object itself.
2424 *
2425 * RETURN VALUE:
2426 * - see DECLARE_FD_DUMP_PROTOTYPE,
2427 */
2428 /* one-line dump with only short information */
2429 DECLARE_FD_DUMP_PROTOTYPE( fd_msg_dump_summary, msg_or_avp *obj, struct dictionary *dict, int force_parsing, int recurse );
2430 /* one-line dump with all the contents of the message */
2431 DECLARE_FD_DUMP_PROTOTYPE( fd_msg_dump_full, msg_or_avp *obj, struct dictionary *dict, int force_parsing, int recurse );
2432 /* multi-line human-readable dump similar to wireshark output */
2433 DECLARE_FD_DUMP_PROTOTYPE( fd_msg_dump_treeview, msg_or_avp *obj, struct dictionary *dict, int force_parsing, int recurse );
2434
2435
2436 /*********************************************/
2437 /* Message metadata management functions */
2438 /*********************************************/
2439 /*
2440 * FUNCTION: fd_msg_model
2441 *
2442 * PARAMETERS:
2443 * reference : Pointer to a valid msg or avp.
2444 * model : on success, pointer to the dictionary model of this command or AVP. NULL if the model is unknown.
2445 *
2446 * DESCRIPTION:
2447 * Retrieve the dictionary object describing this message or avp. If the object is unknown or the fd_msg_parse_dict has not been called,
2448 * *model is set to NULL.
2449 *
2450 * RETURN VALUE:
2451 * 0 : The model has been set.
2452 * EINVAL : A parameter is invalid.
2453 */
2454 int fd_msg_model ( msg_or_avp * reference, struct dict_object ** model );
2455
2456 /*
2457 * FUNCTION: fd_msg_hdr
2458 *
2459 * PARAMETERS:
2460 * msg : Pointer to a valid message object.
2461 * pdata : Upon success, pointer to the msg_hdr structure of this message. The fields may be modified.
2462 *
2463 * DESCRIPTION:
2464 * Retrieve location of modifiable section of a message.
2465 *
2466 * RETURN VALUE:
2467 * 0 : The location has been written.
2468 * EINVAL : A parameter is invalid.
2469 */
2470 int fd_msg_hdr ( struct msg *msg, struct msg_hdr ** pdata );
2471
2472 /*
2473 * FUNCTION: fd_msg_avp_hdr
2474 *
2475 * PARAMETERS:
2476 * avp : Pointer to a valid avp object.
2477 * pdata : Upon success, pointer to the avp_hdr structure of this avp. The fields may be modified.
2478 *
2479 * DESCRIPTION:
2480 * Retrieve location of modifiable data of an avp.
2481 *
2482 * RETURN VALUE:
2483 * 0 : The location has been written.
2484 * EINVAL : A parameter is invalid.
2485 */
2486 int fd_msg_avp_hdr ( struct avp *avp, struct avp_hdr ** pdata );
2487
2488 /*
2489 * FUNCTION: fd_msg_answ_associate, fd_msg_answ_getq, fd_msg_answ_detach
2490 *
2491 * PARAMETERS:
2492 * answer : the received answer message
2493 * query : the corresponding query that had been sent
2494 *
2495 * DESCRIPTION:
2496 * fd_msg_answ_associate associates a query msg with the received answer.
2497 * Query is retrieved with fd_msg_answ_getq.
2498 * If answer message is freed, the query is also freed.
2499 * If the msg_answ_detach function is called, the association is removed.
2500 * This is meant to be called from the daemon only.
2501 *
2502 * RETURN VALUE:
2503 * 0 : ok
2504 * EINVAL: a parameter is invalid
2505 */
2506 int fd_msg_answ_associate( struct msg * answer, struct msg * query );
2507 int fd_msg_answ_getq ( struct msg * answer, struct msg ** query );
2508 int fd_msg_answ_detach ( struct msg * answer );
2509
2510 /*
2511 * FUNCTION: fd_msg_anscb_associate, fd_msg_anscb_get
2512 *
2513 * PARAMETERS:
2514 * msg : the request message
2515 * anscb : the callback to associate with the message
2516 * data : the data to pass to the callback
2517 * expirecb : the expiration callback to associate with the message
2518 * timeout : (optional, use NULL if no timeout) a timeout associated with calling the cb.
2519 *
2520 * DESCRIPTION:
2521 * Associate or retrieve callbacks with an message.
2522 * This is meant to be called from the daemon only.
2523 *
2524 * RETURN VALUE:
2525 * 0 : ok
2526 * EINVAL: a parameter is invalid
2527 */
2528 int fd_msg_anscb_associate( struct msg * msg, void ( *anscb)(void *, struct msg **), void * data, void (*expirecb)(void *, DiamId_t, size_t, struct msg **), const struct timespec *timeout );
2529 int fd_msg_anscb_get( struct msg * msg, void (**anscb)(void *, struct msg **), void (**expirecb)(void *, DiamId_t, size_t, struct msg **), void ** data );
2530 int fd_msg_anscb_reset(struct msg * msg, int clear_anscb, int clear_expirecb);
2531 struct timespec *fd_msg_anscb_gettimeout( struct msg * msg ); /* returns NULL or a valid non-0 timespec */
2532
2533 /*
2534 * FUNCTION: fd_msg_rt_associate, fd_msg_rt_get
2535 *
2536 * PARAMETERS:
2537 * msg : the query message to be sent
2538 * list : the ordered list of possible next-peers
2539 *
2540 * DESCRIPTION:
2541 * Associate a routing list with a query, and retrieve it.
2542 * If the message is freed, the list is also freed.
2543 *
2544 * RETURN VALUE:
2545 * 0 : ok
2546 * EINVAL: a parameter is invalid
2547 */
2548 int fd_msg_rt_associate( struct msg * msg, struct rt_data * rtd );
2549 int fd_msg_rt_get ( struct msg * msg, struct rt_data ** rtd );
2550
2551 /*
2552 * FUNCTION: fd_msg_is_routable
2553 *
2554 * PARAMETERS:
2555 * msg : A msg object.
2556 *
2557 * DESCRIPTION:
2558 * This function returns a boolean telling if a given message is routable in the Diameter network,
2559 * or if it is a local link message only (ex: CER/CEA, DWR/DWA, ...).
2560 *
2561 * RETURN VALUE:
2562 * 0 : The message is not routable / an error occurred.
2563 * 1 : The message is routable.
2564 */
2565 int fd_msg_is_routable ( struct msg * msg );
2566
2567 /*
2568 * FUNCTION: fd_msg_source_(g/s)et
2569 *
2570 * PARAMETERS:
2571 * msg : A msg object.
2572 * diamid,len : The diameter id of the peer from which this message was received.
2573 * dict : a dictionary with definition of Route-Record AVP (for fd_msg_source_setrr)
2574 *
2575 * DESCRIPTION:
2576 * Store or retrieve the diameted id of the peer from which this message was received.
2577 * Will be used for example by the routing module to add the Route-Record AVP in forwarded requests,
2578 * or to direct answers to the appropriate peer.
2579 *
2580 * RETURN VALUE:
2581 * 0 : Operation complete.
2582 * !0 : an error occurred.
2583 */
2584 int fd_msg_source_set( struct msg * msg, DiamId_t diamid, size_t diamidlen );
2585 int fd_msg_source_setrr( struct msg * msg, DiamId_t diamid, size_t diamidlen, struct dictionary * dict );
2586 int fd_msg_source_get( struct msg * msg, DiamId_t *diamid, size_t * diamidlen );
2587
2588 /*
2589 * FUNCTION: fd_msg_eteid_get
2590 *
2591 * PARAMETERS:
2592 * -
2593 *
2594 * DESCRIPTION:
2595 * Get a new unique end-to-end id value for the local peer.
2596 *
2597 * RETURN VALUE:
2598 * The new assigned value. No error code is defined.
2599 */
2600 uint32_t fd_msg_eteid_get ( void );
2601
2602
2603 /*
2604 * FUNCTION: fd_msg_sess_get
2605 *
2606 * PARAMETERS:
2607 * dict : the dictionary that contains the Session-Id AVP definition
2608 * msg : A valid message.
2609 * session : Location to store the session pointer when retrieved.
2610 * isnew : Indicates if the session has been created.
2611 *
2612 * DESCRIPTION:
2613 * This function retrieves or creates the session object corresponding to a message.
2614 * If the message does not contain a Session-Id AVP, *session == NULL on return.
2615 * Note that the Session-Id AVP must never be modified after created in a message.
2616 *
2617 * RETURN VALUE:
2618 * 0 : success
2619 * !0 : standard error code.
2620 */
2621 int fd_msg_sess_get(struct dictionary * dict, struct msg * msg, struct session ** session, int * isnew);
2622
2623 /* This one is used by the libfdcore, you should use fd_msg_new_session rather than fd_sess_new, when possible */
2624 int fd_msg_sess_set(struct msg * msg, struct session * session);
2625
2626
2627 /* Helper for the hooks mechanism, for use from libfdcore */
2628 struct fd_msg_pmdl {
2629 struct fd_list sentinel; /* if the sentinel.o field is NULL, the structure is not initialized. Otherwise it points to the cleanup function in libfdcore. */
2630 pthread_mutex_t lock;
2631 };
2632 struct fd_msg_pmdl * fd_msg_pmdl_get(struct msg * msg);
2633
2634
2635 /***************************************/
2636 /* Manage AVP values */
2637 /***************************************/
2638
2639 /*
2640 * FUNCTION: fd_msg_avp_setvalue
2641 *
2642 * PARAMETERS:
2643 * avp : Pointer to a valid avp object with a NULL avp_value pointer. The model must be known.
2644 * value : pointer to an avp_value. The content will be COPIED into the internal storage area.
2645 * If data type is an octetstring, the data is also copied.
2646 * If value is a NULL pointer, the previous data is erased and value is unset in the AVP.
2647 *
2648 * DESCRIPTION:
2649 * Initialize the avp_value field of an AVP header.
2650 *
2651 * RETURN VALUE:
2652 * 0 : The avp_value pointer has been set.
2653 * EINVAL : A parameter is invalid.
2654 */
2655 int fd_msg_avp_setvalue ( struct avp *avp, union avp_value *value );
2656
2657 /*
2658 * FUNCTION: fd_msg_avp_value_encode
2659 *
2660 * PARAMETERS:
2661 * avp : Pointer to a valid avp object with a NULL avp_value. The model must be known.
2662 * data : Pointer to the data that must be encoded as AVP value and stored in the AVP.
2663 * This is only valid for AVPs of derived type for which type_data_encode callback is set. (ex: Address type)
2664 *
2665 * DESCRIPTION:
2666 * Initialize the avp_value field of an AVP object from formatted data, using the AVP's type "type_data_encode" callback.
2667 *
2668 * RETURN VALUE:
2669 * 0 : The avp_value has been set.
2670 * EINVAL : A parameter is invalid.
2671 * ENOTSUP : There is no appropriate callback registered with this AVP's type.
2672 */
2673 int fd_msg_avp_value_encode ( void *data, struct avp *avp );
2674 /*
2675 * FUNCTION: fd_msg_avp_value_interpret
2676 *
2677 * PARAMETERS:
2678 * avp : Pointer to a valid avp object with a non-NULL avp_value value.
2679 * data : Upon success, formatted interpretation of the AVP value is stored here.
2680 *
2681 * DESCRIPTION:
2682 * Interpret the content of an AVP of Derived type and store the result in data pointer. The structure
2683 * of the data pointer is dependent on the AVP type. This function calls the "type_data_interpret" callback
2684 * of the type.
2685 *
2686 * RETURN VALUE:
2687 * 0 : The avp_value has been set.
2688 * EINVAL : A parameter is invalid.
2689 * ENOTSUP : There is no appropriate callback registered with this AVP's type.
2690 */
2691 int fd_msg_avp_value_interpret ( struct avp *avp, void *data );
2692
2693
2694 /***************************************/
2695 /* Message parsing functions */
2696 /***************************************/
2697
2698 /*
2699 * FUNCTION: fd_msg_bufferize
2700 *
2701 * PARAMETERS:
2702 * msg : A valid msg object. All AVPs must have a value set.
2703 * buffer : Upon success, this points to a buffer (malloc'd) containing the message ready for network transmission (or security transformations).
2704 * The buffer may be freed after use.
2705 * len : if not NULL, the size of the buffer is written here. In any case, this size is updated in the msg header.
2706 *
2707 * DESCRIPTION:
2708 * Renders a message in memory as a buffer that can be sent over the network to the next peer.
2709 *
2710 * RETURN VALUE:
2711 * 0 : The location has been written.
2712 * EINVAL : The buffer does not contain a valid Diameter message.
2713 * ENOMEM : Unable to allocate enough memory to create the buffer object.
2714 */
2715 int fd_msg_bufferize ( struct msg * msg, uint8_t ** buffer, size_t * len );
2716
2717 /*
2718 * FUNCTION: fd_msg_parse_buffer
2719 *
2720 * PARAMETERS:
2721 * buffer : Pointer to a buffer containing a message received from the network.
2722 * buflen : the size in bytes of the buffer.
2723 * msg : Upon success, this points to a valid msg object. No AVP value is resolved in this object, nor grouped AVP.
2724 *
2725 * DESCRIPTION:
2726 * This function parses a buffer an creates a msg object to represent the structure of the message.
2727 * Since no dictionary lookup is performed, the values of the AVPs are not interpreted. To interpret the values,
2728 * the returned message object must be passed to fd_msg_parse_dict function.
2729 * The buffer pointer is saved inside the message and will be freed when not needed anymore.
2730 *
2731 * RETURN VALUE:
2732 * 0 : The location has been written.
2733 * ENOMEM : Unable to allocate enough memory to create the msg object.
2734 * EBADMSG : The buffer does not contain a valid Diameter message (or is truncated).
2735 * EINVAL : A parameter is invalid.
2736 */
2737 int fd_msg_parse_buffer ( uint8_t ** buffer, size_t buflen, struct msg ** msg );
2738
2739 /* Parsing Error Information structure */
2740 struct fd_pei {
2741 char * pei_errcode; /* name of the error code to use */
2742 struct avp * pei_avp; /* pointer to invalid (in original message) or missing AVP (to be freed) */
2743 int pei_avp_free; /* Set to 1 if the pei_avp must be freed */
2744 char * pei_message; /* Overwrite default message if needed */
2745 int pei_protoerr; /* do we set the 'E' bit in the error message ? */
2746 };
2747
2748 /*
2749 * FUNCTION: fd_msg_parse_dict
2750 *
2751 * PARAMETERS:
2752 * object : A msg or AVP object as returned by fd_msg_parse_buffer.
2753 * dict : the dictionary containing the objects definitions to use for resolving all AVPs.
2754 * error_info : If not NULL, will contain the detail about error upon return. May be used to generate an error reply.
2755 *
2756 * DESCRIPTION:
2757 * This function looks up for the command and each children AVP definitions in the dictionary.
2758 * If the dictionary definition is found, avp_model is set and the value of the AVP is interpreted accordingly and:
2759 * - for grouped AVPs, the children AVP are created and interpreted also.
2760 * - for numerical AVPs, the value is converted to host byte order and saved in the avp_value field.
2761 * - for octetstring AVPs, the string is copied into a new buffer and its address is saved in avp_value.
2762 * If the dictionary definition is not found, avp_model is set to NULL and
2763 * the content of the AVP is saved as an octetstring in an internal structure. avp_value is NULL.
2764 * 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.
2765 *
2766 * RETURN VALUE:
2767 * 0 : The message has been fully parsed as described.
2768 * EINVAL : The msg parameter is invalid for this operation.
2769 * ENOMEM : Unable to allocate enough memory to complete the operation.
2770 * ENOTSUP : No dictionary definition for the command or one of the mandatory AVP was found.
2771 */
2772 int fd_msg_parse_dict ( msg_or_avp * object, struct dictionary * dict, struct fd_pei * error_info );
2773
2774 /*
2775 * FUNCTION: fd_msg_parse_rules
2776 *
2777 * PARAMETERS:
2778 * object : A msg or grouped avp object that must be verified.
2779 * dict : The dictionary containing the rules definitions.
2780 * error_info : If not NULL, the first problem information will be saved here.
2781 *
2782 * DESCRIPTION:
2783 * Check that the children of the object do not conflict with the dictionary rules (ABNF compliance).
2784 *
2785 * RETURN VALUE:
2786 * 0 : The message has been fully parsed and complies to the defined rules.
2787 * EBADMSG : A conflict was detected, or a mandatory AVP is unknown in the dictionary.
2788 * EINVAL : The msg or avp object is invalid for this operation.
2789 * ENOMEM : Unable to allocate enough memory to complete the operation.
2790 */
2791 int fd_msg_parse_rules ( msg_or_avp * object, struct dictionary * dict, struct fd_pei * error_info);
2792
2793
2794
2795 /*
2796 * FUNCTION: fd_msg_update_length
2797 *
2798 * PARAMETERS:
2799 * object : Pointer to a valid msg or avp.
2800 *
2801 * DESCRIPTION:
2802 * Update the length field of the object passed as parameter.
2803 * As a side effect, all children objects are also updated. Therefore, all avp_value fields of
2804 * the children AVPs must be set, or an error will occur.
2805 *
2806 * RETURN VALUE:
2807 * 0 : The size has been recomputed.
2808 * EINVAL : A parameter is invalid.
2809 */
2810 int fd_msg_update_length ( msg_or_avp * object );
2811
2812
2813 /*============================================================*/
2814 /* DISPATCH */
2815 /*============================================================*/
2816
2817 /* Dispatch module (passing incoming messages to extensions registered callbacks)
2818 * is split between the library and the daemon.
2819 *
2820 * The library provides the support for associating dispatch callbacks with
2821 * dictionary objects.
2822 *
2823 * The daemon is responsible for calling the callbacks for a message when appropriate.
2824 *
2825 *
2826 * The dispatch module has two main roles:
2827 * - help determine if a message can be handled locally (during the routing step)
2828 * This decision involves only the application-id of the message.
2829 * - pass the message to the callback(s) that will handle it (during the dispatch step)
2830 *
2831 * The first role is handled by the daemon.
2832 *
2833 * About the second, these are the possibilities for registering a dispatch callback:
2834 *
2835 * -> For All messages.
2836 * This callback is called for all messages that are handled locally. This should be used only
2837 * for debug purpose.
2838 *
2839 * -> by AVP value (constants only).
2840 * This callback will be called when a message is received and contains an AVP with a specified enumerated value.
2841 *
2842 * -> by AVP.
2843 * This callback will be called when the received message contains a certain AVP.
2844 *
2845 * -> by command-code.
2846 * This callback will be called when the message is a specific command (and 'R' flag).
2847 *
2848 * -> by application.
2849 * This callback will be called when the message has a specific application-id.
2850 *
2851 * ( by vendor: would this be useful? it may be added later)
2852 */
2853 enum disp_how {
2854 DISP_HOW_ANY = 1, /* Any message. This should be only used for debug. */
2855 DISP_HOW_APPID, /* Any message with the specified application-id */
2856 DISP_HOW_CC, /* Messages of the specified command-code (request or answer). App id may be specified. */
2857 DISP_HOW_AVP, /* Messages containing a specific AVP. Command-code and App id may be specified. */
2858 DISP_HOW_AVP_ENUMVAL /* Messages containing a specific AVP with a specific enumerated value. Command-code and App id may be specified. */
2859 };
2860 /*
2861 * Several criteria may be selected at the same time, for example command-code AND application id.
2862 *
2863 * If several callbacks are registered for the same object, they are called in the order they were registered.
2864 * The order in which the callbacks are called is:
2865 * DISP_HOW_ANY
2866 * DISP_HOW_AVP_ENUMVAL & DISP_HOW_AVP
2867 * DISP_HOW_CC
2868 * DISP_HOW_APPID
2869 */
2870
2871 /* When a callback is registered, a "when" argument is passed in addition to the disp_how value,
2872 * to specify which values the criteria must match. */
2873 struct disp_when {
2874 struct dict_object * app;
2875 struct dict_object * command;
2876 struct dict_object * avp;
2877 struct dict_object * value;
2878 };
2879
2880 /* Note that all the dictionary objects should really belong to the same dictionary!
2881 *
2882 * Here is the details on this "when" argument, depending on the disp_how value.
2883 *
2884 * DISP_HOW_ANY.
2885 * In this case, "when" must be NULL.
2886 *
2887 * DISP_HOW_APPID.
2888 * Only the "app_id" field must be set, other fields are ignored. It points to a dictionary object of type DICT_APPLICATION.
2889 *
2890 * DISP_HOW_CC.
2891 * The "command" field must be defined and point to a dictionary object of type DICT_COMMAND.
2892 * The "app_id" may be also set. In the case it is set, it restricts the callback to be called only with this command-code and app id.
2893 * The other fields are ignored.
2894 *
2895 * DISP_HOW_AVP.
2896 * The "avp" field of the structure must be set and point to a dictionary object of type DICT_AVP.
2897 * The "app_id" field may be set to restrict the messages matching to a specific app id.
2898 * The "command" field may also be set to a valid DICT_COMMAND object.
2899 * The content of the "value" field is ignored.
2900 *
2901 * DISP_HOW_AVP_ENUMVAL.
2902 * All fields have the same constraints and meaning as in DISP_REG_AVP. In addition, the "value" field must be set
2903 * and points to a valid DICT_ENUMVAL object.
2904 *
2905 * Here is a sumary of the fields: ( M : must be set; m : may be set; 0 : ignored )
2906 * field: app_id command avp value
2907 * APPID : M 0 0 0
2908 * CC : m M 0 0
2909 * AVP : m m M 0
2910 * ENUMVA: m m M M
2911 */
2912
2913 enum disp_action {
2914 DISP_ACT_CONT, /* The next handler should be called, unless *msg == NULL. */
2915 DISP_ACT_SEND, /* The updated message must be sent. No further callback is called. */
2916 DISP_ACT_ERROR /* An error must be created and sent as a reply -- not valid for callbacks, only for fd_msg_dispatch. */
2917 };
2918 /* The callbacks that are registered have the following prototype:
2919 * int dispatch_callback( struct msg ** msg, struct avp * avp, struct session * session, enum disp_action * action );
2920 *
2921 * CALLBACK: dispatch_callback
2922 *
2923 * PARAMETERS:
2924 * msg : the received message on function entry. may be updated to answer on return (see description)
2925 * avp : for callbacks registered with DISP_HOW_AVP or DISP_HOW_AVP_ENUMVAL, direct link to the triggering AVP.
2926 * session : if the message contains a Session-Id AVP, the corresponding session object, NULL otherwise.
2927 * opaque : An opaque pointer that is registered along the session handler.
2928 * action : upon return, this tells the daemon what to do next.
2929 *
2930 * DESCRIPTION:
2931 * Called when a received message matchs the condition for which the callback was registered.
2932 * This callback may do any kind of processing on the message, including:
2933 * - create an answer for a request.
2934 * - proxy a request or message, add / remove the Proxy-Info AVP, then forward the message.
2935 * - update a routing table or start a connection with a new peer, then forward the message.
2936 * - ...
2937 *
2938 * When *action == DISP_ACT_SEND on callback return, the msg pointed by *msg is passed to the routing module for sending.
2939 * When *action == DISP_ACT_CONT, the next registered callback is called.
2940 * When the last callback gives also DISP_ACT_CONT action value, a default handler is called. It's behavior is as follow:
2941 * - if the message is an answer, it is discarded.
2942 * - if the message is a request, it is passed again to the routing stack, and marked as non-local handling.
2943 *
2944 * RETURN VALUE:
2945 * 0 : The callback executed successfully and updated *action appropriately.
2946 * !0 : standard errors. In case of error, the message is discarded.
2947 */
2948
2949 /* This structure represents a handler for a registered callback, allowing its de-registration */
2950 struct disp_hdl;
2951
2952 /*
2953 * FUNCTION: fd_disp_register
2954 *
2955 * PARAMETERS:
2956 * cb : The callback function to register (see dispatch_callback description above).
2957 * how : How the callback must be registered.
2958 * when : Values that must match, depending on the how argument.
2959 * opaque : A pointer that is passed back to the handler. The content is not interpreted by the framework.
2960 * handle : On success, a handler to the registered callback is stored here if not NULL.
2961 * This handler can be used to unregister the cb.
2962 *
2963 * DESCRIPTION:
2964 * Register a new callback to handle messages delivered locally.
2965 *
2966 * RETURN VALUE:
2967 * 0 : The callback is registered.
2968 * EINVAL : A parameter is invalid.
2969 * ENOMEM : Not enough memory to complete the operation
2970 */
2971 int fd_disp_register ( int (*cb)( struct msg **, struct avp *, struct session *, void *, enum disp_action *),
2972 enum disp_how how, struct disp_when * when, void * opaque, struct disp_hdl ** handle );
2973
2974 /*
2975 * FUNCTION: fd_disp_unregister
2976 *
2977 * PARAMETERS:
2978 * handle : Location of the handle of the callback that must be unregistered.
2979 * opaque : If not NULL, the opaque data that was registered is restored here.
2980 *
2981 * DESCRIPTION:
2982 * Removes a callback previously registered by fd_disp_register.
2983 *
2984 * RETURN VALUE:
2985 * 0 : The callback is unregistered.
2986 * EINVAL : A parameter is invalid.
2987 */
2988 int fd_disp_unregister ( struct disp_hdl ** handle, void ** opaque );
2989
2990 /* Destroy all handlers */
2991 void fd_disp_unregister_all ( void );
2992
2993 /*
2994 * FUNCTION: fd_msg_dispatch
2995 *
2996 * PARAMETERS:
2997 * msg : A msg object that have already been fd_msg_parse_dict.
2998 * session : The session corresponding to this object, if any.
2999 * action : Upon return, the action that must be taken on the message
3000 * error_code : Upon return with action == DISP_ACT_ERROR, contains the error (such as "DIAMETER_UNABLE_TO_COMPLY")
3001 * drop_reason : if set on return, the message must be freed for this reason.
3002 * drop_msg : if drop_reason is set, this points to the message to be freed while *msg is NULL.
3003 *
3004 * DESCRIPTION:
3005 * Call all handlers registered for a given message.
3006 * The session must have already been resolved on entry.
3007 * The msg pointed may be updated during this process.
3008 * Upon return, the action parameter points to what must be done next.
3009 *
3010 * RETURN VALUE:
3011 * 0 : Success.
3012 * EINVAL : A parameter is invalid.
3013 * (other errors)
3014 */
3015 int fd_msg_dispatch ( struct msg ** msg, struct session * session, enum disp_action *action, char ** error_code, char ** drop_reason, struct msg ** drop_msg );
3016
3017
3018
3019 /*============================================================*/
3020 /* QUEUES */
3021 /*============================================================*/
3022
3023 /* Management of FIFO queues of elements */
3024
3025 /* A queue is an opaque object */
3026 struct fifo;
3027
3028 /*
3029 * FUNCTION: fd_fifo_new
3030 *
3031 * PARAMETERS:
3032 * queue : Upon success, a pointer to the new queue is saved here.
3033 * max : max number of items in the queue. Above this number, adding a new item becomes a
3034 * blocking operation. Use 0 to disable this maximum.
3035 *
3036 * DESCRIPTION:
3037 * Create a new empty queue.
3038 *
3039 * RETURN VALUE :
3040 * 0 : The queue has been initialized successfully.
3041 * EINVAL : The parameter is invalid.
3042 * ENOMEM : Not enough memory to complete the creation.
3043 */
3044 int fd_fifo_new ( struct fifo ** queue, int max );
3045
3046 /*
3047 * FUNCTION: fd_fifo_set_max
3048 *
3049 * PARAMETERS:
3050 * queue : The queue for which to set the maximum value
3051 * max : max number of items in the queue.
3052 *
3053 * DESCRIPTION:
3054 * Modify the maximum number of entries in a queue
3055 *
3056 * RETURN VALUE :
3057 * 0 : Success
3058 */
3059 int fd_fifo_set_max ( struct fifo * queue, int max );
3060
3061 /*
3062 * FUNCTION: fd_fifo_del
3063 *
3064 * PARAMETERS:
3065 * queue : Pointer to an empty queue to delete.
3066 *
3067 * DESCRIPTION:
3068 * Destroys a queue. This is only possible if no thread is waiting for an element,
3069 * and the queue is empty.
3070 *
3071 * RETURN VALUE:
3072 * 0 : The queue has been destroyed successfully.
3073 * EINVAL : The parameter is invalid.
3074 */
3075 int fd_fifo_del ( struct fifo ** queue );
3076
3077 /*
3078 * FUNCTION: fd_fifo_move
3079 *
3080 * PARAMETERS:
3081 * oldq : Location of a FIFO that is to be emptied.
3082 * newq : A FIFO that will receive the old data.
3083 * loc_update : if non NULL, a place to store the pointer to new FIFO atomically with the move.
3084 *
3085 * DESCRIPTION:
3086 * Empties a queue and move its content to another one atomically.
3087 *
3088 * RETURN VALUE:
3089 * 0 : The queue has been destroyed successfully.
3090 * EINVAL : A parameter is invalid.
3091 */
3092 int fd_fifo_move ( struct fifo * oldq, struct fifo * newq, struct fifo ** loc_update );
3093
3094 /*
3095 * FUNCTION: fd_fifo_getstats
3096 *
3097 * PARAMETERS:
3098 * queue : The queue from which to retrieve the information.
3099 * current_count : How many items in the queue at the time of execution. This changes each time an item is pushed or poped.
3100 * limit_count : The maximum number of items allowed in this queue. This is specified during queue creation.
3101 * highest_count : The maximum number of items this queue has contained. This enables to see if limit_count count was reached.
3102 * total_count : the total number of items that went through the queue (already pop'd). Always increasing.
3103 * total : Cumulated time all items spent in this queue, including blocking time (always growing, use deltas for monitoring)
3104 * blocking : Cumulated time threads trying to post new items were blocked (queue full).
3105 * last : For the last element retrieved from the queue, how long it take between posting (including blocking) and poping
3106 *
3107 * DESCRIPTION:
3108 * Retrieve the timing information associated with a queue, for monitoring purpose.
3109 *
3110 * RETURN VALUE:
3111 * 0 : The statistics have been updated.
3112 * EINVAL : A parameter is invalid.
3113 */
3114 int fd_fifo_getstats( struct fifo * queue, int * current_count, int * limit_count, int * highest_count, long long * total_count,
3115 struct timespec * total, struct timespec * blocking, struct timespec * last);
3116
3117 /*
3118 * FUNCTION: fd_fifo_length
3119 *
3120 * PARAMETERS:
3121 * queue : The queue from which to retrieve the number of elements.
3122 *
3123 * DESCRIPTION:
3124 * Retrieve the number of elements in a queue, without error checking.
3125 *
3126 * RETURN VALUE:
3127 * The number of items currently queued.
3128 */
3129 int fd_fifo_length ( struct fifo * queue );
3130
3131 /*
3132 * FUNCTION: fd_fifo_setthrhd
3133 *
3134 * PARAMETERS:
3135 * queue : The queue for which the thresholds are being set.
3136 * data : An opaque pointer that is passed to h_cb and l_cb callbacks.
3137 * high : The high-level threshold. If the number of elements in the queue increase to this value, h_cb is called.
3138 * h_cb : if not NULL, a callback to call when the queue lengh is bigger than "high".
3139 * low : The low-level threshold. Must be < high.
3140 * l_cb : If the number of elements decrease to low, this callback is called.
3141 *
3142 * DESCRIPTION:
3143 * This function allows to adjust the number of producer / consumer threads of a queue.
3144 * If the consumer are slower than the producers, the number of elements in the queue increase.
3145 * By setting a "high" value, we allow a callback to be called when this number is too high.
3146 * The typical use would be to create an additional consumer thread in this callback.
3147 * If the queue continues to grow, the callback will be called again when the length is 2 * high, then 3*high, ... N * high
3148 * (the callback itself should implement a limit on the number of consumers that can be created)
3149 * When the queue starts to decrease, and the number of elements go under ((N - 1) * high + low, the l_cb callback is called
3150 * and would typially stop one of the consumer threads. If the queue continues to reduce, l_cb is again called at (N-2)*high + low,
3151 * and so on.
3152 *
3153 * Since there is no destructor for the data pointer, if cleanup operations are required, they should be performed in
3154 * l_cb when the length of the queue is becoming < low.
3155 *
3156 * Note that the callbacks are called synchronously, during fd_fifo_post or fd_fifo_get. Their operation should be quick.
3157 *
3158 * RETURN VALUE:
3159 * 0 : The thresholds have been set
3160 * EINVAL : A parameter is invalid.
3161 */
3162 int fd_fifo_setthrhd ( struct fifo * queue, void * data, uint16_t high, void (*h_cb)(struct fifo *, void **), uint16_t low, void (*l_cb)(struct fifo *, void **) );
3163
3164 /*
3165 * FUNCTION: fd_fifo_post
3166 *
3167 * PARAMETERS:
3168 * queue : The queue in which the element must be posted.
3169 * item : The element that is put in the queue.
3170 *
3171 * DESCRIPTION:
3172 * An element is added in a queue. Elements are retrieved from the queue in FIFO order
3173 * with the fd_fifo_get, fd_fifo_tryget, or fd_fifo_timedget functions.
3174 *
3175 * RETURN VALUE:
3176 * 0 : The element is queued.
3177 * EINVAL : A parameter is invalid.
3178 * ENOMEM : Not enough memory to complete the operation.
3179 */
3180 int fd_fifo_post_int ( struct fifo * queue, void ** item );
3181 #define fd_fifo_post(queue, item) \
3182 fd_fifo_post_int((queue), (void *)(item))
3183
3184 /* Similar function but does not block. It can cause the number of items in the queue to exceed the maximum set. Do not use for normal operation,
3185 only for failure recovery for example. */
3186 int fd_fifo_post_noblock( struct fifo * queue, void ** item );
3187
3188 /*
3189 * FUNCTION: fd_fifo_get
3190 *
3191 * PARAMETERS:
3192 * queue : The queue from which the first element must be retrieved.
3193 * item : On return, the first element of the queue is stored here.
3194 *
3195 * DESCRIPTION:
3196 * This function retrieves the first element from a queue. If the queue is empty, the function will block the
3197 * thread until a new element is posted to the queue, or until the thread is canceled (in which case the
3198 * function does not return).
3199 *
3200 * RETURN VALUE:
3201 * 0 : A new element has been retrieved.
3202 * EINVAL : A parameter is invalid.
3203 */
3204 int fd_fifo_get_int ( struct fifo * queue, void ** item );
3205 #define fd_fifo_get(queue, item) \
3206 fd_fifo_get_int((queue), (void *)(item))
3207
3208 /*
3209 * FUNCTION: fd_fifo_tryget
3210 *
3211 * PARAMETERS:
3212 * queue : The queue from which the element must be retrieved.
3213 * item : On return, the first element of the queue is stored here.
3214 *
3215 * DESCRIPTION:
3216 * This function is similar to fd_fifo_get, except that it will not block if
3217 * the queue is empty, but return EWOULDBLOCK instead.
3218 *
3219 * RETURN VALUE:
3220 * 0 : A new element has been retrieved.
3221 * EINVAL : A parameter is invalid.
3222 * EWOULDBLOCK : The queue was empty.
3223 */
3224 int fd_fifo_tryget_int ( struct fifo * queue, void ** item );
3225 #define fd_fifo_tryget(queue, item) \
3226 fd_fifo_tryget_int((queue), (void *)(item))
3227
3228 /*
3229 * FUNCTION: fd_fifo_timedget
3230 *
3231 * PARAMETERS:
3232 * queue : The queue from which the element must be retrieved.
3233 * item : On return, the element is stored here.
3234 * abstime : the absolute time until which we allow waiting for an item.
3235 *
3236 * DESCRIPTION:
3237 * This function is similar to fd_fifo_get, except that it will block if the queue is empty
3238 * only until the absolute time abstime (see pthread_cond_timedwait for + info).
3239 * If the queue is still empty when the time expires, the function returns ETIMEDOUT
3240 *
3241 * RETURN VALUE:
3242 * 0 : A new item has been retrieved.
3243 * EINVAL : A parameter is invalid.
3244 * ETIMEDOUT : The time out has passed and no item has been received.
3245 */
3246 int fd_fifo_timedget_int ( struct fifo * queue, void ** item, const struct timespec *abstime );
3247 #define fd_fifo_timedget(queue, item, abstime) \
3248 fd_fifo_timedget_int((queue), (void *)(item), (abstime))
3249
3250
3251 /*
3252 * FUNCTION: fd_fifo_select
3253 *
3254 * PARAMETERS:
3255 * queue : The queue to test.
3256 * abstime : the absolute time until which we can block waiting for an item. If NULL, the function returns immediatly.
3257 *
3258 * DESCRIPTION:
3259 * This function is similar to select(), it waits for data to be available in the queue
3260 * until the abstime is expired.
3261 * Upon function entry, even if abstime is already expired the data availability is tested.
3262 *
3263 * RETURN VALUE:
3264 * 0 : timeout expired without available data.
3265 * <0 : An error occurred (e.g., -EINVAL...)
3266 * >0 : data is available. The next call to fd_fifo_get will not block.
3267 */
3268 int fd_fifo_select ( struct fifo * queue, const struct timespec *abstime );
3269
3270
3271
3272 /* Dump a fifo list and optionally its inner elements -- beware of deadlocks! */
3273 typedef DECLARE_FD_DUMP_PROTOTYPE((*fd_fifo_dump_item_cb), void * item); /* This function should be 1 line if possible, or use indent level. Ends with '\n' */
3274 DECLARE_FD_DUMP_PROTOTYPE(fd_fifo_dump, char * name, struct fifo * queue, fd_fifo_dump_item_cb dump_item);
3275
3276 #ifdef __cplusplus
3277 }
3278 #endif
3279
3280 #endif /* _LIBFDPROTO_H */
3281