Complete Doxygen documentation for RADIUS client

No more warnings from Doxygen about missing documentation from
radius_client.[ch].

diff --git a/src/radius/radius_client.c b/src/radius/radius_client.c
index ec38c0d..4cb9c39 100644 (file)
--- a/src/radius/radius_client.c
+++ b/src/radius/radius_client.c
@@ -62,14 +62,21 @@
  * This data structure is used internally inside the RADIUS client module to
  * store registered RX handlers. These handlers are registered by calls to
  * radius_client_register() and unregistered when the RADIUS client is
- * deinitizlized with a call to radius_client_deinit().
+ * deinitialized with a call to radius_client_deinit().
  */
 struct radius_rx_handler {
+       /**
+        * handler - Received RADIUS message handler
+        */
        RadiusRxResult (*handler)(struct radius_msg *msg,
                                  struct radius_msg *req,
                                  const u8 *shared_secret,
                                  size_t shared_secret_len,
                                  void *data);
+
+       /**
+        * data - Context data for the handler
+        */
        void *data;
 };
 
@@ -81,21 +88,63 @@ struct radius_rx_handler {
  * store pending RADIUS requests that may still need to be retransmitted.
  */
 struct radius_msg_list {
-       u8 addr[ETH_ALEN]; /* STA/client address; used to find RADIUS messages
-                           * for the same STA. */
+       /**
+        * addr - STA/client address
+        *
+        * This is used to find RADIUS messages for the same STA.
+        */
+       u8 addr[ETH_ALEN];
+
+       /**
+        * msg - RADIUS message
+        */
        struct radius_msg *msg;
+
+       /**
+        * msg_type - Message type
+        */
        RadiusType msg_type;
+
+       /**
+        * first_try - Time of the first transmission attempt
+        */
        os_time_t first_try;
+
+       /**
+        * next_try - Time for the next transmission attempt
+        */
        os_time_t next_try;
+
+       /**
+        * attempts - Number of transmission attempts
+        */
        int attempts;
+
+       /**
+        * next_wait - Next retransmission wait time in seconds
+        */
        int next_wait;
+
+       /**
+        * last_attempt - Time of the last transmission attempt
+        */
        struct os_time last_attempt;
 
-       u8 *shared_secret;
+       /**
+        * shared_secret - Shared secret with the target RADIUS server
+        */
+       const u8 *shared_secret;
+
+       /**
+        * shared_secret_len - shared_secret length in octets
+        */
        size_t shared_secret_len;
 
        /* TODO: server config with failover to backup server(s) */
 
+       /**
+        * next - Next message in the list
+        */
        struct radius_msg_list *next;
 };
 
@@ -120,36 +169,68 @@ struct radius_client_data {
        struct hostapd_radius_servers *conf;
 
        /**
-        * auth_serv_sock - Socket for authentication RADIUS messages
+        * auth_serv_sock - IPv4 socket for RADIUS authentication messages
         */
        int auth_serv_sock;
 
        /**
-        * acct_serv_sock - Socket for accounting RADIUS messages
+        * acct_serv_sock - IPv4 socket for RADIUS accounting messages
         */
        int acct_serv_sock;
 
+       /**
+        * auth_serv_sock6 - IPv6 socket for RADIUS authentication messages
+        */
        int auth_serv_sock6;
+
+       /**
+        * acct_serv_sock6 - IPv6 socket for RADIUS accounting messages
+        */
        int acct_serv_sock6;
 
        /**
-        * auth_sock - Current used socket for RADIUS authentication server
+        * auth_sock - Currently used socket for RADIUS authentication server
         */
        int auth_sock;
 
        /**
-        * acct_sock - Current used socket for RADIUS accounting server
+        * acct_sock - Currently used socket for RADIUS accounting server
         */
        int acct_sock;
 
+       /**
+        * auth_handlers - Authentication message handlers
+        */
        struct radius_rx_handler *auth_handlers;
+
+       /**
+        * num_auth_handlers - Number of handlers in auth_handlers
+        */
        size_t num_auth_handlers;
+
+       /**
+        * acct_handlers - Accounting message handlers
+        */
        struct radius_rx_handler *acct_handlers;
+
+       /**
+        * num_acct_handlers - Number of handlers in acct_handlers
+        */
        size_t num_acct_handlers;
 
+       /**
+        * msgs - Pending outgoing RADIUS messages
+        */
        struct radius_msg_list *msgs;
+
+       /**
+        * num_msgs - Number of pending messages in the msgs list
+        */
        size_t num_msgs;
 
+       /**
+        * next_radius_identifier - Next RADIUS message identifier to use
+        */
        u8 next_radius_identifier;
 };
 
@@ -435,7 +516,8 @@ static void radius_client_update_timeout(struct radius_client_data *radius)
 
 static void radius_client_list_add(struct radius_client_data *radius,
                                   struct radius_msg *msg,
-                                  RadiusType msg_type, u8 *shared_secret,
+                                  RadiusType msg_type,
+                                  const u8 *shared_secret,
                                   size_t shared_secret_len, const u8 *addr)
 {
        struct radius_msg_list *entry, *prev;
@@ -548,7 +630,7 @@ int radius_client_send(struct radius_client_data *radius,
                       const u8 *addr)
 {
        struct hostapd_radius_servers *conf = radius->conf;
-       u8 *shared_secret;
+       const u8 *shared_secret;
        size_t shared_secret_len;
        char *name;
        int s, res;
@@ -833,7 +915,7 @@ void radius_client_flush(struct radius_client_data *radius, int only_auth)
 
 
 static void radius_client_update_acct_msgs(struct radius_client_data *radius,
-                                          u8 *shared_secret,
+                                          const u8 *shared_secret,
                                           size_t shared_secret_len)
 {
        struct radius_msg_list *entry;

diff --git a/src/radius/radius_client.h b/src/radius/radius_client.h
index 796b0e1..6c0ae5b 100644 (file)
--- a/src/radius/radius_client.h
+++ b/src/radius/radius_client.h
@@ -28,7 +28,7 @@ struct radius_msg;
  * server.
  *
  * radiusAuthClientPendingRequests (or radiusAccClientPendingRequests) is the
- * length of hapd->radius->msgs for matching msg_type.
+ * number struct radius_client_data::msgs for matching msg_type.
  */
 struct hostapd_radius_server {
        /**
@@ -211,9 +211,30 @@ typedef enum {
  * RadiusRxResult - RADIUS client RX handler result
  */
 typedef enum {
+       /**
+        * RADIUS_RX_PROCESSED - Message processed
+        *
+        * This stops handler calls and frees the message.
+        */
        RADIUS_RX_PROCESSED,
+
+       /**
+        * RADIUS_RX_QUEUED - Message has been queued
+        *
+        * This stops handler calls, but does not free the message; the handler
+        * that returned this is responsible for eventually freeing the
+        * message.
+        */
        RADIUS_RX_QUEUED,
+
+       /**
+        * RADIUS_RX_UNKNOWN - Message is not for this handler
+        */
        RADIUS_RX_UNKNOWN,
+
+       /**
+        * RADIUS_RX_INVALID_AUTHENTICATOR - Message has invalid Authenticator
+        */
        RADIUS_RX_INVALID_AUTHENTICATOR
 } RadiusRxResult;