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.
The bcnm/wpactrl.h header is the reference for the exact function prototypes.
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.
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.
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.
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.
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).
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 <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.