How to use the client API while following the example code

References to functions in client-api-example.c are in square brackets. See Client API for a summary of the available API.

A client starts by calling wth_connect_to_server() to create a wth_connection [main]. Alternatively, it is also possible to create the TCP connection by other means and pass the socket file descriptor to wth_connection_from_fd() with WTH_CONNECTION_SIDE_CLIENT.

The file descriptor of a new wth_connection needs to be polled for events [main]. Use wth_connection_get_fd() to fetch the connection file descriptor and add it in your poll set for POLLIN. (The example also fetches the wth_display for the connection and sets the implementation, but this should be done by Waltham under the hood.)

The wth_connection file descriptor must be serviced as follows [connection_handle_data]:

POLLERR and POLLHUP: the connection has died and resources need to be cleaned up.

POLLOUT: The client explicitly polled for POLLOUT because an earlier call to wth_connection_flush() returned with failure EAGAIN. Now call wth_connection_flush() again. If it succeeds, stop polling for POLLOUT. If it fails with EAGAIN, continue polling for POLLOUT.

POLLIN: The client must read incoming data into a buffer in wth_connection by calling wth_connection_read(). Once the client is ready to process the read messages, it must call wth_connection_dispatch() [mainloop].

Requests sent to a server are not guaranteed to be sent out to the network automatically, the client needs to call wth_connection_flush() explicitly [mainloop], preferably just before sleeping on poll.

Protocol-wise, the first thing to do is to create a wthp_registry [main]. Once the server processes the creation, it will send events for each global interface it supports. An easy way to guarantee that the client has seen all such advertisements is to call wth_connection_roundtrip(). Often binding to the global interfaces happens already in the wthp_registry event handler [registry_handle_global]. Eventually the client enters its main loop [main, mainloop].

If the client causes an error in the server, the server will send an error event. This sets the wth_connection into an error state [not_here_error] and no more events will be dispatched. Instead, wth_connection_dispatch() will fail with EPROTO. The client should clean up and call wth_connection_destroy() to tear down the connection.

The client is reponsible for cleaning up all the resources. Even though wth_connection keeps track of protocol object IDs and wth_object instances, it does not automatically free them.