libfreeDiameter.h @ 648:ae29bf971f20

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

Note: See TracBrowser for help on using the repository browser.

Navigation

source: freeDiameter/include/freeDiameter/libfreeDiameter.h @ 648:ae29bf971f20

Download in other formats: