Common API for both server and client

Data Structures
class	wth_connection
	A Waltham connection. More...
class	wth_object
	A generic Waltham protocol object representation (a proxy) More...

Functions
struct wth_connection *	wth_connection::wth_connection_from_fd (int fd, enum wth_connection_side side)
	Use an already connected socket. More...
int	wth_connection::wth_connection_get_fd (struct wth_connection *conn)
	Get connection file descriptor. More...
void	wth_connection::wth_connection_destroy (struct wth_connection *conn)
	Disconnect. More...
int	wth_connection::wth_connection_flush (struct wth_connection *conn)
	Flush buffered messages to the network. More...
int	wth_connection::wth_connection_read (struct wth_connection *conn)
	Read data received from the network. More...
int	wth_connection::wth_connection_dispatch (struct wth_connection *conn)
	Dispatch incoming messages. More...
int	wth_connection::wth_connection_get_error (struct wth_connection *conn)
	Return the connection error state. More...
uint32_t	wth_connection::wth_connection_get_protocol_error (struct wth_connection *conn, const char **interface, uint32_t *object_id)
	Return protocol error details. More...
void	wth_object::wth_object_delete (struct wth_object *object)
	Destroy a protocol object. More...
void	wth_object::wth_object_set_listener (struct wth_object *obj, void(**listener)(void), void *user_data)
	Set incoming message handlers for a protocol object. More...
void *	wth_object::wth_object_get_user_data (struct wth_object *obj)
	Set incoming message handlers for a protocol object. More...

Detailed Description

Function Documentation

wth_connection_destroy()

void wth_connection_destroy

(

struct wth_connection *

conn

)

Disconnect.

Parameters

conn	The Waltham connection.

Disconnects if still connected, and destroys the wth_connection. The wth_display gets destroyed too.

This call does not block. Messages still en route may get discarded.

wth_connection_dispatch()

int wth_connection_dispatch

(

struct wth_connection *

conn

)

Dispatch incoming messages.

Parameters

conn	The Waltham connection.

Returns

The number of dispatched messages, or -1 on error.

This function calls the message handlers (listeners, interface callbacks) for buffered messages. The messages must have been buffered by an earlier call to wth_connection_read() as no reading from the network is attempted.

On error, errno is set. For nothing to dispatch, 0 is returned.

In case the connection is set to protocol error state during this call or earlier, this function will return -1 and set errno to EPROTO. No further messages will be dispatched once the protocol error state has been set.

Servers should keep the connection open regardless of EPROTO errors to ensure the error event gets delivered to the client.

wth_connection_flush()

int wth_connection_flush

(

struct wth_connection *

conn

)

Flush buffered messages to the network.

Parameters

conn	The Waltham connection.

Returns

The number of bytes written to network, or -1 on failure.

Attempts to send all buffered messages to the network. It writes as much data as possible without blocking. If any data remains unsent, -1 is returned and errno is set to EAGAIN. In case of EAGAIN, poll for writable and flush again.

This call does not block. On failure, errno is set.

This function does not indicate if the connection has been set as failed due to a protocol error. This behaviour allows the server to continue flushing events out so that the protocol error event will reach the client.

wth_connection_from_fd()

struct wth_connection * wth_connection_from_fd	(	int	fd,
		enum wth_connection_side	side
	)

Use an already connected socket.

Parameters

fd	A network TCP socket fd of an existing connection.
side	Defines whether the local side is a server or a client.

Returns

A new wth_connection, or NULL on failure.

This function is used to wrap an already connected file descriptor in a wth_connection. The wth_connection will own a duplicate of the fd, not the fd passed in. The user must close its fd after calling this.

XXX: You could probably use this as an internal helper too, for the common things of wth_connect_to_server() and wth_accept(). But this is completely optional otherwise.

wth_connection_get_error()

int wth_connection_get_error

(

struct wth_connection *

conn

)

Return the connection error state.

Parameters

conn	The Waltham connection.

Returns

The error code from the 'errno' set, or zero for no error.

If the returned code is EPROTO, wth_connection_get_protocol_error() can be used to get the protocol error details.

wth_connection_get_fd()

int wth_connection_get_fd

(

struct wth_connection *

conn

)

Get connection file descriptor.

Parameters

conn	The Waltham connection.

Returns

The file descriptor associated with the connection.

The returned fd can be used for polling for readable and writable, so that wth_connection_read() and wth_connection_flush() can be called at the needed times.

The fd will remain owned by the wth_connection.

wth_connection_get_protocol_error()

uint32_t wth_connection_get_protocol_error	(	struct wth_connection *	conn,
		const char **	interface,
		uint32_t *	object_id
	)

Return protocol error details.

Parameters

conn	The Waltham connection.
interface	Return pointer to the interface name.
object_id	Return the object ID.

Returns

The interface specific error code.

The returned interface name and object ID are for the object that was referenced when the server sent the error event. The returned error code is specific to that interface, and zero does not mean "no error".

See also

wth_connection_get_error()

wth_connection_read()

int wth_connection_read

(

struct wth_connection *

conn

)

Read data received from the network.

Parameters

conn	The Waltham connection.

Returns

0 on success, -1 on failure with errno set.

Reads as much data as available on the network socket into internal buffers. To actually dispatch incoming messages, use wth_connection_dispatch() after reading.

This call does not block. If no data is available, the call returns immediately with success.

The connection being in protocol error state does not cause this function to return error, but it does cause all read data to be discarded.

wth_object_delete()

void wth_object_delete

(

struct wth_object *

object

)

Destroy a protocol object.

Parameters

object

The protocol object cast from a specific interface type.

The wth_object is destroyed and its object ID is no longer valid.

This function is usually called by the wrapper functions created by the code generator. You should not need to call this manually.

wth_object_get_user_data()

void * wth_object_get_user_data

(

struct wth_object *

obj

)

Set incoming message handlers for a protocol object.

Parameters

obj	The protocol object cast from a specific interface type.

Returns the user data pointer set by wth_object_set_listener().

This function is usually called by the wrapper functions created by the code generator. You should not need to call this manually.

wth_object_set_listener()

void wth_object_set_listener	(	struct wth_object *	obj,
		void(**)(void)	listener,
		void *	user_data
	)

Set incoming message handlers for a protocol object.

Parameters

obj	The protocol object cast from a specific interface type.
listener	An array of function pointers, cast from a virtual function table (a struct created by the code generator).
user_data	Arbitrary pointer to store with the wth_object.

After this call, wth_connection_dispatch() will call the given function pointers for incoming messages for this particular protocol object instance.

The user data pointer can be retrieved with wth_object_get_user_data().

This function is usually called by the wrapper functions created by the code generator. You should not need to call this manually.

Note

Server and client side objects use a different set of function pointers.