Client API

Common and exclusive API for clients. More...

Modules
	Common API for both server and client

Functions
struct wth_connection *	wth_connection::wth_connect_to_server (const char *host, const char *port)
	Connect to a remote Waltham server. More...
int	wth_connection::wth_connection_roundtrip (struct wth_connection *conn)
	Make a roundtrip from a client. More...
struct wthp_registry *	wth_connection::wth_connection_create_registry (struct wth_connection *conn)
	Creates a new registry using the internal wth_display. More...
struct wthp_callback *	wth_connection::wth_connection_sync (struct wth_connection *conn)
	Return a callback using the internal wth_display. More...

Detailed Description

Common and exclusive API for clients.

These functions are exclusive to a client. They will abort the program if called in the context of a server-side wth_connection. For the common functions, see Common API for both server and client.

Function Documentation

wth_connect_to_server()

struct wth_connection * wth_connect_to_server	(	const char *	host,
		const char *	port
	)

Connect to a remote Waltham server.

Parameters

host	The address of the server.
port	The port of the server.

Returns

A new connection, or NULL on failure.

This creates a client-side wth_connection, making a connection to a remote Waltham server.

On failure, errno is set.

XXX: This call may block. We should find a way to make this a non-blocking operation, so that if the connection fails to form, we get an error back from read and flush etc.

wth_connection_create_registry()

struct wthp_registry * wth_connection_create_registry

(

struct wth_connection *

conn

)

Creates a new registry using the internal wth_display.

Parameters

conn	The Waltham connection.

Returns

A new registry object.

The returned registry can then be used to retrieve other global objects, using its usual interface.

wth_connection_roundtrip()

int wth_connection_roundtrip

(

struct wth_connection *

conn

)

Make a roundtrip from a client.

Parameters

conn	The Waltham connection.

Returns

0 on success, -1 on failure.

This is a helper for creating a wthp_callback object by sending wth_display.sync request, and waiting for the callback to trigger. As such, it is only usable for clients.

This call blocks indefinitely until the roundtrip completes or the connection fails. It will flush outgoing and dispatch incoming messages until it returns.

On failure, use wth_connection_get_error() to inspect the error.

If blocking indefinitely is not desireable or you want to be able to process other file descriptors in the mean time, you have to write your own roundtrip implementation using the public API.

wth_connection_sync()

struct wthp_callback * wth_connection_sync

(

struct wth_connection *

conn

)

Return a callback using the internal wth_display.

Parameters

conn	The Waltham connection.

Returns

A new callback object.

The returned callback will emit a 'done' event once the server has seen all preceding requests.