AISL Handbook

AislInstance aisl_new(const struct aisl_cfg *cfg);

A constructor of AislInstance class.

• cfg — a pointer to an aisl_cfg configuration structure

Pointer to an AislInstance or NULL if out of memory.

void aisl_free(AislInstance instance);

A destructor of AislInstance object.

• instance — a pointer to an AislInstance.

Returns no value.

AislStatus aisl_run_cycle(AislInstance instance);

Performs an engine work cycle including all queued read and write sockets operations, accepts new clients and triggers engine events. Should be called periodically in a main loop of the application.

• instance — a pointer to an AislInstance.

• AISL_SUCCESS — if some event was triggered
• AISL_IDLE — if no event was triggered
• AISL_MALLOC_ERROR — if system run out of memory
• AISL_SYSCALL_ERROR — if some system call failed

Return value handling should be soft. It is completely safe to continue program execution even if error value was returned.

To preserve CPU time it is recommended to add a delay between aisl_run_cycle calls, at least if anything but AISL_SUCCESS has been returned. You may want to use aisl_sleep for this.

AislStatus aisl_sleep(AislInstance instance, uint32_t usec);

This function runs select system call inside on all opened sockets for read or write depending on a stream state for user defined timeout.

• instance — a pointer to an AislInstance.
• usec — a maximum possible timeout in microseconds for execution blocking

• AISL_SUCCESS — if some socket is ready for an operation
• AISL_IDLE — if timed out without any activity on sockets
• AISL_SYSCALL_ERROR — if select() system call failed

AislInstance aisl_server_get_instance(AislServer server);

Gets an AislInstance associated with a valid AislServer

• server — an AislServer pointer

Associated AislInstance

void aisl_server_get_address(AislServer server, struct sockaddr_in *address);

Copies server's address and port to provided sockaddr_in structure

• server — an AislServer pointer
• address — a pointer to an output structure

Returns no value.

bool aisl_server_get_ssl(AislServer server);

Checks if server works on HTTPS (secure) or HTTP (unsecure) protocol

• server — an AislServer pointer

• true — if server is secure
• false — if server is unsecure

AislServer aisl_client_get_server(AislClient client);

Gets an AislServer associated with a valid AislClient

• client — an AislClient pointer

Associated AislServer

void aisl_client_get_address(AislClient client, struct sockaddr_in *address);

Copies client's address and port to provided sockaddr_in structure

• client — an AislClient pointer
• address — a pointer to an output structure

Returns no value.

AislHttpVersion aisl_client_get_http_version(AislClient client);

Gets the HTTP version of the communication with AislClient. For just connected clients version is set to default AISL_HTTP_1_0.

• client — an AislClient pointer

A constant from AislHttpVersion enumeration

void aisl_client_disconnect(AislClient client);

Closes client's socket immediately. Resources will be cleaned up automatically by aisl_run_cycle call.

• client — an AislClient pointer

Returns no value.

bool aisl_client_is_secure(AislClient client);

Checks if client works on HTTPS (secure) or HTTP (unsecure) protocol.

• client — an AislClient pointer

• true — if communication is secure
• false — if communication is unsecure

bool aisl_client_is_online(AislClient client);

Checks if connection with client is still up.

• client — an AislClient pointer

• true — if client is connected
• false — if client is not connected

AislServer aisl_get_server(AislStream stream);

Gets an AislServer associated with a valid AislStream

• stream — an AislStream pointer

Associated AislServer

AislClient aisl_get_client(AislStream stream);

Gets an AislClient associated with a valid AislStream

• stream — an AislStream pointer

Associated AislClient

AislInstance aisl_get_instance(AislStream stream);

Gets an AislInstance associated with a valid AislStream

Gets an AislInstance associated with a valid AislStream

• stream — an AislStream pointer

Associated AislInstance

bool aisl_is_secure(AislStream stream);

Checks if stream is secured with HTTPS

• stream — an AislStream pointer

• true — when stream is secure
• false — when stream is unsecure

AislHttpVersion aisl_get_http_version(AislStream stream);

Gets an HTTP version requested by client

• stream — an AislStream pointer

A constant from AislHttpVersion enumeration

void aisl_set_context(AislStream stream, void *context);

Store a context pointer into the stream. It could be a pointer to any data of the application. In general it is designed to store a pointer to a page constructor while handling HTTP request.

• stream — an AislStream pointer
• context — an application data pointer

Returns no value.

void * aisl_get_context(AislStream stream);

Gets previously stored with aisl_set_context application data pointer.

• stream — an AislStream pointer

Previously stored application data pointer

void aisl_set_output_event(AislStream stream, bool value);

Switches triggering of AISL_EVENT_STREAM_OUTPUT, default value is false.

• stream — an AislStream pointer
• value — true to enable and false to disable event triggering

Returns no value.

bool aisl_get_output_event(AislStream stream);

Gets current state of AISL_EVENT_STREAM_OUTPUT switch.

• stream — an AislStream pointer

true — when event triggering is enabled

false — when event triggering is disabled

AislStatus aisl_response(AislStream stream, AislHttpResponse status_code, uint64_t content_length);

Starts an HTTP response with user defined status code and content length. If content length is unknown at this stage, it could be calculated automatically during response output, otherwise it is the best practice to provide content length in a very begining with this call, for example when transmitting a file.

Function must be called just once for a stream before any other response function.

• stream — an AislStream pointer
• status_code — a constant from AislHttpResponse enumeration
• content_length — content length in bytes or AISL_AUTO_LENGTH to calculate on the fly

• AISL_SUCCESS — when data was written to the buffer sucessfully
• AISL_IDLE — when response was already started
• AISL_MALLOC_ERROR — when buffer reallocation failed

int aisl_header(AislStream stream, const char *key, const char *value);

Writes an HTTP header at the end of a stream buffer.

This function could be called only before any data was written to a response body.

• stream — an AislStream pointer
• key — an HTTP header key
• value — an HTTP header value

Length of data written to the stream buffer, or -1 if memory allocation or stream workflow error occured

int aisl_header_printf(AislStream stream, const char *key, const char *format, ...);

Writes an HTTP header with a formatted value at the end of a stream buffer.

This function could be called only before any data was written to a response body.

• stream — an AislStream pointer
• key — an HTTP header key
• format — a value printf-like format string of an HTTP header value
• ... — comma separated variable number of arguments

Length of data written to the stream buffer, or -1 if memory allocation or stream workflow error occured

int aisl_header_vprintf(AislStream stream, const char *key, const char *format, va_list args);

Writes an HTTP header with a formatted value at the end of a stream buffer, just like aisl_header_printf, except that it uses va_list instead of a variable number of arguments.

This function could be called only before any data was written to a response body.

• stream — an AislStream pointer
• key — an HTTP header key
• format — a value printf-like format string of an HTTP header value
• args — va_list arguments macro

Length of data written to the stream buffer, or -1 if memory allocation or stream workflow error occured

int aisl_printf(AislStream stream, const char *format, ...);

Writes a formatted body (content) of an HTTP response at the end of a stream buffer.

After a call of this function, you may not use header output calls anymore.

• stream — an AislStream pointer
• format — a value printf-like format string for response content
• ... — comma separated variable number of arguments

Length of data written to the stream buffer, or -1 if memory allocation or stream workflow error occured

int aisl_vprintf(AislStream stream, const char *format, va_list args);

Writes a formatted body (content) of an HTTP response at the end of a stream buffer, just like aisl_printf, except that it uses va_list instead of a variable number of arguments.

• stream — an AislStream pointer
• format — a value printf-like format string for response content
• args — va_list arguments macro

Length of data written to the stream buffer, or -1 if memory allocation or stream workflow error occured

int aisl_write(AislStream stream, const char *data, int d_len);

Writes a part of an HTTP response content of the given length at the end of a stream buffer.

• stream — an AislStream pointer
• data — a pointer to a data array
• d_len — a length of the data to be written

Length of data written to the stream buffer, or -1 if memory allocation or stream workflow error occured

int aisl_puts(const char *str_data, AislStream stream);

Writes a NULL-terminated string as a part of an HTTP response content at the end of a stream buffer.

• str_data — a pointer to a NULL-terminated string
• stream — an AislStream pointer

Length of data written to the stream buffer, or -1 if memory allocation or stream workflow error occured

AislStatus aisl_flush(AislStream stream);

Initiates flushing of a stream buffer. At this stage Content-Type, Content-Length, Connection and Server headers will be added to a response if they were not added manualy before. If AISL_AUTO_LENGTH were given as a content_length to an aisl_response, it will be automatically calculated from a stream buffer size.

After this call all other response functions will return -1.

• stream — an AislStream pointer

• AISL_SUCCESS — when operation was successful
• AISL_MALLOC_ERROR — when system run out of memory

void aisl_reject(AislStream stream);

Rejects the stream. For HTTP > 2.0 it also closes client's connection.

• stream — an AislStream pointer

Returns no value.

AISL_SUCCESS = 0

Represents successfully executed operation.

AISL_IDLE = 1

Represents situation when traget operation was not executed or nothing significant was done. It is not an error state.

AISL_INPUT_ERROR = -4

Represents error, when some input data provided for an operation is incorrect.

AISL_EXTCALL_ERROR = -3

Represents error, when some external library call (i.e. openssl) has failed.

AISL_SYSCALL_ERROR = -2

Represents error, when some system call has failed.

AISL_MALLOC_ERROR = -1

Represents error, when memory allocation has failed.

const char * aisl_status_to_string(AislStatus status);

Converts AislStatus enumeration to a NULL-terminated string.

• status — a constant from AislStatus enumeration

A NULL-terminated string representation of AislStatus

typedef void (* AislCallback) (const struct aisl_evt *evt, void *ctx);

A prototype for event handler function to be defined by application.

• evt — an AislEvent payload
• ctx — a user defined context passed in aisl_cfg on AislInstance initialization

Should not return any value.

AISL_EVENT_SERVER_READY

HTTP server has started and is ready to accept clients.

aisl_evt

AislServer

AISL_EVENT_SERVER_ERROR

HTTP server has not started due to an error.

aisl_evt

AislServer

AISL_EVENT_CLIENT_CONNECT

HTTP client has connected to the server.

aisl_evt

AislClient

AISL_EVENT_CLIENT_DISCONNECT

HTTP client has disconnected from the server.

aisl_evt

AislClient

AISL_EVENT_STREAM_OPEN

First line of the HTTP request has been received and parsed.

aisl_evt_open

AislStream

AISL_EVENT_STREAM_HEADER

HTTP header has been received and parsed.

aisl_evt_header

AislStream

AISL_EVENT_STREAM_INPUT

A part of HTTP request content has been received. To know if it is a last part of the data or not, application shall calculate a sum of lengths of received parts and compare it with the value of Content-Length header or rely on AISL_EVENT_STREAM_REQUEST occurence.

aisl_evt_input

AislStream

AISL_EVENT_STREAM_REQUEST

Full HTTP request has been received. It is a good time for application to start response to the client.

aisl_evt

AislStream

AISL_EVENT_STREAM_OUTPUT

An optional event disabled by default. Could be enabled by aisl_set_output_event call.

Being triggered when AISL is ready to buffer a chunk of data, could be very useful for transmission of big files without need to read them all to the memory first.

aisl_evt

AislStream

AISL_EVENT_STREAM_CLOSE

Stream is about to be destroyed. It is a good time to release all previously allocated resources, for example a context set by aisl_set_context.

aisl_evt

AislStream

AISL_EVENT_STREAM_ERROR

Triggered on invalid client's behavior and misformatted HTTP request.

aisl_evt

AislStream

struct aisl_evt { void *source; AislEvent code; AislStatus status; };

• source — AislServer, AislClient or AislStream, depends on value of code member.
• code — a constant of AislEvent enumeration
• status — a constant of AislStatus specifies the reason of the event.

struct aisl_evt_open { struct aisl_evt evt; const char *path; const char *query; AislHttpMethod http_method; };

• evt — parent aisl_evt structure
• path — HTTP requested page or file
• query — HTTP query also known as GET parameters
• http_method — method of the HTTP request

struct aisl_evt_header { struct aisl_evt evt; const char *key; const char *value; };

• evt — parent aisl_evt structure
• key — HTTP header key string (all characters are in lowercase)
• value — HTTP header value string

struct aisl_evt_input { struct aisl_evt evt; const char *data; int32_t size; };

• evt — parent aisl_evt structure
• data — a pointer to received data array
• size — a size of received data

const char * aisl_event_to_string(AislEvent evt);

Converts AislEvent enumeration to a NULL-terminated string.

• evt — a constant from AislEvent enumeration

A NULL-terminated string representation of AislEvent

const char * aisl_http_version_to_string(AislHttpVersion version);

Converts AislHttpVersion enumeration to a NULL-terminated string.

• version — a constant from AislHttpVersion enumeration

A NULL-terminated string representation of AislHttpVersion

const char * aisl_http_method_to_string(AislHttpMethod method);

Converts AislHttpMethod enumeration to a NULL-terminated string.

• method — a constant from AislHttpMethod enumeration

A NULL-terminated string representation of AislHttpMethod

const char * aisl_http_response_to_string(AislHttpResponse code);

Converts AislHttpResponse enumeration to a NULL-terminated string.

• code — a constant from AislHttpResponse enumeration

A NULL-terminated string representation of AislHttpResponse

struct aisl_cfg { AislCallback callback; void *p_ctx; const struct aisl_cfg_srv *srv; const struct aisl_cfg_ssl *ssl; int srv_cnt; int ssl_cnt; int client_spool_size; int initial_buffer_size; int client_accept_limit; int client_silence_timeout; };

• callback — address of the event handler function.
• p_ctx — user defined pointer that will be passed to the event handler function.
• srv — array of servers to be handled by AISL.
• ssl — array of SSL certificates for secure servers.
• srv_cnt — size of srv array.
• ssl_cnt — size of ssl array.
• client_spool_size — Initial size of the spool (number of clients).
• initial_buffer_size — Initial size of communication buffer. Limits maximal length of supported HTTP headers length.
• client_accept_limit — Maximal number of clients to accept at the same time.
• client_silence_timeout — A time while AISL will wait for incoming data from client.

struct aisl_cfg_srv { const char *host; uint16_t port; bool secure; };

• host — network interface address to listen.
• port — TCP port to start server on.
• secure — set to true to enable SSL for this server, or false otherwise.

struct aisl_cfg_ssl { const char *host; const char *key_file; const char *crt_file; };

• host — a host name (domain) to apply the SSL certificate.
• key_file — a path to SSL certificate key file.
• crt_file — a path to SSL certificate file

#define AISL_CFG_DEFAULTS \ .client_spool_size = 32 \ , .initial_buffer_size = 16536 \ , .client_accept_limit = 1024 \ , .client_silence_timeout = 30 \

Recommended defaults for AISL configuration.

#define AISL_AUTO_LENGTH (~0)

Could be used to say AISL to calculate content length automatically.

#define AISL_CALLBACK(x) ((AislCallback) x)

Prerocessor macro to type cast a function to AislCallback