Navigation


source: freeDiameter/include/freeDiameter/libfdproto.h @ 738:d666051658bd

Last change on this file since 738:d666051658bd was 738:d666051658bd, checked in by Sebastien Decugis <sdecugis@nict.go.jp>, 11 years ago

Fix broken 'almostcasecmp' logic

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