From a38fdf1c696ff9e68b1151ba36c8e35eae277f5f Mon Sep 17 00:00:00 2001
From: Jouni Malinen <j@w1.fi>
Date: Sat, 22 Dec 2012 11:58:33 +0200
Subject: [PATCH] Document gas_query.c functions

Signed-hostap: Jouni Malinen <j@w1.fi>
---
 wpa_supplicant/gas_query.c | 43 ++++++++++++++++++++++++++++++++++++++
 wpa_supplicant/gas_query.h |  3 +++
 2 files changed, 46 insertions(+)

diff --git a/wpa_supplicant/gas_query.c b/wpa_supplicant/gas_query.c
index 0d4ca8ecb..27bcc7aa6 100644
--- a/wpa_supplicant/gas_query.c
+++ b/wpa_supplicant/gas_query.c
@@ -19,9 +19,13 @@
 #include "gas_query.h"
 
 
+/** GAS query timeout in seconds */
 #define GAS_QUERY_TIMEOUT_PERIOD 5
 
 
+/**
+ * struct gas_query_pending - Pending GAS query
+ */
 struct gas_query_pending {
 	struct dl_list list;
 	u8 addr[ETH_ALEN];
@@ -40,6 +44,9 @@ struct gas_query_pending {
 	void *ctx;
 };
 
+/**
+ * struct gas_query - Internal GAS query data
+ */
 struct gas_query {
 	struct wpa_supplicant *wpa_s;
 	struct dl_list pending; /* struct gas_query_pending */
@@ -50,6 +57,11 @@ static void gas_query_tx_comeback_timeout(void *eloop_data, void *user_ctx);
 static void gas_query_timeout(void *eloop_data, void *user_ctx);
 
 
+/**
+ * gas_query_init - Initialize GAS query component
+ * @wpa_s: Pointer to wpa_supplicant data
+ * Returns: Pointer to GAS query data or %NULL on failure
+ */
 struct gas_query * gas_query_init(struct wpa_supplicant *wpa_s)
 {
 	struct gas_query *gas;
@@ -82,6 +94,10 @@ static void gas_query_done(struct gas_query *gas,
 }
 
 
+/**
+ * gas_query_deinit - Deinitialize GAS query component
+ * @gas: GAS query data from gas_query_init()
+ */
 void gas_query_deinit(struct gas_query *gas)
 {
 	struct gas_query_pending *query, *next;
@@ -274,6 +290,17 @@ static void gas_query_rx_comeback(struct gas_query *gas,
 }
 
 
+/**
+ * gas_query_rx - Indicate reception of a Public Action frame
+ * @gas: GAS query data from gas_query_init()
+ * @da: Destination MAC address of the Action frame
+ * @sa: Source MAC address of the Action frame
+ * @bssid: BSSID of the Action frame
+ * @data: Payload of the Action frame
+ * @len: Length of @data
+ * @freq: Frequency (in MHz) on which the frame was received
+ * Returns: 0 if the Public Action frame was a GAS frame or -1 if not
+ */
 int gas_query_rx(struct gas_query *gas, const u8 *da, const u8 *sa,
 		 const u8 *bssid, const u8 *data, size_t len, int freq)
 {
@@ -414,6 +441,16 @@ static int gas_query_dialog_token_available(struct gas_query *gas,
 }
 
 
+/**
+ * gas_query_req - Request a GAS query
+ * @gas: GAS query data from gas_query_init()
+ * @dst: Destination MAC address for the query
+ * @freq: Frequency (in MHz) for the channel on which to send the query
+ * @req: GAS query payload
+ * @cb: Callback function for reporting GAS query result and response
+ * @ctx: Context pointer to use with the @cb call
+ * Returns: dialog token (>= 0) on success or -1 on failure
+ */
 int gas_query_req(struct gas_query *gas, const u8 *dst, int freq,
 		  struct wpabuf *req,
 		  void (*cb)(void *ctx, const u8 *dst, u8 dialog_token,
@@ -465,6 +502,12 @@ int gas_query_req(struct gas_query *gas, const u8 *dst, int freq,
 }
 
 
+/**
+ * gas_query_cancel - Cancel a pending GAS query
+ * @gas: GAS query data from gas_query_init()
+ * @dst: Destination MAC address for the query
+ * @dialog_token: Dialog token from gas_query_req()
+ */
 void gas_query_cancel(struct gas_query *gas, const u8 *dst, u8 dialog_token)
 {
 	struct gas_query_pending *query;
diff --git a/wpa_supplicant/gas_query.h b/wpa_supplicant/gas_query.h
index 01aba6e8a..5c3d161ad 100644
--- a/wpa_supplicant/gas_query.h
+++ b/wpa_supplicant/gas_query.h
@@ -19,6 +19,9 @@ void gas_query_deinit(struct gas_query *gas);
 int gas_query_rx(struct gas_query *gas, const u8 *da, const u8 *sa,
 		 const u8 *bssid, const u8 *data, size_t len, int freq);
 
+/**
+ * enum gas_query_result - GAS query result
+ */
 enum gas_query_result {
 	GAS_QUERY_SUCCESS,
 	GAS_QUERY_FAILURE,
-- 
2.39.2