request.h File Reference

Requests and responses. More...

#include "common.h"
#include "service.h"
#include <stdint.h>
#include <stdio.h>

Go to the source code of this file.

Data Structures
struct	sprkl_request_echo
	Request payload for SPRKL_VERB_ECHO. More...
struct	sprkl_response_echo
	Response payload for SPRKL_VERB_ECHO (same as request). More...
struct	sprkl_request_fetchservice
	Request payload for SPRKL_VERB_FETCHSERVICE. More...
struct	sprkl_response_fetchservice
	Response payload for SPRKL_VERB_FETCHSERVICE. More...
struct	sprkl_request
	Request tagged union. More...
struct	sprkl_response
	Response tagged union (varies on the associated request verb and status). More...

Macros
#define	SPRKL_REQUEST_MAGIC   "PawRqust"
	Magic bytes for requests.
#define	SPRKL_REQUEST_MAGIC_SZ   ((sizeof SPRKL_REQUEST_MAGIC) - 1)
#define	SPRKL_RESPONSE_MAGIC   "PawRspns"
	Magic bytes for responses.
#define	SPRKL_RESPONSE_MAGIC_SZ   ((sizeof SPRKL_RESPONSE_MAGIC) - 1)
#define	SPRKL_PROTO_VERSION   1
	Currently supported protocol version.

Enumerations
enum	sprkl_request_verb { SPRKL_VERB_ECHO = 0 , SPRKL_VERB_FETCHSERVICE = 1 }
	Request verb, indicates what action the request is performing. More...
enum	sprkl_response_status {   SPRKL_STATUS_OK = 0x0200 , SPRKL_STATUS_REQ_ERR = 0x0400 , SPRKL_STATUS_NOT_FOUND = 0x0404 , SPRKL_STATUS_RESP_ERR = 0x0500 ,   SPRKL_STATUS_NOT_IMPL = 0x0501 , SPRKL_STATUS_UNAVAIL = 0x0503 , SPRKL_STATUS_VERB_UNK = 0x0505 }
	Response status code, indicates the outcome of a request. More...

Functions
int	sprkl_request_write (struct sprkl_request *request, FILE *stream)
	Encodes and writes a request in wire format to a stream.
int	sprkl_request_read (struct sprkl_request *request, FILE *stream)
	Reads and decodes a request in wire format from a stream.
void	sprkl_request_freeparts (struct sprkl_request *request)
	Frees any pointers contained within the request, but not the request itself.
void	sprkl_request_freeall (struct sprkl_request *request)
	Frees any pointers contained within the request, and then the request itself.
struct sprkl_request *	sprkl_request_make_fetchservice (enum sprkl_sigalgo keyalgo, uint8_t *key, uint16_t serviceidx)
	Allocates and returns a new request to fetch a service given its key and index.
char *	sprkl_response_statusmsg (enum sprkl_response_status status)
	Returns a default message for the given status code.
int	sprkl_response_write (struct sprkl_response *response, FILE *stream)
	Encodes and writes a response in wire format to a stream.
int	sprkl_response_read (struct sprkl_response *response, FILE *stream)
	Reads and decodes a response in wire format from a stream.
void	sprkl_response_freeparts (struct sprkl_response *response, bool errmsg)
	Frees any pointers contained within the response, but not the response itself.
void	sprkl_response_freeall (struct sprkl_response *response)
	Frees any pointers contained within the response, and then the response itself.

Detailed Description

Requests and responses.

Enumeration Type Documentation

sprkl_request_verb

enum sprkl_request_verb

Request verb, indicates what action the request is performing.

Enumerator
SPRKL_VERB_ECHO	Return same data back in the response.
SPRKL_VERB_FETCHSERVICE	Fetch a service by key and index.

sprkl_response_status

enum sprkl_response_status

Response status code, indicates the outcome of a request.

Enumerator
SPRKL_STATUS_OK	Success.
SPRKL_STATUS_REQ_ERR	Requester ("client") made an unspecified mistake.
SPRKL_STATUS_NOT_FOUND	Requested resource was not found.
SPRKL_STATUS_RESP_ERR	Responder ("server") encountered an unspecified error.
SPRKL_STATUS_NOT_IMPL	Operation not implemented. This should not be used for unimplemented verbs; see SPRKL_STATUS_VERB_UNK.
SPRKL_STATUS_UNAVAIL	Responder is temporarily unable to process the request (for example due to maintenance or overload).
SPRKL_STATUS_VERB_UNK	Responder doesn't know how to deal with the request verb.

Function Documentation

sprkl_request_freeall()

void sprkl_request_freeall

(

struct sprkl_request *

request

)

Frees any pointers contained within the request, and then the request itself.

Same as sprkl_request_freeparts() followed by free(request).

Parameters

request

Request to free.

sprkl_request_freeparts()

void sprkl_request_freeparts

(

struct sprkl_request *

request

)

Frees any pointers contained within the request, but not the request itself.

What exactly gets freed varies depending on the request verb.

Parameters

request

Request to free.

sprkl_request_make_fetchservice()

struct sprkl_request * sprkl_request_make_fetchservice	(	enum sprkl_sigalgo	keyalgo,
		uint8_t *	key,
		uint16_t	serviceidx )

Allocates and returns a new request to fetch a service given its key and index.

Copies the key, so both the request and the key need to be freed.

Parameters

keyalgo	Algorithm used for the zone's public key.
key	The zone's public key (will be copied). Does not require a length or terminator as the length is determined based on the algorithm.
serviceidx	The index of the desired service within the zone.

Returns

a pointer to the new request struct.

Todo

check the algorithm properly instead of using assert i think

sprkl_request_read()

int sprkl_request_read	(	struct sprkl_request *	request,
		FILE *	stream )

Reads and decodes a request in wire format from a stream.

This could fail if the protocol magic constant is wrong or the version is unsupported, in which case it will set errno to EPROTO, or if the verb is unsupported, in which case it will set errno to ENOTSUP. When reading a fetch service request, it will allocate a buffer for the key.

Parameters

[out]	request	Empty request to read into.
[in]	stream	Stream to read it from.

Returns

number of bytes read.

sprkl_request_write()

int sprkl_request_write	(	struct sprkl_request *	request,
		FILE *	stream )

Encodes and writes a request in wire format to a stream.

Parameters

[in]	request	Request to write.
[out]	stream	Stream to write the request to.

Returns

number of bytes written.

sprkl_response_freeall()

void sprkl_response_freeall

(

struct sprkl_response *

response

)

Frees any pointers contained within the response, and then the response itself.

Same as sprkl_response_freeparts() followed by free(response).

Parameters

response

Response to free.

sprkl_response_freeparts()

void sprkl_response_freeparts	(	struct sprkl_response *	response,
		bool	errmsg )

Frees any pointers contained within the response, but not the response itself.

What exactly gets freed varies depending on the request verb.

Parameters

response	Response to free.
errmsg	If false, never free the error message buffer, even if it's not null.

sprkl_response_read()

int sprkl_response_read	(	struct sprkl_response *	response,
		FILE *	stream )

Reads and decodes a response in wire format from a stream.

This could fail if the protocol magic constant is wrong or the version is unsupported, in which case it will set errno to EPROTO, or if the verb is unsupported, in which case it will set errno to ENOTSUP. Will allocate various buffers; use sprkl_response_freeparts() or sprkl_response_freeall() to get rid of them.

Parameters

[out]	response	Response to read into. Should be empty except for sprkl_response::verb, which is needed in order to parse the response properly. If this isn't set it will trigger an assertion, assuming assertions are enabled (i.e. the library was built in debug mode).
[in]	stream	Stream to read it from.

Returns

number of bytes read.

sprkl_response_statusmsg()

char * sprkl_response_statusmsg

(

enum sprkl_response_status

status

)

Returns a default message for the given status code.

Parameters

status

The status code to look up.

Returns

the message as a null-terminated non-localised string (does not need to be freed).

sprkl_response_write()

int sprkl_response_write	(	struct sprkl_response *	response,
		FILE *	stream )

Encodes and writes a response in wire format to a stream.

Parameters

[in]	response	Response to write.
[out]	stream	Stream to write the response to.

Returns

number of bytes written.