HTTP

This page contains all available public functions related to understanding and responding to HTTP requests.

Index

http_response

Synopsis

void http_response(struct http_request *req, int status, const void *data, size_t length)

Description

Creates an HTTP response for an HTTP request.

Parameter Description
req The HTTP request to respond to.
status The HTTP status code to include in the response.
data The data to be sent in the response body.
length The length of the data to be sent.

Returns

Nothing

http_response_header

Synopsis

void http_response_header(struct http_request *req, const char *header, const char *value)

Description

Includes HTTP header into response.

Parameter Description
req The HTTP request to respond to.
header The HTTP header to include in the response.
value The HTTP header value to include in the response.

Returns

Nothing

http_response_stream

Synopsis

void http_response_stream(struct http_request *req, int status, void *base, size_t length, int (*cb)(struct netbuf *), void *arg)

Description

Creates an HTTP response for an HTTP request much like http_response().

However unlike that function this one does not copy the response body data but rather streams from it. It will call the given callback cb when all data has been sent.

Parameter Description
req The HTTP request to respond to.
status The HTTP status code to include in the response.
base The base pointer of the data to be sent in the response body.
length The length of the data to be sent.
cb A callback that is called when all data has been sent.
arg A user supplied argument that is passed in the callback.

Returns

Nothing

http_response_fileref

Synopsis

void http_response_fileref(struct http_request *req, struct kore_fileref *ref)

Description

Creates an HTTP response for an HTTP request much like http_response().

This function however takes a kore filereference data structure as its argument and will send the ondisk file it represents to the client.

Parameter Description
req The HTTP request to respond to.
ref The kore file reference.

Returns

Nothing

http_response_close

Synopsis

void http_response_close(struct http_request *req, int code, const void *data, size_t length)

Description

Creates an HTTP response for an HTTP request much like http_response().

This function however will force the connection to be closed immediately after the response has been sent to the server.

It will automatically add a "connection" header with "close" as its value.

Parameter Description
req The HTTP request to respond to.
status The HTTP status code to include in the response.
data The data to be sent in the response body.
length The length of the data to be sent.

Returns

Nothing

http_response_json

Synopsis

void http_response_json(struct http_request *req, int code, struct kore_json_item *json)

Description

Creates an HTTP response for an HTTP request much like http_response().

This function takes a Kore JSON item that is to be sent as a response.

It will automatically add a "content-type" header with "application/json" as its value.

The caller must not free the provided JSON item nor use it after calling this function as this function will free it.

Parameter Description
req The HTTP request to respond to.
status The JSON data to be sent that was previously created.
json The data to be sent in the response body.

Returns

Nothing

http_request_header

Synopsis

int http_request_header(struct http_request *req, const char *header, const char **out)

Description

Attempts to find the given header in an HTTP request and returns the value of the header in the out parameter. The returned pointer should not be freed.

Parameter Description
req The HTTP request.
header The name of the header to find.
out Pointer to where the pointer to the result is stored.

Returns

KORE_RESULT_OK if a result was set in out. KORE_RESULT_ERROR if the header was not present in the request.

http_file_lookup

Synopsis

struct http_file *http_file_lookup(struct http_request *req, const char *name)

Description

Lookup a file that was uploaded as part of a multipart form submission.

Parameter Description
req The HTTP request.
name The name of the form field the file was sent as.

Returns

A pointer to an http_file data structure containing information about the uploaded file.

Will return NULL if the file could not be found.

Note

You must call http_populate_multipart_form() before this function will return any result at all.

http_file_read

Synopsis

ssize_t http_file_read(struct http_file *file, void *buf, size_t length)

Description

Read file data from the given file up to length size.

Parameter Description
file The file from which to read.
buf Where the file data is copied into.
length The maximum length that can be copied into buf.

Returns

Returns the number of bytes successfully read from the file, or 0 on end of file, or -1 on error.

http_file_rewind

Synopsis

void http_file_rewind(struct http_file *file)

Description

Sets the offset member of the given file data structure back to 0 for sequential reads.

Parameter Description
file The file to rewind.

Returns

Nothing

http_populate_post

Synopsis

void http_populate_post(struct http_request *req)

Description

Processes an HTTP POST by taking the HTTP body and parsing it according to application/x-www-form-urlencoded.

This function will automatically match any fields found against configured validators to check if they contained sensible data. If the validators fail the field is automatically removed.

Parameter Description
req The HTTP request to parse.

Returns

Nothing

http_populate_qs

Synopsis

void http_populate_qs(struct http_request *req)

Description

The same as http_populate_post() but for query string parameters instead.

Parameter Description
req The HTTP request to parse.

Returns

Nothing

http_populate_multipart_form

Synopsis

void http_populate_multipart_form(struct http_request *req)

Description

Parses a multipart form that was received via a POST request.

Parameter Description
req The HTTP request to parse.

Returns

Nothing

http_body_read

Synopsis

ssize_t http_body_read(struct http_request *req, void *out, size_t length)

Description

Attempts to read data from the HTTP body received in a request.

Parameter Description
req The HTTP request.
out Where the data is copied into.
length The maximum number of bytes that will fit in out.

Returns

Returns the number of bytes copied or 0 on end of body or -1 on error.

http_state_run

Synopsis

int http_state_run(struct http_state *states, u_int8_t elm, struct http_request *req)

Description

Runs an HTTP state machine.

Parameter Description
states The HTTP state machine to be run.
elm The number of elements in this state machine.
req The HTTP request to be passed to the state machine functions.

Returns

  • KORE_RESULT_OK
  • KORE_RESULT_ERROR
  • KORE_RESULT_RETRY

Note

This should be called from a page handler.

http_state_create

Synopsis

void *http_state_create(struct http_request *req, size_t len, void (*onfree)(struct http_request *))

Description

Allocates a state attached to the HTTP request that the user can use to store temporary data for the request.

Parameter Description
req The HTTP request.
len Size of the state context.
onfree Callback function called when an HTTP request is being free'd.

Returns

The state context.

http_state_get

Synopsis

void *http_state_get(struct http_request *req)

Description

Get the user-defined state attached to the HTTP request.

Parameter Description
req The HTTP request.

Returns

The state context or NULL if none was set.

http_state_cleanup

Synopsis

void http_state_cleanup(struct http_request *req)

Description

Free the previously allocated user-defined state attached to the HTTP request.

Parameter Description
req The HTTP request.

Returns

Nothing

http_status_text

Synopsis

const char *http_status_text(int status)

Description

Returns a pointer to a human readable string for the given HTTP status code.

Parameter Description
status The HTTP status code for which to find the string.

Returns

A pointer to a human readable string for the HTTP status code.

http_method_text

Synopsis

const char *http_method_text(int method)

Description

Returns a pointer to a human readable string for the given HTTP method.

Parameter Description
method The HTTP method for which to find the matching string.

Returns

A pointer to a human readable string for the HTTP method.

http_argument_get_string

Synopsis

int http_argument_get_string(struct http_request *req, const char *name, char **out)

Description

Lookup an argument as a string. The caller should not free the result.

Parameter Description
req The HTTP request.
name The name of the argument to find.
out Where the pointer to the result is stored.

Returns

KORE_RESULT_OK if the argument was found or KORE_RESULT_ERROR if it was not found.

http_argument_get_byte

Synopsis

int http_argument_get_byte(struct http_request *req, const char *name, u_int8_t *out)

Description

Lookup an argument as a byte.

Parameter Description
req The HTTP request.
name The name of the argument to find.
out Where the result is stored.

Returns

KORE_RESULT_OK if the argument was found or KORE_RESULT_ERROR if it was not found.

http_argument_get_int16

Synopsis

int http_argument_get_int16(struct http_request *req, const char *name, int16_t *out)

Description

Lookup an argument as a 16-bit signed integer. This function will check that the result fits in a 16-bit signed integer before returning it.

Parameter Description
req The HTTP request.
name The name of the argument to find.
out Where the result is stored.

Returns

KORE_RESULT_OK if the argument was found or KORE_RESULT_ERROR if it was not found.

http_argument_get_uint16

Synopsis

int http_argument_get_uint16(struct http_request *req, const char *name, uint16_t *out)

Description

Lookup an argument as a 16-bit unsigned integer. This function will check that the result fits in a 16-bit unsigned integer before returning it.

Parameter Description
req The HTTP request.
name The name of the argument to find.
out Where the result is stored.

Returns

KORE_RESULT_OK if the argument was found or KORE_RESULT_ERROR if it was not found.

http_argument_get_int32

Synopsis

int http_argument_get_int32(struct http_request *req, const char *name, int32_t *out)

Description

Lookup an argument as a 32-bit signed integer. This function will check that the result fits in a 32-bit signed integer before returning it.

Parameter Description
req The HTTP request.
name The name of the argument to find.
out Where the result is stored.

Returns

KORE_RESULT_OK if the argument was found or KORE_RESULT_ERROR if it was not found.

http_argument_get_uint32

Synopsis

int http_argument_get_uint32(struct http_request *req, const char *name, uint32_t *out)

Description

Lookup an argument as a 32-bit unsigned integer. This function will check that the result fits in a 32-bit unsigned integer before returning it.

Parameter Description
req The HTTP request.
name The name of the argument to find.
out Where the result is stored.

Returns

KORE_RESULT_OK if the argument was found or KORE_RESULT_ERROR if it was not found.

http_argument_get_int64

Synopsis

int http_argument_get_int64(struct http_request *req, const char *name, int64_t *out)

Description

Lookup an argument as a 64-bit signed integer. This function will check that the result fits in a 64-bit signed integer before returning it.

Parameter Description
req The HTTP request.
name The name of the argument to find.
out Where the result is stored.

Returns

KORE_RESULT_OK if the argument was found or KORE_RESULT_ERROR if it was not found.

http_argument_get_uint64

Synopsis

int http_argument_get_uint64(struct http_request *req, const char *name, uint64_t *out)

Description

Lookup an argument as a 64-bit unsigned integer. This function will check that the result fits in a 64-bit unsigned integer before returning it.

Parameter Description
req The HTTP request.
name The name of the argument to find.
out Where the result is stored.

Returns

KORE_RESULT_OK if the argument was found or KORE_RESULT_ERROR if it was not found.

http_argument_get_float

Synopsis

int http_argument_get_float(struct http_request *req, const char *name, float *out)

Description

Lookup an argument as a float. This function will check that the result fits in a float before returning it.

Parameter Description
req The HTTP request.
name The name of the argument to find.
out Where the result is stored.

Returns

KORE_RESULT_OK if the argument was found or KORE_RESULT_ERROR if it was not found.

http_argument_get_double

Synopsis

int http_argument_get_double(struct http_request *req, const char *name, double *out)

Description

Lookup an argument as a double. This function will check that the result fits in a double before returning it.

Parameter Description
req The HTTP request.
name The name of the argument to find.
out Where the result is stored.

Returns

KORE_RESULT_OK if the argument was found or KORE_RESULT_ERROR if it was not found.

http_runlock_init

Synopsis

void http_runlock_init(struct http_runlock *lock)

Description

Initializes a runlock for use later.

Parameter Description
lock The HTTP runlock to initialize.

Returns

Nothing

http_runlock_acquire

Synopsis

int http_runlock_acquire(struct http_runlock *lock, struct http_request *req)

Description

Attempts to acquire a runlock. If the runlock is busy the req request is put to sleep.

Parameter Description
lock The HTTP runlock.
req The HTTP request that wants the lock.

Returns

Returns KORE_RESULT_OK if the runlock was acquired or KORE_RESULT_ERROR if the runlock was busy. If the runlock was busy the HTTP request is automatically put to sleep and the calling handler should return KORE_RESULT_RETRY accordingly.

http_runlock_release

Synopsis

void http_runlock_release(struct http_runlock *lock, struct http_request *req)

Description

Releases the runlock held by the given req request. If the holder of the lock mismatches the request given the worker will fatal().

Parameter Description
lock The HTTP runlock.
req The HTTP request that held the lock.

Returns

Nothing

Data structures

http_request

http_file

http_header

http_arg

http_state

results matching ""

    No results matching ""