/*********************************************************************************************************
* Software License Agreement (BSD License)                                                               *
* Author: Sebastien Decugis <sdecugis@nict.go.jp>							 *
*													 *
* Copyright (c) 2009, WIDE Project and NICT								 *
* All rights reserved.											 *
* 													 *
* Redistribution and use of this software in source and binary forms, with or without modification, are  *
* permitted provided that the following conditions are met:						 *
* 													 *
* * Redistributions of source code must retain the above 						 *
*   copyright notice, this list of conditions and the 							 *
*   following disclaimer.										 *
*    													 *
* * Redistributions in binary form must reproduce the above 						 *
*   copyright notice, this list of conditions and the 							 *
*   following disclaimer in the documentation and/or other						 *
*   materials provided with the distribution.								 *
* 													 *
* * Neither the name of the WIDE Project or NICT nor the 						 *
*   names of its contributors may be used to endorse or 						 *
*   promote products derived from this software without 						 *
*   specific prior written permission of WIDE Project and 						 *
*   NICT.												 *
* 													 *
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED *
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A *
* PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR *
* ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 	 *
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 	 *
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR *
* TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF   *
* ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.								 *
*********************************************************************************************************/
/* This file contains the description of the API between the base radius_gw extension and
  its extensions that add support for specific RADIUS attributes and/or commands.
  The "notes.txt" file contains the basic mechanism for use of this API. */

#ifndef _RG_API_H
#define _RG_API_H

#define RADIUS_GW_API_VER	1 /* increment when making changes to radius_gw_api definition bellow */

struct rga_conf_state;		/* A structure (definition is subextension-dependant) to hold the subext configuration and state */

struct radius_gw_api {
	struct rga_conf_state *  
		(*rga_conf_parse_cb) ( char * conf_file );		/* configuration parser. Returns NULL on error only. Called even if no configuration file is passed (with NULL parameter then) */
	void	(*rga_conf_free_cb) (struct rga_conf_state * cs); 	/* Free an object returned by rga_conf_parse_cb */
	
	/* handle an incoming RADIUS message */
	int	(*rga_rad_req_cb) ( struct rga_conf_state * cs, sess_id_t ** session, struct radius_msg * rad_req, struct radius_msg ** rad_ans, msg_t ** diam_fw );
	/* ret 0: continue; 
	   ret -1: stop processing this message and destroy the session (or fallback if supported)
	   ret -2: stop processing this message and keep the session (or fallback if supported)
	   ret -3: reply the content of rad_ans to the RADIUS client immediatly and destroy the session
	   ret -4: reply the content of rad_ans to the RADIUS client immediatly and keep the session
	   ret >0: critical error (errno), log and exit.
			   
	   for cases 3 and 4, the answer must be created with rg_msg_create_ans.
	 */
	
	/* handle the corresponding Diameter answer */
	int	(*rga_diam_ans_cb) ( struct rga_conf_state * cs, sess_id_t ** session, msg_t ** diam_ans, struct radius_msg ** rad_fw );
	/* ret 0: continue; ret >0: error; ret: -1 ... (tbd) */
};

/* All extensions must provide the following entry point that is called when the extension is loaded.
Beware, the same extension may be loaded several times, and receive different configuration files. 
No global data should be initialized during this function; instead it should be done during the rga_conf_parse_cb call,
and store in the memory pointed by "conf" that is passed in turn to all callbacks. */
extern int rga_register(int version, waaad_api_t * waaad_api, struct radius_gw_api * api);

#endif /* _RG_API_H */