diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/libwpactrl/index.html | 176 |
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→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→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> |