A Waltham connection. More...

#include <waltham-connection.h>

Public Types
typedef void(*	wth_registry_callback_func) (struct wthp_registry registry, void user_data)
	Prototype of the callback to be called whenever a client creates a registry. More...

Public Member Functions
struct wth_connection *	wth_connect_to_server (const char host, const char port)
	Connect to a remote Waltham server. More...

struct wth_connection *	wth_accept (int sockfd, struct sockaddr addr, socklen_t addrlen)
	Accept a Waltham client connection. More...

struct wth_connection *	wth_connection_from_fd (int fd, enum wth_connection_side side)
	Use an already connected socket. More...

int	wth_connection_get_fd (struct wth_connection *conn)
	Get connection file descriptor. More...

void	wth_connection_destroy (struct wth_connection *conn)
	Disconnect. More...

int	wth_connection_flush (struct wth_connection *conn)
	Flush buffered messages to the network. More...

int	wth_connection_read (struct wth_connection *conn)
	Read data received from the network. More...

int	wth_connection_dispatch (struct wth_connection *conn)
	Dispatch incoming messages. More...

int	wth_connection_roundtrip (struct wth_connection *conn)
	Make a roundtrip from a client. More...

int	wth_connection_get_error (struct wth_connection *conn)
	Return the connection error state. More...

uint32_t	wth_connection_get_protocol_error (struct wth_connection conn, const char interface, uint32_t object_id)
	Return protocol error details. More...

struct wthp_registry *	wth_connection_create_registry (struct wth_connection *conn)
	Creates a new registry using the internal wth_display. More...

struct wthp_callback *	wth_connection_sync (struct wth_connection *conn)
	Return a callback using the internal wth_display. More...

void	wth_connection_set_registry_callback (struct wth_connection conn, wth_registry_callback_func registry_callback, void user_data)
	Set the callback to be called once a client creates a registry. More...

void	wth_connection_post_error_no_memory (struct wth_connection *conn)
	Post an out of memory display error. More...

Detailed Description

A Waltham connection.

This represents the TCP connection carrying Waltham messages.

A Waltham client creates a wth_connection with wth_connect_to_server(). A Waltham server creates a wth_connection with wth_accept().

You set up polling with the help of wth_connection_get_fd(). When the fd becomes readable, you call wth_connection_read() followed by wth_connection_dispatch().

After you have sent protocol messages, wth_connection_flush() must be called to flush the messages to the network before you wait for incoming messages.

A server should not destroy a wth_connection before the client has closed it, so that the TCP TIME_WAIT state is left on the client system. In case of a protocol error, the server should call wth_object_post_error() and wait for the client to disconnect.

A client should do one final roundtrip before destroying a wth_connection to ensure that all sent events have reached the server.

Once the connection goes into error state due to remote timeout, disconnect, Waltham protocol error, or any other reason, the various functions will start returning appropriate errors as described in each of them.

When the connection is specifically in protocol error state:

reading will discard all incoming data
dispatching will discard all pending messages and not dispatch
sending messages still works
flush still works The protocol error state is only returned from wth_connection_dispatch(), other functions will silently succeed unless there are further errors.

Examples:: client-api-example.c, and server-api-example.c.

The documentation for this class was generated from the following file:

waltham-connection.h

Public Types

Public Member Functions

Detailed Description