Navigation


Ignore:
File:
1 edited

Legend:

Unmodified
Added
Removed

  • include/freeDiameter/libfreeDiameter.h

    r1 r3  
    122122char * fd_log_time ( char * buf, size_t len );
    123123
    124 /************************** DEBUG MACROS ************************************/
    125124
    126125/* levels definitions */
    … …  
    137136#endif /* TRACE_LEVEL */
    138137
    139 /* The level of the file being compiled */
     138/* The level of the file being compiled. */
    140139static int local_debug_level = TRACE_LEVEL;
    141140
    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__ */
     141/* A global level, changed by configuration or cmd line for example. default is 0. */
     142extern int fd_g_debug_lvl;
     143
     144/* Some portability code to get nice function name in __PRETTY_FUNCTION__ */
    149145#if __STDC_VERSION__ < 199901L
    150146# if __GNUC__ >= 2
    … …  
    159155
    160156/* Boolean for tracing at a certain level */
    161 #define TRACE_BOOL(_level_) ( (_level_) <= local_debug_level )
    162 
    163 /* The general debug macro, each call results in two lines of debug messages */
     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) */
    164160#define TRACE_DEBUG(level,format,args... ) {                                                                                    \
    165161        if ( TRACE_BOOL(level) ) {                                                                                              \
    … …  
    173169}
    174170
    175 /* Helper for function entry */
     171/* Helper for function entry -- for very detailed trace of the execution */
    176172#define TRACE_ENTRY(_format,_args... ) \
    177173        TRACE_DEBUG(FCTS, "->%s (" #_args ") = (" _format ") >", __PRETTY_FUNCTION__, ##_args );
    178174
    179 /* Helper for debugging by adding traces */
     175/* Helper for debugging by adding traces -- for debuging a specific location of the code */
    180176#define TRACE_HERE()    \
    181         TRACE_DEBUG(INFO, " -- debug checkpoint -- ");
    182 
    183 /* Helper for tracing the CHECK_* macros bellow */
     177        TRACE_DEBUG(NONE, " -- debug checkpoint -- ");
     178
     179/* Helper for tracing the CHECK_* macros bellow -- very very verbose code execution! */
    184180#define TRACE_DEBUG_ALL( str )  \
    185181        TRACE_DEBUG(CALL, str );
    … …  
    284280}
    285281
    286 /****************************** Socket helpers ************************************/
     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 )
    287292
    288293/* Some aliases to socket addresses structures */
    … …  
    337342        (((in_addr_t *)(a6))[3])
    338343
    339 /*
    340  * Other macros
    341  */
    342344
    343345/* We provide macros to convert 64 bit values to and from network byte-order, on systems where it is not already provided. */
    … …  
    354356#endif /* HAVE_NTOHLL */
    355357
    356 /* This macro will pad a size to the next multiple of 4. */
     358/* This macro will give the next multiple of 4 for an integer (used for padding sizes of AVP). */
    357359#define PAD4(_x) ((_x) + ( (4 - (_x)) & 3 ) )
    358360
    359 /* Useful to display as ASCII some bytes values */
     361/* Useful to display as safe ASCII a value (will garbage UTF-8 output...) */
    360362#define ASCII(_c) ( ((_c < 32) || (_c > 127)) ? ( _c ? '?' : ' ' ) : _c )
    361363
    … …  
    365367          || ((ts1)->tv_nsec < (ts2)->tv_nsec) )
    366368
    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':'-'
    372369
    373370/*============================================================*/
    … …  
    403400}
    404401
    405 /* Cleanups for cancellation (all threads should be safely cancelable!) */
     402/* Cleanups for cancellation (all threads should be safely cancelable...) */
    406403static __inline__ void fd_cleanup_mutex( void * mutex )
    407404{
    … …  
    591588be freed automatically along with the object itself with call to dict_fini later.
    592589 
    593 - dict_new:
     590- fd_dict_new:
    594591 The "parent" parameter is not used for vendors.
    595592 Sample code to create a vendor:
    … …  
    598595         struct dict_object * myvendor;
    599596         struct dict_vendor_data myvendordata = { 23455, "my vendor name" };  -- just an example...
    600          ret = dict_new ( DICT_VENDOR, &myvendordata, NULL, &myvendor );
     597         ret = fd_dict_new ( dict, DICT_VENDOR, &myvendordata, NULL, &myvendor );
    601598 }
    602599
    603 - dict_search:
     600- fd_dict_search:
    604601 Sample codes to look for a vendor object, by its id or name:
    605602 {
    … …  
    607604         struct dict_object * vendor_found;
    608605         vendor_id_t vendorid = 23455;
    609          ret = dict_search ( DICT_VENDOR, VENDOR_BY_ID, &vendorid, &vendor_found, ENOENT);
     606         ret = fd_dict_search ( dict, DICT_VENDOR, VENDOR_BY_ID, &vendorid, &vendor_found, ENOENT);
    610607         - or -
    611          ret = dict_search ( DICT_VENDOR, VENDOR_BY_NAME, "my vendor name", &vendor_found, ENOENT);
     608         ret = fd_dict_search ( dict, DICT_VENDOR, VENDOR_BY_NAME, "my vendor name", &vendor_found, ENOENT);
    612609 }
    613610 
    614  - dict_getval:
     611 - fd_dict_getval:
    615612 Sample code to retrieve the data from a vendor object:
    616613 {
    … …  
    618615         struct dict_object * myvendor;
    619616         struct dict_vendor_data myvendordata;
    620          ret = dict_search ( DICT_VENDOR, VENDOR_BY_NAME, "my vendor name", &myvendor, ENOENT);
    621          ret = dict_getval ( myvendor, &myvendordata );
     617         ret = fd_dict_search ( dict, DICT_VENDOR, VENDOR_BY_NAME, "my vendor name", &myvendor, ENOENT);
     618         ret = fd_dict_getval ( myvendor, &myvendordata );
    622619         printf("my vendor id: %d\n", myvendordata.vendor_id );
    623620 }
    … …  
    660657The vendor associated to an application is retrieved with VENDOR_OF_APPLICATION search criteria on vendors.
    661658
    662 - dict_new:
     659- fd_dict_new:
    663660 Sample code for application creation:
    664661 {
    … …  
    675672         };
    676673       
    677          ret = dict_new ( DICT_VENDOR, &vendor_data, NULL, &vendor );
    678          ret = dict_new ( DICT_APPLICATION, &app_data, vendor, &appl );
     674         ret = fd_dict_new ( dict, DICT_VENDOR, &vendor_data, NULL, &vendor );
     675         ret = fd_dict_new ( dict, DICT_APPLICATION, &app_data, vendor, &appl );
    679676 }
    680677
    681 - dict_search:
     678- fd_dict_search:
    682679 Sample code to retrieve the vendor of an application
    683680 {
    … …  
    685682         struct dict_object * vendor, * appli;
    686683         
    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);
     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);
    689686 }
    690687 
    691  - dict_getval:
     688 - fd_dict_getval:
    692689 Sample code to retrieve the data from an application object:
    693690 {
    … …  
    695692         struct dict_object * appli;
    696693         struct dict_application_data appl_data;
    697          ret = dict_search ( DICT_APPLICATION, APPLICATION_BY_NAME, "my vendor's application", &appli, ENOENT);
    698          ret = dict_getval ( appli, &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 );
    699696         printf("my application id: %s\n", appl_data.application_id );
    700697 }
    … …  
    797794 *  API usage :
    798795
    799 - dict_new:
     796- fd_dict_new:
    800797 The "parent" parameter may point to an application object, when a type is defined by a Diameter application.
    801798 
    … …  
    811808                 NULL
    812809                };
    813          ret = dict_new ( DICT_TYPE, &mytypedata, NULL, &mytype );
     810         ret = fd_dict_new ( dict, DICT_TYPE, &mytypedata, NULL, &mytype );
    814811 }
    815812
    816 - dict_search:
     813- fd_dict_search:
    817814 Sample code:
    818815 {
    819816         int ret;
    820817         struct dict_object * address_type;
    821          ret = dict_search ( DICT_TYPE, TYPE_BY_NAME, "Address", &address_type, ENOENT);
     818         ret = fd_dict_search ( dict, DICT_TYPE, TYPE_BY_NAME, "Address", &address_type, ENOENT);
    822819 }
    823820 
    … …  
    858855 *  API usage :
    859856
    860 - dict_new:
     857- fd_dict_new:
    861858 The "parent" parameter must point to a derived type object.
    862859 Sample code to create a type "Boolean" with two constants "True" and "False":
    … …  
    881878                 .enum_value.i32 = -1
    882879                };
    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 );
     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 );
    886883         
    887884 }
    888885
    889 - dict_search:
     886- fd_dict_search:
    890887 Sample code to look for a constant name, by its value:
    891888 {
    … …  
    899896                };
    900897         
    901          ret = dict_search ( DICT_ENUMVAL, ENUMVAL_BY_STRUCT, &boolean_by_value, &value_found, ENOENT);
     898         ret = fd_dict_search ( dict, DICT_ENUMVAL, ENUMVAL_BY_STRUCT, &boolean_by_value, &value_found, ENOENT);
    902899 }
    903900 
    904  - dict_getval:
     901 - fd_dict_getval:
    905902 Sample code to retrieve the data from a constant object:
    906903 {
    … …  
    915912                };
    916913         
    917          ret = dict_search ( DICT_ENUMVAL, ENUMVAL_BY_STRUCT, &boolean_by_value, &value_found, ENOENT);
    918          ret = dict_getval ( value_found, &boolean_data );
     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 );
    919916         printf(" Boolean with value 0: %s", boolean_data.enum_name );
    920917 }
    … …  
    944941#define AVP_FLAG_RESERVED8      0x01
    945942
     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 - dict_new:
     983- fd_dict_new:
    984984 Sample code for AVP creation:
    985985 {
    … …  
    10061006       
    10071007         -- Create an AVP with a base type --
    1008          ret = dict_new ( DICT_AVP, &user_name_data, NULL, &user_name_avp );
     1008         ret = fd_dict_new ( dict, DICT_AVP, &user_name_data, NULL, &user_name_avp );
    10091009         
    10101010         -- Create an AVP with a derived type --
    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 );
     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 );
    10131013         
    10141014 }
    10151015
    1016 - dict_search:
     1016- fd_dict_search:
    10171017 Sample code to look for an AVP
    10181018 {
    … …  
    10261026                };
    10271027         
    1028          ret = dict_search ( DICT_AVP, AVP_BY_NAME, "User-Name", &avp_username, ENOENT);
     1028         ret = fd_dict_search ( dict, DICT_AVP, AVP_BY_NAME, "User-Name", &avp_username, ENOENT);
    10291029         
    1030          ret = dict_search ( DICT_AVP, AVP_BY_NAME_AND_VENDOR, &avpvendorboolean, &avp_sampleboolean, ENOENT);
     1030         ret = fd_dict_search ( dict, DICT_AVP, AVP_BY_NAME_AND_VENDOR, &avpvendorboolean, &avp_sampleboolean, ENOENT);
    10311031         
    10321032 }
    10331033 
    1034  - dict_getval:
     1034 - fd_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 = dict_search ( DICT_AVP, AVP_BY_NAME, "User-Name", &avp_username, ENOENT);
    1041          ret = dict_getval ( avp_username, &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 );
    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
    10701074/* Type to hold data associated to a command */
    10711075struct dict_cmd_data {
    … …  
    10951099Note that the "Request" and "Answer" commands are two independant objects. This allows to have different rules for each.
    10961100
    1097 - dict_new:
     1101- fd_dict_new:
    10981102 Sample code for command creation:
    10991103 {
    … …  
    11081112         };
    11091113       
    1110          ret = dict_new ( DICT_COMMAND, &ce_data, NULL, &cer );
     1114         ret = fd_dict_new (dict, DICT_COMMAND, &ce_data, NULL, &cer );
    11111115         
    11121116         ce_data.cmd_name = "Capabilities-Exchange-Answer";
    11131117         ce_data.cmd_flag_val = 0;                      // Same constraint on "R" flag, but this time it must be cleared.
    11141118
    1115          ret = dict_new ( DICT_COMMAND, &ce_data, NULL, &cea );
     1119         ret = fd_dict_new ( dict, DICT_COMMAND, &ce_data, NULL, &cea );
    11161120 }
    11171121
    1118 - dict_search:
     1122- fd_dict_search:
    11191123 Sample code to look for a command
    11201124 {
    … …  
    11221126         struct dict_object * cer, * cea;
    11231127         command_code_t code = 257;
    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);
     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);
    11261130 }
    11271131 
    1128  - dict_getval:
     1132 - fd_dict_getval:
    11291133 Sample code to retrieve the data from a command object:
    11301134 {
    … …  
    11331137         struct dict_object * cea;
    11341138         struct dict_cmd_data 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 );
     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 );
    11381142         printf("Answer to CER: %s\n", cea_data.cmd_name );
    11391143 }
    … …  
    11861190The "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).
    11871191
    1188 - dict_new:
     1192- fd_dict_new:
    11891193 Sample code for rule creation. Let's create the Proxy-Info grouped AVP for example.
    11901194 {
    … …  
    12011205       
    12021206        -- Create the parent AVP
    1203         ret = dict_new ( DICT_AVP, &proxy_info_data, NULL, &proxy_info_avp );
     1207        ret = fd_dict_new ( dict, DICT_AVP, &proxy_info_data, NULL, &proxy_info_avp );
    12041208       
    12051209        -- Create the first child 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 );
     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 );
    12081212       
    12091213        -- Create the other child AVP
    1210         ret = dict_new ( DICT_AVP, &proxy_state_data, NULL, &proxy_state_avp );
     1214        ret = fd_dict_new ( dict, DICT_AVP, &proxy_state_data, NULL, &proxy_state_avp );
    12111215       
    12121216        -- Now we can create the rules. Both children AVP are mandatory.
    … …  
    12161220       
    12171221        rule_data.rule_avp = proxy_host_avp;
    1218         ret = dict_new ( DICT_RULE, &rule_data, proxy_info_avp, NULL );
     1222        ret = fd_dict_new ( dict, DICT_RULE, &rule_data, proxy_info_avp, NULL );
    12191223       
    12201224        rule_data.rule_avp = proxy_state_avp;
    1221         ret = dict_new ( DICT_RULE, &rule_data, proxy_info_avp, NULL );
     1225        ret = fd_dict_new ( dict, DICT_RULE, &rule_data, proxy_info_avp, NULL );
    12221226}
    12231227
    1224 - dict_search and dict_getval are similar to previous examples.
     1228- fd_dict_search and fd_dict_getval are similar to previous examples.
    12251229
    12261230*/
    … …  
    12741278#define ER_DIAMETER_REDIRECT_INDICATION         3006
    12751279
    1276 /* Iterator on the rules of a parent object */
    1277 int fd_dict_iterate_rules ( struct dict_object *parent, void * data, int (*cb)(void *, struct dict_rule_data *) );
     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 */
     1286struct session_handler;
     1287
     1288/* This opaque structure represents a session associated with a Session-Id */
     1289struct session;
     1290
     1291/* The state information that a module associate with a session -- each module define its own data format */
     1292typedef 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 */
     1311int 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 */
     1331int 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 */
     1358int 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 */
     1379int 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 */
     1398int 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 */
     1422int 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 */
     1438int 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 */
     1461int 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 */
     1481int fd_sess_state_retrieve ( struct session_handler * handler, struct session * session, session_state ** state );
     1482
     1483
     1484/* For debug */
     1485void fd_sess_dump(int level, struct session * session);
     1486void 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
    12781534
    12791535
Note: See TracChangeset for help on using the changeset viewer.