Mercurial > hg > freeDiameter

comparison include/freediameter/libfreediameter.h @ 0:13530e1f02e3

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Initial files imported
author Sebastien Decugis <sdecugis@nict.go.jp>
date Fri, 28 Aug 2009 19:14:42 +0900
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:13530e1f02e3
1 /*********************************************************************************************************
2 * Software License Agreement (BSD License) *
3 * Author: Sebastien Decugis <sdecugis@nict.go.jp> *
4 * *
5 * Copyright (c) 2009, 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 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 *
40 * It provides the tools to manipulate Diameter messages and related data.
41 *
42 * This file should always be included as #include <freediameter/libfreediameter.h>
43 * Note that this library does not store any state. The daemon must pass the pointer to
44 * the dictionary and other global objects to all extensions that use the libfreediameter
45 * library.
46 */
47
48 #ifndef _LIBFREEDIAMETER_H
49 #define _LIBFREEDIAMETER_H
50
51 #ifndef FD_IS_CONFIG
52 #error "You must include 'freediameter-host.h' before this file."
53 #endif /* FD_IS_CONFIG */
54
55 #include <pthread.h>
56 #include <string.h>
57 #include <assert.h>
58 #include <errno.h>
59 #include <arpa/inet.h>
60 #include <sys/socket.h>
61 #include <netdb.h>
62 #include <stdio.h>
63 #include <stdlib.h>
64 #include <unistd.h>
65
66 /*============================================================*/
67 /* DEBUG */
68 /*============================================================*/
69 #ifndef ASSERT
70 #define ASSERT(x) assert(x)
71 #endif /* ASSERT */
72
73 /*
74 * FUNCTION: fd_log_debug
75 *
76 * PARAMETERS:
77 * format : Same format string as in the printf function
78 * ... : Same list as printf
79 *
80 * DESCRIPTION:
81 * Log internal information for use of developpers only.
82 * The format and arguments may contain UTF-8 encoded data. The
83 * output medium (file or console) is expected to support this encoding.
84 *
85 * This function assumes that a global mutex called "fd_log_lock" exists
86 * in the address space of the current process.
87 *
88 * RETURN VALUE:
89 * None.
90 */
91 void fd_log_debug ( char * format, ... );
92 extern pthread_mutex_t fd_log_lock;
93
94 /*
95 * FUNCTION: fd_log_threadname
96 *
97 * PARAMETERS:
98 * name : \0-terminated string containing a name to identify the current thread.
99 *
100 * DESCRIPTION:
101 * Name the current thread, useful for debugging multi-threaded problems.
102 *
103 * This function assumes that a global thread-specific key called "fd_log_thname" exists
104 * in the address space of the current process.
105 *
106 * RETURN VALUE:
107 * None.
108 */
109 void fd_log_threadname ( char * name );
110 extern pthread_key_t fd_log_thname;
111
112 /*
113 * FUNCTION: fd_log_time
114 *
115 * PARAMETERS:
116 * buf : An array where the time must be stored
117 * len : size of the buffer
118 *
119 * DESCRIPTION:
120 * Writes the current timestamp (in human readable format) in a buffer.
121 *
122 * RETURN VALUE:
123 * pointer to buf.
124 */
125 char * fd_log_time ( char * buf, size_t len );
126
127 /************************** DEBUG MACROS ************************************/
128
129 /* levels definitions */
130 #define NONE 0 /* Display no debug message */
131 #define INFO 1 /* Display errors only */
132 #define FULL 2 /* Display additional information to follow code execution */
133 #define ANNOYING 4 /* Very verbose, for example in loops */
134 #define FCTS 6 /* Display entry parameters of most functions */
135 #define CALL 9 /* Display calls to most functions (with CHECK macros) */
136
137 /* Default level is INFO */
138 #ifndef TRACE_LEVEL
139 #define TRACE_LEVEL INFO
140 #endif /* TRACE_LEVEL */
141
142 /* The level of the file being compiled */
143 static int local_debug_level = TRACE_LEVEL;
144
145 /* helper macros (pre-processor hacks) */
146 #define __str( arg ) #arg
147 #define _stringize( arg ) __str( arg )
148 #define __agr( arg1, arg2 ) arg1 ## arg2
149 #define _aggregate( arg1, arg2 ) __agr( arg1, arg2 )
150
151 /* Some portability tricks to get nice function name in __PRETTY_FUNCTION__ */
152 #if __STDC_VERSION__ < 199901L
153 # if __GNUC__ >= 2
154 # define __func__ __FUNCTION__
155 # else /* __GNUC__ >= 2 */
156 # define __func__ "<unknown>"
157 # endif /* __GNUC__ >= 2 */
158 #endif /* __STDC_VERSION__ < 199901L */
159 #ifndef __PRETTY_FUNCTION__
160 #define __PRETTY_FUNCTION__ __func__
161 #endif /* __PRETTY_FUNCTION__ */
162
163 /* Boolean for tracing at a certain level */
164 #define TRACE_BOOL(_level_) ( (_level_) <= local_debug_level )
165
166 /* The general debug macro, each call results in two lines of debug messages */
167 #define TRACE_DEBUG(level,format,args... ) { \
168 if ( TRACE_BOOL(level) ) { \
169 char __buf[25]; \
170 char * __thn = ((char *)pthread_getspecific(fd_log_thname) ?: "unnamed"); \
171 fd_log_debug("\t | th:%-30s\t%s\tin %s@%s:%d\n" \
172 "\t%s|%*s" format "\n", \
173 __thn, fd_log_time(__buf, sizeof(__buf)), __PRETTY_FUNCTION__, __FILE__, __LINE__, \
174 (level < FULL)?"@":" ",level, "", ## args); \
175 } \
176 }
177
178 /* Helper for function entry */
179 #define TRACE_ENTRY(_format,_args... ) \
180 TRACE_DEBUG(FCTS, "->%s (" #_args ") = (" _format ") >", __PRETTY_FUNCTION__, ##_args );
181
182 /* Helper for debugging by adding traces */
183 #define TRACE_HERE() \
184 TRACE_DEBUG(INFO, " -- debug checkpoint -- ");
185
186 /* Helper for tracing the CHECK_* macros bellow */
187 #define TRACE_DEBUG_ALL( str ) \
188 TRACE_DEBUG(CALL, str );
189
190
191 /* Macros to check a return value and branch out in case of error.
192 * These macro must be used only when errors are highly improbable, not for expected errors.
193 */
194
195 /* Check the return value of a system function and execute fallback in case of error */
196 #define CHECK_SYS_DO( __call__, __fallback__ ) { \
197 int __ret__; \
198 TRACE_DEBUG_ALL( "Check SYS: " #__call__ ); \
199 __ret__ = (__call__); \
200 if (__ret__ < 0) { \
201 int __err__ = errno; /* We may handle EINTR here */ \
202 TRACE_DEBUG(NONE, "ERROR: in '" #__call__ "' :\t%s", strerror(__err__));\
203 __fallback__; \
204 } \
205 }
206 /* Check the return value of a system function, return error code on error */
207 #define CHECK_SYS( __call__ ) { \
208 int __ret__; \
209 TRACE_DEBUG_ALL( "Check SYS: " #__call__ ); \
210 __ret__ = (__call__); \
211 if (__ret__ < 0) { \
212 int __err__ = errno; /* We may handle EINTR here */ \
213 TRACE_DEBUG(NONE, "ERROR: in '" #__call__ "' :\t%s", strerror(__err__));\
214 return __err__; \
215 } \
216 }
217
218 /* Check the return value of a POSIX function and execute fallback in case of error or special value */
219 #define CHECK_POSIX_DO2( __call__, __speval__, __fallback1__, __fallback2__ ) { \
220 int __ret__; \
221 TRACE_DEBUG_ALL( "Check POSIX: " #__call__ ); \
222 __ret__ = (__call__); \
223 if (__ret__ != 0) { \
224 if (__ret__ == (__speval__)) { \
225 __fallback1__; \
226 } else { \
227 TRACE_DEBUG(NONE, "ERROR: in '" #__call__ "':\t%s", strerror(__ret__)); \
228 __fallback2__; \
229 } \
230 } \
231 }
232
233 /* Check the return value of a POSIX function and execute fallback in case of error */
234 #define CHECK_POSIX_DO( __call__, __fallback__ ) \
235 CHECK_POSIX_DO2( (__call__), 0, , __fallback__ );
236
237 /* Check the return value of a POSIX function and return it if error */
238 #define CHECK_POSIX( __call__ ) { \
239 int __v__; \
240 CHECK_POSIX_DO( __v__ = (__call__), return __v__ ); \
241 }
242
243 /* Check that a memory allocator did not return NULL, otherwise log an error and execute fallback */
244 #define CHECK_MALLOC_DO( __call__, __fallback__ ) { \
245 void * __ret__; \
246 TRACE_DEBUG_ALL( "Check MALLOC: " #__call__ ); \
247 __ret__ = (void *)( __call__ ); \
248 if (__ret__ == NULL) { \
249 int __err__ = errno; \
250 TRACE_DEBUG(NONE, "ERROR: in '" #__call__ "':\t%s", strerror(__err__)); \
251 __fallback__; \
252 } \
253 }
254
255 /* Check that a memory allocator did not return NULL, otherwise return ENOMEM */
256 #define CHECK_MALLOC( __call__ ) \
257 CHECK_MALLOC_DO( __call__, return ENOMEM );
258
259
260 /* The next macros can be used also for expected errors */
261
262 /* Check parameters at function entry, execute fallback on error */
263 #define CHECK_PARAMS_DO( __bool__, __fallback__ ) \
264 TRACE_DEBUG_ALL( "Check PARAMS: " #__bool__ ); \
265 if ( ! (__bool__) ) { \
266 TRACE_DEBUG(INFO, "Invalid parameter received in '" #__bool__ "'"); \
267 __fallback__; \
268 }
269 /* Check parameters at function entry, return EINVAL if the boolean is false (similar to assert) */
270 #define CHECK_PARAMS( __bool__ ) \
271 CHECK_PARAMS_DO( __bool__, return EINVAL );
272
273 /* Check the return value of an internal function, log and propagate */
274 #define CHECK_FCT_DO( __call__, __fallback__ ) { \
275 int __ret__; \
276 TRACE_DEBUG_ALL( "Check FCT: " #__call__ ); \
277 __ret__ = (__call__); \
278 if (__ret__ != 0) { \
279 TRACE_DEBUG(INFO, "Error in '" #__call__ "':\t%s", strerror(__ret__)); \
280 __fallback__; \
281 } \
282 }
283 /* Check the return value of a function call, return any error code */
284 #define CHECK_FCT( __call__ ) { \
285 int __v__; \
286 CHECK_FCT_DO( __v__ = (__call__), return __v__ ); \
287 }
288
289 /****************************** Socket helpers ************************************/
290
291 /* Some aliases to socket addresses structures */
292 #define sSS struct sockaddr_storage
293 #define sSA struct sockaddr
294 #define sSA4 struct sockaddr_in
295 #define sSA6 struct sockaddr_in6
296
297 /* Dump one sockaddr */
298 #define sSA_DUMP( level, text, sa ) { \
299 sSA * __sa = (sSA *)(sa); \
300 char *__str, __addrbuf[INET6_ADDRSTRLEN]; \
301 if (__sa) { \
302 int __rc = getnameinfo(__sa, \
303 sizeof(sSS), \
304 __addrbuf, \
305 sizeof(__addrbuf), \
306 NULL, \
307 0, \
308 0); \
309 if (__rc) \
310 __str = (char *)gai_strerror(__rc); \
311 else \
312 __str = &__addrbuf[0]; \
313 } else { \
314 __str = "(NULL / ANY)"; \
315 } \
316 TRACE_DEBUG(level, text "%s", __str); \
317 }
318
319 /* The sockaddr length of a sSS structure */
320 #define sSSlen( _ss_ ) \
321 ( (socklen_t) ( ((_ss_)->ss_family == AF_INET) ? (sizeof(sSA4)) : \
322 (((_ss_)->ss_family == AF_INET6) ? (sizeof(sSA6)) : \
323 0 ) ) )
324
325 /* Define the value of IP loopback address */
326 #ifndef INADDR_LOOPBACK
327 #define INADDR_LOOPBACK inet_addr("127.0.0.1")
328 #endif /* INADDR_LOOPBACK */
329
330 /* create a V4MAPPED address */
331 #define IN6_ADDR_V4MAP( a6, a4 ) { \
332 ((uint32_t *)(a6))[0] = 0; \
333 ((uint32_t *)(a6))[1] = 0; \
334 ((uint32_t *)(a6))[2] = htonl(0xffff); \
335 ((uint32_t *)(a6))[3] = (uint32_t)(a4); \
336 }
337
338 /* Retrieve a v4 value from V4MAPPED address ( takes a s6_addr as param) */
339 #define IN6_ADDR_V4UNMAP( a6 ) \
340 (((in_addr_t *)(a6))[3])
341
342 /*
343 * Other macros
344 */
345
346 /* We provide macros to convert 64 bit values to and from network byte-order, on systems where it is not already provided. */
347 #ifndef HAVE_NTOHLL /* Defined in config.h, if the ntohll symbol is defined on the system */
348 # if HOST_BIG_ENDIAN
349 /* In big-endian systems, we don't have to change the values, since the order is the same as network */
350 # define ntohll(x) (x)
351 # define htonll(x) (x)
352 # else /* HOST_BIG_ENDIAN */
353 /* For these systems, we must reverse the bytes. Use ntohl and htonl on sub-32 blocs, and inverse these blocs. */
354 # define ntohll(x) (typeof (x))( (((uint64_t)ntohl( (uint32_t)(x))) << 32 ) | ((uint64_t) ntohl( ((uint64_t)(x)) >> 32 )))
355 # define htonll(x) (typeof (x))( (((uint64_t)htonl( (uint32_t)(x))) << 32 ) | ((uint64_t) htonl( ((uint64_t)(x)) >> 32 )))
356 # endif /* HOST_BIG_ENDIAN */
357 #endif /* HAVE_NTOHLL */
358
359 /* This macro will pad a size to the next multiple of 4. */
360 #define PAD4(_x) ((_x) + ( (4 - (_x)) & 3 ) )
361
362 /* Useful to display as ASCII some bytes values */
363 #define ASCII(_c) ( ((_c < 32) || (_c > 127)) ? ( _c ? '?' : ' ' ) : _c )
364
365 /* Compare timespec structures */
366 #define TS_IS_INFERIOR( ts1, ts2 ) \
367 ( ((ts1)->tv_sec < (ts2)->tv_sec ) \
368 || ((ts1)->tv_nsec < (ts2)->tv_nsec) )
369
370 /* Some constants for dumping flags and values */
371 #define DUMP_AVPFL_str "%c%c"
372 #define DUMP_AVPFL_val(_val) (_val & AVP_FLAG_VENDOR)?'V':'-' , (_val & AVP_FLAG_MANDATORY)?'M':'-'
373 #define DUMP_CMDFL_str "%c%c%c%c"
374 #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':'-'
375
376 /*============================================================*/
377 /* THREADS */
378 /*============================================================*/
379
380 /* Terminate a thread */
381 static __inline__ int fd_thr_term(pthread_t * th)
382 {
383 int ret = 0;
384 void * th_ret = NULL;
385
386 CHECK_PARAMS(th);
387
388 /* Test if it was already terminated */
389 if (*th == (pthread_t)NULL)
390 return 0;
391
392 /* Cancel the thread if it is still running - ignore error if it was already terminated */
393 (void) pthread_cancel(*th);
394
395 /* Then join the thread */
396 CHECK_POSIX_DO( ret = pthread_join(*th, &th_ret), /* continue */ );
397
398 if (th_ret != NULL) {
399 TRACE_DEBUG(FULL, "The thread returned the following value: %p (ignored)", th_ret);
400 }
401
402 /* Clean the location */
403 *th = (pthread_t)NULL;
404
405 return ret;
406 }
407
408 /* Cleanups for cancellation (all threads should be safely cancelable!) */
409 static __inline__ void fd_cleanup_mutex( void * mutex )
410 {
411 CHECK_POSIX_DO( pthread_mutex_unlock((pthread_mutex_t *)mutex), /* */);
412 }
413
414 static __inline__ void fd_cleanup_rwlock( void * rwlock )
415 {
416 CHECK_POSIX_DO( pthread_rwlock_unlock((pthread_rwlock_t *)rwlock), /* */);
417 }
418
419 static __inline__ void fd_cleanup_buffer( void * buffer )
420 {
421 free(buffer);
422 }
423
424 /*============================================================*/
425 /* LISTS */
426 /*============================================================*/
427
428 /* The following structure represents a chained list element */
429 struct fd_list {
430 struct fd_list *next; /* next element in the list */
431 struct fd_list *prev; /* previous element in the list */
432 struct fd_list *head; /* head of the list */
433 void *o; /* additional avialbe pointer used for start of the parento object or other purpose */
434 };
435
436 #define FD_LIST( _li ) ((struct fd_list *)( _li ))
437
438 /* Initialize a list element */
439 void fd_list_init ( struct fd_list * list, void *obj );
440
441 /* Return boolean, true if the list is empty */
442 #define FD_IS_LIST_EMPTY( _list ) (((FD_LIST(_list))->head == (_list)) && ((FD_LIST(_list))->next == (_list)))
443
444 /* Insert an item in a list at known position */
445 void fd_list_insert_after ( struct fd_list * ref, struct fd_list * item );
446 void fd_list_insert_before ( struct fd_list * ref, struct fd_list * item );
447
448 /* Insert an item in an ordered list -- ordering function provided. If duplicate object found, EEXIST and it is returned in ref_duplicate */
449 int fd_list_insert_ordered( struct fd_list * head, struct fd_list * item, int (*cmp_fct)(void *, void *), void ** ref_duplicate);
450
451 /* Unlink an item from a list */
452 void fd_list_unlink ( struct fd_list * item );
453
454 /* Compute a hash value of a string (session id, diameter id, ...) */
455 uint32_t fd_hash ( char * string, size_t len );
456
457
458
459 /*============================================================*/
460 /* DICTIONARY */
461 /*============================================================*/
462 /* Structure that contains the complete dictionary definitions */
463 struct dictionary;
464
465 /* Structure that contains a dictionary object */
466 struct dict_object;
467
468 /* Types of object in the dictionary. */
469 enum dict_object_type {
470 DICT_VENDOR = 1, /* Vendor */
471 DICT_APPLICATION, /* Diameter Application */
472 DICT_TYPE, /* AVP data type */
473 DICT_ENUMVAL, /* Named constant (value of an enumerated AVP type) */
474 DICT_AVP, /* AVP */
475 DICT_COMMAND, /* Diameter Command */
476 DICT_RULE /* a Rule for AVP in command or grouped AVP */
477 #define DICT_TYPE_MAX DICT_RULE
478 };
479
480 /* Initialize a dictionary */
481 int fd_dict_init(struct dictionary ** dict);
482 /* Destroy a dictionary */
483 int fd_dict_fini(struct dictionary ** dict);
484
485 /*
486 * FUNCTION: fd_dict_new
487 *
488 * PARAMETERS:
489 * dict : Pointer to the dictionnary where the object is created
490 * type : What kind of object must be created
491 * data : pointer to the data for the object.
492 * type parameter is used to determine the type of data (see bellow for detail).
493 * parent : a reference to a parent object, if needed.
494 * ref : upon successful creation, reference to new object is stored here if !null.
495 *
496 * DESCRIPTION:
497 * Create a new object in the dictionary.
498 * See following object sections in this header file for more information on data and parent parameters format.
499 *
500 * RETURN VALUE:
501 * 0 : The object is created in the dictionary.
502 * EINVAL : A parameter is invalid.
503 * EEXIST : This object is already defined in the dictionary (with conflicting data).
504 * If "ref" is not NULL, it points to the existing element on return.
505 * (other standard errors may be returned, too, with their standard meaning. Example:
506 * ENOMEM : Memory allocation for the new object element failed.)
507 */
508 int fd_dict_new ( struct dictionary * dict, enum dict_object_type type, void * data, struct dict_object * parent, struct dict_object **ref );
509
510 /*
511 * FUNCTION: fd_dict_search
512 *
513 * PARAMETERS:
514 * dict : Pointer to the dictionnary where the object is searched
515 * type : type of object that is being searched
516 * criteria : how the object must be searched. See object-related sections bellow for more information.
517 * what : depending on criteria, the data that must be searched.
518 * result : On successful return, pointer to the object is stored here.
519 * retval : this value is returned if the object is not found and result is not NULL.
520 *
521 * DESCRIPTION:
522 * Perform a search in the dictionary.
523 * See the object-specific sections bellow to find how to look for each objects.
524 * If the "result" parameter is NULL, the function is used to check if an object is in the dictionary.
525 * Otherwise, a reference to the object is stored in result if found.
526 * If result is not NULL and the object is not found, retval is returned (should be 0 or ENOENT usually)
527 *
528 * RETURN VALUE:
529 * 0 : The object has been found in the dictionary, or *result is NULL.
530 * EINVAL : A parameter is invalid.
531 * ENOENT : No matching object has been found, and result was NULL.
532 */
533 int fd_dict_search ( struct dictionary * dict, enum dict_object_type type, int criteria, void * what, struct dict_object **result, int retval );
534
535 /* Special case: get the generic error command object */
536 int fd_dict_get_error_cmd(struct dictionary * dict, struct dict_object **obj);
537
538 /*
539 * FUNCTION: fd_dict_getval
540 *
541 * PARAMETERS:
542 * object : Pointer to a dictionary object.
543 * data : pointer to a structure to hold the data for the object.
544 * The type is the same as "data" parameter in fd_dict_new function.
545 *
546 * DESCRIPTION:
547 * Retrieve content of a dictionary object.
548 * See following object sections in this header file for more information on data and parent parameters format.
549 *
550 * RETURN VALUE:
551 * 0 : The content of the object has been retrieved.
552 * EINVAL : A parameter is invalid.
553 */
554 int fd_dict_getval ( struct dict_object * object, void * val);
555 int fd_dict_gettype ( struct dict_object * object, enum dict_object_type * type);
556 int fd_dict_getdict ( struct dict_object * object, struct dictionary ** dict);
557
558 /* Debug functions */
559 void fd_dict_dump_object(struct dict_object * obj);
560 void fd_dict_dump(struct dictionary * dict);
561
562
563 /*
564 ***************************************************************************
565 *
566 * Vendor object
567 *
568 * These types are used to manage vendors in the dictionary
569 *
570 ***************************************************************************
571 */
572
573 /* Type to hold a Vendor ID: "SMI Network Management Private Enterprise Codes" (RFC3232) */
574 typedef uint32_t vendor_id_t;
575
576 /* Type to hold data associated to a vendor */
577 struct dict_vendor_data {
578 vendor_id_t vendor_id; /* ID of a vendor */
579 char *vendor_name; /* The name of this vendor */
580 };
581
582 /* The criteria for searching a vendor object in the dictionary */
583 enum {
584 VENDOR_BY_ID = 10, /* "what" points to a vendor_id_t */
585 VENDOR_BY_NAME, /* "what" points to a string */
586 VENDOR_OF_APPLICATION /* "what" points to a struct dict_object containing an application (see bellow) */
587 };
588
589 /***
590 * API usage :
591
592 Note: the value of "vendor_name" is copied when the object is created, and the string may be disposed afterwards.
593 On the other side, when value is retrieved with dict_getval, the string is not copied and MUST NOT be freed. It will
594 be freed automatically along with the object itself with call to dict_fini later.
595
596 - dict_new:
597 The "parent" parameter is not used for vendors.
598 Sample code to create a vendor:
599 {
600 int ret;
601 struct dict_object * myvendor;
602 struct dict_vendor_data myvendordata = { 23455, "my vendor name" }; -- just an example...
603 ret = dict_new ( DICT_VENDOR, &myvendordata, NULL, &myvendor );
604 }
605
606 - dict_search:
607 Sample codes to look for a vendor object, by its id or name:
608 {
609 int ret;
610 struct dict_object * vendor_found;
611 vendor_id_t vendorid = 23455;
612 ret = dict_search ( DICT_VENDOR, VENDOR_BY_ID, &vendorid, &vendor_found, ENOENT);
613 - or -
614 ret = dict_search ( DICT_VENDOR, VENDOR_BY_NAME, "my vendor name", &vendor_found, ENOENT);
615 }
616
617 - dict_getval:
618 Sample code to retrieve the data from a vendor object:
619 {
620 int ret;
621 struct dict_object * myvendor;
622 struct dict_vendor_data myvendordata;
623 ret = dict_search ( DICT_VENDOR, VENDOR_BY_NAME, "my vendor name", &myvendor, ENOENT);
624 ret = dict_getval ( myvendor, &myvendordata );
625 printf("my vendor id: %d\n", myvendordata.vendor_id );
626 }
627
628
629 */
630
631 /*
632 ***************************************************************************
633 *
634 * Application object
635 *
636 * These types are used to manage Diameter applications in the dictionary
637 *
638 ***************************************************************************
639 */
640
641 /* Type to hold a Diameter application ID: IANA assigned value for this application. */
642 typedef uint32_t application_id_t;
643
644 /* Type to hold data associated to an application */
645 struct dict_application_data {
646 application_id_t application_id; /* ID of the application */
647 char *application_name; /* The name of this application */
648 };
649
650 /* The criteria for searching an application object in the dictionary */
651 enum {
652 APPLICATION_BY_ID = 20, /* "what" points to a application_id_t */
653 APPLICATION_BY_NAME, /* "what" points to a string */
654 APPLICATION_OF_TYPE, /* "what" points to a struct dict_object containing a type object (see bellow) */
655 APPLICATION_OF_COMMAND /* "what" points to a struct dict_object containing a command (see bellow) */
656 };
657
658 /***
659 * API usage :
660
661 The "parent" parameter of dict_new may point to a vendor object to inform of what vendor defines the application.
662 for standard-track applications, the "parent" parameter should be NULL.
663 The vendor associated to an application is retrieved with VENDOR_OF_APPLICATION search criteria on vendors.
664
665 - dict_new:
666 Sample code for application creation:
667 {
668 int ret;
669 struct dict_object * vendor;
670 struct dict_object * appl;
671 struct dict_vendor_data vendor_data = {
672 23455,
673 "my vendor name"
674 };
675 struct dict_application_data app_data = {
676 9789,
677 "my vendor's application"
678 };
679
680 ret = dict_new ( DICT_VENDOR, &vendor_data, NULL, &vendor );
681 ret = dict_new ( DICT_APPLICATION, &app_data, vendor, &appl );
682 }
683
684 - dict_search:
685 Sample code to retrieve the vendor of an application
686 {
687 int ret;
688 struct dict_object * vendor, * appli;
689
690 ret = dict_search ( DICT_APPLICATION, APPLICATION_BY_NAME, "my vendor's application", &appli, ENOENT);
691 ret = dict_search ( DICT_VENDOR, VENDOR_OF_APPLICATION, appli, &vendor, ENOENT);
692 }
693
694 - dict_getval:
695 Sample code to retrieve the data from an application object:
696 {
697 int ret;
698 struct dict_object * appli;
699 struct dict_application_data appl_data;
700 ret = dict_search ( DICT_APPLICATION, APPLICATION_BY_NAME, "my vendor's application", &appli, ENOENT);
701 ret = dict_getval ( appli, &appl_data );
702 printf("my application id: %s\n", appl_data.application_id );
703 }
704
705 */
706
707 /*
708 ***************************************************************************
709 *
710 * Type object
711 *
712 * These types are used to manage AVP data types in the dictionary
713 *
714 ***************************************************************************
715 */
716
717 /* Type to store any AVP value */
718 union avp_value {
719 struct {
720 uint8_t *data; /* bytes buffer */
721 size_t len; /* length of the data buffer */
722 } os; /* Storage for an octet string, data is alloc'd and must be freed */
723 int32_t i32; /* integer 32 */
724 int64_t i64; /* integer 64 */
725 uint32_t u32; /* unsigned 32 */
726 uint64_t u64; /* unsigned 64 */
727 float f32; /* float 32 */
728 double f64; /* float 64 */
729 };
730
731 /* These are the basic AVP types defined in RFC3588bis */
732 enum dict_avp_basetype {
733 AVP_TYPE_GROUPED,
734 AVP_TYPE_OCTETSTRING,
735 AVP_TYPE_INTEGER32,
736 AVP_TYPE_INTEGER64,
737 AVP_TYPE_UNSIGNED32,
738 AVP_TYPE_UNSIGNED64,
739 AVP_TYPE_FLOAT32,
740 AVP_TYPE_FLOAT64
741 #define AVP_TYPE_MAX AVP_TYPE_FLOAT64
742 };
743
744 /* Callbacks that can be associated with a derived type to easily interpret the AVP value. */
745 /*
746 * CALLBACK: dict_avpdata_interpret
747 *
748 * PARAMETERS:
749 * val : Pointer to the AVP value that must be interpreted.
750 * interpreted : The result of interpretation is stored here. The format and meaning depends on each type.
751 *
752 * DESCRIPTION:
753 * This callback can be provided with a derived type in order to facilitate the interpretation of formated data.
754 * For example, when an AVP of type "Address" is received, it can be used to convert the octetstring into a struct sockaddr.
755 * This callback is not called directly, but through the message's API msg_avp_value_interpret function.
756 *
757 * RETURN VALUE:
758 * 0 : Operation complete.
759 * !0 : An error occurred, the error code is returned.
760 */
761 typedef int (*dict_avpdata_interpret) (union avp_value * value, void * interpreted);
762 /*
763 * CALLBACK: dict_avpdata_encode
764 *
765 * PARAMETERS:
766 * data : The formated data that must be stored in the AVP value.
767 * val : Pointer to the AVP value storage area where the data must be stored.
768 *
769 * DESCRIPTION:
770 * This callback can be provided with a derived type in order to facilitate the encoding of formated data.
771 * For example, it can be used to convert a struct sockaddr in an AVP value of type Address.
772 * This callback is not called directly, but through the message's API msg_avp_value_encode function.
773 * If the callback is defined for an OctetString based type, the created string must be malloc'd. free will be called
774 * automatically later.
775 *
776 * RETURN VALUE:
777 * 0 : Operation complete.
778 * !0 : An error occurred, the error code is returned.
779 */
780 typedef int (*dict_avpdata_encode) (void * data, union avp_value * val);
781
782
783 /* Type to hold data associated to a derived AVP data type */
784 struct dict_type_data {
785 enum dict_avp_basetype type_base; /* How the data of such AVP must be interpreted */
786 char *type_name; /* The name of this type */
787 dict_avpdata_interpret type_interpret;/* cb to convert the AVP value in more comprehensive format (or NULL) */
788 dict_avpdata_encode type_encode; /* cb to convert formatted data into an AVP value (or NULL) */
789 };
790
791 /* The criteria for searching a type object in the dictionary */
792 enum {
793 TYPE_BY_NAME = 30, /* "what" points to a string */
794 TYPE_OF_ENUMVAL, /* "what" points to a struct dict_object containing an enumerated constant (DICT_ENUMVAL, see bellow). */
795 TYPE_OF_AVP /* "what" points to a struct dict_object containing an AVP object. */
796 };
797
798
799 /***
800 * API usage :
801
802 - dict_new:
803 The "parent" parameter may point to an application object, when a type is defined by a Diameter application.
804
805 Sample code:
806 {
807 int ret;
808 struct dict_object * mytype;
809 struct dict_type_data mytypedata =
810 {
811 AVP_TYPE_OCTETSTRING,
812 "Address",
813 NULL,
814 NULL
815 };
816 ret = dict_new ( DICT_TYPE, &mytypedata, NULL, &mytype );
817 }
818
819 - dict_search:
820 Sample code:
821 {
822 int ret;
823 struct dict_object * address_type;
824 ret = dict_search ( DICT_TYPE, TYPE_BY_NAME, "Address", &address_type, ENOENT);
825 }
826
827 */
828
829 /*
830 ***************************************************************************
831 *
832 * Enumerated values object
833 *
834 * These types are used to manage named constants of some AVP,
835 * for enumerated types. Waaad allows contants for types others than Unsigned32
836 *
837 ***************************************************************************
838 */
839
840 /* Type to hold data of named constants for AVP */
841 struct dict_enumval_data {
842 char *enum_name; /* The name of this constant */
843 union avp_value enum_value; /* Value of the constant. Union term depends on parent type's base type. */
844 };
845
846 /* The criteria for searching a constant in the dictionary */
847 enum {
848 ENUMVAL_BY_STRUCT = 40, /* "what" points to a struct dict_enumval_request as defined bellow */
849 };
850
851 struct dict_enumval_request {
852 /* Identifier of the parent type, one of the following must not be NULL */
853 struct dict_object *type_obj;
854 char *type_name;
855
856 /* Search criteria for the constant */
857 struct dict_enumval_data search; /* search.enum_value is used only if search.enum_name == NULL */
858 };
859
860 /***
861 * API usage :
862
863 - dict_new:
864 The "parent" parameter must point to a derived type object.
865 Sample code to create a type "Boolean" with two constants "True" and "False":
866 {
867 int ret;
868 struct dict_object * type_boolean;
869 struct dict_type_data type_boolean_data =
870 {
871 AVP_TYPE_INTEGER32,
872 "Boolean",
873 NULL,
874 NULL
875 };
876 struct dict_enumval_data boolean_false =
877 {
878 .enum_name="False",
879 .enum_value.i32 = 0
880 };
881 struct dict_enumval_data boolean_true =
882 {
883 .enum_name="True",
884 .enum_value.i32 = -1
885 };
886 ret = dict_new ( DICT_TYPE, &type_boolean_data, NULL, &type_boolean );
887 ret = dict_new ( DICT_ENUMVAL, &boolean_false, type_boolean, NULL );
888 ret = dict_new ( DICT_ENUMVAL, &boolean_true , type_boolean, NULL );
889
890 }
891
892 - dict_search:
893 Sample code to look for a constant name, by its value:
894 {
895 int ret;
896 struct dict_object * value_found;
897 struct dict_enumval_request boolean_by_value =
898 {
899 .type_name = "Boolean",
900 .search.enum_name=NULL,
901 .search.enum_value.i32 = -1
902 };
903
904 ret = dict_search ( DICT_ENUMVAL, ENUMVAL_BY_STRUCT, &boolean_by_value, &value_found, ENOENT);
905 }
906
907 - dict_getval:
908 Sample code to retrieve the data from a constant object:
909 {
910 int ret;
911 struct dict_object * value_found;
912 struct dict_enumval_data boolean_data = NULL;
913 struct dict_enumval_request boolean_by_value =
914 {
915 .type_name = "Boolean",
916 .search.enum_name=NULL,
917 .search.enum_value.i32 = 0
918 };
919
920 ret = dict_search ( DICT_ENUMVAL, ENUMVAL_BY_STRUCT, &boolean_by_value, &value_found, ENOENT);
921 ret = dict_getval ( value_found, &boolean_data );
922 printf(" Boolean with value 0: %s", boolean_data.enum_name );
923 }
924 */
925
926 /*
927 ***************************************************************************
928 *
929 * AVP object
930 *
931 * These objects are used to manage AVP definitions in the dictionary
932 *
933 ***************************************************************************
934 */
935
936 /* Type to hold an AVP code. For vendor 0, these codes are assigned by IANA. Otherwise, it is managed by the vendor */
937 typedef uint32_t avp_code_t;
938
939 /* Values of AVP flags */
940 #define AVP_FLAG_VENDOR 0x80
941 #define AVP_FLAG_MANDATORY 0x40
942 #define AVP_FLAG_RESERVED3 0x20
943 #define AVP_FLAG_RESERVED4 0x10
944 #define AVP_FLAG_RESERVED5 0x08
945 #define AVP_FLAG_RESERVED6 0x04
946 #define AVP_FLAG_RESERVED7 0x02
947 #define AVP_FLAG_RESERVED8 0x01
948
949
950 /* Type to hold data associated to an avp */
951 struct dict_avp_data {
952 avp_code_t avp_code; /* Code of the avp */
953 vendor_id_t avp_vendor; /* Vendor of the AVP, or 0 */
954 char *avp_name; /* Name of this AVP */
955 uint8_t avp_flag_mask; /* Mask of fixed AVP flags */
956 uint8_t avp_flag_val; /* Values of the fixed flags */
957 enum dict_avp_basetype avp_basetype; /* Basic type of data found in the AVP */
958 };
959
960 /* The criteria for searching an avp object in the dictionary */
961 enum {
962 AVP_BY_CODE = 50, /* "what" points to an avp_code_t, vendor is always 0 */
963 AVP_BY_NAME, /* "what" points to a string, vendor is always 0 */
964 AVP_BY_CODE_AND_VENDOR, /* "what" points to a struct dict_avp_request (see bellow), where avp_vendor and avp_code are set */
965 AVP_BY_NAME_AND_VENDOR /* "what" points to a struct dict_avp_request (see bellow), where avp_vendor and avp_name are set */
966 };
967
968 /* Struct used for some researchs */
969 struct dict_avp_request {
970 vendor_id_t avp_vendor;
971 avp_code_t avp_code;
972 char *avp_name;
973 };
974
975
976 /***
977 * API usage :
978
979 If "parent" parameter is not NULL during AVP creation, it must point to a DICT_TYPE object.
980 The extended type is then attached to the AVP. In case where it is an enumerated type, the value of
981 AVP is automatically interpreted in debug messages, and in message checks.
982 The derived type of an AVP can be retrieved with: dict_search ( DICT_TYPE, TYPE_OF_AVP, avp, ... )
983
984 To create the rules (ABNF) for children of Grouped AVP, see the DICT_RULE related part.
985
986 - dict_new:
987 Sample code for AVP creation:
988 {
989 int ret;
990 struct dict_object * user_name_avp;
991 struct dict_object * boolean_type;
992 struct dict_object * sample_boolean_avp;
993 struct dict_avp_data user_name_data = {
994 1, // code
995 0, // vendor
996 "User-Name", // name
997 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
998 AVP_FLAG_MANDATORY, // the V flag must be cleared, the M flag must be set.
999 AVP_TYPE_OCTETSTRING // User-Name AVP contains OctetString data (further precision such as UTF8String can be given with a parent derived type)
1000 };
1001 struct dict_avp_data sample_boolean_data = {
1002 31337,
1003 23455,
1004 "Sample-Boolean",
1005 AVP_FLAG_VENDOR | AVP_FLAG_MANDATORY,
1006 AVP_FLAG_VENDOR,
1007 AVP_TYPE_INTEGER32 // This MUST be the same as parent type's
1008 };
1009
1010 -- Create an AVP with a base type --
1011 ret = dict_new ( DICT_AVP, &user_name_data, NULL, &user_name_avp );
1012
1013 -- Create an AVP with a derived type --
1014 ret = dict_search ( DICT_TYPE, TYPE_BY_NAME, "Boolean", &boolean_type, ENOENT);
1015 ret = dict_new ( DICT_AVP, &sample_boolean_data , boolean_type, &sample_boolean_avp );
1016
1017 }
1018
1019 - dict_search:
1020 Sample code to look for an AVP
1021 {
1022 int ret;
1023 struct dict_object * avp_username;
1024 struct dict_object * avp_sampleboolean;
1025 struct dict_avp_request avpvendorboolean =
1026 {
1027 .avp_vendor = 23455,
1028 .avp_name = "Sample-Boolean"
1029 };
1030
1031 ret = dict_search ( DICT_AVP, AVP_BY_NAME, "User-Name", &avp_username, ENOENT);
1032
1033 ret = dict_search ( DICT_AVP, AVP_BY_NAME_AND_VENDOR, &avpvendorboolean, &avp_sampleboolean, ENOENT);
1034
1035 }
1036
1037 - dict_getval:
1038 Sample code to retrieve the data from an AVP object:
1039 {
1040 int ret;
1041 struct dict_object * avp_username;
1042 struct dict_avp_data user_name_data;
1043 ret = dict_search ( DICT_AVP, AVP_BY_NAME, "User-Name", &avp_username, ENOENT);
1044 ret = dict_getval ( avp_username, &user_name_data );
1045 printf("User-Name code: %d\n", user_name_data.avp_code );
1046 }
1047
1048 */
1049
1050 /*
1051 ***************************************************************************
1052 *
1053 * Command object
1054 *
1055 * These types are used to manage commands objects in the dictionary
1056 *
1057 ***************************************************************************
1058 */
1059
1060 /* Type to hold a Diameter command code: IANA assigned values. 0x0-0x7fffff=standard, 0x800000-0xfffffd=vendors, 0xfffffe-0xffffff=experimental */
1061 typedef uint32_t command_code_t;
1062
1063 /* Values of command flags */
1064 #define CMD_FLAG_REQUEST 0x80
1065 #define CMD_FLAG_PROXIABLE 0x40
1066 #define CMD_FLAG_ERROR 0x20
1067 #define CMD_FLAG_RETRANSMIT 0x10
1068 #define CMD_FLAG_RESERVED5 0x08
1069 #define CMD_FLAG_RESERVED6 0x04
1070 #define CMD_FLAG_RESERVED7 0x02
1071 #define CMD_FLAG_RESERVED8 0x01
1072
1073 /* Type to hold data associated to a command */
1074 struct dict_cmd_data {
1075 command_code_t cmd_code; /* code of the command */
1076 char *cmd_name; /* Name of the command */
1077 uint8_t cmd_flag_mask; /* Mask of fixed-value flags */
1078 uint8_t cmd_flag_val; /* values of the fixed flags */
1079 };
1080
1081 /* The criteria for searching an avp object in the dictionary */
1082 enum {
1083 CMD_BY_NAME = 60, /* "what" points to a string */
1084 CMD_BY_CODE_R, /* "what" points to a command_code_t. The "Request" command is returned. */
1085 CMD_BY_CODE_A, /* "what" points to a command_code_t. The "Answer" command is returned. */
1086 CMD_ANSWER /* "what" points to a struct dict_object of a request command. The corresponding "Answer" command is returned. */
1087 };
1088
1089
1090 /***
1091 * API usage :
1092
1093 The "parent" parameter of dict_new may point to an application object to inform of what application defines the command.
1094 The application associated to a command is retrieved with APPLICATION_OF_COMMAND search criteria on applications.
1095
1096 To create the rules for children of commands, see the DICT_RULE related part.
1097
1098 Note that the "Request" and "Answer" commands are two independant objects. This allows to have different rules for each.
1099
1100 - dict_new:
1101 Sample code for command creation:
1102 {
1103 int ret;
1104 struct dict_object * cer;
1105 struct dict_object * cea;
1106 struct dict_cmd_data ce_data = {
1107 257, // code
1108 "Capabilities-Exchange-Request", // name
1109 CMD_FLAG_REQUEST, // mask
1110 CMD_FLAG_REQUEST // value. Only the "R" flag is constrained here, set.
1111 };
1112
1113 ret = dict_new ( DICT_COMMAND, &ce_data, NULL, &cer );
1114
1115 ce_data.cmd_name = "Capabilities-Exchange-Answer";
1116 ce_data.cmd_flag_val = 0; // Same constraint on "R" flag, but this time it must be cleared.
1117
1118 ret = dict_new ( DICT_COMMAND, &ce_data, NULL, &cea );
1119 }
1120
1121 - dict_search:
1122 Sample code to look for a command
1123 {
1124 int ret;
1125 struct dict_object * cer, * cea;
1126 command_code_t code = 257;
1127 ret = dict_search ( DICT_COMMAND, CMD_BY_NAME, "Capabilities-Exchange-Request", &cer, ENOENT);
1128 ret = dict_search ( DICT_COMMAND, CMD_BY_CODE_R, &code, &cer, ENOENT);
1129 }
1130
1131 - dict_getval:
1132 Sample code to retrieve the data from a command object:
1133 {
1134 int ret;
1135 struct dict_object * cer;
1136 struct dict_object * cea;
1137 struct dict_cmd_data cea_data;
1138 ret = dict_search ( DICT_COMMAND, CMD_BY_NAME, "Capabilities-Exchange-Request", &cer, ENOENT);
1139 ret = dict_search ( DICT_COMMAND, CMD_ANSWER, cer, &cea, ENOENT);
1140 ret = dict_getval ( cea, &cea_data );
1141 printf("Answer to CER: %s\n", cea_data.cmd_name );
1142 }
1143
1144 */
1145
1146 /*
1147 ***************************************************************************
1148 *
1149 * Rule object
1150 *
1151 * These objects are used to manage rules in the dictionary (ABNF implementation)
1152 * This is used for checking messages validity (more powerful than a DTD)
1153 *
1154 ***************************************************************************
1155 */
1156
1157 /* This defines the kind of rule that is defined */
1158 enum rule_position {
1159 RULE_FIXED_HEAD = 1, /* The AVP must be at the head of the group. The rule_order field is used to specify the position. */
1160 RULE_REQUIRED, /* The AVP must be present in the parent, but its position is not defined. */
1161 RULE_OPTIONAL, /* The AVP may be present in the message. Used to specify a max number of occurences for example */
1162 RULE_FIXED_TAIL /* The AVP must be at the end of the group. The rule_order field is used to specify the position. */
1163 };
1164
1165 /* Content of a RULE object data */
1166 struct dict_rule_data {
1167 struct dict_object *rule_avp; /* Pointer to the AVP object that is concerned by this rule */
1168 enum rule_position rule_position; /* The position in which the rule_avp must appear in the parent */
1169 unsigned rule_order; /* for RULE_FIXED_* rules, the place. 1,2,3.. for HEAD rules; ...,3,2,1 for TAIL rules. */
1170 int rule_min; /* Minimum number of occurences. -1 means "default": 0 for optional rules, 1 for other rules */
1171 int rule_max; /* Maximum number of occurences. -1 means no maximum. 0 means the AVP is forbidden. */
1172 };
1173
1174 /* The criteria for searching a rule in the dictionary */
1175 enum {
1176 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?" */
1177 };
1178
1179 /* Structure for querying the dictionary about a rule */
1180 struct dict_rule_request {
1181 struct dict_object *rule_parent; /* The grouped avp or command to which the rule apply */
1182 struct dict_object *rule_avp; /* The AVP concerned by this rule */
1183 };
1184
1185
1186 /***
1187 * API usage :
1188
1189 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).
1190
1191 - dict_new:
1192 Sample code for rule creation. Let's create the Proxy-Info grouped AVP for example.
1193 {
1194 int ret;
1195 struct dict_object * proxy_info_avp;
1196 struct dict_object * proxy_host_avp;
1197 struct dict_object * proxy_state_avp;
1198 struct dict_object * diameteridentity_type;
1199 struct dict_rule_data rule_data;
1200 struct dict_type_data di_type_data = { AVP_TYPE_OCTETSTRING, "DiameterIdentity", NULL, NULL };
1201 struct dict_avp_data proxy_info_data = { 284, 0, "Proxy-Info", AVP_FLAG_VENDOR | AVP_FLAG_MANDATORY, AVP_FLAG_MANDATORY, AVP_TYPE_GROUPED };
1202 struct dict_avp_data proxy_host_data = { 280, 0, "Proxy-Host", AVP_FLAG_VENDOR | AVP_FLAG_MANDATORY, AVP_FLAG_MANDATORY, AVP_TYPE_OCTETSTRING };
1203 struct dict_avp_data proxy_state_data = { 33, 0, "Proxy-State",AVP_FLAG_VENDOR | AVP_FLAG_MANDATORY, AVP_FLAG_MANDATORY, AVP_TYPE_OCTETSTRING };
1204
1205 -- Create the parent AVP
1206 ret = dict_new ( DICT_AVP, &proxy_info_data, NULL, &proxy_info_avp );
1207
1208 -- Create the first child AVP.
1209 ret = dict_new ( DICT_TYPE, &di_type_data, NULL, &diameteridentity_type );
1210 ret = dict_new ( DICT_AVP, &proxy_host_data, diameteridentity_type, &proxy_host_avp );
1211
1212 -- Create the other child AVP
1213 ret = dict_new ( DICT_AVP, &proxy_state_data, NULL, &proxy_state_avp );
1214
1215 -- Now we can create the rules. Both children AVP are mandatory.
1216 rule_data.rule_position = RULE_REQUIRED;
1217 rule_data.rule_min = -1;
1218 rule_data.rule_max = -1;
1219
1220 rule_data.rule_avp = proxy_host_avp;
1221 ret = dict_new ( DICT_RULE, &rule_data, proxy_info_avp, NULL );
1222
1223 rule_data.rule_avp = proxy_state_avp;
1224 ret = dict_new ( DICT_RULE, &rule_data, proxy_info_avp, NULL );
1225 }
1226
1227 - dict_search and dict_getval are similar to previous examples.
1228
1229 */
1230
1231 /* Define some hard-coded values */
1232 /* Commands Codes */
1233 #define CC_CAPABILITIES_EXCHANGE 257
1234 #define CC_RE_AUTH 258
1235 #define CC_ACCOUNTING 271
1236 #define CC_ABORT_SESSION 274
1237 #define CC_SESSION_TERMINATION 275
1238 #define CC_DEVICE_WATCHDOG 280
1239 #define CC_DISCONNECT_PEER 282
1240
1241 /* AVPs (Vendor 0) */
1242 #define AC_PROXY_STATE 33
1243 #define AC_HOST_IP_ADDRESS 257
1244 #define AC_AUTH_APPLICATION_ID 258
1245 #define AC_ACCT_APPLICATION_ID 259
1246 #define AC_VENDOR_SPECIFIC_APPLICATION_ID 260
1247 #define AC_REDIRECT_HOST_USAGE 261
1248 #define AC_REDIRECT_MAX_CACHE_TIME 262
1249 #define AC_SESSION_ID 263
1250 #define AC_ORIGIN_HOST 264
1251 #define AC_SUPPORTED_VENDOR_ID 265
1252 #define AC_VENDOR_ID 266
1253 #define AC_FIRMWARE_REVISION 267
1254 #define AC_RESULT_CODE 268
1255 #define AC_PRODUCT_NAME 269
1256 #define AC_DISCONNECT_CAUSE 273
1257 #define ACV_DC_REBOOTING 0
1258 #define ACV_DC_BUSY 1
1259 #define ACV_DC_NOT_FRIEND 2
1260 #define AC_ORIGIN_STATE_ID 278
1261 #define AC_FAILED_AVP 279
1262 #define AC_PROXY_HOST 280
1263 #define AC_ERROR_MESSAGE 281
1264 #define AC_ROUTE_RECORD 282
1265 #define AC_DESTINATION_REALM 283
1266 #define AC_PROXY_INFO 284
1267 #define AC_REDIRECT_HOST 292
1268 #define AC_DESTINATION_HOST 293
1269 #define AC_ERROR_REPORTING_HOST 294
1270 #define AC_ORIGIN_REALM 296
1271 #define AC_INBAND_SECURITY_ID 299
1272
1273 /* Error codes */
1274 #define ER_DIAMETER_SUCCESS 2001
1275 #define ER_DIAMETER_REALM_NOT_SERVED 3003
1276 #define ER_DIAMETER_TOO_BUSY 3004
1277 #define ER_DIAMETER_REDIRECT_INDICATION 3006
1278
1279 /* Iterator on the rules of a parent object */
1280 int fd_dict_iterate_rules ( struct dict_object *parent, void * data, int (*cb)(void *, struct dict_rule_data *) );
1281
1282
1283 /*============================================================*/
1284 /* MESSAGES */
1285 /*============================================================*/
1286
1287 /* The following types are opaque */
1288 struct msg; /* A message: command with children AVPs (possibly grand children) */
1289 struct avp; /* AVP object */
1290
1291 /* Some details about chaining:
1292 *
1293 * A message is made of a header ( msg ) and 0 or more AVPs ( avp ).
1294 * The structure is a kind of tree, where some AVPs (grouped AVPs) can contain other AVPs.
1295 * Exemple:
1296 * msg
1297 * |-avp
1298 * |-gavp
1299 * | |-avp
1300 * | |-avp
1301 * | \-avp
1302 * |-avp
1303 * \-avp
1304 *
1305 */
1306
1307 /* The following type is used to point to either a msg or an AVP */
1308 typedef void msg_or_avp;
1309
1310 /* The Diameter protocol version */
1311 #define DIAMETER_VERSION 1
1312
1313 /* In the two following types, some fields are marked (READONLY).
1314 * This means that the content of these fields will be overwritten by the daemon so modifying it is useless.
1315 */
1316
1317 /* The following structure represents the header of a message. All data is in host byte order. */
1318 struct msg_hdr {
1319 uint8_t msg_version; /* (READONLY) Version of Diameter: must be DIAMETER_VERSION. */
1320 uint32_t msg_length; /* (READONLY)(3 bytes) indicates the length of the message */
1321 uint8_t msg_flags; /* Message flags: CMD_FLAG_* */
1322 command_code_t msg_code; /* (3 bytes) the command-code. See dictionary-api.h for more detail */
1323 application_id_t msg_appl; /* The application issuing this message */
1324 uint32_t msg_hbhid; /* The Hop-by-Hop identifier of the message */
1325 uint32_t msg_eteid; /* The End-to-End identifier of the message */
1326 };
1327
1328 /* The following structure represents the visible content of an AVP. All data is in host byte order. */
1329 struct avp_hdr {
1330 avp_code_t avp_code; /* the AVP Code */
1331 uint8_t avp_flags; /* AVP_FLAG_* flags */
1332 uint32_t avp_len; /* (READONLY)(Only 3 bytes are used) the length of the AVP as described in the RFC */
1333 vendor_id_t avp_vendor; /* Only used if AVP_FLAG_VENDOR is present */
1334 union avp_value *avp_value; /* pointer to the value of the AVP. NULL means that the value is not set / not understood.
1335 One should not directly change this value. Use the msg_avp_setvalue function instead.
1336 The content of the pointed structure can be changed directly, with this restriction:
1337 if the AVP is an OctetString, and you change the value of the pointer avp_value->os.data, then
1338 you must call free() on the previous value, and the new one must be free()-able.
1339 */
1340 };
1341
1342 /* The following enum is used to browse inside message hierarchy (msg, gavp, avp) */
1343 enum msg_brw_dir {
1344 MSG_BRW_NEXT = 1, /* Get the next element at the same level, or NULL if this is the last element. */
1345 MSG_BRW_PREV, /* Get the previous element at the same level, or NULL if this is the first element. */
1346 MSG_BRW_FIRST_CHILD, /* Get the first child AVP of this element, if any. */
1347 MSG_BRW_LAST_CHILD, /* Get the last child AVP of this element, if any. */
1348 MSG_BRW_PARENT, /* Get the parent element of this element, if any. Only the msg_t object has no parent. */
1349 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. */
1350 };
1351
1352 /* Some flags used in the functions bellow */
1353 #define MSGFL_ALLOC_ETEID 0x01 /* When creating a message, a new end-to-end ID is allocated and set in the message */
1354 #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 */
1355 #define MSGFL_MAX MSGFL_ANSW_ERROR /* The biggest valid flag value */
1356
1357 /**************************************************/
1358 /* Message creation, manipulation, disposal */
1359 /**************************************************/
1360 /*
1361 * FUNCTION: fd_msg_avp_new
1362 *
1363 * PARAMETERS:
1364 * model : Pointer to a DICT_AVP dictionary object describing the avp to create, or NULL.
1365 * flags : Flags to use in creation (not used yet, should be 0).
1366 * avp : Upon success, pointer to the new avp is stored here.
1367 *
1368 * DESCRIPTION:
1369 * Create a new AVP instance.
1370 *
1371 * RETURN VALUE:
1372 * 0 : The AVP is created.
1373 * EINVAL : A parameter is invalid.
1374 * (other standard errors may be returned, too, with their standard meaning. Example:
1375 * ENOMEM : Memory allocation for the new avp failed.)
1376 */
1377 int fd_msg_avp_new ( struct dict_object * model, int flags, struct avp ** avp );
1378
1379 /*
1380 * FUNCTION: fd_msg_new
1381 *
1382 * PARAMETERS:
1383 * model : Pointer to a DICT_COMMAND dictionary object describing the message to create, or NULL.
1384 * flags : combination of MSGFL_* flags.
1385 * msg : Upon success, pointer to the new message is stored here.
1386 *
1387 * DESCRIPTION:
1388 * Create a new empty Diameter message.
1389 *
1390 * RETURN VALUE:
1391 * 0 : The message is created.
1392 * EINVAL : A parameter is invalid.
1393 * (other standard errors may be returned, too, with their standard meaning. Example:
1394 * ENOMEM : Memory allocation for the new message failed.)
1395 */
1396 int fd_msg_new ( struct dict_object * model, int flags, struct msg ** msg );
1397
1398 /*
1399 * FUNCTION: msg_new_answer_from_req
1400 *
1401 * PARAMETERS:
1402 * dict : Pointer to the dictionary containing the model of the query.
1403 * msg : The location of the query on function call. Updated by the location of answer message on return.
1404 * flag : Pass MSGFL_ANSW_ERROR to indicate if the answer is an error message (will set the 'E' bit)
1405 *
1406 * DESCRIPTION:
1407 * This function creates the empty answer message corresponding to a request.
1408 * The header is set properly (R flag, ccode, appid, hbhid, eteid)
1409 * The Session-Id AVP is copied if present.
1410 * The calling code should usually call fd_msg_rescode_set function on the answer.
1411 * Upon return, the original query may be retrieved by calling fd_msg_answ_getq on the message.
1412 *
1413 * RETURN VALUE:
1414 * 0 : Operation complete.
1415 * !0 : an error occurred.
1416 */
1417 int fd_msg_new_answer_from_req ( struct dictionary * dict, struct msg ** msg, int flag );
1418
1419 /*
1420 * FUNCTION: fd_msg_browse
1421 *
1422 * PARAMETERS:
1423 * reference : Pointer to a struct msg or struct avp.
1424 * dir : Direction for browsing
1425 * found : If not NULL, updated with the element that has been found, if any, or NULL if no element was found / an error occurred.
1426 * 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.
1427 *
1428 * DESCRIPTION:
1429 * Explore the content of a message object (hierarchy). If "found" is null, only error checking is performed.
1430 * If "depth" is provided, it is updated as follow on successful function return:
1431 * - not modified for MSG_BRW_NEXT and MSG_BRW_PREV.
1432 * - *depth = *depth + 1 for MSG_BRW_FIRST_CHILD and MSG_BRW_LAST_CHILD.
1433 * - *depth = *depth - 1 for MSG_BRW_PARENT.
1434 * - *depth = *depth + X for MSG_BRW_WALK, with X between 1 (returned the 1st child) and -N (returned the Nth parent's next).
1435 *
1436 * RETURN VALUE:
1437 * 0 : found has been updated (if non NULL).
1438 * EINVAL : A parameter is invalid.
1439 * ENOENT : No element has been found where requested, and "found" was NULL (otherwise, *found is set to NULL and 0 is returned).
1440 */
1441 int fd_msg_browse_internal ( msg_or_avp * reference, enum msg_brw_dir dir, msg_or_avp ** found, int * depth );
1442 /* Macro to avoid having to cast the third parameter everywhere */
1443 #define fd_msg_browse( ref, dir, found, depth ) \
1444 fd_msg_browse_internal( (ref), (dir), (void *)(found), (depth) )
1445
1446
1447 /*
1448 * FUNCTION: fd_msg_avp_add
1449 *
1450 * PARAMETERS:
1451 * reference : Pointer to a valid msg or avp.
1452 * dir : location where the new AVP should be inserted, relative to the reference. MSG_BRW_PARENT and MSG_BRW_WALK are not valid.
1453 * avp : pointer to the AVP object that must be inserted.
1454 *
1455 * DESCRIPTION:
1456 * Adds an AVP into an object that can contain it: grouped AVP or message.
1457 *
1458 * RETURN VALUE:
1459 * 0 : The AVP has been added.
1460 * EINVAL : A parameter is invalid.
1461 */
1462 int fd_msg_avp_add ( msg_or_avp * reference, enum msg_brw_dir dir, struct avp *avp);
1463
1464 /*
1465 * FUNCTION: fd_msg_search_avp
1466 *
1467 * PARAMETERS:
1468 * msg : The message structure in which to search the AVP.
1469 * what : The dictionary model of the AVP to search.
1470 * avp : location where the AVP reference is stored if found.
1471 *
1472 * DESCRIPTION:
1473 * Search the first top-level AVP of a given model inside a message.
1474 * Note: only the first instance of the AVP is returned by this function.
1475 * Note: only top-level AVPs are searched, not inside grouped AVPs.
1476 * Use msg_browse if you need more advanced research features.
1477 *
1478 * RETURN VALUE:
1479 * 0 : The AVP has been found.
1480 * EINVAL : A parameter is invalid.
1481 * ENOENT : No AVP has been found, and "avp" was NULL (otherwise, *avp is set to NULL and 0 returned).
1482 */
1483 int fd_msg_search_avp ( struct msg * msg, struct dict_object * what, struct avp ** avp );
1484
1485 /*
1486 * FUNCTION: fd_msg_free
1487 *
1488 * PARAMETERS:
1489 * object : pointer to the message or AVP object that must be unlinked and freed.
1490 *
1491 * DESCRIPTION:
1492 * Unlink and free a message or AVP object and its children.
1493 * If the object is an AVP linked into a message, the AVP is removed before being freed.
1494 *
1495 * RETURN VALUE:
1496 * 0 : The message has been freed.
1497 * EINVAL : A parameter is invalid.
1498 */
1499 int fd_msg_free ( msg_or_avp * object );
1500
1501 /***************************************/
1502 /* Dump functions */
1503 /***************************************/
1504 /*
1505 * FUNCTION: fd_msg_dump_*
1506 *
1507 * PARAMETERS:
1508 * level : the log level (INFO, FULL, ...) at which the object is dumped
1509 * obj : A msg or avp object.
1510 *
1511 * DESCRIPTION:
1512 * These functions dump the content of a message to the debug log
1513 * either recursively or only the object itself.
1514 *
1515 * RETURN VALUE:
1516 * -
1517 */
1518 void fd_msg_dump_walk ( int level, msg_or_avp *obj );
1519 void fd_msg_dump_one ( int level, msg_or_avp *obj );
1520
1521
1522 /*********************************************/
1523 /* Message metadata management functions */
1524 /*********************************************/
1525 /*
1526 * FUNCTION: fd_msg_model
1527 *
1528 * PARAMETERS:
1529 * reference : Pointer to a valid msg or avp.
1530 * model : on success, pointer to the dictionary model of this command or AVP. NULL if the model is unknown.
1531 *
1532 * DESCRIPTION:
1533 * Retrieve the dictionary object describing this message or avp. If the object is unknown or the fd_msg_parse_dict has not been called,
1534 * *model is set to NULL.
1535 *
1536 * RETURN VALUE:
1537 * 0 : The model has been set.
1538 * EINVAL : A parameter is invalid.
1539 */
1540 int fd_msg_model ( msg_or_avp * reference, struct dict_object ** model );
1541
1542 /*
1543 * FUNCTION: fd_msg_hdr
1544 *
1545 * PARAMETERS:
1546 * msg : Pointer to a valid message object.
1547 * pdata : Upon success, pointer to the msg_hdr structure of this message. The fields may be modified.
1548 *
1549 * DESCRIPTION:
1550 * Retrieve location of modifiable section of a message.
1551 *
1552 * RETURN VALUE:
1553 * 0 : The location has been written.
1554 * EINVAL : A parameter is invalid.
1555 */
1556 int fd_msg_hdr ( struct msg *msg, struct msg_hdr **pdata );
1557
1558 /*
1559 * FUNCTION: fd_msg_avp_hdr
1560 *
1561 * PARAMETERS:
1562 * avp : Pointer to a valid avp object.
1563 * pdata : Upon success, pointer to the avp_hdr structure of this avp. The fields may be modified.
1564 *
1565 * DESCRIPTION:
1566 * Retrieve location of modifiable data of an avp.
1567 *
1568 * RETURN VALUE:
1569 * 0 : The location has been written.
1570 * EINVAL : A parameter is invalid.
1571 */
1572 int fd_msg_avp_hdr ( struct avp *avp, struct avp_hdr **pdata );
1573
1574 /*
1575 * FUNCTION: fd_msg_answ_associate, fd_msg_answ_getq, fd_msg_answ_detach
1576 *
1577 * PARAMETERS:
1578 * answer : the received answer message
1579 * query : the corresponding query that had been sent
1580 *
1581 * DESCRIPTION:
1582 * fd_msg_answ_associate associates a query msg with the received answer.
1583 * Query is retrieved with fd_msg_answ_getq.
1584 * If answer message is freed, the query is also freed.
1585 * If the msg_answ_detach function is called, the association is removed.
1586 * This is meant to be called from the daemon only.
1587 *
1588 * RETURN VALUE:
1589 * 0 : ok
1590 * EINVAL: a parameter is invalid
1591 */
1592 int fd_msg_answ_associate( struct msg * answer, struct msg * query );
1593 int fd_msg_answ_getq ( struct msg * answer, struct msg ** query );
1594 int fd_msg_answ_detach ( struct msg * answer );
1595
1596 /*
1597 * FUNCTION: fd_msg_anscb_associate, fd_msg_anscb_get
1598 *
1599 * PARAMETERS:
1600 * msg : the answer message
1601 * anscb : the callback to associate with the message
1602 * data : the data to pass to the callback
1603 *
1604 * DESCRIPTION:
1605 * Associate or retrieve a callback with an answer message.
1606 * This is meant to be called from the daemon only.
1607 *
1608 * RETURN VALUE:
1609 * 0 : ok
1610 * EINVAL: a parameter is invalid
1611 */
1612 int fd_msg_anscb_associate( struct msg * msg, void ( *anscb)(void *, struct msg **), void * data );
1613 int fd_msg_anscb_get ( struct msg * msg, void (**anscb)(void *, struct msg **), void ** data );
1614
1615 /*
1616 * FUNCTION: fd_msg_rt_associate, fd_msg_rt_get
1617 *
1618 * PARAMETERS:
1619 * msg : the query message to be sent
1620 * list : the ordered list of possible next-peers
1621 *
1622 * DESCRIPTION:
1623 * Associate a routing list with a query, and retrieve it.
1624 * If the message is freed, the list is also freed.
1625 *
1626 * RETURN VALUE:
1627 * 0 : ok
1628 * EINVAL: a parameter is invalid
1629 */
1630 int fd_msg_rt_associate( struct msg * msg, struct fd_list ** list );
1631 int fd_msg_rt_get ( struct msg * msg, struct fd_list ** list );
1632
1633 /*
1634 * FUNCTION: fd_msg_is_routable
1635 *
1636 * PARAMETERS:
1637 * msg : A msg object.
1638 *
1639 * DESCRIPTION:
1640 * This function returns a boolean telling if a given message is routable in the Diameter network,
1641 * or if it is a local link message only (ex: CER/CEA, DWR/DWA, ...).
1642 *
1643 * RETURN VALUE:
1644 * 0 : The message is not routable / an error occurred.
1645 * 1 : The message is routable.
1646 */
1647 int fd_msg_is_routable ( struct msg * msg );
1648
1649 /*
1650 * FUNCTION: fd_msg_source_(g/s)et
1651 *
1652 * PARAMETERS:
1653 * msg : A msg object.
1654 * diamid : The diameter id of the peer from which this message was received.
1655 * hash : The hash for the diamid value.
1656 * add_rr : if true, a Route-Record AVP is added to the message with content diamid. In that case, dict must be supplied.
1657 * dict : a dictionary with definition of Route-Record AVP (if add_rr is true)
1658 *
1659 * DESCRIPTION:
1660 * Store or retrieve the diameted id of the peer from which this message was received.
1661 * Will be used for example by the routing module to add the Route-Record AVP in forwarded requests,
1662 * or to direct answers to the appropriate peer.
1663 *
1664 * RETURN VALUE:
1665 * 0 : Operation complete.
1666 * !0 : an error occurred.
1667 */
1668 int fd_msg_source_set( struct msg * msg, char * diamid, uint32_t hash, int add_rr, struct dictionary * dict );
1669 int fd_msg_source_get( struct msg * msg, char ** diamid, uint32_t *hash );
1670
1671 /*
1672 * FUNCTION: fd_msg_eteid_get
1673 *
1674 * PARAMETERS:
1675 * -
1676 *
1677 * DESCRIPTION:
1678 * Get a new unique end-to-end id value for the local peer.
1679 *
1680 * RETURN VALUE:
1681 * The new assigned value. No error code is defined.
1682 */
1683 uint32_t fd_msg_eteid_get ( void );
1684
1685
1686 /***************************************/
1687 /* Manage AVP values */
1688 /***************************************/
1689
1690 /*
1691 * FUNCTION: fd_msg_avp_setvalue
1692 *
1693 * PARAMETERS:
1694 * avp : Pointer to a valid avp object with a NULL avp_value pointer. The model must be known.
1695 * value : pointer to an avp_value. The content will be COPIED into the internal storage area.
1696 * If data type is an octetstring, the data is also copied.
1697 * If value is a NULL pointer, the previous data is erased and value is unset in the AVP.
1698 *
1699 * DESCRIPTION:
1700 * Initialize the avp_value field of an AVP header.
1701 *
1702 * RETURN VALUE:
1703 * 0 : The avp_value pointer has been set.
1704 * EINVAL : A parameter is invalid.
1705 */
1706 int fd_msg_avp_setvalue ( struct avp *avp, union avp_value *value );
1707
1708 /*
1709 * FUNCTION: fd_msg_avp_value_encode
1710 *
1711 * PARAMETERS:
1712 * avp : Pointer to a valid avp object with a NULL avp_value. The model must be known.
1713 * data : Pointer to the data that must be encoded as AVP value and stored in the AVP.
1714 * This is only valid for AVPs of derived type for which type_data_encode callback is set. (ex: Address type)
1715 *
1716 * DESCRIPTION:
1717 * Initialize the avp_value field of an AVP object from formatted data, using the AVP's type "type_data_encode" callback.
1718 *
1719 * RETURN VALUE:
1720 * 0 : The avp_value has been set.
1721 * EINVAL : A parameter is invalid.
1722 * ENOTSUP : There is no appropriate callback registered with this AVP's type.
1723 */
1724 int fd_msg_avp_value_encode ( void *data, struct avp *avp );
1725
1726 /*
1727 * FUNCTION: fd_msg_avp_value_interpret
1728 *
1729 * PARAMETERS:
1730 * avp : Pointer to a valid avp object with a non-NULL avp_value value.
1731 * data : Upon success, formatted interpretation of the AVP value is stored here.
1732 *
1733 * DESCRIPTION:
1734 * Interpret the content of an AVP of Derived type and store the result in data pointer. The structure
1735 * of the data pointer is dependent on the AVP type. This function calls the "type_data_interpret" callback
1736 * of the type.
1737 *
1738 * RETURN VALUE:
1739 * 0 : The avp_value has been set.
1740 * EINVAL : A parameter is invalid.
1741 * ENOTSUP : There is no appropriate callback registered with this AVP's type.
1742 */
1743 int fd_msg_avp_value_interpret ( struct avp *avp, void *data );
1744
1745
1746 /***************************************/
1747 /* Message parsing functions */
1748 /***************************************/
1749
1750 /*
1751 * FUNCTION: fd_msg_bufferize
1752 *
1753 * PARAMETERS:
1754 * msg : A valid msg object. All AVPs must have a value set.
1755 * buffer : Upon success, this points to a buffer (malloc'd) containing the message ready for network transmission (or security transformations).
1756 * The buffer may be freed after use.
1757 * len : if not NULL, the size of the buffer is written here. In any case, this size is updated in the msg header.
1758 *
1759 * DESCRIPTION:
1760 * Renders a message in memory as a buffer that can be sent over the network to the next peer.
1761 *
1762 * RETURN VALUE:
1763 * 0 : The location has been written.
1764 * EINVAL : The buffer does not contain a valid Diameter message.
1765 * ENOMEM : Unable to allocate enough memory to create the buffer object.
1766 */
1767 int fd_msg_bufferize ( struct msg * msg, unsigned char ** buffer, size_t * len );
1768
1769 /*
1770 * FUNCTION: fd_msg_parse_buffer
1771 *
1772 * PARAMETERS:
1773 * buffer : Pointer to a buffer containing a message received from the network.
1774 * buflen : the size in bytes of the buffer.
1775 * msg : Upon success, this points to a valid msg object. No AVP value is resolved in this object, nor grouped AVP.
1776 *
1777 * DESCRIPTION:
1778 * This function parses a buffer an creates a msg object to represent the structure of the message.
1779 * Since no dictionary lookup is performed, the values of the AVPs are not interpreted. To interpret the values,
1780 * the returned message object must be passed to fd_msg_parse_dict function.
1781 * The buffer pointer is saved inside the message and will be freed when not needed anymore.
1782 *
1783 * RETURN VALUE:
1784 * 0 : The location has been written.
1785 * ENOMEM : Unable to allocate enough memory to create the msg object.
1786 * EBADMSG : The buffer does not contain a valid Diameter message (or is truncated).
1787 * EINVAL : A parameter is invalid.
1788 */
1789 int fd_msg_parse_buffer ( unsigned char ** buffer, size_t buflen, struct msg ** msg );
1790
1791 /*
1792 * FUNCTION: fd_msg_parse_dict
1793 *
1794 * PARAMETERS:
1795 * object : A msg or AVP object as returned by fd_msg_parse_buffer.
1796 * dict : the dictionary containing the objects definitions to use for resolving all AVPs.
1797 *
1798 * DESCRIPTION:
1799 * This function looks up for the command and each children AVP definitions in the dictionary.
1800 * If the dictionary definition is found, avp_model is set and the value of the AVP is interpreted accordingly and:
1801 * - for grouped AVPs, the children AVP are created and interpreted also.
1802 * - for numerical AVPs, the value is converted to host byte order and saved in the avp_value field.
1803 * - for octetstring AVPs, the string is copied into a new buffer and its address is saved in avp_value.
1804 * If the dictionary definition is not found, avp_model is set to NULL and
1805 * the content of the AVP is saved as an octetstring in an internal structure. avp_value is NULL.
1806 * As a result, after this function has been called, there is no more dependency of the msg object to the message buffer, that is be freed.
1807 *
1808 * RETURN VALUE:
1809 * 0 : The message has been fully parsed as described.
1810 * EINVAL : The msg parameter is invalid for this operation.
1811 * ENOMEM : Unable to allocate enough memory to complete the operation.
1812 * ENOTSUP : No dictionary definition for the command or one of the mandatory AVP was found.
1813 */
1814 int fd_msg_parse_dict ( msg_or_avp * object, struct dictionary * dict );
1815
1816 /*
1817 * FUNCTION: fd_msg_parse_rules
1818 *
1819 * PARAMETERS:
1820 * object : A msg or grouped avp object that must be verified.
1821 * dict : The dictionary containing the rules definitions.
1822 * rule : If not NULL, the first conflicting rule will be saved here if a conflict is found.
1823 *
1824 * DESCRIPTION:
1825 * Check that the children of the object do not conflict with the dictionary rules (ABNF compliance).
1826 *
1827 * RETURN VALUE:
1828 * 0 : The message has been fully parsed and complies to the defined rules.
1829 * EBADMSG : A conflict was detected, or a mandatory AVP is unknown in the dictionary.
1830 * EINVAL : The msg or avp object is invalid for this operation.
1831 * ENOMEM : Unable to allocate enough memory to complete the operation.
1832 */
1833 int fd_msg_parse_rules ( msg_or_avp * object, struct dictionary * dict, struct dict_object ** rule);
1834
1835
1836 /*
1837 * FUNCTION: fd_msg_update_length
1838 *
1839 * PARAMETERS:
1840 * object : Pointer to a valid msg or avp.
1841 *
1842 * DESCRIPTION:
1843 * Update the length field of the object passed as parameter.
1844 * As a side effect, all children objects are also updated. Therefore, all avp_value fields of
1845 * the children AVPs must be set, or an error will occur.
1846 *
1847 * RETURN VALUE:
1848 * 0 : The size has been recomputed.
1849 * EINVAL : A parameter is invalid.
1850 */
1851 int fd_msg_update_length ( msg_or_avp * object );
1852
1853
1854
1855 /*============================================================*/
1856 /* MESSAGE QUEUES */
1857 /*============================================================*/
1858
1859 /* Management of queues of messages */
1860
1861 /* A message queue is an opaque object */
1862 struct mqueue;
1863
1864 /*
1865 * FUNCTION: fd_mq_new
1866 *
1867 * PARAMETERS:
1868 * queue : Upon success, a pointer to the new message queue is saved here.
1869 *
1870 * DESCRIPTION:
1871 * Create a new empty message queue.
1872 *
1873 * RETURN VALUE :
1874 * 0 : The message queue has been initialized successfully.
1875 * EINVAL : The parameter is invalid.
1876 * ENOMEM : Not enough memory to complete the creation.
1877 */
1878 int fd_mq_new ( struct mqueue ** queue );
1879
1880 /*
1881 * FUNCTION: fd_mq_del
1882 *
1883 * PARAMETERS:
1884 * queue : Pointer to an empty message queue to delete.
1885 *
1886 * DESCRIPTION:
1887 * Destroys a message queue. This is only possible if no thread is waiting for a message,
1888 * and the queue is empty.
1889 *
1890 * RETURN VALUE:
1891 * 0 : The message queue has been destroyed successfully.
1892 * EINVAL : The parameter is invalid.
1893 */
1894 int fd_mq_del ( struct mqueue ** queue );
1895
1896 /*
1897 * FUNCTION: fd_mq_length
1898 *
1899 * PARAMETERS:
1900 * queue : The queue from which to retrieve the length.
1901 * length : Upon success, the current number of messages in the queue is stored here.
1902 *
1903 * DESCRIPTION:
1904 * Retrieve the number of messages pending in a queue.
1905 *
1906 * RETURN VALUE:
1907 * 0 : The length of the queue has been written.
1908 * EINVAL : A parameter is invalid.
1909 */
1910 int fd_mq_length ( struct mqueue * queue, int * length );
1911 int fd_mq_length_noerr ( struct mqueue * queue ); /* alternate with no error checking */
1912
1913 /*
1914 * FUNCTION: fd_mq_setthrhd
1915 *
1916 * PARAMETERS:
1917 * queue : The queue for which the thresholds are being set.
1918 * data : An opaque pointer that is passed to h_cb and l_cb callbacks.
1919 * high : The high-level threshold. If the number of elements in the queue increase to this value, h_cb is called.
1920 * h_cb : if not NULL, a callback to call when the queue lengh is bigger than "high".
1921 * low : The low-level threshold. Must be < high.
1922 * l_cb : If the number of elements decrease to low, this callback is called.
1923 *
1924 * DESCRIPTION:
1925 * This function allows to adjust the number of producer / consumer threads of a queue.
1926 * If the consumer are slower than the producers, the number of messages in the queue increase.
1927 * By setting a "high" value, we allow a callback to be called when this number is too high.
1928 * The typical use would be to create an additional consumer thread in this callback.
1929 * If the queue continues to grow, the callback will be called again when the length is 2 * high, then 3*high, ... N * high
1930 * (the callback itself may implement a limit on the number of consumers that can be created)
1931 * When the queue starts to decrease, and the number of elements go under ((N - 1) * high + low, the l_cb callback is called
1932 * and would typially stop one of the consumer threads. If the queue continue to reduce, l_cb is again called at (N-2)*high + low,
1933 * and so on.
1934 *
1935 * Since there is no destructor for the data pointer, if cleanup operations are required, they should be performed in
1936 * l_cb when the length of the queue is becoming < low.
1937 *
1938 * Note that the callbacks are called synchronously, during fd_mq_post or fd_mq_get. Their operation should be quick.
1939 *
1940 * RETURN VALUE:
1941 * 0 : The thresholds have been set
1942 * EINVAL : A parameter is invalid.
1943 */
1944 int fd_mq_setthrhd ( struct mqueue * queue, void * data, uint16_t high, void (*h_cb)(struct mqueue *, void **), uint16_t low, void (*l_cb)(struct mqueue *, void **) );
1945
1946 /*
1947 * FUNCTION: fd_mq_post
1948 *
1949 * PARAMETERS:
1950 * queue : The queue in which the message must be posted.
1951 * msg : The message that is put in the queue.
1952 *
1953 * DESCRIPTION:
1954 * A message is added in a queue. Messages are retrieved from the queue (in FIFO order)
1955 * with the fd_mq_get, fd_mq_tryget, or fd_mq_timedget functions.
1956 *
1957 * RETURN VALUE:
1958 * 0 : The message is queued.
1959 * EINVAL : A parameter is invalid.
1960 * ENOMEM : Not enough memory to complete the operation.
1961 */
1962 int fd_mq_post ( struct mqueue * queue, struct msg ** msg );
1963
1964 /*
1965 * FUNCTION: fd_mq_get
1966 *
1967 * PARAMETERS:
1968 * queue : The queue from which the message must be retrieved.
1969 * msg : On return, the first message of the queue is stored here.
1970 *
1971 * DESCRIPTION:
1972 * This function retrieves a message from a queue. If the queue is empty, the function will block the
1973 * thread until a new message is posted to the queue, or until the thread is canceled (in which case the
1974 * function does not return).
1975 *
1976 * RETURN VALUE:
1977 * 0 : A new message has been retrieved.
1978 * EINVAL : A parameter is invalid.
1979 */
1980 int fd_mq_get ( struct mqueue * queue, struct msg ** msg );
1981
1982 /*
1983 * FUNCTION: fd_mq_tryget
1984 *
1985 * PARAMETERS:
1986 * queue : The queue from which the message must be retrieved.
1987 * msg : On return, the message is stored here.
1988 *
1989 * DESCRIPTION:
1990 * This function is similar to fd_mq_get, except that it will not block if
1991 * the queue is empty, but return EWOULDBLOCK instead.
1992 *
1993 * RETURN VALUE:
1994 * 0 : A new message has been retrieved.
1995 * EINVAL : A parameter is invalid.
1996 * EWOULDBLOCK : The queue was empty.
1997 */
1998 int fd_mq_tryget ( struct mqueue * queue, struct msg ** msg );
1999
2000 /*
2001 * FUNCTION: fd_mq_timedget
2002 *
2003 * PARAMETERS:
2004 * queue : The queue from which the message must be retrieved.
2005 * msg : On return, the message is stored here.
2006 * abstime : the absolute time until which we allow waiting for a message.
2007 *
2008 * DESCRIPTION:
2009 * This function is similar to fd_mq_get, except that it will block if the queue is empty
2010 * only until the absolute time abstime (see pthread_cond_timedwait for + info).
2011 * If the queue is still empty when the time expires, the function returns ETIMEDOUT
2012 *
2013 * RETURN VALUE:
2014 * 0 : A new message has been retrieved.
2015 * EINVAL : A parameter is invalid.
2016 * ETIMEDOUT : The time out has passed and no message has been received.
2017 */
2018 int fd_mq_timedget ( struct mqueue * queue, struct msg ** msg, const struct timespec *abstime );
2019
2020 #endif /* _LIBFREEDIAMETER_H */
"Welcome to our mercurial repository"