transport.h File Reference

Generic transport mechanism and concrete implementations. More...

#include "request.h"
#include <stdio.h>

Go to the source code of this file.

Data Structures
struct	sprkl_transport
	Generic transport vtable. More...

Functions
int	sprkl_transport_sendrequest (struct sprkl_transport *t, struct sprkl_request *request)
	Sends a request via the given transport.
int	sprkl_transport_recvrequest (struct sprkl_transport *t, struct sprkl_request *request)
	Receives a request via the given transport.
int	sprkl_transport_sendresponse (struct sprkl_transport *t, struct sprkl_response *response)
	Sends a response via the given transport.
int	sprkl_transport_recvresponse (struct sprkl_transport *t, struct sprkl_response *response)
	Receives a response via the given transport.
char *	sprkl_transport_strerror (struct sprkl_transport *t, int error)
	Converts a transport-defined error number to a string description.
struct sprkl_transport	sprkl_transport_make_stream (FILE *stream)
	Creates a new transport operating on the given stdio stream.
int	sprkl_transport_make_default (struct sprkl_transport *transport)
	Creates the platform's default transport, usually configured by environment variable(s).
void	sprkl_transport_fini_default (struct sprkl_transport *transport)
	Finalises the default transport.

Detailed Description

Generic transport mechanism and concrete implementations.

Function Documentation

sprkl_transport_fini_default()

void sprkl_transport_fini_default

(

struct sprkl_transport *

transport

)

Finalises the default transport.

Parameters

transport

Reference to the default transport.

sprkl_transport_make_default()

int sprkl_transport_make_default

(

struct sprkl_transport *

transport

)

Creates the platform's default transport, usually configured by environment variable(s).

The default transport will usually connect to the user's preferred "local daemon" (although it may or may not be on the same physical machine). It should only be used to act as a client (i.e. sending requests and receiving responses).

You must call this function before every new request to allow the underlying transport connection to be configured appropriately, and also call sprkl_transport_fini_default() after receiving each response.

For now, the default transport will always use TCP/IPv4 as configured by the environment variables SPRKL_TMP_DEFTP_HOST and SPRKL_TMP_DEFTP_PORT. This will change in future.

Parameters

[out]

Pointer

to transport struct to be filled in appropriately.

Returns

0 if successful, -1 if there is no default transport configured, or a transport-defined positive integer error number otherwise.

Todo

make this much more robust

sprkl_transport_make_stream()

struct sprkl_transport sprkl_transport_make_stream

(

FILE *

stream

)

Creates a new transport operating on the given stdio stream.

The stream will be left open after using transport functions, so remember to close it yourself.

Parameters

stream

Read-write stream, for example a network socket.

Returns

a transport that reads and writes to the stream.

sprkl_transport_recvrequest()

int sprkl_transport_recvrequest	(	struct sprkl_transport *	t,
		struct sprkl_request *	request )

Receives a request via the given transport.

Parameters

t	Concrete transport to use.
request	Empty request to receive data into.

Returns

0 if successful, or a transport-defined error number.

sprkl_transport_recvresponse()

int sprkl_transport_recvresponse	(	struct sprkl_transport *	t,
		struct sprkl_response *	response )

Receives a response via the given transport.

Parameters

t	Concrete transport to use.
response	Response struct to receive data into. It should be empty except for the sprkl_response::verb field, which you should set to match the verb of the associated request, in order for the response to be parsed correctly.

Returns

0 if successful, or a transport-defined error number.

sprkl_transport_sendrequest()

int sprkl_transport_sendrequest	(	struct sprkl_transport *	t,
		struct sprkl_request *	request )

Sends a request via the given transport.

Parameters

t	Concrete transport to use.
request	Request to send.

Returns

0 if successful, or a transport-defined error number.

sprkl_transport_sendresponse()

int sprkl_transport_sendresponse	(	struct sprkl_transport *	t,
		struct sprkl_response *	response )

Sends a response via the given transport.

Parameters

t	Concrete transport to use.
response	Response to send.

Returns

0 if successful, or a transport-defined error number.

sprkl_transport_strerror()

char * sprkl_transport_strerror	(	struct sprkl_transport *	t,
		int	error )

Converts a transport-defined error number to a string description.

Parameters

t	Transport which generated the error.
error	Error number returned from another transport function.

Returns

Null-terminated string describing the error. Should not be freed by caller.