Asynchronous Interface (libevent-based)

Typedefs
typedef int(*	afdt_request_handler_t )(const uint8_t *request, uint32_t request_length, uint8_t *response, uint32_t *response_length, void *userdata)
	Callback type for processing an AFDT request. More...
typedef void(*	afdt_response_handler_t )(const uint8_t *response, uint32_t response_length, int received_fd, void *userdata)
	Callback type for processing an AFDT response. More...
typedef void(*	afdt_post_handler_t )(const uint8_t *request, uint32_t request_length, const uint8_t *response, uint32_t response_length, int sent_fd, void *userdata)
	Callback type for after a response is sent. More...
typedef void(*	afdt_error_handler_t )(const struct afdt_error_t *err, void *userdata)
	Callback type for processing errors during AFDT operations. More...

Functions
void	afdt_no_post (const uint8_t *request, uint32_t request_length, const uint8_t *response, uint32_t response_length, int sent_fd, void *userdata)
	No-op function that can be used as a post_handler.
int	afdt_create_server (const char *fname, struct event_base *eb, afdt_request_handler_t request_handler, afdt_post_handler_t post_handler, afdt_error_handler_t error_handler, void **out_close_handle, void *userdata)
	Create a server to make file descriptors available. More...
int	afdt_close_server (void *close_handle)
	Shut down a server created by afdt_create_server. More...
int	afdt_create_client (const char *fname, struct event_base *eb, const uint8_t *request, uint32_t request_length, afdt_response_handler_t response_handler, afdt_error_handler_t error_handler, const struct timeval *timeout, void *userdata)
	Request a file descriptor from a server. More...

Detailed Description

The asynchronous interface provides functions for setting up clients and servers that use event-driven I/O to avoid blocking a thread. libevent is used to make the interface work with many different event APIs.

The asynchronous interface is adds more restrictions than the low-level API. Interactions are always composed of two messages: a plain message from the client to the server (the request) followed by an fd message from the server to the client(the response). There is currently no support for a client sending a file descriptor to the server. (In most cases, it is not too hard to invert the "client" and "server" roles to get around this. The server is simply the program that listens on the Unix domain socket.)

Most functions in this interface report errors by calling an error callback and passing error information to it. errno will be set to an appropriate code, or 0 if no error code is applicable.

Typedef Documentation

typedef void(* afdt_error_handler_t)(const struct afdt_error_t *err, void *userdata)

Callback type for processing errors during AFDT operations.

For example, a callback could log an error message, then try some other means of acquiring the resources it needs.

Parameters

phase	AFDT phase during which the error occurred.
operation	Operation that resulted in the error.
message	Extra information message (often empty).
userdata	Extra parameter passed to create_client or create_server.

typedef void(* afdt_post_handler_t)(const uint8_t *request, uint32_t request_length, const uint8_t *response, uint32_t response_length, int sent_fd, void *userdata)

Callback type for after a response is sent.

For example, a callback could close sent_fd if the recipient is going to take over all operations.

The post handler is called before the server returns to the event loop.

Parameters

request	Request buffer sent by the client.
request_length	Length of request.
response	Response buffer sent by the server.
response_length	Length of response.
received_fd	File descriptor sent (by request_handler).
userdata	Extra parameter passed to create_server.

typedef int(* afdt_request_handler_t)(const uint8_t *request, uint32_t request_length, uint8_t *response, uint32_t *response_length, void *userdata)

Callback type for processing an AFDT request.

For example, a callback could check some authentication information in the request, look in the request for the name of some resource, then return the appropriate fd or send an error message in the response. Remember to set *response_length to 0 if you are sending an empty response.

Parameters

request	Request buffer sent by the client.
request_length	Length of request.
response	Buffer into which to write the response.
response_length	IN/OUT: response buffer/content size.
userdata	Extra parameter passed to create_server.

Returns

File descriptor to send, or <0 for none.

typedef void(* afdt_response_handler_t)(const uint8_t *response, uint32_t response_length, int received_fd, void *userdata)

Callback type for processing an AFDT response.

For example, a callback could pass the file descriptor to evhttp_accept_socket and start serving requests, or send another request if the response indicates that the transfer was not authorized.

Parameters

response	Response buffer sent by the server.
response_length	Length of response.
received_fd	File descriptor received, or <0 for none.
userdata	Extra parameter passed to create_client.

Function Documentation

int afdt_close_server

(

void *

close_handle

)

Shut down a server created by afdt_create_server.

Any client connections that have already been created will continue to exist.

Parameters

close_handle

Handle provided by afdt_create_server.

Returns

>=0 if successful, <0 on failure.

int afdt_create_client	(	const char *	fname,
		struct event_base *	eb,
		const uint8_t *	request,
		uint32_t	request_length,
		afdt_response_handler_t	response_handler,
		afdt_error_handler_t	error_handler,
		const struct timeval *	timeout,
		void *	userdata
	)

Request a file descriptor from a server.

Exactly one of response_handler and error_handler will be called, unless timeout is NULL and the server never responds.

Note

This function currently does a blocking connect and send.

Parameters

fname	File to connect PF_LOCAL socket to.
eb	struct event_base to manage this client.
request	Request buffer to send.
request_length	Length of request.
response_handler	Callback to handle response.
error_handler	Callback to handle errors.
timeout	Timeout when waiting for response, or NULL.
userdata	Arbitrary value to pass to callbacks.

Returns

>=0 if connection and request successful, <0 on failure. error_handler will also be called on failure.

int afdt_create_server	(	const char *	fname,
		struct event_base *	eb,
		afdt_request_handler_t	request_handler,
		afdt_post_handler_t	post_handler,
		afdt_error_handler_t	error_handler,
		void **	out_close_handle,
		void *	userdata
	)

Create a server to make file descriptors available.

request_handler and error_handler may both be called multiple times.

Parameters

fname	File to bind PF_LOCAL socket to. Must not exist.
eb	struct event_base to manage this server.
request_handler	Callback to handle requests.
post_handler	Callback called after sending a response.
error_handler	Callback to handle errors.
out_close_handle	If non-NULL, set to a handle for afdt_close_server.
userdata	Arbitrary value to pass to callbacks.

Returns

>=0 if successful, <0 on failure. error_handler will also be called on failure.