From 330f54ac7f780872223f9cac62347393ffb4ef86 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Thu, 6 Jul 2017 21:42:01 +0000 Subject: Initial commit --- doc/libwpactrl/index.html | 233 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 233 insertions(+) create mode 100644 doc/libwpactrl/index.html (limited to 'doc/libwpactrl/index.html') diff --git a/doc/libwpactrl/index.html b/doc/libwpactrl/index.html new file mode 100644 index 0000000..845cc7b --- /dev/null +++ b/doc/libwpactrl/index.html @@ -0,0 +1,233 @@ + + + + + + bcnm: the wpactrl library interface + + + + + +

+bcn,
+Software
+skarnet.org +

+ +

The wpactrl library interface

+ +

+wpactrl is a library designed to interface a client +with the wpa_supplicant +program, in a smaller, cleaner, more user-friendly and more +packager-friendly way than the wpa_ctrl interface that +comes with the wpa_supplicant +distribution. +

+ +

Compiling

+ + + +

Linking

+ + + + +

Programming

+ +

+ The bcnm/wpactrl.h header is the reference for the exact +function prototypes. +

+ +

General usage

+ +

+ libwpactrl stores its information in a wpactrl_t structure. +Such a structure must be allocated (can be declared in the stack) and +initialized to WPACTRL_ZERO before use. The address of that wpactrl_t +structure is then used as a handle and given as an argument to all the +wpactrl_* function calls. +

+ +

Connections

+ +

+ A wpactrl_t instance represents two connections to a wpa_supplicant +program: an attached one and a detached one. For proper operation, +it is important to regularly read the data from the attached connection. This is +achieved by calling the wpactrl_update() function whenever data is available +on the attached connection; this is notified by the connection's fd becoming +readable. The attached connection's fd can be obtained via the wpactrl_fd() +function. So, proper usage of a wpactrl_t instance involves an asynchronous +event loop. +

+ +

Synchronous functions

+ +

+ The bulk of libwpactrl functions take two extra arguments at the end, named +deadline and stamp, of type +tain_t. This means +they are synchronous function calls, and the extra arguments are 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 +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 +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 +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. +

+ + +

Starting and stopping a session

+ +

+ int wpactrl_start (wpactrl_t *a, char const *path, tain_t const *deadline, tain_t *stamp)
+Starts a session with a wpa_supplicant instance listening on a Unix socket +at path. +The function returns 1 if it succeeds, or 0 (and sets errno) if +it fails. +

+ +

+ int wpactrl_end (wpactrl_t *a)
+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 +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 +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 +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 +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). +

+ +

Reading from the attached connection

+ +

+ int wpactrl_update (wpactrl_t *a)
+Reads unsolicited messages from wpa_supplicant. If the messages +are whitelisted, it keeps them, otherwise it discards them. +The function returns the number of messages that have been read, +or -1 in case of failure. A positive number does not mean that +all pending messages have been read: there is a cap on the +number of messages that can be consecutively read, to prevent +a spamming wpa_supplicant from monopolizing your program. +

+ +

+ char *wpactrl_data (wpactrl_t *a)
+Returns a pointer to the unsolicited messages from wpa_supplicant +that have been read by wpactrl_update() but haven't been +acknowledged yet. +

+ +

+ char *wpactrl_datalen (wpactrl_t *a)
+Returns the length of unsolicited messages from wpa_supplicant +that have been read by wpactrl_update() but haven't been +acknowledged yet. +

+ +

+ void wpactrl_ackdata (wpactrl_t *a) +Acknowledges reading the latest batch of unsolicited messages +from wpa_supplicant: allows the next invocation of +wpactrl_update() to reuse the storage. +

+ +

+ int wpactrl_filter_add (wpactrl_t *a, char const *prefix)
+Adds prefix to the whitelist. Unsolicited messages from +wpa_supplicant will be stored and made available to the application +if they start with %lt;priority>prefix, +priority being a single nonzero digit. If the filter is +activated (which is the default), then only messages matching prefixes +registered via wpactrl_filter_add() will be stored, and all +other messages will be discarded. The function returns +1 if it succeeds and 0 if it fails. +

+ +

+ void wpactrl_filter_remove (wpactrl_t *a, char const *prefix)
+Removes prefix from the whitelist. +

+ +

+ 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 +is the default. +

+ +

+ 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

+ + + -- cgit v1.2.3