Navigation


Ignore:
File:
1 edited

Legend:

Unmodified
Added
Removed

  • include/freeDiameter/libfreeDiameter.h

    r3 r1  
    122122char * fd_log_time ( char * buf, size_t len );
    123123
     124/************************** DEBUG MACROS ************************************/
    124125
    125126/* levels definitions */
    … …  
    136137#endif /* TRACE_LEVEL */
    137138
    138 /* The level of the file being compiled. */
     139/* The level of the file being compiled */
    139140static int local_debug_level = TRACE_LEVEL;
    140141
    141 /* A global level, changed by configuration or cmd line for example. default is 0. */
    142 extern int fd_g_debug_lvl;
    143 
    144 /* Some portability code to get nice function name in __PRETTY_FUNCTION__ */
     142/* helper macros (pre-processor hacks) */
     143#define __str( arg )  #arg
     144#define _stringize( arg ) __str( arg )
     145#define __agr( arg1, arg2 ) arg1 ## arg2
     146#define _aggregate( arg1, arg2 ) __agr( arg1, arg2 )
     147
     148/* Some portability tricks to get nice function name in __PRETTY_FUNCTION__ */
    145149#if __STDC_VERSION__ < 199901L
    146150# if __GNUC__ >= 2
    … …  
    155159
    156160/* Boolean for tracing at a certain level */
    157 #define TRACE_BOOL(_level_) ( (_level_) <= local_debug_level + fd_g_debug_lvl )
    158 
    159 /* The general debug macro, each call results in two lines of debug messages (change the macro for more compact output) */
     161#define TRACE_BOOL(_level_) ( (_level_) <= local_debug_level )
     162
     163/* The general debug macro, each call results in two lines of debug messages */
    160164#define TRACE_DEBUG(level,format,args... ) {                                                                                    \
    161165        if ( TRACE_BOOL(level) ) {                                                                                              \
    … …  
    169173}
    170174
    171 /* Helper for function entry -- for very detailed trace of the execution */
     175/* Helper for function entry */
    172176#define TRACE_ENTRY(_format,_args... ) \
    173177        TRACE_DEBUG(FCTS, "->%s (" #_args ") = (" _format ") >", __PRETTY_FUNCTION__, ##_args );
    174178
    175 /* Helper for debugging by adding traces -- for debuging a specific location of the code */
     179/* Helper for debugging by adding traces */
    176180#define TRACE_HERE()    \
    177         TRACE_DEBUG(NONE, " -- debug checkpoint -- ");
    178 
    179 /* Helper for tracing the CHECK_* macros bellow -- very very verbose code execution! */
     181        TRACE_DEBUG(INFO, " -- debug checkpoint -- ");
     182
     183/* Helper for tracing the CHECK_* macros bellow */
    180184#define TRACE_DEBUG_ALL( str )  \
    181185        TRACE_DEBUG(CALL, str );
    … …  
    280284}
    281285
    282 
    283 /*============================================================*/
    284 /*                          MACROS                            */
    285 /*============================================================*/
    286 
    287 /* helper macros (pre-processor hacks to allow macro arguments) */
    288 #define __str( arg )  #arg
    289 #define _stringize( arg ) __str( arg )
    290 #define __agr( arg1, arg2 ) arg1 ## arg2
    291 #define _aggregate( arg1, arg2 ) __agr( arg1, arg2 )
     286/****************************** Socket helpers ************************************/
    292287
    293288/* Some aliases to socket addresses structures */
    … …  
    342337        (((in_addr_t *)(a6))[3])
    343338
     339/*
     340 * Other macros
     341 */
    344342
    345343/* We provide macros to convert 64 bit values to and from network byte-order, on systems where it is not already provided. */
    … …  
    356354#endif /* HAVE_NTOHLL */
    357355
    358 /* This macro will give the next multiple of 4 for an integer (used for padding sizes of AVP). */
     356/* This macro will pad a size to the next multiple of 4. */
    359357#define PAD4(_x) ((_x) + ( (4 - (_x)) & 3 ) )
    360358
    361 /* Useful to display as safe ASCII a value (will garbage UTF-8 output...) */
     359/* Useful to display as ASCII some bytes values */
    362360#define ASCII(_c) ( ((_c < 32) || (_c > 127)) ? ( _c ? '?' : ' ' ) : _c )
    363361
    … …  
    367365          || ((ts1)->tv_nsec < (ts2)->tv_nsec) )
    368366
     367/* Some constants for dumping flags and values */
     368#define DUMP_AVPFL_str  "%c%c"
     369#define DUMP_AVPFL_val(_val) (_val & AVP_FLAG_VENDOR)?'V':'-' , (_val & AVP_FLAG_MANDATORY)?'M':'-'
     370#define DUMP_CMDFL_str  "%c%c%c%c"
     371#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':'-'
    369372
    370373/*============================================================*/
    … …  
    400403}
    401404
    402 /* Cleanups for cancellation (all threads should be safely cancelable...) */
     405/* Cleanups for cancellation (all threads should be safely cancelable!) */
    403406static __inline__ void fd_cleanup_mutex( void * mutex )
    404407{
    … …  
    588591be freed automatically along with the object itself with call to dict_fini later.
    589592 
    590 - fd_dict_new:
     593- dict_new:
    591594 The "parent" parameter is not used for vendors.
    592595 Sample code to create a vendor:
    … …  
    595598         struct dict_object * myvendor;
    596599         struct dict_vendor_data myvendordata = { 23455, "my vendor name" };  -- just an example...
    597          ret = fd_dict_new ( dict, DICT_VENDOR, &myvendordata, NULL, &myvendor );
     600         ret = dict_new ( DICT_VENDOR, &myvendordata, NULL, &myvendor );
    598601 }
    599602
    600 - fd_dict_search:
     603- dict_search:
    601604 Sample codes to look for a vendor object, by its id or name:
    602605 {
    … …  
    604607         struct dict_object * vendor_found;
    605608         vendor_id_t vendorid = 23455;
    606          ret = fd_dict_search ( dict, DICT_VENDOR, VENDOR_BY_ID, &vendorid, &vendor_found, ENOENT);
     609         ret = dict_search ( DICT_VENDOR, VENDOR_BY_ID, &vendorid, &vendor_found, ENOENT);
    607610         - or -
    608          ret = fd_dict_search ( dict, DICT_VENDOR, VENDOR_BY_NAME, "my vendor name", &vendor_found, ENOENT);
     611         ret = dict_search ( DICT_VENDOR, VENDOR_BY_NAME, "my vendor name", &vendor_found, ENOENT);
    609612 }
    610613 
    611  - fd_dict_getval:
     614 - dict_getval:
    612615 Sample code to retrieve the data from a vendor object:
    613616 {
    … …  
    615618         struct dict_object * myvendor;
    616619         struct dict_vendor_data myvendordata;
    617          ret = fd_dict_search ( dict, DICT_VENDOR, VENDOR_BY_NAME, "my vendor name", &myvendor, ENOENT);
    618          ret = fd_dict_getval ( myvendor, &myvendordata );
     620         ret = dict_search ( DICT_VENDOR, VENDOR_BY_NAME, "my vendor name", &myvendor, ENOENT);
     621         ret = dict_getval ( myvendor, &myvendordata );
    619622         printf("my vendor id: %d\n", myvendordata.vendor_id );
    620623 }
    … …  
    657660The vendor associated to an application is retrieved with VENDOR_OF_APPLICATION search criteria on vendors.
    658661
    659 - fd_dict_new:
     662- dict_new:
    660663 Sample code for application creation:
    661664 {
    … …  
    672675         };
    673676       
    674          ret = fd_dict_new ( dict, DICT_VENDOR, &vendor_data, NULL, &vendor );
    675          ret = fd_dict_new ( dict, DICT_APPLICATION, &app_data, vendor, &appl );
     677         ret = dict_new ( DICT_VENDOR, &vendor_data, NULL, &vendor );
     678         ret = dict_new ( DICT_APPLICATION, &app_data, vendor, &appl );
    676679 }
    677680
    678 - fd_dict_search:
     681- dict_search:
    679682 Sample code to retrieve the vendor of an application
    680683 {
    … …  
    682685         struct dict_object * vendor, * appli;
    683686         
    684          ret = fd_dict_search ( dict, DICT_APPLICATION, APPLICATION_BY_NAME, "my vendor's application", &appli, ENOENT);
    685          ret = fd_dict_search ( dict, DICT_VENDOR, VENDOR_OF_APPLICATION, appli, &vendor, ENOENT);
     687         ret = dict_search ( DICT_APPLICATION, APPLICATION_BY_NAME, "my vendor's application", &appli, ENOENT);
     688         ret = dict_search ( DICT_VENDOR, VENDOR_OF_APPLICATION, appli, &vendor, ENOENT);
    686689 }
    687690 
    688  - fd_dict_getval:
     691 - dict_getval:
    689692 Sample code to retrieve the data from an application object:
    690693 {
    … …  
    692695         struct dict_object * appli;
    693696         struct dict_application_data appl_data;
    694          ret = fd_dict_search ( dict, DICT_APPLICATION, APPLICATION_BY_NAME, "my vendor's application", &appli, ENOENT);
    695          ret = fd_dict_getval ( appli, &appl_data );
     697         ret = dict_search ( DICT_APPLICATION, APPLICATION_BY_NAME, "my vendor's application", &appli, ENOENT);
     698         ret = dict_getval ( appli, &appl_data );
    696699         printf("my application id: %s\n", appl_data.application_id );
    697700 }
    … …  
    794797 *  API usage :
    795798
    796 - fd_dict_new:
     799- dict_new:
    797800 The "parent" parameter may point to an application object, when a type is defined by a Diameter application.
    798801 
    … …  
    808811                 NULL
    809812                };
    810          ret = fd_dict_new ( dict, DICT_TYPE, &mytypedata, NULL, &mytype );
     813         ret = dict_new ( DICT_TYPE, &mytypedata, NULL, &mytype );
    811814 }
    812815
    813 - fd_dict_search:
     816- dict_search:
    814817 Sample code:
    815818 {
    816819         int ret;
    817820         struct dict_object * address_type;
    818          ret = fd_dict_search ( dict, DICT_TYPE, TYPE_BY_NAME, "Address", &address_type, ENOENT);
     821         ret = dict_search ( DICT_TYPE, TYPE_BY_NAME, "Address", &address_type, ENOENT);
    819822 }
    820823 
    … …  
    855858 *  API usage :
    856859
    857 - fd_dict_new:
     860- dict_new:
    858861 The "parent" parameter must point to a derived type object.
    859862 Sample code to create a type "Boolean" with two constants "True" and "False":
    … …  
    878881                 .enum_value.i32 = -1
    879882                };
    880          ret = fd_dict_new ( dict, DICT_TYPE, &type_boolean_data, NULL, &type_boolean );
    881          ret = fd_dict_new ( dict, DICT_ENUMVAL, &boolean_false, type_boolean, NULL );
    882          ret = fd_dict_new ( dict, DICT_ENUMVAL, &boolean_true , type_boolean, NULL );
     883         ret = dict_new ( DICT_TYPE, &type_boolean_data, NULL, &type_boolean );
     884         ret = dict_new ( DICT_ENUMVAL, &boolean_false, type_boolean, NULL );
     885         ret = dict_new ( DICT_ENUMVAL, &boolean_true , type_boolean, NULL );
    883886         
    884887 }
    885888
    886 - fd_dict_search:
     889- dict_search:
    887890 Sample code to look for a constant name, by its value:
    888891 {
    … …  
    896899                };
    897900         
    898          ret = fd_dict_search ( dict, DICT_ENUMVAL, ENUMVAL_BY_STRUCT, &boolean_by_value, &value_found, ENOENT);
     901         ret = dict_search ( DICT_ENUMVAL, ENUMVAL_BY_STRUCT, &boolean_by_value, &value_found, ENOENT);
    899902 }
    900903 
    901  - fd_dict_getval:
     904 - dict_getval:
    902905 Sample code to retrieve the data from a constant object:
    903906 {
    … …  
    912915                };
    913916         
    914          ret = fd_dict_search ( dict, DICT_ENUMVAL, ENUMVAL_BY_STRUCT, &boolean_by_value, &value_found, ENOENT);
    915          ret = fd_dict_getval ( value_found, &boolean_data );
     917         ret = dict_search ( DICT_ENUMVAL, ENUMVAL_BY_STRUCT, &boolean_by_value, &value_found, ENOENT);
     918         ret = dict_getval ( value_found, &boolean_data );
    916919         printf(" Boolean with value 0: %s", boolean_data.enum_name );
    917920 }
    … …  
    941944#define AVP_FLAG_RESERVED8      0x01
    942945
    943 /* For dumping flags and values */
    944 #define DUMP_AVPFL_str  "%c%c"
    945 #define DUMP_AVPFL_val(_val) (_val & AVP_FLAG_VENDOR)?'V':'-' , (_val & AVP_FLAG_MANDATORY)?'M':'-'
    946946
    947947/* Type to hold data associated to an avp */
    … …  
    981981To create the rules (ABNF) for children of Grouped AVP, see the DICT_RULE related part.
    982982
    983 - fd_dict_new:
     983- dict_new:
    984984 Sample code for AVP creation:
    985985 {
    … …  
    10061006       
    10071007         -- Create an AVP with a base type --
    1008          ret = fd_dict_new ( dict, DICT_AVP, &user_name_data, NULL, &user_name_avp );
     1008         ret = dict_new ( DICT_AVP, &user_name_data, NULL, &user_name_avp );
    10091009         
    10101010         -- Create an AVP with a derived type --
    1011          ret = fd_dict_search ( dict, DICT_TYPE, TYPE_BY_NAME, "Boolean", &boolean_type, ENOENT);
    1012          ret = fd_dict_new ( dict, DICT_AVP, &sample_boolean_data , boolean_type, &sample_boolean_avp );
     1011         ret = dict_search ( DICT_TYPE, TYPE_BY_NAME, "Boolean", &boolean_type, ENOENT);
     1012         ret = dict_new ( DICT_AVP, &sample_boolean_data , boolean_type, &sample_boolean_avp );
    10131013         
    10141014 }
    10151015
    1016 - fd_dict_search:
     1016- dict_search:
    10171017 Sample code to look for an AVP
    10181018 {
    … …  
    10261026                };
    10271027         
    1028          ret = fd_dict_search ( dict, DICT_AVP, AVP_BY_NAME, "User-Name", &avp_username, ENOENT);
     1028         ret = dict_search ( DICT_AVP, AVP_BY_NAME, "User-Name", &avp_username, ENOENT);
    10291029         
    1030          ret = fd_dict_search ( dict, DICT_AVP, AVP_BY_NAME_AND_VENDOR, &avpvendorboolean, &avp_sampleboolean, ENOENT);
     1030         ret = dict_search ( DICT_AVP, AVP_BY_NAME_AND_VENDOR, &avpvendorboolean, &avp_sampleboolean, ENOENT);
    10311031         
    10321032 }
    10331033 
    1034  - fd_dict_getval:
     1034 - dict_getval:
    10351035 Sample code to retrieve the data from an AVP object:
    10361036 {
    … …  
    10381038         struct dict_object * avp_username;
    10391039         struct dict_avp_data user_name_data;
    1040          ret = fd_dict_search ( dict, DICT_AVP, AVP_BY_NAME, "User-Name", &avp_username, ENOENT);
    1041          ret = fd_dict_getval ( avp_username, &user_name_data );
     1040         ret = dict_search ( DICT_AVP, AVP_BY_NAME, "User-Name", &avp_username, ENOENT);
     1041         ret = dict_getval ( avp_username, &user_name_data );
    10421042         printf("User-Name code: %d\n", user_name_data.avp_code );
    10431043 }
    … …  
    10681068#define CMD_FLAG_RESERVED8      0x01
    10691069
    1070 /* For dumping flags and values */
    1071 #define DUMP_CMDFL_str  "%c%c%c%c"
    1072 #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':'-'
    1073 
    10741070/* Type to hold data associated to a command */
    10751071struct dict_cmd_data {
    … …  
    10991095Note that the "Request" and "Answer" commands are two independant objects. This allows to have different rules for each.
    11001096
    1101 - fd_dict_new:
     1097- dict_new:
    11021098 Sample code for command creation:
    11031099 {
    … …  
    11121108         };
    11131109       
    1114          ret = fd_dict_new (dict, DICT_COMMAND, &ce_data, NULL, &cer );
     1110         ret = dict_new ( DICT_COMMAND, &ce_data, NULL, &cer );
    11151111         
    11161112         ce_data.cmd_name = "Capabilities-Exchange-Answer";
    11171113         ce_data.cmd_flag_val = 0;                      // Same constraint on "R" flag, but this time it must be cleared.
    11181114
    1119          ret = fd_dict_new ( dict, DICT_COMMAND, &ce_data, NULL, &cea );
     1115         ret = dict_new ( DICT_COMMAND, &ce_data, NULL, &cea );
    11201116 }
    11211117
    1122 - fd_dict_search:
     1118- dict_search:
    11231119 Sample code to look for a command
    11241120 {
    … …  
    11261122         struct dict_object * cer, * cea;
    11271123         command_code_t code = 257;
    1128          ret = fd_dict_search ( dict, DICT_COMMAND, CMD_BY_NAME, "Capabilities-Exchange-Request", &cer, ENOENT);
    1129          ret = fd_dict_search ( dict, DICT_COMMAND, CMD_BY_CODE_R, &code, &cer, ENOENT);
     1124         ret = dict_search ( DICT_COMMAND, CMD_BY_NAME, "Capabilities-Exchange-Request", &cer, ENOENT);
     1125         ret = dict_search ( DICT_COMMAND, CMD_BY_CODE_R, &code, &cer, ENOENT);
    11301126 }
    11311127 
    1132  - fd_dict_getval:
     1128 - dict_getval:
    11331129 Sample code to retrieve the data from a command object:
    11341130 {
    … …  
    11371133         struct dict_object * cea;
    11381134         struct dict_cmd_data cea_data;
    1139          ret = fd_dict_search ( dict, DICT_COMMAND, CMD_BY_NAME, "Capabilities-Exchange-Request", &cer, ENOENT);
    1140          ret = fd_dict_search ( dict, DICT_COMMAND, CMD_ANSWER, cer, &cea, ENOENT);
    1141          ret = fd_dict_getval ( cea, &cea_data );
     1135         ret = dict_search ( DICT_COMMAND, CMD_BY_NAME, "Capabilities-Exchange-Request", &cer, ENOENT);
     1136         ret = dict_search ( DICT_COMMAND, CMD_ANSWER, cer, &cea, ENOENT);
     1137         ret = dict_getval ( cea, &cea_data );
    11421138         printf("Answer to CER: %s\n", cea_data.cmd_name );
    11431139 }
    … …  
    11901186The "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).
    11911187
    1192 - fd_dict_new:
     1188- dict_new:
    11931189 Sample code for rule creation. Let's create the Proxy-Info grouped AVP for example.
    11941190 {
    … …  
    12051201       
    12061202        -- Create the parent AVP
    1207         ret = fd_dict_new ( dict, DICT_AVP, &proxy_info_data, NULL, &proxy_info_avp );
     1203        ret = dict_new ( DICT_AVP, &proxy_info_data, NULL, &proxy_info_avp );
    12081204       
    12091205        -- Create the first child AVP.
    1210         ret = fd_dict_new ( dict, DICT_TYPE, &di_type_data, NULL, &diameteridentity_type );
    1211         ret = fd_dict_new ( dict, DICT_AVP, &proxy_host_data, diameteridentity_type, &proxy_host_avp );
     1206        ret = dict_new ( DICT_TYPE, &di_type_data, NULL, &diameteridentity_type );
     1207        ret = dict_new ( DICT_AVP, &proxy_host_data, diameteridentity_type, &proxy_host_avp );
    12121208       
    12131209        -- Create the other child AVP
    1214         ret = fd_dict_new ( dict, DICT_AVP, &proxy_state_data, NULL, &proxy_state_avp );
     1210        ret = dict_new ( DICT_AVP, &proxy_state_data, NULL, &proxy_state_avp );
    12151211       
    12161212        -- Now we can create the rules. Both children AVP are mandatory.
    … …  
    12201216       
    12211217        rule_data.rule_avp = proxy_host_avp;
    1222         ret = fd_dict_new ( dict, DICT_RULE, &rule_data, proxy_info_avp, NULL );
     1218        ret = dict_new ( DICT_RULE, &rule_data, proxy_info_avp, NULL );
    12231219       
    12241220        rule_data.rule_avp = proxy_state_avp;
    1225         ret = fd_dict_new ( dict, DICT_RULE, &rule_data, proxy_info_avp, NULL );
     1221        ret = dict_new ( DICT_RULE, &rule_data, proxy_info_avp, NULL );
    12261222}
    12271223
    1228 - fd_dict_search and fd_dict_getval are similar to previous examples.
     1224- dict_search and dict_getval are similar to previous examples.
    12291225
    12301226*/
    … …  
    12781274#define ER_DIAMETER_REDIRECT_INDICATION         3006
    12791275
    1280 
    1281 /*============================================================*/
    1282 /*                         SESSIONS                           */
    1283 /*============================================================*/
    1284 
    1285 /* Modules that want to associate a state with a Session-Id must first register a handler of this type */
    1286 struct session_handler;
    1287 
    1288 /* This opaque structure represents a session associated with a Session-Id */
    1289 struct session;
    1290 
    1291 /* The state information that a module associate with a session -- each module define its own data format */
    1292 typedef void session_state;
    1293 
    1294 /*
    1295  * FUNCTION:    fd_sess_handler_create
    1296  *
    1297  * PARAMETERS:
    1298  *  handler     : location where the new handler must be stored.
    1299  *  cleanup     : a callback function that must be called when the session with associated data is destroyed.
    1300  *
    1301  * DESCRIPTION:
    1302  *  Create a new session handler. This is needed by a module to associate a state with a session object.
    1303  * The cleanup handler is called when the session timeout expires, or fd_sess_destroy is called. It must free
    1304  * the state associated with the session, and eventually trig other actions (send a STR, ...).
    1305  *
    1306  * RETURN VALUE:
    1307  *  0           : The new handler has been created.
    1308  *  EINVAL      : A parameter is invalid.
    1309  *  ENOMEM      : Not enough memory to complete the operation
    1310  */
    1311 int fd_sess_handler_create_int ( struct session_handler ** handler, void (*cleanup)(char * sid, session_state * state) );
    1312 /* Macro to avoid casting everywhere */
    1313 #define fd_sess_handler_create( _handler, _cleanup ) \
    1314         fd_sess_handler_create_int( (_handler), (void (*)(char *, session_state *))(_cleanup) )
    1315 
    1316 /*
    1317  * FUNCTION:    fd_sess_handler_destroy
    1318  *
    1319  * PARAMETERS:
    1320  *  handler     : location of an handler created by fd_sess_handler_create.
    1321  *
    1322  * DESCRIPTION:
    1323  *  This destroys a session handler (typically called when an application is shutting down).
    1324  * If sessions states are registered with this handler, the cleanup callback is called on them.
    1325  *
    1326  * RETURN VALUE:
    1327  *  0           : The handler was destroyed.
    1328  *  EINVAL      : A parameter is invalid.
    1329  *  ENOMEM      : Not enough memory to complete the operation
    1330  */
    1331 int fd_sess_handler_destroy ( struct session_handler ** handler );
    1332 
    1333 
    1334 
    1335 /*
    1336  * FUNCTION:    fd_sess_new
    1337  *
    1338  * PARAMETERS:
    1339  *  session       : The location where the session object will be created upon success.
    1340  *  diamId        : \0-terminated string containing a Diameter Identity.
    1341  *  opt           : Additional string. Usage is described bellow.
    1342  *  optlen        : if opt is \0-terminated, this can be 0. Otherwise, the length of opt.
    1343  *
    1344  * DESCRIPTION:
    1345  *   Create a new session object. The Session-Id string associated with this session is generated as follow:
    1346  *  If diamId parameter is provided, the string is created according to the RFC: <diamId>;<high32>;<low32>[;opt] where
    1347  *    diamId is a Diameter Identity.
    1348  *    high32 and low32 are the parts of a monotonic 64 bits counter initialized to (time, 0) at startup.
    1349  *    opt is an optional string that can be concatenated to the identifier.
    1350  *  If diamId is NULL, the string is exactly the content of opt.
    1351  *
    1352  * RETURN VALUE:
    1353  *  0           : The session is created.
    1354  *  EINVAL      : A parameter is invalid.
    1355  *  EALREADY    : A session with the same name already exists (returned in *session)
    1356  *  ENOMEM      : Not enough memory to complete the operation
    1357  */
    1358 int fd_sess_new ( struct session ** session, char * diamId, char * opt, size_t optlen );
    1359 
    1360 /*
    1361  * FUNCTION:    fd_sess_fromsid
    1362  *
    1363  * PARAMETERS:
    1364  *  sid         : pointer to a string containing a Session-Id (UTF-8).
    1365  *  len         : length of the sid string (which does not need to be '\0'-terminated)
    1366  *  session     : On success, pointer to the session object created / retrieved.
    1367  *  new         : if not NULL, set to 1 on return if the session object has been created, 0 if it was simply retrieved.
    1368  *
    1369  * DESCRIPTION:
    1370  *   Retrieve a session object from a Session-Id string. Calling this function makes an implicit call to the
    1371  *  fd_sess_link function on the returned session. In case no session object was previously existing with this
    1372  *  id, a new object is silently created (equivalent to fd_sess_new with flag SESSION_NEW_FULL).
    1373  *
    1374  * RETURN VALUE:
    1375  *  0           : The session parameter has been updated.
    1376  *  EINVAL      : A parameter is invalid.
    1377  *  ENOMEM      : Not enough memory to complete the operation
    1378  */
    1379 int fd_sess_fromsid ( char * sid, size_t len, struct session ** session, int * new);
    1380 
    1381 /*
    1382  * FUNCTION:    fd_sess_getsid
    1383  *
    1384  * PARAMETERS:
    1385  *  session     : Pointer to a session object.
    1386  *  sid         : On success, the location of a (\0-terminated) string is stored here.
    1387  *
    1388  * DESCRIPTION:
    1389  *   Retrieve the session identifier (Session-Id) corresponding to a session object.
    1390  *  The returned sid is an UTF-8 string terminated by \0, suitable for calls to strlen and strcpy.
    1391  *  It may be used for example to set the value of an AVP.
    1392  *  Note that the sid string is not copied, just its reference... do not free it!
    1393  *
    1394  * RETURN VALUE:
    1395  *  0           : The sid parameter has been updated.
    1396  *  EINVAL      : A parameter is invalid.
    1397  */
    1398 int fd_sess_getsid ( struct session * session, char ** sid );
    1399 
    1400 /*
    1401  * FUNCTION:    fd_sess_settimeout
    1402  *
    1403  * PARAMETERS:
    1404  *  session     : The session for which to set the timeout.
    1405  *  timeout     : The date when the session times out.
    1406  *
    1407  * DESCRIPTION:
    1408  *   Set the lifetime for a given session object. This function may be
    1409  * called several times on the same object to update the timeout value.
    1410  *   When the timeout date is reached, the cleanup handler of each
    1411  * module that registered data with this session is called, then the
    1412  * session is cleared.
    1413  *
    1414  *   There is a possible race condition between cleanup of the session
    1415  * and use of its data; applications should ensure that they are not
    1416  * using data from a session that is about to expire / expired.
    1417  *
    1418  * RETURN VALUE:
    1419  *  0           : The session timeout has been updated.
    1420  *  EINVAL      : A parameter is invalid.
    1421  */
    1422 int fd_sess_settimeout( struct session * session, const struct timespec * timeout );
    1423 
    1424 /*
    1425  * FUNCTION:    fd_sess_destroy
    1426  *
    1427  * PARAMETERS:
    1428  *  session     : Pointer to a session object.
    1429  *
    1430  * DESCRIPTION:
    1431  *   Destroys a session an all associated data, if any.
    1432  * Equivalent to a session timeout expired, but the effect is immediate.
    1433  *
    1434  * RETURN VALUE:
    1435  *  0           : The session no longer exists.
    1436  *  EINVAL      : A parameter is invalid.
    1437  */
    1438 int fd_sess_destroy ( struct session ** session );
    1439 
    1440 
    1441 
    1442 /*
    1443  * FUNCTION:    fd_sess_state_store
    1444  *
    1445  * PARAMETERS:
    1446  *  handler     : The handler with which the state is registered.
    1447  *  session     : The session object with which the state is registered.
    1448  *  state       : An application state (opaque data) to store with the session.
    1449  *
    1450  * DESCRIPTION:
    1451  *  Stores an application state with a session. This state can later be retrieved
    1452  * with fd_sess_state_retrieve, or implicitly in the cleanup handler when the session
    1453  * is destroyed.
    1454  *
    1455  * RETURN VALUE:
    1456  *  0           : The state has been stored.
    1457  *  EINVAL      : A parameter is invalid.
    1458  *  EALREADY    : Data was already associated with this session and client.
    1459  *  ENOMEM      : Not enough memory to complete the operation
    1460  */
    1461 int fd_sess_state_store ( struct session_handler * handler, struct session * session, session_state ** state );
    1462 
    1463 /*
    1464  * FUNCTION:    fd_sess_state_retrieve
    1465  *
    1466  * PARAMETERS:
    1467  *  handler     : The handler with which the state was registered.
    1468  *  session     : The session object with which the state was registered.
    1469  *  state       : Location where the state must be saved if it is found.
    1470  *
    1471  * DESCRIPTION:
    1472  *  Retrieves a state saved by fd_sess_state_store.
    1473  * After this function has been called, the state is no longer associated with
    1474  * the session. A new call to fd_sess_state_store must be performed in order to
    1475  * store again the data with the session.
    1476  *
    1477  * RETURN VALUE:
    1478  *  0           : *state is updated (NULL or points to the state if it was found).
    1479  *  EINVAL      : A parameter is invalid.
    1480  */
    1481 int fd_sess_state_retrieve ( struct session_handler * handler, struct session * session, session_state ** state );
    1482 
    1483 
    1484 /* For debug */
    1485 void fd_sess_dump(int level, struct session * session);
    1486 void fd_sess_dump_hdl(int level, struct session_handler * handler);
    1487 
    1488 
    1489 /*============================================================*/
    1490 /*                         DISPATCH                           */
    1491 /*============================================================*/
    1492 
    1493 /* The dispatch process consists in passing a message to some handlers
    1494  (typically provided by extensions) based on its content (app id, cmd code...) */
    1495 
    1496 /* The dispatch module has two main roles:
    1497  *  - help determine if a message can be handled locally (during the routing step)
    1498  *  - pass the message to the callback(s) that will handle it (during the dispatch step)
    1499  *
    1500  * These are the possibilities for registering a callback:
    1501  *
    1502  * -> For All messages.
    1503  *  This callback is called for all messages that are handled locally. This should be used only
    1504  *  internally by the daemon, or for debug purpose.
    1505  *
    1506  * -> by AVP value (constants).
    1507  *  This callback will be called when a message is received and contains a certain AVP with a specified value.
    1508  *
    1509  * -> by AVP.
    1510  *  This callback will be called when the received message contains a certain AVP.
    1511  *
    1512  * -> by command-code.
    1513  *  This callback will be called when the message is a specific command.
    1514  *
    1515  * -> by application.
    1516  *  This callback will be called when the message has a specific application-id.
    1517  *
    1518  * ( by vendor: would this be useful? it may be added later)
    1519  *
    1520  * Note that several criteria may be selected at the same time, for example command-code AND application id.
    1521  *
    1522  * When a callback is called, it receives the message as parameter, and eventually a pointer to
    1523  * the AVP in the message when this is appropriate.
    1524  *
    1525  * The callback must process the message, and eventually create an answer to it. See the definition
    1526  * bellow for more information.
    1527  *
    1528  * If no callback has handled the message, a default handler will be called with the effect of
    1529  * requeuing the message for forwarding on the network to another peer (for requests, if possible), or
    1530  * discarding the message (for answers).
    1531  */
    1532 
    1533 
     1276/* Iterator on the rules of a parent object */
     1277int fd_dict_iterate_rules ( struct dict_object *parent, void * data, int (*cb)(void *, struct dict_rule_data *) );
    15341278
    15351279
Note: See TracChangeset for help on using the changeset viewer.