This document describes main concepts and API of AISL library v.1.0.x.
-Last update: 2019-06-16
+Last update: 2019-06-18
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 @@ -282,48 +288,64 @@
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
+ #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.
-struct aisl_cfg_srv[] srv = {{
- .host = "0.0.0.0",
- .port = 8080,
- .secure = false
+
+ static const struct aisl_cfg_srv m_srv[] = {{
+ .host = "0.0.0.0",
+ .port = 80,
+ .secure = false
}};
- To initialize configuration structure we use default values.
- struct aisl_cfg cfg = AISL_CFG_DEFAULT;
+ 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
+};
- An address of the defined servers configuration and their number must be
- also stored in the structure.
- cfg.srv = srv;
-cfg.srv_cnt = sizeof (srv) / sizeof (srv[0]);
+ Event handler callback called hello_world in
+ our example is a core function of the web application. It should match
+ AislCallback prototype.
- Event handler is a core function of the web application. It should match
- AislCallback prototype and its address also
- must be stored in the configuration structure before library
- initialization.
- cfg.callback = hello_world;
+ The simpliest main function should allocate
+ and initialize our AislInstance and start
+ application loop.
- When configuration is ready, it is time to allocate and initialize our
- AislInstance and start application loop.
- 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);
+ int
+main(int argc, char **argv)
+{
+ AislInstance aisl;
+ AislStatus status;
- if ( status != AISL_SUCCESS )
- aisl_sleep(aisl, 500);
+ 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;
}
- aisl_free(aisl);
-} else {
- fprintf(stderr, "Failed to initialize AISL\n");
+
+ 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
@@ -333,12 +355,12 @@ if ( (aisl = aisl_new(&cfg)) != NULL ) {
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)
+ static void
+hello_world(const struct aisl_evt *evt, void *p_ctx)
{
- AislStream s;
+ AislStream s;
- const char html[] =
+ const char html[] =
"<html>"
"<head>"
"<title>Hello World</title>"
@@ -347,22 +369,22 @@ hello_world(const struct aisl_evt *evt, void *p_ctx)
"<h1>Hello World</h1>"
"<p>Powered by AISL</p>"
"</body>"
- "</html>";
+ "</html>";
- if (evt->code != AISL_EVENT_STREAM_REQUEST)
- return;
+ 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;
+ 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;
+ 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
@@ -393,23 +415,23 @@ hello_world(const struct aisl_evt *evt, void *p_ctx)
components carry more auxiliary function.
API Reference
- AISL library API has object oriented model. Although C has no objects,
- it still allows to use transparent data structures to represent classes and
- functions as methods.
+ 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 (methods), include name of the type in
- their names, i.e. AislServer - aisl_server_get_address().
+
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.
- Class AislInstance
- This class represents library engine, that could be dynamically allocated
+
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
@@ -420,479 +442,1061 @@ hello_world(const struct aisl_evt *evt, void *p_ctx)
server and event handler matching AislCallback
prototype.
-
Methods
- aisl_new
- AislInstance
-aisl_new(const struct aisl_cfg *cfg);
+ 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.
+
- 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.
-
- aisl_free
- void
+
+ void
aisl_free(AislInstance instance);
- DESCRIPTION
- Frees previously allocated pointer of AISL instance.
- PARAMETERS
-
- - instance — a pointer to an AislInstance.
-
- RETURN VALUE
- Returns no value.
+ Description
+ A destructor of AislInstance object.
+ Arguments
+
+ - instance — a pointer to an AislInstance.
+
+ Return value
+ Returns no value.
+
- aisl_run_cycle
- AislStatus
+
+ AislStatus
aisl_run_cycle(AislInstance instance);
- DESCRIPTION
-
- PARAMETERS
-
- - 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.
+ 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.
+
- aisl_sleep
- DESCRIPTION
-
- PARAMETERS
-
-
-
- RETURN VALUE
-
+
+ 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:
+
+
+ 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:
+
+
+ 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.
+
- Class AislServer
- Class AislClient
- Class AislStream
Enumeration AislStatus
- Enumeration AislEvent
+
+
+ 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
+
+ Source
+
+
+
+ AISL_EVENT_SERVER_ERROR
+ Description
+ HTTP server has not started due to an error.
+ Payload
+
+ Source
+
+
+
+ AISL_EVENT_CLIENT_CONNECT
+ Description
+ HTTP client has connected to the server.
+ Payload
+
+ Source
+
+
+
+ AISL_EVENT_CLIENT_DISCONNECT
+ Description
+ HTTP client has disconnected from the server.
+ Payload
+
+ Source
+
+
+
+ AISL_EVENT_STREAM_OPEN
+ Description
+ First line of the HTTP request has been received and parsed.
+ Payload
+
+ Source
+
+
+
+ AISL_EVENT_STREAM_HEADER
+ Description
+ HTTP header has been received and parsed.
+ Payload
+
+ Source
+
+
+
+ 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
+
+ Source
+
+
+
+ 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
+
+ Source
+
+
+
+ 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
+
+ Source
+
+
+
+ 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
+
+ Source
+
+
+
+ AISL_EVENT_STREAM_ERROR
+ Description
+ Triggered on invalid client's behavior and misformatted HTTP request.
+ Payload
+
+ Source
+
+
+
+ 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
- Data Structures
+ , 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
- struct aisl_cfg
- struct aisl_cfg_ssl
- struct aisl_cfg_srv
- struct aisl_evt
- struct aisl_evt_open
- struct aisl_evt_header
- struct aisl_evt_input
+ , 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.
- Events
+
+ 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.
+
+
- 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
+
+ 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.
+
- Functions
-
-
-
- aisl_get_server
- DESCRIPTION
-
- PARAMETERS
-
-
-
- RETURN VALUE
-
-
-
- aisl_get_client
- DESCRIPTION
-
- PARAMETERS
-
-
-
- RETURN VALUE
-
-
- aisl_stream_get_instance
- DESCRIPTION
-
- PARAMETERS
-
-
-
- RETURN VALUE
-
-
- aisl_is_secure
- DESCRIPTION
-
- PARAMETERS
-
-
-
- RETURN VALUE
-
-
-
- aisl_get_http_version
- DESCRIPTION
-
- PARAMETERS
-
-
-
- RETURN VALUE
-
-
- aisl_set_context
- DESCRIPTION
-
- PARAMETERS
-
-
-
- RETURN VALUE
-
-
- aisl_get_context
- DESCRIPTION
-
- PARAMETERS
-
-
-
- RETURN VALUE
-
-
- aisl_set_output_event
- DESCRIPTION
-
- PARAMETERS
-
-
-
- RETURN VALUE
-
-
- aisl_get_output_event
- DESCRIPTION
-
- PARAMETERS
-
-
-
- RETURN VALUE
-
-
-
- aisl_response
- DESCRIPTION
-
- PARAMETERS
-
-
-
- RETURN VALUE
-
-
- aisl_header
- DESCRIPTION
-
- PARAMETERS
-
-
-
- RETURN VALUE
-
-
- aisl_header_printf
- DESCRIPTION
-
- PARAMETERS
-
-
-
- RETURN VALUE
-
-
- aisl_header_vprintf
- DESCRIPTION
-
- PARAMETERS
-
-
-
- RETURN VALUE
-
-
- aisl_printf
- DESCRIPTION
-
- PARAMETERS
-
-
-
- RETURN VALUE
-
-
- aisl_vprintf
- DESCRIPTION
-
- PARAMETERS
-
-
-
- RETURN VALUE
-
-
- aisl_write
- DESCRIPTION
-
- PARAMETERS
-
-
-
- RETURN VALUE
-
-
- aisl_puts
- DESCRIPTION
-
- PARAMETERS
-
-
-
- RETURN VALUE
-
-
- aisl_flush
- DESCRIPTION
-
- PARAMETERS
-
-
-
- RETURN VALUE
-
-
- aisl_reject
- DESCRIPTION
-
- PARAMETERS
-
-
-
- RETURN VALUE
-
-
-
- aisl_server_get_instance
- DESCRIPTION
-
- PARAMETERS
-
-
-
- RETURN VALUE
-
-
- aisl_server_get_address
- DESCRIPTION
-
- PARAMETERS
-
-
-
- RETURN VALUE
-
-
- aisl_server_get_ssl
- DESCRIPTION
-
- PARAMETERS
-
-
-
- RETURN VALUE
-
-
-
- aisl_client_get_server
- DESCRIPTION
-
- PARAMETERS
-
-
-
- RETURN VALUE
-
-
- aisl_client_get_address
- DESCRIPTION
-
- PARAMETERS
-
-
-
- RETURN VALUE
-
-
- aisl_client_get_http_version
- DESCRIPTION
-
- PARAMETERS
-
-
-
- RETURN VALUE
-
-
- aisl_client_disconnect
- DESCRIPTION
-
- PARAMETERS
-
-
-
- RETURN VALUE
-
-
- aisl_client_is_secure
- DESCRIPTION
-
- PARAMETERS
-
-
-
- RETURN VALUE
-
-
- aisl_client_is_online
- DESCRIPTION
-
- PARAMETERS
-
-
-
- RETURN VALUE
-
-
-
-
- aisl_status_to_string
- DESCRIPTION
-
- PARAMETERS
-
-
-
- RETURN VALUE
-
-
- aisl_event_to_string
- DESCRIPTION
-
- PARAMETERS
-
-
-
- RETURN VALUE
-
-
- aisl_http_version_to_string
- DESCRIPTION
-
- PARAMETERS
-
-
-
- RETURN VALUE
-
-
- aisl_http_method_to_string
- DESCRIPTION
-
- PARAMETERS
-
-
-
- RETURN VALUE
-
-
- aisl_http_response_to_string
- DESCRIPTION
-
- PARAMETERS
-
-
-
- RETURN VALUE
-
+
+ #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
+
diff --git a/aisl/hello-world.jpg b/aisl/hello-world.jpg
index 252a986..546d6cd 100644
Binary files a/aisl/hello-world.jpg and b/aisl/hello-world.jpg differ
diff --git a/static/style.css b/static/style.css
index 5ad73ca..0da3035 100644
--- a/static/style.css
+++ b/static/style.css
@@ -27,7 +27,7 @@ section, summary, ul, li, code, blockquote, .section
body,
article, aside, details, figcaption, figure, footer, header, hgroup, main, nav,
-section, summary, ul, li, code, blockquote, img, h1, h2, h3, h4, p
+section, summary, ul, li, code, blockquote, img, h1, h2, h3, h4, h5, p
{
margin: 0;
padding: 0;
@@ -121,6 +121,55 @@ h3, .h3-like {
font-size: 1.6em;
}
+h4, .h4-like {
+ font-family: 'Jura', sans-serif;
+ font-weight: normal;
+ font-size: 1.6em;
+}
+
+h5, .h5-like {
+ font-family: 'Jura', sans-serif;
+ font-weight: normal;
+ font-size: 1em;
+}
+
+code {
+ background-color: #f8f8fc;
+ border-radius: 5px;
+ padding: 20px;
+ font-size: 1em;
+ font-family: monospace;
+ white-space: pre;
+ margin: 0 0 1em;
+ tab-size: 4;
+ -moz-tab-size: 4;
+}
+
+code.inline {
+ padding: 0;
+ margin: 0;
+ display: inline;
+ color: #9f353d;
+}
+
+ code a {
+ text-decoration: none;
+ }
+
+ code .keyword {
+ font-weight: bold;
+ color: #8c0915;
+ }
+
+ code .string {
+ color: #33692b;
+ }
+
+hr {
+ border: 0;
+ border-top: 1px solid #d9dfe3;
+}
+
/* -------------------------------------------------------------------------- */
.icon {
@@ -367,10 +416,18 @@ h3, .h3-like {
}
.text-content h1 {
- padding: 0 0 1em;
+ padding: 0 0 1.5em;
}
.text-content h2 {
+ padding: 1em 0;
+}
+
+.text-content h3 {
+ padding: .7em 0;
+}
+
+.text-content h4 {
padding: .5em 0;
}
@@ -403,13 +460,33 @@ h3, .h3-like {
text-decoration: none;
}
+.code-doc {
+ padding: 0 0 3em;
+}
+
+ .code-doc p {
+ padding: 0 3em;
+ }
+
+
+ .code-doc .h5-like {
+ font-weight: normal;
+ padding: .5em 20px .5em;
+ text-transform: uppercase;
+ }
+
+ .code-doc ul {
+ padding: 0 40px;
+ list-style-type: square;
+ }
+
/* -------------------------------------------------------------------------- */
.main-content {
min-width: 320px;
}
-.anouncement {
+.anouncem ent {
max-width: 1366px;
margin: 0 auto;
}