Löwenware

# AISL Handbook
Author: Löwenware s.r.o

This document describes main concepts and API of AISL library v.1.0.x.

Last update: 2019-06-18

## Table of Contents

- AISL Overview
  - Features
  - Installation
  - Getting started — Hello World
  - Getting advanced
- API Reference
  - Type AislInstance
    - Functions:
      - aisl_new
      - aisl_free
      - aisl_run_cycle
      - aisl_sleep
  - Type AislServer
    - Functions:
      - aisl_server_get_instance
      - aisl_server_get_address
      - aisl_server_get_ssl
  - Type AislClient
    - Functions:
      - aisl_client_get_server
      - aisl_client_get_address
      - aisl_client_get_http_version
      - aisl_client_disconnect
      - aisl_client_is_secure
      - aisl_client_is_online
  - Type AislStream
    - Functions:
      - aisl_is_secure
      - aisl_get_server
      - aisl_get_client
      - aisl_get_instance
      - aisl_get_http_version
      - aisl_set_context
      - aisl_get_context
      - aisl_set_output_event
      - aisl_get_output_event
    - Response Functions:
      - aisl_response
      - aisl_header
      - aisl_header_printf
      - aisl_header_vprintf
      - aisl_printf
      - aisl_vprintf
      - aisl_write
      - aisl_puts
      - aisl_flush
      - aisl_reject
  - Enumeration AislStatus
    - Functions:
      - aisl_status_to_string
  - Events
    - Enumeration AislEvent
      - AISL_EVENT_SERVER_READY
      - AISL_EVENT_SERVER_ERROR
      - AISL_EVENT_CLIENT_CONNECT
      - AISL_EVENT_CLIENT_DISCONNECT
      - AISL_EVENT_STREAM_OPEN
      - AISL_EVENT_STREAM_HEADER
      - AISL_EVENT_STREAM_INPUT
      - AISL_EVENT_STREAM_REQUEST
      - AISL_EVENT_STREAM_OUTPUT
      - AISL_EVENT_STREAM_CLOSE
      - AISL_EVENT_STREAM_ERROR
    - Callback:
      - AislCallback — AISL event callback prototype
    - Payloads:
      - struct aisl_evt — Common event payload
      - struct aisl_evt_open — Event specific payload
      - struct aisl_evt_header — Event specific payload
      - struct aisl_evt_input — Event specific payload
    - Functions:
      - aisl_event_to_string
  - Enumeration AislHttpVersion
    - Functions:
      - aisl_http_version_to_string
  - Enumeration AislHttpMethod
    - Functions:
      - aisl_http_method_to_string
  - Enumeration AislHttpResponse
    - Functions:
      - aisl_http_response_to_string
  - Configuration structures
  - struct aisl_cfg
  - struct aisl_cfg_ssl
  - struct aisl_cfg_srv
- Preprocessor definitions

- struct aisl_cfg
- AISL_AUTO_LENGTH
- AISL_CALLBACK

## AISL Overview

If you are reading this, either you are somehow already familiar with web applications and web servers and you probably used to count them as an independent entities. Indeed, most of the existing web technologies are based on standalone web server and HTTP parser that together provide some programming interface to work with cached in memory and on a hard disk HTTP request. It is not that efficient and sometimes even vulnerable in sence of DDoS attacks.

AISL works differently. Using AISL you can create web application that is a web server. It means that developer can keep under control all the workflow of an HTTP stream, by appropriate reactoin on triggered by AISL programmable events, which is a great performance and security advantage. For example, application may want to already start some routines to prepare response, when just first line of the HTTP request like GET /index.html HTTP/1.1 was received. Or it may also want to ignore some of the HTTP headers or even full body content to preserve resources and CPU time, if they are unnecessary or even unwelcome.

### Features

- Asynchronous event-based engine
- Lightweight solution: size of the shared C library is just about 38 Kbytes.
- HTTP 1.x support (support of HTTP 2.0 is planned).
- HTTPS support (using openssl).
- Free software with open source code.
- CC BY-ND 4.0 License.

### Installation

One can get AISL sources from GitHub at any time. Master branch is always stable. To get the Library follow these steps:

1. Clone GIT repositroy`$ git clone https://github.com/lowenware/aisl.git`
2. Navigate to cloned folder`$ cd aisl`
3. Compile the library`$ make PREFIX=/usr/local LIB_DIR=lib` Set `PREFIX` to preffered installation path and `LIB_DIR` to your system related name of library directory (lib, lib32 or lib64).
4. Install the library`$ sudo make install`
5. Optionaly advanced users may want to build library with one or more options: `AISL_WITH_SSL=0` - disable HTTPS support, `AISL_WITH_STRINGIFIERS=0` - disable several optional *_to_string functions to preserve library sizea, `AISL_WITH_DEBUG=1` - enable library debug output.
6. You may also want to edit (if you have changed `PREFIX` or `LIB_DIR`) and copy libaisl.pc.example file to /usr/lib/pkgconfig, so pkgconfig could be used to simplify future linking.

### Getting started - Hello World

If you have AISL installed, it is time to try it out with simple `Hello World!` application. Full source code could be found on a GitHub and the most important steps are highlighted bellow.

Include AISL meta-header file to add necessary declarations to you code file. You should never include other AISL header files in to your projects.

`#include <aisl/aisl.h>`

In this example we create one HTTP server without encryption, that will listen to port 8080 on all available network interfaces.

`static const struct aisl_cfg_srv m_srv[] = {{ .host = "0.0.0.0", .port = 80, .secure = false }};`

Now we initialize configuration structure

`static const struct aisl_cfg m_cfg = { AISL_CFG_DEFAULTS , .srv = m_srv , .srv_cnt = sizeof (m_srv) / sizeof (m_srv[0]) , .ssl = NULL , .ssl_cnt = 0 , .callback = hello_world , .p_ctx = NULL };`

Event handler callback called `hello_world` in our example is a core function of the web application. It should match AislCallback prototype.

The simpliest `main` function should allocate and initialize our AislInstance and start application loop.

`int main(int argc, char **argv) { AislInstance aisl; AislStatus status; if ( (aisl = aisl_new(&cfg)) != NULL ) { /* launch application loop */ fprintf(stdout, "Entering main loop\n" ); for(;;) { status = aisl_run_cycle(aisl); if ( status != AISL_SUCCESS ) aisl_sleep(aisl, 500); } aisl_free(aisl); } else { fprintf(stderr, "Failed to initialize AISL\n"); return -1; } return 0; }`

Function aisl_run_cycle being called within a loop does all the core routines of our HTTP server and triggers event callback defined in configuration structure. To avoid unnecessary CPU loading we also execute aisl_sleep on idle cycles. To release allocated by AISL resources on a runtime we are using aisl_sleep.

And finally it is time to define the event handler matching AislCallback prototype.

`static void hello_world(const struct aisl_evt *evt, void *p_ctx) { AislStream s; const char html[] = "<html>" "<head>" "<title>Hello World</title>" "</head>" "<body>" "<h1>Hello World</h1>" "<p>Powered by AISL</p>" "</body>" "</html>"; if (evt->code != AISL_EVENT_STREAM_REQUEST) return; s = evt->source; if (aisl_response(s, AISL_HTTP_OK, sizeof (html)-1) == AISL_SUCCESS) { if (aisl_write(s, html, sizeof (html)-1) != -1) { aisl_flush(s); return; } } aisl_reject(s); (void) p_ctx; }`

The function is being called by AISL engine on every event, but proceeds only if AISL_EVENT_STREAM_REQUEST is received. It starts an HTML response stored in `html` constant. Make sure you use `sizeof (htmk)-1` for content length, to avoid unwanted write of last NULL terminating character of `html` string constant.

To compile the example using GCC and pkgconfig run:

`$ gcc `pkgconf --libs --cflags libaisl` hello-world.c -o hello-world`

Or specify paths to installed header files and library manualy:

`$ -I/usr/local/include -L/usr/local/lib -laisl hello-world.c -o hello-world`

Now execute compiled hello_world binary and open http://localhost:8080 in your browser. If you get any `symbol lookup error` on execution attempt, try to specify the path to the library in the environment variable:

`$ LD_LIBRARY_PATH="/usr/local/lib" ./hello-world`

The result should look like this:

### Getting advanced

Right after this chapter you will find full AISL API Reference that guides through all the types and functions. The most significant of them you may already know from the Hello World example. To become an advanced AISL developer, you will need to understand events model and stream concept. The rest of library components carry more auxiliary function.

## API Reference

AISL library API defines several types (pointers on transparent data structures), functions to work with them, enumerations, data structures and preprocessor definitions.

Each AISL component has a library specific prefix:

- Aisl* - for data types (typedefs)
- aisl_* - for functions and structures names
- AISL_* - for constants and macro definitions

Functions, related to some data type, include name of the type in their names, i.e. `AislServer -> aisl_server_get_address()`. There are two exceptions from this rule though introduced for simplicity and shorter names for the functions being used most often: AislInstance and AislStream.

### Type AislInstance

Pointer of this type represents library engine, that could be dynamically allocated in memory. It means that you can have several library instances in one application, though you may never meet a real use case for this.

Every instance may handle several independent HTTP servers running on different network sockets and manages SSL certificates and communication with clients.

Each instance must be configured with proper parameters stored in aisl_cfg data structure with at least one HTTP server and event handler matching AislCallback prototype.

#### Functions

`AislInstance aisl_new(const struct aisl_cfg *cfg);`
DESCRIPTION

A constructor of AislInstance class.

PARAMETERS

- cfg — a pointer to an aisl_cfg configuration structure

RETURN VALUE

Pointer to an AislInstance or NULL if out of memory.

`void aisl_free(AislInstance instance);`
Description

A destructor of AislInstance object.

Arguments

- instance — a pointer to an AislInstance.

Return value

Returns no value.

`AislStatus aisl_run_cycle(AislInstance instance);`
Description

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.

Arguments

- instance — a pointer to an AislInstance.

Return value

- 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);`
Description

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

Arguments

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

Return value

- 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

### Type AislServer

Pointer of this type represents an HTTP server constructed using configuration from `srv` and `srv_cnt` members of an structure used for AislInstance construction.

AislServer can be a source of the following events:

- AISL_EVENT_SERVER_READY
- AISL_EVENT_SERVER_ERROR

#### Functions

`AislInstance aisl_server_get_instance(AislServer server);`
Description

Gets an AislInstance associated with a valid AislServer

Arguments

- server — an AislServer pointer

Return value

Associated AislInstance

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

Copies server's address and port to provided sockaddr_in structure

Arguments

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

Return value

Returns no value.

`bool aisl_server_get_ssl(AislServer server);`
Description

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

Arguments

- server — an AislServer pointer

Return value

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

### Type AislClient

Pointer of this type represents HTTP client connected to an AislServer.

AislClient can be a source of the following events:

- AISL_EVENT_CLIENT_CONNECT
- AISL_EVENT_CLIENT_DISCONNECT

#### Functions

`AislServer aisl_client_get_server(AislClient client);`
Description

Gets an AislServer associated with a valid AislClient

Arguments

- client — an AislClient pointer

Return value

Associated AislServer

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

Copies client's address and port to provided sockaddr_in structure

Arguments

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

Return value

Returns no value.

`AislHttpVersion aisl_client_get_http_version(AislClient client);`
Description

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

Arguments

- client — an AislClient pointer

Return value

A constant from AislHttpVersion enumeration

`void aisl_client_disconnect(AislClient client);`
Description

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

Arguments

- client — an AislClient pointer

Return value

Returns no value.

`bool aisl_client_is_secure(AislClient client);`
Description

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

Arguments

- client — an AislClient pointer

Return value

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

`bool aisl_client_is_online(AislClient client);`
Description

Checks if connection with client is still up.

Arguments

- client — an AislClient pointer

Return value

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

### Type AislStream

A pointer of this type represents a sequence of a request from AislClient and a response from the application. First by handling events you can get any or all the data from the HTTP request being parsed, and then write the response to the stream.

Each stream has own extandable internal buffer that is used to store the response. When you write to the stream using one of the appropriate functions, the date is being written to this buffer first.

Application must respect the order of write calls to keep response structure: response code, headers, body. For more information refer description of related functions.

AislStream can be a source of the following events:

- AISL_EVENT_STREAM_OPEN
- AISL_EVENT_STREAM_HEADER
- AISL_EVENT_STREAM_INPUT
- AISL_EVENT_STREAM_REQUEST
- AISL_EVENT_STREAM_OUTPUT
- AISL_EVENT_STREAM_CLOSE
- AISL_EVENT_STREAM_ERROR

#### Functions

`AislServer aisl_get_server(AislStream stream);`
Description

Gets an AislServer associated with a valid AislStream

Arguments

- stream — an AislStream pointer

Return value

Associated AislServer

`AislClient aisl_get_client(AislStream stream);`
Description

Gets an AislClient associated with a valid AislStream

Arguments

- stream — an AislStream pointer

Return value

Associated AislClient

`AislInstance aisl_get_instance(AislStream stream);`

Gets an AislInstance associated with a valid AislStream

Description

Gets an AislInstance associated with a valid AislStream

Arguments

- stream — an AislStream pointer

Return value

Associated AislInstance

`bool aisl_is_secure(AislStream stream);`
Description

Checks if stream is secured with HTTPS

Arguments

- stream — an AislStream pointer

Return value

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

`AislHttpVersion aisl_get_http_version(AislStream stream);`
Description

Gets an HTTP version requested by client

Arguments

- stream — an AislStream pointer

Return value

A constant from AislHttpVersion enumeration

`void aisl_set_context(AislStream stream, void *context);`
Description

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.

Arguments

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

Return value

Returns no value.

`void * aisl_get_context(AislStream stream);`
Description

Gets previously stored with aisl_set_context application data pointer.

Arguments

- stream — an AislStream pointer

Return value

Previously stored application data pointer

`void aisl_set_output_event(AislStream stream, bool value);`
Description

Switches triggering of AISL_EVENT_STREAM_OUTPUT, default value is false.

Arguments

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

Return value

Returns no value.

`bool aisl_get_output_event(AislStream stream);`
Description

Gets current state of AISL_EVENT_STREAM_OUTPUT switch.

Arguments

- stream — an AislStream pointer

Return value
- true — when event triggering is enabled
- false — when event triggering is disabled

#### Response functions

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

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.

Arguments

- 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

Return value

- 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);`
Description

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.

Arguments

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

Return 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, ...);`
Description

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.

Arguments

- 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

Return value

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);`
Description

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.

Arguments

- 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

Return value

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, ...);`
Description

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.

Arguments

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

Return value

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);`
Description

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.

Arguments

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

Return value

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);`
Description

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

Arguments

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

Return value

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);`
Description

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

Arguments

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

Return value

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

`AislStatus aisl_flush(AislStream stream);`
Description

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.

Arguments

- stream — an AislStream pointer

Return value

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

`void aisl_reject(AislStream stream);`
Description

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

Arguments

- stream — an AislStream pointer

Return value

Returns no value.

### Enumeration AislStatus

`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.

#### Functions

`const char * aisl_status_to_string(AislStatus status);`
Description

Converts AislStatus enumeration to a NULL-terminated string.

Arguments

- status — a constant from AislStatus enumeration

Return value

A NULL-terminated string representation of AislStatus

### Events

Events triggered by AISL inform application about HTTP server and client activity, communication state, provide parsed results of HTTP request.

To recieve events notification application have to define an event handler function, matching AislCallback prototype and assign its pointer to a member named `callback` of an aisl_cfg structure, given as a parameter to aisl_new call.

Also `p_ctx` member of the aisl_cfg could be set, so its value will be passed as a second argument of the event handler function.

Different events may have different payload passed as a first argument to the event handler function and different source types. In this case you can access event specific data using type casting. Refer event description of this document for detailed infromation.

`void on_aisl_evt(const struct aisl_evt *evt, void *ctx) { switch (evt->code) { ... case AISL_EVENT_STREAM_HEADER: { struct aisl_evt_header *evt_header = (struct aisl_evt_headeraisl_evt_header *) evt; AislStream s = (AislStream) evt->source; printf("Stream (HTTP%s): header received %s = %s\n", aisl_is_secure(s) ? "S" : "", evt_header->key, evt_header->value); } break; ... } (void) ctx; }`

#### Callback

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

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

Arguments

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

Return value

Should not return any value.

#### Enumeration AislEvent

`AISL_EVENT_SERVER_READY`
Description

HTTP server has started and is ready to accept clients.

Payload

aisl_evt

Source

AislServer

`AISL_EVENT_SERVER_ERROR`
Description

HTTP server has not started due to an error.

Payload

aisl_evt

Source

AislServer

`AISL_EVENT_CLIENT_CONNECT`
Description

HTTP client has connected to the server.

Payload

aisl_evt

Source

AislClient

`AISL_EVENT_CLIENT_DISCONNECT`
Description

HTTP client has disconnected from the server.

Payload

aisl_evt

Source

AislClient

`AISL_EVENT_STREAM_OPEN`
Description

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

Payload

aisl_evt_open

Source

AislStream

`AISL_EVENT_STREAM_HEADER`
Description

HTTP header has been received and parsed.

Payload

aisl_evt_header

Source

AislStream

`AISL_EVENT_STREAM_INPUT`
Description

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.

Payload

aisl_evt_input

Source

AislStream

`AISL_EVENT_STREAM_REQUEST`
Description

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

Payload

aisl_evt

Source

AislStream

`AISL_EVENT_STREAM_OUTPUT`
Description

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.

Payload

aisl_evt

Source

AislStream

`AISL_EVENT_STREAM_CLOSE`
Description

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.

Payload

aisl_evt

Source

AislStream

`AISL_EVENT_STREAM_ERROR`
Description

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

Payload

aisl_evt

Source

AislStream

#### Payload

`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

#### Functions

`const char * aisl_event_to_string(AislEvent evt);`
Description

Converts AislEvent enumeration to a NULL-terminated string.

Arguments

- evt — a constant from AislEvent enumeration

Return value

A NULL-terminated string representation of AislEvent

### Enumeration AislHttpVersion

`typedef enum { AISL_HTTP_0_9 = 0x0009 , AISL_HTTP_1_0 = 0x0100 , AISL_HTTP_1_1 = 0x0101 , AISL_HTTP_2_0 = 0x0200 } AislHttpVersion;`

#### Functions

`const char * aisl_http_version_to_string(AislHttpVersion version);`
Description

Converts AislHttpVersion enumeration to a NULL-terminated string.

Arguments

- version — a constant from AislHttpVersion enumeration

Return value

A NULL-terminated string representation of AislHttpVersion

### Enumeration AislHttpMethod

`typedef enum { AISL_HTTP_METHOD_UNKNOWN , AISL_HTTP_GET , AISL_HTTP_PUT , AISL_HTTP_POST , AISL_HTTP_HEAD , AISL_HTTP_TRACE , AISL_HTTP_DELETE , AISL_HTTP_OPTIONS , AISL_HTTP_CONNECT , AISL_HTTP_PRI } AislHttpMethod;`

#### Functions

`const char * aisl_http_method_to_string(AislHttpMethod method);`
Description

Converts AislHttpMethod enumeration to a NULL-terminated string.

Arguments

- method — a constant from AislHttpMethod enumeration

Return value

A NULL-terminated string representation of AislHttpMethod

### Enumeration AislHttpResponse

`typedef enum { AISL_HTTP_CONTINUE = 100 , AISL_HTTP_SWITCHING_PROTOCOLS , AISL_HTTP_OK = 200 , AISL_HTTP_CREATED , AISL_HTTP_ACCEPTED , AISL_HTTP_NON_AUTHORITATIVE_INFORMATION , AISL_HTTP_NO_CONTENT , AISL_HTTP_RESET_CONTENT , AISL_HTTP_PARTIAL_CONTENT , AISL_HTTP_MULTIPLE_CHOICES = 300 , AISL_HTTP_MOVED_PERMANENTLY , AISL_HTTP_FOUND , AISL_HTTP_SEE_OTHER , AISL_HTTP_NOT_MODIFIED , AISL_HTTP_USE_PROXY , AISL_HTTP_UNUSED , AISL_HTTP_TEMPORARY_REDIRECT , AISL_HTTP_BAD_REQUEST = 400 , AISL_HTTP_UNAUTHORIZED , AISL_HTTP_PAYMENT_REQUIRED , AISL_HTTP_FORBIDDEN , AISL_HTTP_NOT_FOUND , AISL_HTTP_METHOD_NOT_ALLOWED , AISL_HTTP_NOT_ACCEPTABLE , AISL_HTTP_PROXY_AUTHENTICATION_REQUIRED , AISL_HTTP_REQUEST_TIMEOUT , AISL_HTTP_CONFLICT , AISL_HTTP_GONE , AISL_HTTP_LENGTH_REQUIRED , AISL_HTTP_PRECONDITION_FAILED , AISL_HTTP_REQUEST_ENTITY_TOO_LARGE , AISL_HTTP_REQUEST_URI_TOO_LONG , AISL_HTTP_UNSUPPORTED_MEDIA_TYPE , AISL_HTTP_REQUESTED_RANGE_NOT_SATISFIABLE , AISL_HTTP_EXPECTATION_FAILED , AISL_HTTP_INTERNAL_SERVER_ERROR = 500 , AISL_HTTP_NOT_IMPLEMENTED , AISL_HTTP_BAD_GATEWAY , AISL_HTTP_SERVICE_UNAVAILABLE , AISL_HTTP_GATEWAY_TIMEOUT , AISL_HTTP_VERSION_NOT_SUPPORTED } AislHttpResponse;`

#### Functions

`const char * aisl_http_response_to_string(AislHttpResponse code);`
Description

Converts AislHttpResponse enumeration to a NULL-terminated string.

Arguments

- code — a constant from AislHttpResponse enumeration

Return value

A NULL-terminated string representation of AislHttpResponse

## Configuration structures

`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.

A recommended configuration is defined in a preprocessor macro AISL_CFG_DEFAULTS.

`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

## Preprocessor definitions

`#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