From babf43abf301d072192bda1f72a47440c354b072 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Fri, 4 Aug 2017 22:46:45 +0000 Subject: Add the higher layer of libwpactrl --- doc/libwpactrl/index.html | 176 +++++++++++++++++++++++++++++++++++++++------- 1 file changed, 149 insertions(+), 27 deletions(-) (limited to 'doc/libwpactrl') diff --git a/doc/libwpactrl/index.html b/doc/libwpactrl/index.html index 1115787..72ee538 100644 --- a/doc/libwpactrl/index.html +++ b/doc/libwpactrl/index.html @@ -80,17 +80,15 @@ event loop.

Synchronous functions

- The bulk of libwpactrl functions take two extra arguments at the end, named -deadline and stamp, of type + The bulk of libwpactrl functions takes an extra stamp argument +at the end, of type tain_t. This means -they are synchronous function calls, and the extra arguments are there to ensure +they are synchronous function calls, and the extra argument is there to ensure those calls do not block forever.

-deadline is an absolute date: if the function has not returned when this -date is reached, it will immediately return with a code meaning "failure" and -errno set to ETIMEDOUT. stamp must be first initialized to an +stamp must be first initialized to an accurate enough approximation of the current time, for instance via skalibs' tain_now() function; it will then be automatically updated by the libwpactrl function calls to always contain (an accurate enough approximation @@ -100,9 +98,9 @@ of) the current time.

skalibs can keep track of the timestamp for you, in the global STAMP variable. All libwpactrl -functions taking deadline and stamp arguments also have a -version with a name ending in _g, that only takes a deadline -argument, and assumes the STAMP variable always contains (an accurate +functions taking a stamp argument also have a +version with a name ending in _g, that does not take it and instead +assumes the STAMP variable always contains (an accurate enough approximation of) the current time.

@@ -110,20 +108,26 @@ enough approximation of) the current time. Those synchronous function calls normally return almost instantly: there should be no blocking code path between the function call and its return. Nevertheless, since they involve communication with a complex wpa_supplicant process, -it's impossible to guarantee that they will never block, so the deadline pattern -is there to set a cap on the amount of time they block. A deadline set a few -seconds into the future should be enough. +it's impossible to guarantee that they will never block, so the use of the +stamp argument, plus a timeout given at wpactrl_start time, +ensures there is a cap on the amount of time they block.

Starting and stopping a session

- int wpactrl_start (wpactrl_t *a, char const *path, tain_t const *deadline, tain_t *stamp)
+ int wpactrl_start (wpactrl_t *a, char const *path, unsigned int timeout, tain_t *stamp)
Starts a session with a wpa_supplicant instance listening on a Unix socket -at path. +at path. a is a handle that must be initialized to +WPACTRL_ZERO before the call to wpactrl_start, and that must then +be passed to every wpactrl_* call in the session. The function returns 1 if it succeeds, or 0 (and sets errno) if -it fails. +it fails. The timeout argument is interpreted as milliseconds: +it sets the number of milliseconds for which every subsequent synchronous call +to wpa_supplicant in the current session will be willing to wait. If a call +to wpa_supplicant takes longer than timeout milliseconds, the call +will immediately be aborted.

@@ -134,8 +138,8 @@ Ends the session, freeing all used resources.

Low-level command sending

- ssize_t wpactrl_query (wpactrl_t *a, char const *q, size_t qlen, char *ans, size_t anslen, tain_t const *deadline, tain_t *stamp)
-Sends the query q of size qlen to the connected instance + ssize_t wpactrl_query (wpactrl_t *a, char const *q, char *ans, size_t anslen, tain_t *stamp)
+Sends the query q to the connected instance of wpa_supplicant, and reads its answer into the buffer pointed to by ans. Returns -1 in case of failure, or the number of bytes of the answer in case of success. Returns -1 with errno set to EMSGSIZE if @@ -143,25 +147,26 @@ the answer is bigger than anslen bytes.

- ssize_t wpactrl_querysa (wpactrl_t *a, char const *q, size_t qlen, stralloc *sa, tain_t const *deadline, tain_t *stamp)
-Sends the query q of size qlen to the connected instance + ssize_t wpactrl_querysa (wpactrl_t *a, char const *q, stralloc *sa, tain_t *stamp)
+Sends the query q to the connected instance of wpa_supplicant, and reads its answer into the stralloc pointed to by sa. Returns 1 if it succeeds and 0 if it fails.

- wparesponse_t wpactrl_command (wpactrl_t *a, char const *q, size_t qlen, tain_t const *deadline, tain_t *stamp)
-Sends the command q of size qlen to the connected instance + wparesponse_t wpactrl_command (wpactrl_t *a, char const *q, tain_t *stamp)
+Sends the command q to the connected instance of wpa_supplicant, and returns its answer under the form of a wparesponse_t, which is an enumeration defined in the bcnm/wpactrl.h header. This function is meant to be used with commands returning a well-known value, such as RECONFIGURE (returning OK or FAIL) or PING -(returning PONG). +(returning PONG). The wparesponse_t enumeration +type lists all the possible values for the function's return code.

-

Reading from the attached connection

+

Reading from the attached (asynchronous) connection

int wpactrl_update (wpactrl_t *a)
@@ -183,7 +188,7 @@ returns NULL.

- void wpactrl_nextmsg (wpactrl_t *a)
+ void wpactrl_ackmsg (wpactrl_t *a)
Acknowledges reading of one unsolicited message from wpa_supplicant. The next invocation of wpactrl_msg() will point to the next one. @@ -207,7 +212,7 @@ Removes prefix from the whitelist.

- void wpactrl_filter_activate (wpactrl_t *a) + void wpactrl_filter_activate (wpactrl_t *a)
Activates the message filter. Unsolicited messages from wpa_supplicant will be discarded unless they are explicitly whitelisted by a call to wpactrl_filter_add(). This @@ -215,13 +220,130 @@ is the default.

- void wpactrl_filter_deactivate (wpactrl_t *a) + void wpactrl_filter_deactivate (wpactrl_t *a)
Dectivates the message filter. All the unsolicited messages from wpa_supplicant will be stored and made available to the application.

-

Higher-level commands

+

+ int wpactrl_filter_match (wpactrl_t const *a, char const *s, size_t len)
+Returns 1 if the string s of size len matches one of the +registered filters, and 0 otherwise. +

+ + +

Helper functions for parsing answers from wpa_supplicant

+ +

+ size_t wpactrl_bssid_scan (char const *s, char *bssid)
+Parses a BSSID of the form a:b:c:d:e:f in string s +and writes it as an array of 6 bytes pointed to by bssid. +The string "any" is specifically recognized and yields a bssid +of 6 zero bytes. The function returns the number of characters eaten +in s, or 0 if it fails to recognize a BSSID. +

+ +

+ size_t wpactrl_flags_scan (char const *s, stralloc *sa)
+Parses a wpa_supplicant "flags" field in the string s +and appends them to the +stralloc +pointed to by sa. The flags are written without their +surrounding square brackets, and every flag is terminated by a null +byte. +

+ +

+ unsigned int wpactrl_env_parse (char *s, size_t len)
+Replaces newlines with null bytes in the string s of length len. +Returns the number of replaced newlines. +

+ +

+ int wpactrl_scan_parse (char const *s, size_t len, genalloc *ga, stralloc *storage)
+Parses the string s of length len, expecting it to be +wpa_supplicant's response to a SCAN_RESULTS command. The result is a series of +wpactrl_scanres_t structures, appended to the +genalloc +pointed to by ga, and variable length data is appended to the +stralloc +pointed to by storage. + The ssid_start and flags_start fields of a +wpactrl_scanres_t are indices pointing into the storage→s +string. +

+ +

+ int wpactrl_networks_parse (char const *s, size_t len, genalloc *ga, stralloc *storage)
+Parses the string s of length len, expecting it to be +wpa_supplicant's response to a LIST_NETWORKS command. The result is a series of +wpactrl_networks_t structures, appended to the +genalloc +pointed to by ga, and variable length data is appended to the +stralloc +pointed to by storage. + The ssid_start and flags_start fields of a +wpactrl_networks_t are indices pointing into the storage→s +string. +

+ +

High-level functions for common calls to wpa_supplicant

+ +

+ 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)
+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)
+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)
+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)
+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)
+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. +If psk is not NULL, the network authentication will be assumed using +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

+ +

+ 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_init (wpactrl_xchg_t *dt, wpactrl_xchgitem_t const *tab, unsigned int n, tain_t const *limit, void *aux)
+Initializes. +

-- cgit v1.2.3