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