From: Arran Cudbard-Bell <a.cudbardb@freeradius.org>
Date: Wed, 20 Feb 2013 19:28:22 +0000 (-0500)
Subject: Some documentation for the request struct
X-Git-Tag: release_3_0_0_beta1~979
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=45c277166d743e5bb5fef368a533da7b1467d71c;p=thirdparty%2Ffreeradius-server.git

Some documentation for the request struct
---

diff --git a/src/include/radiusd.h b/src/include/radiusd.h
index 8dd735a113a..eea6c49d8f0 100644
--- a/src/include/radiusd.h
+++ b/src/include/radiusd.h
@@ -167,47 +167,82 @@ typedef		int (*RAD_REQUEST_FUNP)(REQUEST *);
 
 struct auth_req {
 #ifndef NDEBUG
-	uint32_t		magic; /* for debugging only */
+	uint32_t		magic; 		//!< Magic number used to 
+						//!< detect memory corruption,
+						//!< or request structs that
+						//!< have not been properly
+						//!< initialised.
 #endif
-	RADIUS_PACKET		*packet;
+	RADIUS_PACKET		*packet;	//!< Incoming request.
 #ifdef WITH_PROXY
-	RADIUS_PACKET		*proxy;
+	RADIUS_PACKET		*proxy;		//!< Outgoing request.
 #endif
-	RADIUS_PACKET		*reply;
+	RADIUS_PACKET		*reply;		//!< Outgoing response.
 #ifdef WITH_PROXY
-	RADIUS_PACKET		*proxy_reply;
-#endif
-	VALUE_PAIR		*config_items;
-	VALUE_PAIR		*username;
-	VALUE_PAIR		*password;
-
-	fr_request_process_t	process;
-	RAD_REQUEST_FUNP	handle;
-	struct main_config_t	*root;
-
-	request_data_t		*data;
-	RADCLIENT		*client;
+	RADIUS_PACKET		*proxy_reply;	//!< Incoming response.
+#endif
+	VALUE_PAIR		*config_items;	//!< VALUE_PAIR s used to set
+						//!< per request parameters for
+						//!< modules and the server 
+						//!< core at runtime.
+	VALUE_PAIR		*username;	//!< Cached username VALUE_PAIR.
+	VALUE_PAIR		*password;	//!< Cached password VALUE_PAIR.
+
+	fr_request_process_t	process;	//!< The function to call to
+						//!< move the request through
+						//!< the state machine.
+						
+	RAD_REQUEST_FUNP	handle;		//!< The function to call to
+						//!< move the request through
+						//!< the various server
+						//!< configuration sections.
+						
+	struct main_config_t	*root;		//!< Pointer to the main config
+						//!< hack to try and deal with
+						//!< hup. 
+
+	request_data_t		*data;		//!< Request metadata.
+	
+	RADCLIENT		*client;	//!< The client that originally
+						//!< sent us the request.
+						
 #ifdef HAVE_PTHREAD_H
-	pthread_t    		child_pid;
+	pthread_t    		child_pid;	//!< Current thread handling
+						//!< the request.
 #endif
-	time_t			timestamp;
-	unsigned int	       	number; /* internal server number */
+	time_t			timestamp;	//!< When the request was 
+						//!< received.
+	unsigned int	       	number; 	//!< Monotonically increasing
+						//!< request number. Reset on 
+						//!< server restart.
 
-	rad_listen_t		*listener;
+	rad_listen_t		*listener;	//!< The listener that received
+						//!< the request.
 #ifdef WITH_PROXY
-	rad_listen_t		*proxy_listener;
+	rad_listen_t		*proxy_listener;//!< Listener for outgoing 
+						//!< requests.
 #endif
 
 
-	int                     simul_max; /* see modcall.c && xlat.c */
+	int                     simul_max;	//!< Maximum number of 
+						//!< concurrent sessions for
+						//!< this user.
 #ifdef WITH_SESSION_MGMT
-	int                     simul_count;
-	int                     simul_mpp; /* WEIRD: 1 is false, 2 is true */
-#endif
-
-	int			options; /* miscellanous options */
-	const char		*module; /* for debugging unresponsive children */
-	const char		*component; /* ditto */
+	int                     simul_count;	//!< The current number of
+						//!< sessions for this user.
+	int                     simul_mpp; 	//!< WEIRD: 1 is false,
+						//!< 2 is true.
+#endif
+
+	int			options;	//!< Request options, currently
+						//!< just holds the debug level 
+						//!< for the request.
+						
+	const char		*module;	//!< Module the request is
+						//!< currently being processed
+						//!< by.	
+	const char		*component; 	//!< Section the request is
+						//!< in.
 
 	int			delay;