From 2c09af30680baf4c7a6ec2ee7f175c301e2d5cda Mon Sep 17 00:00:00 2001 From: Jouni Malinen Date: Thu, 27 Dec 2012 12:29:05 +0200 Subject: [PATCH] Add Doxygen documentation for functionality related to scanning Signed-hostap: Jouni Malinen --- doc/doxygen.conf | 2 +- wpa_supplicant/bss.c | 159 +++++++++++++++++++++++++++++++++++++++++- wpa_supplicant/bss.h | 43 +++++++----- wpa_supplicant/scan.c | 91 +++++++++++++++++++++++- 4 files changed, 274 insertions(+), 21 deletions(-) diff --git a/doc/doxygen.conf b/doc/doxygen.conf index 55a9433db..b8c40e375 100644 --- a/doc/doxygen.conf +++ b/doc/doxygen.conf @@ -1278,7 +1278,7 @@ INCLUDE_FILE_PATTERNS = # undefined via #undef or recursively expanded use the := operator # instead of the = operator. -PREDEFINED = IEEE8021X_EAPOL CONFIG_CTRL_IFACE +PREDEFINED = IEEE8021X_EAPOL CONFIG_CTRL_IFACE CONFIG_P2P # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then # this tag can be used to specify a list of macro names that should be expanded. diff --git a/wpa_supplicant/bss.c b/wpa_supplicant/bss.c index 0babbd5ef..87b7db89a 100644 --- a/wpa_supplicant/bss.c +++ b/wpa_supplicant/bss.c @@ -1,6 +1,6 @@ /* * BSS table - * Copyright (c) 2009-2010, Jouni Malinen + * Copyright (c) 2009-2012, Jouni Malinen * * This software may be distributed under the terms of the BSD license. * See README for more details. @@ -51,6 +51,14 @@ static void wpa_bss_set_hessid(struct wpa_bss *bss) } +/** + * wpa_bss_anqp_alloc - Allocate ANQP data structure for a BSS entry + * Returns: Allocated ANQP data structure or %NULL on failure + * + * The allocated ANQP data structure has its users count set to 1. It may be + * shared by multiple BSS entries and each shared entry is freed with + * wpa_bss_anqp_free(). + */ struct wpa_bss_anqp * wpa_bss_anqp_alloc(void) { struct wpa_bss_anqp *anqp; @@ -62,6 +70,11 @@ struct wpa_bss_anqp * wpa_bss_anqp_alloc(void) } +/** + * wpa_bss_anqp_clone - Clone an ANQP data structure + * @anqp: ANQP data structure from wpa_bss_anqp_alloc() + * Returns: Cloned ANQP data structure or %NULL on failure + */ static struct wpa_bss_anqp * wpa_bss_anqp_clone(struct wpa_bss_anqp *anqp) { struct wpa_bss_anqp *n; @@ -92,6 +105,14 @@ static struct wpa_bss_anqp * wpa_bss_anqp_clone(struct wpa_bss_anqp *anqp) } +/** + * wpa_bss_anqp_unshare_alloc - Unshare ANQP data (if shared) in a BSS entry + * @bss: BSS entry + * Returns: 0 on success, -1 on failure + * + * This function ensures the specific BSS entry has an ANQP data structure that + * is not shared with any other BSS entry. + */ int wpa_bss_anqp_unshare_alloc(struct wpa_bss *bss) { struct wpa_bss_anqp *anqp; @@ -116,6 +137,10 @@ int wpa_bss_anqp_unshare_alloc(struct wpa_bss *bss) } +/** + * wpa_bss_anqp_free - Free an ANQP data structure + * @anqp: ANQP data structure from wpa_bss_anqp_alloc() or wpa_bss_anqp_clone() + */ static void wpa_bss_anqp_free(struct wpa_bss_anqp *anqp) { if (anqp == NULL) @@ -175,6 +200,14 @@ static void wpa_bss_remove(struct wpa_supplicant *wpa_s, struct wpa_bss *bss, } +/** + * wpa_bss_get - Fetch a BSS table entry based on BSSID and SSID + * @wpa_s: Pointer to wpa_supplicant data + * @bssid: BSSID + * @ssid: SSID + * @ssid_len: Length of @ssid + * Returns: Pointer to the BSS entry or %NULL if not found + */ struct wpa_bss * wpa_bss_get(struct wpa_supplicant *wpa_s, const u8 *bssid, const u8 *ssid, size_t ssid_len) { @@ -496,6 +529,15 @@ wpa_bss_update(struct wpa_supplicant *wpa_s, struct wpa_bss *bss, } +/** + * wpa_bss_update_start - Start a BSS table update from scan results + * @wpa_s: Pointer to wpa_supplicant data + * + * This function is called at the start of each BSS table update round for new + * scan results. The actual scan result entries are indicated with calls to + * wpa_bss_update_scan_res() and the update round is finished with a call to + * wpa_bss_update_end(). + */ void wpa_bss_update_start(struct wpa_supplicant *wpa_s) { wpa_s->bss_update_idx++; @@ -505,6 +547,15 @@ void wpa_bss_update_start(struct wpa_supplicant *wpa_s) } +/** + * wpa_bss_update_scan_res - Update a BSS table entry based on a scan result + * @wpa_s: Pointer to wpa_supplicant data + * @res: Scan result + * + * This function updates a BSS table entry (or adds one) based on a scan result. + * This is called separately for each scan result between the calls to + * wpa_bss_update_start() and wpa_bss_update_end(). + */ void wpa_bss_update_scan_res(struct wpa_supplicant *wpa_s, struct wpa_scan_res *res) { @@ -610,6 +661,16 @@ static int wpa_bss_included_in_scan(const struct wpa_bss *bss, } +/** + * wpa_bss_update_end - End a BSS table update from scan results + * @wpa_s: Pointer to wpa_supplicant data + * @info: Information about scan parameters + * @new_scan: Whether this update round was based on a new scan + * + * This function is called at the end of each BSS table update round for new + * scan results. The start of the update was indicated with a call to + * wpa_bss_update_start(). + */ void wpa_bss_update_end(struct wpa_supplicant *wpa_s, struct scan_info *info, int new_scan) { @@ -655,6 +716,13 @@ void wpa_bss_update_end(struct wpa_supplicant *wpa_s, struct scan_info *info, } +/** + * wpa_bss_flush_by_age - Flush old BSS entries + * @wpa_s: Pointer to wpa_supplicant data + * @age: Maximum entry age in seconds + * + * Remove BSS entries that have not been updated during the last @age seconds. + */ void wpa_bss_flush_by_age(struct wpa_supplicant *wpa_s, int age) { struct wpa_bss *bss, *n; @@ -688,6 +756,14 @@ static void wpa_bss_timeout(void *eloop_ctx, void *timeout_ctx) } +/** + * wpa_bss_init - Initialize BSS table + * @wpa_s: Pointer to wpa_supplicant data + * Returns: 0 on success, -1 on failure + * + * This prepares BSS table lists and timer for periodic updates. The BSS table + * is deinitialized with wpa_bss_deinit() once not needed anymore. + */ int wpa_bss_init(struct wpa_supplicant *wpa_s) { dl_list_init(&wpa_s->bss); @@ -698,6 +774,10 @@ int wpa_bss_init(struct wpa_supplicant *wpa_s) } +/** + * wpa_bss_flush - Flush all unused BSS entries + * @wpa_s: Pointer to wpa_supplicant data + */ void wpa_bss_flush(struct wpa_supplicant *wpa_s) { struct wpa_bss *bss, *n; @@ -713,6 +793,10 @@ void wpa_bss_flush(struct wpa_supplicant *wpa_s) } +/** + * wpa_bss_deinit - Deinitialize BSS table + * @wpa_s: Pointer to wpa_supplicant data + */ void wpa_bss_deinit(struct wpa_supplicant *wpa_s) { eloop_cancel_timeout(wpa_bss_timeout, wpa_s, NULL); @@ -720,6 +804,12 @@ void wpa_bss_deinit(struct wpa_supplicant *wpa_s) } +/** + * wpa_bss_get_bssid - Fetch a BSS table entry based on BSSID + * @wpa_s: Pointer to wpa_supplicant data + * @bssid: BSSID + * Returns: Pointer to the BSS entry or %NULL if not found + */ struct wpa_bss * wpa_bss_get_bssid(struct wpa_supplicant *wpa_s, const u8 *bssid) { @@ -735,6 +825,12 @@ struct wpa_bss * wpa_bss_get_bssid(struct wpa_supplicant *wpa_s, #ifdef CONFIG_P2P +/** + * wpa_bss_get_p2p_dev_addr - Fetch a BSS table entry based on P2P Device Addr + * @wpa_s: Pointer to wpa_supplicant data + * @dev_addr: P2P Device Address of the GO + * Returns: Pointer to the BSS entry or %NULL if not found + */ struct wpa_bss * wpa_bss_get_p2p_dev_addr(struct wpa_supplicant *wpa_s, const u8 *dev_addr) { @@ -751,6 +847,12 @@ struct wpa_bss * wpa_bss_get_p2p_dev_addr(struct wpa_supplicant *wpa_s, #endif /* CONFIG_P2P */ +/** + * wpa_bss_get_id - Fetch a BSS table entry based on identifier + * @wpa_s: Pointer to wpa_supplicant data + * @id: Unique identifier (struct wpa_bss::id) assigned for the entry + * Returns: Pointer to the BSS entry or %NULL if not found + */ struct wpa_bss * wpa_bss_get_id(struct wpa_supplicant *wpa_s, unsigned int id) { struct wpa_bss *bss; @@ -762,6 +864,15 @@ struct wpa_bss * wpa_bss_get_id(struct wpa_supplicant *wpa_s, unsigned int id) } +/** + * wpa_bss_get_ie - Fetch a specified information element from a BSS entry + * @bss: BSS table entry + * @ie: Information element identitifier (WLAN_EID_*) + * Returns: Pointer to the information element (id field) or %NULL if not found + * + * This function returns the first matching information element in the BSS + * entry. + */ const u8 * wpa_bss_get_ie(const struct wpa_bss *bss, u8 ie) { const u8 *end, *pos; @@ -781,6 +892,15 @@ const u8 * wpa_bss_get_ie(const struct wpa_bss *bss, u8 ie) } +/** + * wpa_bss_get_vendor_ie - Fetch a vendor information element from a BSS entry + * @bss: BSS table entry + * @vendor_type: Vendor type (four octets starting the IE payload) + * Returns: Pointer to the information element (id field) or %NULL if not found + * + * This function returns the first matching information element in the BSS + * entry. + */ const u8 * wpa_bss_get_vendor_ie(const struct wpa_bss *bss, u32 vendor_type) { const u8 *end, *pos; @@ -801,6 +921,16 @@ const u8 * wpa_bss_get_vendor_ie(const struct wpa_bss *bss, u32 vendor_type) } +/** + * wpa_bss_get_vendor_ie_multi - Fetch vendor IE data from a BSS entry + * @bss: BSS table entry + * @vendor_type: Vendor type (four octets starting the IE payload) + * Returns: Pointer to the information element payload or %NULL if not found + * + * This function returns concatenated payload of possibly fragmented vendor + * specific information elements in the BSS entry. The caller is responsible for + * freeing the returned buffer. + */ struct wpabuf * wpa_bss_get_vendor_ie_multi(const struct wpa_bss *bss, u32 vendor_type) { @@ -832,6 +962,19 @@ struct wpabuf * wpa_bss_get_vendor_ie_multi(const struct wpa_bss *bss, } +/** + * wpa_bss_get_vendor_ie_multi_beacon - Fetch vendor IE data from a BSS entry + * @bss: BSS table entry + * @vendor_type: Vendor type (four octets starting the IE payload) + * Returns: Pointer to the information element payload or %NULL if not found + * + * This function returns concatenated payload of possibly fragmented vendor + * specific information elements in the BSS entry. The caller is responsible for + * freeing the returned buffer. + * + * This function is like wpa_bss_get_vendor_ie_multi(), but uses IE buffer only + * from Beacon frames instead of either Beacon or Probe Response frames. + */ struct wpabuf * wpa_bss_get_vendor_ie_multi_beacon(const struct wpa_bss *bss, u32 vendor_type) { @@ -864,6 +1007,11 @@ struct wpabuf * wpa_bss_get_vendor_ie_multi_beacon(const struct wpa_bss *bss, } +/** + * wpa_bss_get_max_rate - Get maximum legacy TX rate supported in a BSS + * @bss: BSS table entry + * Returns: Maximum legacy rate in units of 500 kbps + */ int wpa_bss_get_max_rate(const struct wpa_bss *bss) { int rate = 0; @@ -886,6 +1034,15 @@ int wpa_bss_get_max_rate(const struct wpa_bss *bss) } +/** + * wpa_bss_get_bit_rates - Get legacy TX rates supported in a BSS + * @bss: BSS table entry + * @rates: Buffer for returning a pointer to the rates list (units of 500 kbps) + * Returns: number of legacy TX rates or -1 on failure + * + * The caller is responsible for freeing the returned buffer with os_free() in + * case of success. + */ int wpa_bss_get_bit_rates(const struct wpa_bss *bss, u8 **rates) { const u8 *ie, *ie2; diff --git a/wpa_supplicant/bss.h b/wpa_supplicant/bss.h index eb01f2dae..01f6c59d2 100644 --- a/wpa_supplicant/bss.h +++ b/wpa_supplicant/bss.h @@ -19,7 +19,11 @@ struct wpa_scan_res; #define WPA_BSS_ASSOCIATED BIT(5) #define WPA_BSS_ANQP_FETCH_TRIED BIT(6) +/** + * struct wpa_bss_anqp - ANQP data for a BSS entry (struct wpa_bss) + */ struct wpa_bss_anqp { + /** Number of BSS entries referring to this ANQP data instance */ unsigned int users; #ifdef CONFIG_INTERWORKING struct wpabuf *venue_name; @@ -40,49 +44,52 @@ struct wpa_bss_anqp { /** * struct wpa_bss - BSS table - * @list: List entry for struct wpa_supplicant::bss - * @list_id: List entry for struct wpa_supplicant::bss_id - * @id: Unique identifier for this BSS entry - * @scan_miss_count: Number of counts without seeing this BSS - * @flags: information flags about the BSS/IBSS (WPA_BSS_*) - * @last_update_idx: Index of the last scan update - * @bssid: BSSID - * @hessid: HESSID - * @freq: frequency of the channel in MHz (e.g., 2412 = channel 1) - * @beacon_int: beacon interval in TUs (host byte order) - * @caps: capability information field in host byte order - * @qual: signal quality - * @noise: noise level - * @level: signal level - * @tsf: Timestamp of last Beacon/Probe Response frame - * @last_update: Time of the last update (i.e., Beacon or Probe Response RX) - * @ie_len: length of the following IE field in octets (from Probe Response) - * @beacon_ie_len: length of the following Beacon IE field in octets * * This structure is used to store information about neighboring BSSes in * generic format. It is mainly updated based on scan results from the driver. */ struct wpa_bss { + /** List entry for struct wpa_supplicant::bss */ struct dl_list list; + /** List entry for struct wpa_supplicant::bss_id */ struct dl_list list_id; + /** Unique identifier for this BSS entry */ unsigned int id; + /** Number of counts without seeing this BSS */ unsigned int scan_miss_count; + /** Index of the last scan update */ unsigned int last_update_idx; + /** Information flags about the BSS/IBSS (WPA_BSS_*) */ unsigned int flags; + /** BSSID */ u8 bssid[ETH_ALEN]; + /** HESSID */ u8 hessid[ETH_ALEN]; + /** SSID */ u8 ssid[32]; + /** Length of SSID */ size_t ssid_len; + /** Frequency of the channel in MHz (e.g., 2412 = channel 1) */ int freq; + /** Beacon interval in TUs (host byte order) */ u16 beacon_int; + /** Capability information field in host byte order */ u16 caps; + /** Signal quality */ int qual; + /** Noise level */ int noise; + /** Signal level */ int level; + /** Timestamp of last Beacon/Probe Response frame */ u64 tsf; + /** Time of the last update (i.e., Beacon or Probe Response RX) */ struct os_time last_update; + /** ANQP data */ struct wpa_bss_anqp *anqp; + /** Length of the following IE field in octets (from Probe Response) */ size_t ie_len; + /** Length of the following Beacon IE field in octets */ size_t beacon_ie_len; /* followed by ie_len octets of IEs */ /* followed by beacon_ie_len octets of IEs */ diff --git a/wpa_supplicant/scan.c b/wpa_supplicant/scan.c index 82c5b7863..64b4fe40e 100644 --- a/wpa_supplicant/scan.c +++ b/wpa_supplicant/scan.c @@ -1,6 +1,6 @@ /* * WPA Supplicant - Scanning - * Copyright (c) 2003-2010, Jouni Malinen + * Copyright (c) 2003-2012, Jouni Malinen * * This software may be distributed under the terms of the BSD license. * See README for more details. @@ -81,6 +81,15 @@ static int wpas_wps_in_use(struct wpa_supplicant *wpa_s, #endif /* CONFIG_WPS */ +/** + * wpa_supplicant_enabled_networks - Check whether there are enabled networks + * @wpa_s: Pointer to wpa_supplicant data + * Returns: 0 if no networks are enabled, >0 if networks are enabled + * + * This function is used to figure out whether any networks (or Interworking + * with enabled credentials and auto_interworking) are present in the current + * configuration. + */ int wpa_supplicant_enabled_networks(struct wpa_supplicant *wpa_s) { struct wpa_ssid *ssid = wpa_s->conf->ssid; @@ -199,6 +208,12 @@ static void int_array_sort_unique(int *a) } +/** + * wpa_supplicant_trigger_scan - Request driver to start a scan + * @wpa_s: Pointer to wpa_supplicant data + * @params: Scan parameters + * Returns: 0 on success, -1 on failure + */ int wpa_supplicant_trigger_scan(struct wpa_supplicant *wpa_s, struct wpa_driver_scan_params *params) { @@ -847,6 +862,7 @@ void wpa_supplicant_req_scan(struct wpa_supplicant *wpa_s, int sec, int usec) * @wpa_s: Pointer to wpa_supplicant data * @sec: Number of seconds after which to scan * @usec: Number of microseconds after which to scan + * Returns: 0 on success or -1 otherwise * * This function is used to schedule periodic scans for neighboring * access points after the specified time. @@ -868,6 +884,7 @@ int wpa_supplicant_delayed_sched_scan(struct wpa_supplicant *wpa_s, /** * wpa_supplicant_req_sched_scan - Start a periodic scheduled scan * @wpa_s: Pointer to wpa_supplicant data + * Returns: 0 is sched_scan was started or -1 otherwise * * This function is used to schedule periodic scans for neighboring * access points repeating the scan continuously. @@ -1116,6 +1133,16 @@ void wpa_supplicant_cancel_sched_scan(struct wpa_supplicant *wpa_s) } +/** + * wpa_supplicant_notify_scanning - Indicate possible scan state change + * @wpa_s: Pointer to wpa_supplicant data + * @scanning: Whether scanning is currently in progress + * + * This function is to generate scanning notifycations. It is called whenever + * there may have been a change in scanning (scan started, completed, stopped). + * wpas_notify_scanning() is called whenever the scanning state changed from the + * previously notified state. + */ void wpa_supplicant_notify_scanning(struct wpa_supplicant *wpa_s, int scanning) { @@ -1148,6 +1175,15 @@ static int wpa_scan_get_max_rate(const struct wpa_scan_res *res) } +/** + * wpa_scan_get_ie - Fetch a specified information element from a scan result + * @res: Scan result entry + * @ie: Information element identitifier (WLAN_EID_*) + * Returns: Pointer to the information element (id field) or %NULL if not found + * + * This function returns the first matching information element in the scan + * result. + */ const u8 * wpa_scan_get_ie(const struct wpa_scan_res *res, u8 ie) { const u8 *end, *pos; @@ -1167,6 +1203,15 @@ const u8 * wpa_scan_get_ie(const struct wpa_scan_res *res, u8 ie) } +/** + * wpa_scan_get_vendor_ie - Fetch vendor information element from a scan result + * @res: Scan result entry + * @vendor_type: Vendor type (four octets starting the IE payload) + * Returns: Pointer to the information element (id field) or %NULL if not found + * + * This function returns the first matching information element in the scan + * result. + */ const u8 * wpa_scan_get_vendor_ie(const struct wpa_scan_res *res, u32 vendor_type) { @@ -1188,6 +1233,16 @@ const u8 * wpa_scan_get_vendor_ie(const struct wpa_scan_res *res, } +/** + * wpa_scan_get_vendor_ie_multi - Fetch vendor IE data from a scan result + * @res: Scan result entry + * @vendor_type: Vendor type (four octets starting the IE payload) + * Returns: Pointer to the information element payload or %NULL if not found + * + * This function returns concatenated payload of possibly fragmented vendor + * specific information elements in the scan result. The caller is responsible + * for freeing the returned buffer. + */ struct wpabuf * wpa_scan_get_vendor_ie_multi(const struct wpa_scan_res *res, u32 vendor_type) { @@ -1219,6 +1274,19 @@ struct wpabuf * wpa_scan_get_vendor_ie_multi(const struct wpa_scan_res *res, } +/** + * wpa_scan_get_vendor_ie_multi_beacon - Fetch vendor IE data from a scan result + * @res: Scan result entry + * @vendor_type: Vendor type (four octets starting the IE payload) + * Returns: Pointer to the information element payload or %NULL if not found + * + * This function returns concatenated payload of possibly fragmented vendor + * specific information elements in the scan result. The caller is responsible + * for freeing the returned buffer. + * + * This function is like wpa_scan_get_vendor_ie_multi(), but uses IE buffer only + * from Beacon frames instead of either Beacon or Probe Response frames. + */ struct wpabuf * wpa_scan_get_vendor_ie_multi_beacon( const struct wpa_scan_res *res, u32 vendor_type) { @@ -1416,6 +1484,15 @@ static void dump_scan_res(struct wpa_scan_results *scan_res) } +/** + * wpa_supplicant_filter_bssid_match - Is the specified BSSID allowed + * @wpa_s: Pointer to wpa_supplicant data + * @bssid: BSSID to check + * Returns: 0 if the BSSID is filtered or 1 if not + * + * This function is used to filter out specific BSSIDs from scan reslts mainly + * for testing purposes (SET bssid_filter ctrl_iface command). + */ int wpa_supplicant_filter_bssid_match(struct wpa_supplicant *wpa_s, const u8 *bssid) { @@ -1507,6 +1584,18 @@ wpa_supplicant_get_scan_results(struct wpa_supplicant *wpa_s, } +/** + * wpa_supplicant_update_scan_results - Update scan results from the driver + * @wpa_s: Pointer to wpa_supplicant data + * Returns: 0 on success, -1 on failure + * + * This function updates the BSS table within wpa_supplicant based on the + * currently available scan results from the driver without requesting a new + * scan. This is used in cases where the driver indicates an association + * (including roaming within ESS) and wpa_supplicant does not yet have the + * needed information to complete the connection (e.g., to perform validation + * steps in 4-way handshake). + */ int wpa_supplicant_update_scan_results(struct wpa_supplicant *wpa_s) { struct wpa_scan_results *scan_res;