summaryrefslogtreecommitdiff
path: root/doc/libwpactrl
diff options
context:
space:
mode:
authorLaurent Bercot <ska-skaware@skarnet.org>2017-08-04 22:46:45 +0000
committerLaurent Bercot <ska-skaware@skarnet.org>2017-08-04 22:46:45 +0000
commitbabf43abf301d072192bda1f72a47440c354b072 (patch)
treed917d33ebb97d2b783e163f299b360be4f5b3a0a /doc/libwpactrl
parent69099d84949a8044fdfc74e9d7ff6b9e57fc0bcd (diff)
downloadbcnm-babf43abf301d072192bda1f72a47440c354b072.tar.xz
Add the higher layer of libwpactrl
Diffstat (limited to 'doc/libwpactrl')
-rw-r--r--doc/libwpactrl/index.html176
1 files changed, 149 insertions, 27 deletions
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.
<h3> Synchronous functions </h3>
<p>
- The bulk of <tt>libwpactrl</tt> functions take two extra arguments at the end, named
-<em>deadline</em> and <em>stamp</em>, of type
+ The bulk of <tt>libwpactrl</tt> functions takes an extra <em>stamp</em> argument
+at the end, of type
<a href="//skarnet.org/software/skalibs/libstddjb/tai.html">tain_t</a>. 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.
</p>
<p>
-<em>deadline</em> 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
-<tt>errno</tt> set to ETIMEDOUT. <em>stamp</em> must be first initialized to an
+<em>stamp</em> must be first initialized to an
accurate enough approximation of the current time, for instance via skalibs'
<tt>tain_now()</tt> 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.
<p>
<a href="//skarnet.org/software/skalibs/">skalibs</a> can keep track of the
timestamp for you, in the global <tt>STAMP</tt> variable. All <tt>libwpactrl</tt>
-functions taking <em>deadline</em> and <em>stamp</em> arguments also have a
-version with a name ending in <tt>_g</tt>, that only takes a <tt>deadline</tt>
-argument, and assumes the <tt>STAMP</tt> variable always contains (an accurate
+functions taking a <em>stamp</em> argument also have a
+version with a name ending in <tt>_g</tt>, that does not take it and instead
+assumes the <tt>STAMP</tt> variable always contains (an accurate
enough approximation of) the current time.
<p>
@@ -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 <tt>wpa_supplicant</tt> 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
+<em>stamp</em> argument, plus a timeout given at <tt>wpactrl_start</tt> time,
+ensures there is a cap on the amount of time they block.
</p>
<h3> Starting and stopping a session </h3>
<p>
-<code> int wpactrl_start (wpactrl_t *a, char const *path, tain_t const *deadline, tain_t *stamp) </code> <br />
+<code> int wpactrl_start (wpactrl_t *a, char const *path, unsigned int timeout, tain_t *stamp) </code> <br />
Starts a session with a <tt>wpa_supplicant</tt> instance listening on a Unix socket
-at <em>path</em>.
+at <em>path</em>. <em>a</em> is a handle that must be initialized to
+WPACTRL_ZERO before the call to <tt>wpactrl_start</tt>, and that must then
+be passed to every <tt>wpactrl_*</tt> call in the session.
The function returns 1 if it succeeds, or 0 (and sets errno) if
-it fails.
+it fails. The <em>timeout</em> 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 <em>timeout</em> milliseconds, the call
+will immediately be aborted.
</p>
<p>
@@ -134,8 +138,8 @@ Ends the session, freeing all used resources.
<h3> Low-level command sending </h3>
<p>
-<code> 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) </code> <br />
-Sends the query <em>q</em> of size <em>qlen</em> to the connected instance
+<code> ssize_t wpactrl_query (wpactrl_t *a, char const *q, char *ans, size_t anslen, tain_t *stamp) </code> <br />
+Sends the query <em>q</em> to the connected instance
of wpa_supplicant, and reads its answer into the buffer pointed to by
<em>ans</em>. 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 <em>anslen</em> bytes.
</p>
<p>
-<code> ssize_t wpactrl_querysa (wpactrl_t *a, char const *q, size_t qlen, stralloc *sa, tain_t const *deadline, tain_t *stamp) </code> <br />
-Sends the query <em>q</em> of size <em>qlen</em> to the connected instance
+<code> ssize_t wpactrl_querysa (wpactrl_t *a, char const *q, stralloc *sa, tain_t *stamp) </code> <br />
+Sends the query <em>q</em> to the connected instance
of wpa_supplicant, and reads its answer into the
<a href="//skarnet.org/software/skalibs/libstddjb/stralloc.html">stralloc</a>
pointed to by <em>sa</em>. Returns 1 if it succeeds and 0 if it fails.
</p>
<p>
-<code> wparesponse_t wpactrl_command (wpactrl_t *a, char const *q, size_t qlen, tain_t const *deadline, tain_t *stamp) </code> <br />
-Sends the command <em>q</em> of size <em>qlen</em> to the connected instance
+<code> wparesponse_t wpactrl_command (wpactrl_t *a, char const *q, tain_t *stamp) </code> <br />
+Sends the command <em>q</em> to the connected instance
of wpa_supplicant, and returns its answer under the form of a
<tt>wparesponse_t</tt>, which is an enumeration defined in the
<tt>bcnm/wpactrl.h</tt> header. This function is meant to be used
with commands returning a well-known value, such as <tt>RECONFIGURE</tt>
(returning <tt>OK</tt> or <tt>FAIL</tt>) or <tt>PING</tt>
-(returning <tt>PONG</tt>).
+(returning <tt>PONG</tt>). The <tt>wparesponse_t</tt> enumeration
+type lists all the possible values for the function's return code.
</p>
-<h3> Reading from the attached connection </h3>
+<h3> Reading from the attached (asynchronous) connection </h3>
<p>
<code> int wpactrl_update (wpactrl_t *a) </code> <br />
@@ -183,7 +188,7 @@ returns NULL.
</p>
<p>
-<code> void wpactrl_nextmsg (wpactrl_t *a) </code> <br />
+<code> void wpactrl_ackmsg (wpactrl_t *a) </code> <br />
Acknowledges reading of one unsolicited message from wpa_supplicant.
The next invocation of <tt>wpactrl_msg()</tt> will point to the next
one.
@@ -207,7 +212,7 @@ Removes <em>prefix</em> from the whitelist.
</p>
<p>
-<code> void wpactrl_filter_activate (wpactrl_t *a) </code>
+<code> void wpactrl_filter_activate (wpactrl_t *a) </code> <br />
Activates the message filter. Unsolicited messages from
wpa_supplicant will be discarded unless they are explicitly
whitelisted by a call to <tt>wpactrl_filter_add()</tt>. This
@@ -215,13 +220,130 @@ is the default.
</p>
<p>
-<code> void wpactrl_filter_deactivate (wpactrl_t *a) </code>
+<code> void wpactrl_filter_deactivate (wpactrl_t *a) </code> <br />
Dectivates the message filter. All the unsolicited messages from
wpa_supplicant will be stored and made available to the
application.
</p>
-<h3> Higher-level commands </h3>
+<p>
+<code> int wpactrl_filter_match (wpactrl_t const *a, char const *s, size_t len) </code> <br />
+Returns 1 if the string <em>s</em> of size <em>len</em> matches one of the
+registered filters, and 0 otherwise.
+</p>
+
+
+<h3> Helper functions for parsing answers from wpa_supplicant </h3>
+
+<p>
+<code> size_t wpactrl_bssid_scan (char const *s, char *bssid) </code> <br />
+Parses a BSSID of the form <em>a:b:c:d:e:f</em> in string <em>s</em>
+and writes it as an array of 6 bytes pointed to by <em>bssid</em>.
+The string "any" is specifically recognized and yields a <em>bssid</em>
+of 6 zero bytes. The function returns the number of characters eaten
+in <em>s</em>, or 0 if it fails to recognize a BSSID.
+</p>
+
+<p>
+<code> size_t wpactrl_flags_scan (char const *s, stralloc *sa) </code> <br />
+Parses a wpa_supplicant "flags" field in the string <em>s</em>
+and appends them to the
+<a href="//skarnet.org/software/skalibs/libstddjb/stralloc.html">stralloc</a>
+pointed to by <em>sa</em>. The flags are written without their
+surrounding square brackets, and every flag is terminated by a null
+byte.
+</p>
+
+<p>
+<code> unsigned int wpactrl_env_parse (char *s, size_t len) </code> <br />
+Replaces newlines with null bytes in the string <em>s</em> of length <em>len</em>.
+Returns the number of replaced newlines.
+</p>
+
+<p>
+<code> int wpactrl_scan_parse (char const *s, size_t len, genalloc *ga, stralloc *storage) </code> <br />
+Parses the string <em>s</em> of length <em>len</em>, expecting it to be
+wpa_supplicant's response to a SCAN_RESULTS command. The result is a series of
+<tt>wpactrl_scanres_t</tt> structures, appended to the
+<a href="//skarnet.org/software/skalibs/libstddjb/genalloc.html">genalloc</a>
+pointed to by <em>ga</em>, and variable length data is appended to the
+<a href="//skarnet.org/software/skalibs/libstddjb/stralloc.html">stralloc</a>
+pointed to by <em>storage</em>.
+ The <tt>ssid_start</tt> and <tt>flags_start</tt> fields of a
+<tt>wpactrl_scanres_t</tt> are indices pointing into the <em>storage&rarr;s</em>
+string.
+</p>
+
+<p>
+<code> int wpactrl_networks_parse (char const *s, size_t len, genalloc *ga, stralloc *storage) </code> <br />
+Parses the string <em>s</em> of length <em>len</em>, expecting it to be
+wpa_supplicant's response to a LIST_NETWORKS command. The result is a series of
+<tt>wpactrl_networks_t</tt> structures, appended to the
+<a href="//skarnet.org/software/skalibs/libstddjb/genalloc.html">genalloc</a>
+pointed to by <em>ga</em>, and variable length data is appended to the
+<a href="//skarnet.org/software/skalibs/libstddjb/stralloc.html">stralloc</a>
+pointed to by <em>storage</em>.
+ The <tt>ssid_start</tt> and <tt>flags_start</tt> fields of a
+<tt>wpactrl_networks_t</tt> are indices pointing into the <em>storage&rarr;s</em>
+string.
+</p>
+
+<h3> High-level functions for common calls to wpa_supplicant </h3>
+
+<p>
+</code> int wpactrl_addnetwork (wpactrl_t *a, uint32_t *id, tain_t *stamp) </code> </br>
+Tells wpa_supplicant to create a new network. If it fails, returns 0. If it
+succeeds, stores the new network id in <em>*id</em> and returns 1.
+</p>
+
+<p>
+</code> wparesponse_t wpactrl_removenetwork (wpactrl_t *a, uint32_t id, tain_t *stamp) </code> </br>
+Tells wpa_supplicant to remove the network with id <em>id</em>. Returns the
+response code of wpa_supplicant: WPA_OK on success, WPA_FAIL or something
+else on failure.
+</p>
+
+<p>
+</code> int wpactrl_findnetwork (wpactrl_t *a, char const *ssid, uint32_t *id, tain_t *stamp) </code> </br>
+Finds the network id (as seen by wpa_supplicant) of the network with ssid <em>ssid</em>.
+Stores it into <em>*id</em> if found, and returns 1. Returns 0 if not found;
+returns -1 (and sets errno) if an error occurs.
+</p>
+
+<p>
+</code> wparesponse_t wpactrl_setnetworkoption (wpactrl_t *a, uint32_t id, char const *var, char const *val, tain_t *stamp) </code> </br>
+Sets parameter <em>var</em> to value <em>val</em> for network <em>id</em>.
+Returns the response code of wpa_supplicant, most likely WPA_OK or WPA_FAIL.
+</p>
+
+<p>
+</code> wparesponse_t wpactrl_selectnetwork (wpactrl_t *a, uint32_t id, tain_t *stamp) </code> </br>
+Selects network <em>id</em> to associate with.
+Returns the response code of wpa_supplicant, most likely WPA_OK or WPA_FAIL.
+</p>
+
+<p>
+</code> int wpactrl_associate (wpactrl_t *, char const *ssid, char const *psk, tain_t *stamp) </code> </br>
+Tells wpa_supplicant to associate with the wifi network having the ssid <em>ssid</em>,
+creating it if it's not already known by wpa_supplicant. If <em>psk</em> is NULL,
+the network will be assumed open and authentication will use a NONE protocol.
+If <em>psk</em> is not NULL, the network authentication will be assumed using
+WPA-PSK or WPA2-PSK, and <em>psk</em> will be sent as pre-shared key.
+The function returns 1 on success, or 0 if something went wrong.
+</p>
+
+<h3> Medium-level functions to use with an asynchronous event loop </h3>
+
+<p>
+ The following functions can be used when performing calls to wpa_supplicant
+such as <tt>SCAN</tt> that answer with an asynchronous message on the "attached"
+interface.
+</p>
+
+<p>
+</code> int wpactrl_xchg_init (wpactrl_xchg_t *dt, wpactrl_xchgitem_t const *tab, unsigned int n, tain_t const *limit, void *aux) </code> </br>
+Initializes.
+</p>
</body>
</html>