libfdproto.h @ 784:e87d083d0342

Revision 784:e87d083d0342, 112.0 KB checked in by Sebastien Decugis <sdecugis@nict.go.jp>, 7 weeks ago (diff)
Added ability to register another log function; thanks to Zack for the code

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

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

Navigation

source: freeDiameter/include/freeDiameter/libfdproto.h @ 784:e87d083d0342

Download in other formats: