freeDiameter: include/freeDiameter/libfreeDiameter.h comparison

comparison include/freeDiameter/libfreeDiameter.h @ 6:b0d377c79d80

Progress on dispatch API spec; added fd_sess_reclaim function and test

author	Sebastien Decugis <sdecugis@nict.go.jp>
date	Thu, 03 Sep 2009 16:03:25 +0900
parents	c2d2729e3603
children	e5af94b04946

comparison

equal deleted inserted replaced

-:c2d2729e3603
+:b0d377c79d80
 * RETURN VALUE:
 *  0      	: The new handler has been created.
 *  EINVAL 	: A parameter is invalid.
 *  ENOMEM	: Not enough memory to complete the operation
 */
-int fd_sess_handler_create_int ( struct session_handler ** handler, void (*cleanup)(char * sid, session_state * state) );
+int fd_sess_handler_create_internal ( struct session_handler ** handler, void (*cleanup)(char * sid, session_state * state) );
 /* Macro to avoid casting everywhere */
 #define fd_sess_handler_create( _handler, _cleanup ) \
-	fd_sess_handler_create_int( (_handler), (void (*)(char *, session_state *))(_cleanup) )
+	fd_sess_handler_create_internal( (_handler), (void (*)(char *, session_state *))(_cleanup) )
 /*
 * FUNCTION:	fd_sess_handler_destroy
 *
 * PARAMETERS:
 *  0      	: The session no longer exists.
 *  EINVAL 	: A parameter is invalid.
 */
 int fd_sess_destroy ( struct session ** session );
+/*
+* FUNCTION:	fd_sess_reclaim
+*
+* PARAMETERS:
+*  session	: Pointer to a session object.
+*
+* DESCRIPTION:
+*   Destroys the resources of a session, only if no session_state is associated with it.
+*
+* RETURN VALUE:
+*  0      	: The session no longer exists.
+*  EINVAL 	: A parameter is invalid.
+*/
+int fd_sess_reclaim ( struct session ** session );
 /*
 * FUNCTION:	fd_sess_state_store
 *
 *  0      	: The state has been stored.
 *  EINVAL 	: A parameter is invalid.
 *  EALREADY	: Data was already associated with this session and client.
 *  ENOMEM	: Not enough memory to complete the operation
 */
-int fd_sess_state_store_int ( struct session_handler * handler, struct session * session, session_state ** state );
+int fd_sess_state_store_internal ( struct session_handler * handler, struct session * session, session_state ** state );
 #define fd_sess_state_store( _handler, _session, _state ) \
-	fd_sess_state_store_int( (_handler), (_session), (void *)(_state) )
+	fd_sess_state_store_internal( (_handler), (_session), (void *)(_state) )
 /*
 * FUNCTION:	fd_sess_state_retrieve
 *
 * PARAMETERS:
 *
 * RETURN VALUE:
 *  0      	: *state is updated (NULL or points to the state if it was found).
 *  EINVAL 	: A parameter is invalid.
 */
-int fd_sess_state_retrieve_int ( struct session_handler * handler, struct session * session, session_state ** state );
+int fd_sess_state_retrieve_internal ( struct session_handler * handler, struct session * session, session_state ** state );
 #define fd_sess_state_retrieve( _handler, _session, _state ) \
-	fd_sess_state_retrieve_int( (_handler), (_session), (void *)(_state) )
+	fd_sess_state_retrieve_internal( (_handler), (_session), (void *)(_state) )
 /* For debug */
 void fd_sess_dump(int level, struct session * session);
 void fd_sess_dump_hdl(int level, struct session_handler * handler);
 /*============================================================*/
 /*                         DISPATCH                           */
 /*============================================================*/
-/* The dispatch process consists in passing a message to some handlers
+/* Dispatch module (passing incoming messages to extensions registered callbacks)
-(typically provided by extensions) based on its content (app id, cmd code...) */
+* is split between the library and the daemon.
+*
-/* The dispatch module has two main roles:
+* The library provides the support for associating dispatch callbacks with
+* dictionary objects.
+*
+* The daemon is responsible for calling the callbacks for a message when appropriate.
+*
+*
+* The dispatch module has two main roles:
 *  - help determine if a message can be handled locally (during the routing step)
+*        This decision involves only the application-id of the message.
 *  - pass the message to the callback(s) that will handle it (during the dispatch step)
 *
-* These are the possibilities for registering a callback:
+* These are the possibilities for registering a so-called dispatch callback:
 *
 * -> For All messages.
 *  This callback is called for all messages that are handled locally. This should be used only
-*  internally by the daemon, or for debug purpose.
+*  for debug purpose.
 *
-* -> by AVP value (constants).
+* -> by AVP value (constants only).
-*  This callback will be called when a message is received and contains a certain AVP with a specified value.
+*  This callback will be called when a message is received and contains an AVP with a specified enumerated value.
 *
 * -> by AVP.
 *  This callback will be called when the received message contains a certain AVP.
 *
 * -> by command-code.
-*  This callback will be called when the message is a specific command.
+*  This callback will be called when the message is a specific command (and 'R' flag).
 *
 * -> by application.
 *  This callback will be called when the message has a specific application-id.
 *
 * ( by vendor: would this be useful? it may be added later)
-*
+*/
-* Note that several criteria may be selected at the same time, for example command-code AND application id.
+enum disp_how {
-*
+	DISP_HOW_ANY = 1,		/* Any message. This should be only used for debug. */
-* When a callback is called, it receives the message as parameter, and eventually a pointer to
+	DISP_HOW_APPID,			/* Any message with the specified application-id */
-* the AVP in the message when this is appropriate.
+	DISP_HOW_CC,			/* Messages of the specified command-code (request or answer). App id may be specified. */
-*
+	DISP_HOW_AVP,			/* Messages containing a specific AVP. Command-code and App id may be specified. */
-* The callback must process the message, and eventually create an answer to it. See the definition
+	DISP_HOW_AVP_ENUMVAL		/* Messages containing a specific AVP with a specific enumerated value. Command-code and App id may be specified. */
-* bellow for more information.
+};
-*
+/*
-* If no callback has handled the message, a default handler will be called with the effect of
+* Several criteria may be selected at the same time, for example command-code AND application id.
-* requeuing the message for forwarding on the network to another peer (for requests, if possible), or
+*
-* discarding the message (for answers).
+* If several callbacks are registered for the same object, their order is unspecified.
-*/
+* The order in which the callbacks are called is:
+*  DISP_HOW_ANY
+*  DISP_HOW_AVP_ENUMVAL & DISP_HOW_AVP
+*  DISP_HOW_CC
+*  DISP_HOW_APPID
+*/
+/* When a callback is registered, a "when" argument is passed in addition to the disp_how value,
+* to specify which values the criteria must match. */
+struct disp_when {
+	struct dict_object *	app_id;
+	struct dict_object *	command;
+	struct dict_object *	avp;
+	struct dict_object *	value;
+};
+/* Here is the details on this "when" argument, depending on the disp_how value.
+*
+* DISP_HOW_ANY.
+*  In this case, "when" must be NULL.
+*
+* DISP_HOW_APPID.
+*  Only the "app_id" field must be set, other fields are ignored. It points to a dictionary object of type DICT_APPLICATION.
+*
+* DISP_HOW_CC.
+*  The "command" field must be defined and point to a dictionary object of type DICT_COMMAND.
+*  The "app_id" may be also set. In the case it is set, it restricts the callback to be called only with this command-code and app id.
+*  The other fields are ignored.
+*
+* DISP_HOW_AVP.
+*  The "avp" field of the structure must be set and point to a dictionary object of type DICT_AVP.
+*  The "app_id" field may be set to restrict the messages matching to a specific app id.
+*  The "command" field may also be set to a valid DICT_COMMAND object.
+*  The content of the "value" field is ignored.
+*
+* DISP_HOW_AVP_ENUMVAL.
+*  All fields have the same constraints and meaning as in DISP_REG_AVP. In addition, the "value" field must be set
+*  and points to a valid DICT_ENUMVAL object.
+*
+* Here is a sumary of the fields: ( M : must be set; m : may be set; 0 : ignored )
+*  field:     app_id    command     avp    value
+* APPID :       M          0         0       0
+* CC    :       m          M         0       0
+* AVP   :       m          m         M       0
+* ENUMVA:       m          m         M       M
+*/
+/* The callbacks that are registered have the following prototype:
+*
+*  int dispatch_callback( struct msg ** msg, struct avp * avp, struct session * session, int * is_answer );
+*
+* FUNCTION:	dispatch_callback
+*
+* PARAMETERS:
+*  msg 	: the received message on function entry. may be updated to answer on return (see description)
+*  avp 	: for callbacks registered with DISP_HOW_AVP or DISP_HOW_AVP_ENUMVAL, direct link to the triggering AVP.
+*  session	: if the message contains a Session-Id AVP, the corresponding session object.
+*
+* DESCRIPTION:
+*   Create a new AVP instance.
+*
+* RETURN VALUE:
+*  0      	: The AVP is created.
+*  EINVAL 	: A parameter is invalid.
+*  (other standard errors may be returned, too, with their standard meaning. Example:
+*    ENOMEM 	: Memory allocation for the new avp failed.)
+*/
 /*============================================================*/
 /*                         MESSAGES                           */
 /*============================================================*/

Mercurial > hg > freeDiameter

comparison include/freeDiameter/libfreeDiameter.h @ 6:b0d377c79d80