From 5445a1d653cddb7b9321c87aec6b025c7627fe1d Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Thu, 10 Aug 2017 20:51:40 +0000 Subject: Complete first draft of libwpactrl, with documentation --- doc/libwpactrl/index.html | 153 ++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 140 insertions(+), 13 deletions(-) (limited to 'doc') diff --git a/doc/libwpactrl/index.html b/doc/libwpactrl/index.html index 72ee538..e5823da 100644 --- a/doc/libwpactrl/index.html +++ b/doc/libwpactrl/index.html @@ -288,42 +288,47 @@ pointed to by storage. string.

-

High-level functions for common calls to wpa_supplicant

+

+ void wpactrl_xchg_cbres_free (wpactrl_xchg_cbres_t *res)
+Frees the heap memory used by the object pointed to by res. +

+ +

User functions for common calls to wpa_supplicant

- int wpactrl_addnetwork (wpactrl_t *a, uint32_t *id, tain_t *stamp)
+ int wpactrl_addnetwork (wpactrl_t *a, uint32_t *id, tain_t *stamp)
Tells wpa_supplicant to create a new network. If it fails, returns 0. If it succeeds, stores the new network id in *id and returns 1.

- wparesponse_t wpactrl_removenetwork (wpactrl_t *a, uint32_t id, tain_t *stamp)
+ wparesponse_t wpactrl_removenetwork (wpactrl_t *a, uint32_t id, tain_t *stamp)
Tells wpa_supplicant to remove the network with id id. Returns the response code of wpa_supplicant: WPA_OK on success, WPA_FAIL or something else on failure.

- int wpactrl_findnetwork (wpactrl_t *a, char const *ssid, uint32_t *id, tain_t *stamp)
+ int wpactrl_findnetwork (wpactrl_t *a, char const *ssid, uint32_t *id, tain_t *stamp)
Finds the network id (as seen by wpa_supplicant) of the network with ssid ssid. Stores it into *id if found, and returns 1. Returns 0 if not found; returns -1 (and sets errno) if an error occurs.

- wparesponse_t wpactrl_setnetworkoption (wpactrl_t *a, uint32_t id, char const *var, char const *val, tain_t *stamp)
+ wparesponse_t wpactrl_setnetworkoption (wpactrl_t *a, uint32_t id, char const *var, char const *val, tain_t *stamp)
Sets parameter var to value val for network id. Returns the response code of wpa_supplicant, most likely WPA_OK or WPA_FAIL.

- wparesponse_t wpactrl_selectnetwork (wpactrl_t *a, uint32_t id, tain_t *stamp)
+ wparesponse_t wpactrl_selectnetwork (wpactrl_t *a, uint32_t id, tain_t *stamp)
Selects network id to associate with. Returns the response code of wpa_supplicant, most likely WPA_OK or WPA_FAIL.

- int wpactrl_associate (wpactrl_t *, char const *ssid, char const *psk, tain_t *stamp)
+ int wpactrl_associate (wpactrl_t *, char const *ssid, char const *psk, tain_t *stamp)
Tells wpa_supplicant to associate with the wifi network having the ssid ssid, creating it if it's not already known by wpa_supplicant. If psk is NULL, the network will be assumed open and authentication will use a NONE protocol. @@ -332,18 +337,140 @@ WPA-PSK or WPA2-PSK, and psk will be sent as pre-shared key. The function returns 1 on success, or 0 if something went wrong.

-

Medium-level functions to use with an asynchronous event loop

+

+ int wpactrl_startscan (wpactrl_t *a, wpactrl_xchgitem_t *item, wpactrl_xchg_cbres_t *res, tain_t const *limit, tain_t *stamp)
+Asks wpa_supplicant to start a scan. Sets up the wpactrl_xchgitem_t +structure pointed to by item so it can be used in an asynchronous +event loop to check for availability of the scan results (see below). +limit is an absolute deadline after which the scan should be +considered failed: if the current time goes over limit, then +wpactrl_xchg_timeout() will report a timeout on item. +But if wpactrl_xchg_event() reports that an event occurs on +item, instead, the results will be available in the +wpactrl_xchg_cbres_t structure pointed to by res: +res&arr;parsed will be a +genalloc +made of wpactrl_scanres_t objects, constructed by the +wpactrl_scan_parse() function, and res&arr;storage will +be the associated storage. +wpactrl_startscan() returns 0 (and sets errno) if an error +occurs, and 1 if the scan is properly started. +

+ +

Functions to use within an asynchronous event loop

+ +

+ int wpactrl_xchg_init (wpactrl_xchg_t *dt, wpactrl_xchgitem_t const *tab, unsigned int tablen, tain_t const *limit, void *aux)
+Initializes the wpactrl_xchg_t structure pointed to by dt. +Returns 0 on failure and 1 on success. +

+ +

+A wpactrl_xchg_t contains the state for an asynchronous call to +wpa_supplicant (i.e. a command has been sent and we're now waiting on +reception of an event on the attached interface). It is initialized with +the tab, n and aux values. +

+ +

+aux is a user-provided pointer used to pass external data +to the function callbacks defined in tab. +

+ +

+tab points to tablen caller-provided objects of type wpactrl_xchgitem_t. +This type is a struct containing the following members: +

+ + + +

+The *cb function must return 0 (and set errno) if it fails, or a +positive integer if it succeeds. The objects in tab will be used +sequentially: first a message with dt→tab[0].filter will +be waited for, then *dt→tab[0].cb will be run; if it +succeeds, a message with dt→tab[1].filter will be waited for, +and so on. The last function, *dt→tab[tablen-1].cb, should +write the final result of the whole to a place accessible by the +user; this is one of the uses for the aux pointer. +

+ +

+limit is a deadline: an absolute date after which the whole series of +exchanges with wpa_supplicant will stop and be considered failed, i.e. +iopause +will report a timeout and wpactrl_xchg_timeout() called on +dt will return 1. +

+ +

+ int wpactrl_xchg_start (wpactrl_t *a, wpactrl_xchg_t *dt)
+Starts the exchange defined in the object pointed to by dt, with the +wpa_supplicant instance defined by the handle a. Returns 1 if it +succeeds and 0 if it fails. +

+ +

+ void wpactrl_xchg_computedeadline (wpactrl_xchg_t const *dt, tain_t *deadline)
+Updates the deadline pointed to by deadline, destined to be used in the next +iopause invocation, +with the one contained in *dt. Namely: if the deadline defined by *dt +is earlier than *deadline, replaces the latter with the former. +

+ +

+ int wpactrl_xchg_timeout (wpactrl_t *a, wpactrl_xchg_t *dt, tain_t const *stamp)
+To be called after an iopause invocation that returned 0. +Tests whether the exchange +defined by dt has timed out. Returns 1 (and cleans up the relevant +filters in a if it is the case, and 0 otherwise. stamp must +point to the current time. +

- The following functions can be used when performing calls to wpa_supplicant -such as SCAN that answer with an asynchronous message on the "attached" -interface. + int wpactrl_xchg_event (wpactrl_t *a, wpactrl_xchg_t *dt, tain_t *stamp)
+To be called after an iopause invocation that returned a positive number, and +after a wpactrl_update(a) invocation. +Advances the exchange described in *dt, if applicable: if a message arrived +that matches the current filter set up by *dt, executes the corresponding +callback, then sets up the next filter. stamp must point to the current +time.

- int wpactrl_xchg_init (wpactrl_xchg_t *dt, wpactrl_xchgitem_t const *tab, unsigned int n, tain_t const *limit, void *aux)
-Initializes. + The function returns a negative number if an error occurred and the exchange needs +to be cancelled and freed; 0 if the exchange isn't over yet; and a positive number +if the exchange completed successfully. Namely:

+ + -- cgit 1.4.1