Moved documentation from developer.txt into source code files

Use Doxygen comments for functions to replace the old text file that was
not up-to-date anymore.
This commit is contained in:
Jouni Malinen 2009-01-08 16:33:00 +02:00 committed by Jouni Malinen
parent 72f24de82c
commit 1c6e69ccda
11 changed files with 185 additions and 230 deletions

View File

@ -225,6 +225,11 @@ static void accounting_interim_update(void *eloop_ctx, void *timeout_ctx)
}
/**
* accounting_sta_start - Start STA accounting
* @hapd: hostapd BSS data
* @sta: The station
*/
void accounting_sta_start(struct hostapd_data *hapd, struct sta_info *sta)
{
struct radius_msg *msg;
@ -363,6 +368,11 @@ static void accounting_sta_report(struct hostapd_data *hapd,
}
/**
* accounting_sta_interim - Send a interim STA accounting report
* @hapd: hostapd BSS data
* @sta: The station
*/
void accounting_sta_interim(struct hostapd_data *hapd, struct sta_info *sta)
{
if (sta->acct_session_started)
@ -370,6 +380,11 @@ void accounting_sta_interim(struct hostapd_data *hapd, struct sta_info *sta)
}
/**
* accounting_sta_stop - Stop STA accounting
* @hapd: hostapd BSS data
* @sta: The station
*/
void accounting_sta_stop(struct hostapd_data *hapd, struct sta_info *sta)
{
if (sta->acct_session_started) {
@ -396,7 +411,15 @@ static void accounting_sta_get_id(struct hostapd_data *hapd,
}
/* Process the RADIUS frames from Accounting Server */
/**
* accounting_receive - Process the RADIUS frames from Accounting Server
* @msg: RADIUS response message
* @req: RADIUS request message
* @shared_secret: RADIUS shared secret
* @shared_secret_len: Length of shared_secret in octets
* @data: Context data (struct hostapd_data *)
* Returns: Processing status
*/
static RadiusRxResult
accounting_receive(struct radius_msg *msg, struct radius_msg *req,
u8 *shared_secret, size_t shared_secret_len, void *data)
@ -444,6 +467,11 @@ static void accounting_report_state(struct hostapd_data *hapd, int on)
}
/**
* accounting_init: Initialize accounting
* @hapd: hostapd BSS data
* Returns: 0 on success, -1 on failure
*/
int accounting_init(struct hostapd_data *hapd)
{
/* Acct-Session-Id should be unique over reboots. If reliable clock is
@ -460,6 +488,10 @@ int accounting_init(struct hostapd_data *hapd)
}
/**
* accounting_deinit: Deinitilize accounting
* @hapd: hostapd BSS data
*/
void accounting_deinit(struct hostapd_data *hapd)
{
accounting_report_state(hapd, 0);

View File

@ -1377,6 +1377,11 @@ static int hostapd_config_ht_capab(struct hostapd_config *conf,
#endif /* CONFIG_IEEE80211N */
/**
* hostapd_config_read - Read and parse a configuration file
* @fname: Configuration file name (including path, if needed)
* Returns: Allocated configuration data structure
*/
struct hostapd_config * hostapd_config_read(const char *fname)
{
struct hostapd_config *conf;
@ -2366,6 +2371,10 @@ static void hostapd_config_free_bss(struct hostapd_bss_config *conf)
}
/**
* hostapd_config_free - Free hostapd configuration
* @conf: Configuration data from hostapd_config_read().
*/
void hostapd_config_free(struct hostapd_config *conf)
{
size_t i;
@ -2381,8 +2390,16 @@ void hostapd_config_free(struct hostapd_config *conf)
}
/* Perform a binary search for given MAC address from a pre-sorted list.
* Returns 1 if address is in the list or 0 if not. */
/**
* hostapd_maclist_found - Find a MAC address from a list
* @list: MAC address list
* @num_entries: Number of addresses in the list
* @addr: Address to search for
* @vlan_id: Buffer for returning VLAN ID or %NULL if not needed
* Returns: 1 if address is in the list or 0 if not.
*
* Perform a binary search for given MAC address from a pre-sorted list.
*/
int hostapd_maclist_found(struct mac_acl_entry *list, int num_entries,
const u8 *addr, int *vlan_id)
{

View File

@ -1,219 +0,0 @@
Developer notes for hostapd
===========================
hostapd daemon setup, operations, and shutdown
----------------------------------------------
Files: hostapd.[ch]
Externally called functions:
hostapd_new_assoc_sta() is called when a station associates with the AP
Event loop functions:
handle_term() is called on SIGINT and SIGTERM to terminate hostapd process
handle_reload() is called on SIGHUP to reload configuration
handle_dump_state() is called on SIGUSR1 to dump station state data to a
text file
hostapd_rotate_wep() is called to periodically change WEP keys
Configuration parsing
---------------------
Configuration file parsing and data structure definition.
Files: config.[ch]
Externally called functions:
hostapd_config_read() is called to read and parse a configuration file;
allocates and returns configuration data structure
hostapd_config_free() is called to free configuration data structure
hostapd_maclist_found() is called to check whether a given address is found
in a list of MAC addresses
Kernel driver access
--------------------
Helper functions for configuring the Host AP kernel driver and
accessing data from it.
Files: driver.[ch]
IEEE 802.11 frame handling (netdevice wlan#ap)
----------------------------------------------
Receive all incoming IEEE 802.11 frames from the kernel driver via
wlan#ap interface.
Files: receive.c
Externally called functions:
hostapd_init_sockets() is called to initialize sockets for receiving and
sending IEEE 802.11 frames via wlan#ap interface
Event loop functions:
handle_read() is called for each incoming packet from wlan#ap net device
Station table
-------------
Files: sta_info.[ch], ap.h
Event loop functions:
ap_handle_timer() is called to check station activity and to remove
inactive stations
IEEE 802.11 management
----------------------
IEEE 802.11 management frame sending and processing (mainly,
authentication and association). IEEE 802.11 station functionality
(authenticate and associate with another AP as an station).
Files: ieee802_11.[ch]
Externally called functions:
ieee802_11_mgmt() is called for each received IEEE 802.11 management frame
(from handle_frame() in hostapd.c)
ieee802_11_mgmt_cb() is called for each received TX callback of IEEE 802.11
management frame (from handle_tx_callback() in hostapd.c)
ieee802_11_send_deauth() is called to send deauthentication frame
ieee802_11_send_disassoc() is called to send disassociation frame
ieee802_11_parse_elems() is used to parse information elements in
IEEE 802.11 management frames
Event loop functions:
ieee802_11_sta_authenticate() called to retry authentication (with another
AP)
ieee802_11_sta_associate() called to retry association (with another AP)
IEEE 802.11 authentication
--------------------------
Access control list for IEEE 802.11 authentication. Uses staticly
configured ACL from configuration files or an external RADIUS
server. Results from external RADIUS queries are cached to allow
faster authentication frame processing.
Files: ieee802_11_auth.[ch]
Externally called functions:
hostapd_acl_init() called once during hostapd startup
hostapd_acl_deinit() called once during hostapd shutdown
hostapd_acl_recv_radius() called by IEEE 802.1X code for incoming RADIUS
Authentication messages (returns 0 if message was processed)
hostapd_allowed_address() called to check whether a specified station can be
authenticated
Event loop functions:
hostapd_acl_expire() is called to expire ACL cache entries
IEEE 802.1X Authenticator
-------------------------
Files: ieee802_1x.[ch]
Externally called functions:
ieee802_1x_receive() is called for each incoming EAPOL frame from the
wireless interface
ieee802_1x_new_station() is called to start IEEE 802.1X authentication when
a new station completes IEEE 802.11 association
Event loop functions:
ieee802_1x_receive_auth() called for each incoming RADIUS Authentication
message
EAPOL state machine
-------------------
IEEE 802.1X state machine for EAPOL.
Files: eapol_sm.[ch]
Externally called functions:
eapol_sm_step() is called to advance EAPOL state machines after any change
that could affect their state
Event loop functions:
eapol_port_timers_tick() called once per second to advance Port Timers state
machine
IEEE 802.11f (IAPP)
-------------------
Files: iapp.[ch]
Externally called functions:
iapp_new_station() is called to start accounting session when a new station
completes IEEE 802.11 association or IEEE 802.1X authentication
Event loop functions:
iapp_receive_udp() is called for incoming IAPP frames over UDP
Per station accounting
----------------------
Send RADIUS Accounting start and stop messages to a RADIUS Accounting
server. Process incoming RADIUS Accounting messages.
Files: accounting.[ch]
Externally called functions:
accounting_init() called once during hostapd startup
accounting_deinit() called once during hostapd shutdown
accounting_sta_start() called when a station starts new session
accounting_sta_stop() called when a station session is terminated
Event loop functions:
accounting_receive() called for each incoming RADIUS Accounting message
accounting_list_timer() called to retransmit accounting messages and to
remove expired entries
RADIUS messages
---------------
RADIUS message generation and parsing functions.
Files: radius.[ch]
Event loop
----------
Event loop for registering timeout calls, signal handlers, and socket
read events.
Files: eloop.[ch]
RC4
---
RC4 encryption
Files: rc4.[ch]
MD5
---
MD5 hash and HMAC-MD5.
Files: md5.[ch]
Miscellaneous helper functions
------------------------------
Files: common.[ch]

View File

@ -140,9 +140,14 @@ static void eapol_auth_tx_req(struct eapol_state_machine *sm)
}
/* Port Timers state machine - implemented as a function that will be called
* once a second as a registered event loop timeout */
/**
* eapol_port_timers_tick - Port Timers state machine
* @eloop_ctx: struct eapol_state_machine *
* @timeout_ctx: Not used
*
* This statemachine is implemented as a function that will be called
* once a second as a registered event loop timeout.
*/
static void eapol_port_timers_tick(void *eloop_ctx, void *timeout_ctx)
{
struct eapol_state_machine *state = timeout_ctx;
@ -941,6 +946,13 @@ static void eapol_sm_step_cb(void *eloop_ctx, void *timeout_ctx)
}
/**
* eapol_auth_step - Advance EAPOL state machines
* @sm: EAPOL state machine
*
* This function is called to advance EAPOL state machines after any change
* that could affect their state.
*/
void eapol_auth_step(struct eapol_state_machine *sm)
{
/*

View File

@ -281,6 +281,9 @@ static void hostapd_sim_db_cb(void *ctx, void *session_ctx)
#endif /* EAP_SERVER */
/**
* handle_term - SIGINT and SIGTERM handler to terminate hostapd process
*/
static void handle_term(int sig, void *eloop_ctx, void *signal_ctx)
{
printf("Signal %d received - terminating\n", sig);
@ -384,6 +387,9 @@ int hostapd_reload_config(struct hostapd_iface *iface)
#ifndef CONFIG_NATIVE_WINDOWS
/**
* handle_reload - SIGHUP handler to reload configuration
*/
static void handle_reload(int sig, void *eloop_ctx, void *signal_ctx)
{
struct hapd_interfaces *hapds = (struct hapd_interfaces *) eloop_ctx;
@ -402,6 +408,9 @@ static void handle_reload(int sig, void *eloop_ctx, void *signal_ctx)
#ifdef HOSTAPD_DUMP_STATE
/**
* hostapd_dump_state - SIGUSR1 handler to dump hostapd state to a text file
*/
static void hostapd_dump_state(struct hostapd_data *hapd)
{
FILE *f;

View File

@ -13,7 +13,7 @@
*
* Note: IEEE 802.11F-2003 was a experimental use specification. It has expired
* and IEEE has withdrawn it. In other words, it is likely better to look at
* using some other mechanism for AP-to-AP communication than extenting the
* using some other mechanism for AP-to-AP communication than extending the
* implementation here.
*/
@ -238,6 +238,11 @@ static void iapp_send_layer2_update(struct iapp_data *iapp, u8 *addr)
}
/**
* iapp_new_station - IAPP processing for a new STA
* @iapp: IAPP data
* @sta: The associated station
*/
void iapp_new_station(struct iapp_data *iapp, struct sta_info *sta)
{
struct ieee80211_mgmt *assoc;
@ -306,6 +311,12 @@ static void iapp_process_add_notify(struct iapp_data *iapp,
}
/**
* iapp_receive_udp - Process IAPP UDP frames
* @sock: File descriptor for the socket
* @eloop_ctx: IAPP data (struct iapp_data *)
* @sock_ctx: Not used
*/
static void iapp_receive_udp(int sock, void *eloop_ctx, void *sock_ctx)
{
struct iapp_data *iapp = eloop_ctx;

View File

@ -335,6 +335,12 @@ void ieee802_11_print_ssid(char *buf, const u8 *ssid, u8 len)
}
/**
* ieee802_11_send_deauth - Send Deauthentication frame
* @hapd: hostapd BSS data
* @addr: Address of the destination STA
* @reason: Reason code for Deauthentication
*/
void ieee802_11_send_deauth(struct hostapd_data *hapd, u8 *addr, u16 reason)
{
struct ieee80211_mgmt mgmt;
@ -1631,6 +1637,15 @@ static void handle_assoc_cb(struct hostapd_data *hapd,
}
/**
* ieee802_11_mgmt_cb - Process management frame TX status callback
* @hapd: hostapd BSS data structure (the BSS from which the management frame
* was sent from)
* @buf: management frame data (starting from IEEE 802.11 header)
* @len: length of frame data in octets
* @stype: management frame subtype from frame control field
* @ok: Whether the frame was ACK'ed
*/
void ieee802_11_mgmt_cb(struct hostapd_data *hapd, u8 *buf, size_t len,
u16 stype, int ok)
{

View File

@ -10,6 +10,11 @@
* license.
*
* See README and COPYING for more details.
*
* Access control list for IEEE 802.11 authentication can uses statically
* configured ACL from configuration files or an external RADIUS server.
* Results from external RADIUS queries are cached to allow faster
* authentication frame processing.
*/
#include "includes.h"
@ -193,6 +198,17 @@ static int hostapd_radius_acl_query(struct hostapd_data *hapd, const u8 *addr,
}
/**
* hostapd_allowed_address - Check whether a specified STA can be authenticated
* @hapd: hostapd BSS data
* @addr: MAC address of the STA
* @msg: Authentication message
* @len: Length of msg in octets
* @session_timeout: Buffer for returning session timeout (from RADIUS)
* @acct_interim_interval: Buffer for returning account interval (from RADIUS)
* @vlan_id: Buffer for returning VLAN ID
* Returns: HOSTAPD_ACL_ACCEPT, HOSTAPD_ACL_REJECT, or HOSTAPD_ACL_PENDING
*/
int hostapd_allowed_address(struct hostapd_data *hapd, const u8 *addr,
const u8 *msg, size_t len, u32 *session_timeout,
u32 *acct_interim_interval, int *vlan_id)
@ -337,6 +353,11 @@ static void hostapd_acl_expire_queries(struct hostapd_data *hapd, time_t now)
}
/**
* hostapd_acl_expire - ACL cache expiration callback
* @eloop_ctx: struct hostapd_data *
* @timeout_ctx: Not used
*/
static void hostapd_acl_expire(void *eloop_ctx, void *timeout_ctx)
{
struct hostapd_data *hapd = eloop_ctx;
@ -350,8 +371,16 @@ static void hostapd_acl_expire(void *eloop_ctx, void *timeout_ctx)
}
/* Return 0 if RADIUS message was a reply to ACL query (and was processed here)
* or -1 if not. */
/**
* hostapd_acl_recv_radius - Process incoming RADIUS Authentication messages
* @msg: RADIUS response message
* @req: RADIUS request message
* @shared_secret: RADIUS shared secret
* @shared_secret_len: Length of shared_secret in octets
* @data: Context data (struct hostapd_data *)
* Returns: RADIUS_RX_PROCESSED if RADIUS message was a reply to ACL query (and
* was processed here) or RADIUS_RX_UNKNOWN if not.
*/
static RadiusRxResult
hostapd_acl_recv_radius(struct radius_msg *msg, struct radius_msg *req,
u8 *shared_secret, size_t shared_secret_len,
@ -443,6 +472,11 @@ hostapd_acl_recv_radius(struct radius_msg *msg, struct radius_msg *req,
}
/**
* hostapd_acl_init: Initialize IEEE 802.11 ACL
* @hapd: hostapd BSS data
* Returns: 0 on success, -1 on failure
*/
int hostapd_acl_init(struct hostapd_data *hapd)
{
if (radius_client_register(hapd->radius, RADIUS_AUTH,
@ -455,6 +489,10 @@ int hostapd_acl_init(struct hostapd_data *hapd)
}
/**
* hostapd_acl_deinit - Deinitialize IEEE 802.11 ACL
* @hapd: hostapd BSS data
*/
void hostapd_acl_deinit(struct hostapd_data *hapd)
{
struct hostapd_acl_query_data *query, *prev;

View File

@ -647,7 +647,15 @@ static void handle_eap(struct hostapd_data *hapd, struct sta_info *sta,
}
/* Process the EAPOL frames from the Supplicant */
/**
* ieee802_1x_receive - Process the EAPOL frames from the Supplicant
* @hapd: hostapd BSS data
* @sa: Source address (sender of the EAPOL frame)
* @buf: EAPOL frame
* @len: Length of buf in octets
*
* This function is called for each incoming EAPOL frame from the interface
*/
void ieee802_1x_receive(struct hostapd_data *hapd, const u8 *sa, const u8 *buf,
size_t len)
{
@ -796,6 +804,14 @@ void ieee802_1x_receive(struct hostapd_data *hapd, const u8 *sa, const u8 *buf,
}
/**
* ieee802_1x_new_station - Start IEEE 802.1X authentication
* @hapd: hostapd BSS data
* @sta: The station
*
* This function is called to start IEEE 802.1X authentication when a new
* station completes IEEE 802.11 association.
*/
void ieee802_1x_new_station(struct hostapd_data *hapd, struct sta_info *sta)
{
struct rsn_pmksa_cache_entry *pmksa;
@ -1186,7 +1202,15 @@ ieee802_1x_search_radius_identifier(struct hostapd_data *hapd, u8 identifier)
}
/* Process the RADIUS frames from Authentication Server */
/**
* ieee802_1x_receive_auth - Process RADIUS frames from Authentication Server
* @msg: RADIUS response message
* @req: RADIUS request message
* @shared_secret: RADIUS shared secret
* @shared_secret_len: Length of shared_secret in octets
* @data: Context data (struct hostapd_data *)
* Returns: Processing status
*/
static RadiusRxResult
ieee802_1x_receive_auth(struct radius_msg *msg, struct radius_msg *req,
u8 *shared_secret, size_t shared_secret_len,

View File

@ -219,6 +219,14 @@ void hostapd_free_stas(struct hostapd_data *hapd)
}
/**
* ap_handle_timer - Per STA timer handler
* @eloop_ctx: struct hostapd_data *
* @timeout_ctx: struct sta_info *
*
* This function is called to check station activity and to remove inactive
* stations.
*/
void ap_handle_timer(void *eloop_ctx, void *timeout_ctx)
{
struct hostapd_data *hapd = eloop_ctx;

View File

@ -116,6 +116,14 @@ static int ieee802_11_parse_vendor_specific(u8 *pos, size_t elen,
}
/**
* ieee802_11_parse_elems - Parse information elements in management frames
* @start: Pointer to the start of IEs
* @len: Length of IE buffer in octets
* @elems: Data structure for parsed elements
* @show_errors: Whether to show parsing errors in debug log
* Returns: Parsing result
*/
ParseRes ieee802_11_parse_elems(u8 *start, size_t len,
struct ieee802_11_elems *elems,
int show_errors)