Stream

/* @file aisl/types.h */

typedef struct aisl_stream * 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 response functions.

AislStream can be a source of the following events:

Control Functions

Response Functions:


Function aisl_get_server

Gets AislServer associated with AislStream

AislServer
aisl_get_server(AislStream stream);

Arguments

Return value

Associated AislServer


Function aisl_get_get_client

Gets AislClient associated with AislStream

AislClient
aisl_get_client(AislStream stream);

Arguments

Return value

Associated AislClient


Function aisl_get_instance

Gets AislInstance associated with AislStream

AislInstance
aisl_get_instance(AislStream stream);

Arguments

Return value

Associated AislInstance


Function aisl_is_secure

Checks if stream is secured with HTTPS

bool aisl_is_secure(AislStream stream);

Arguments

Return value


Function aisl_get_http_version

Gets an HTTP version requested by client

AislHttpVersion
aisl_get_http_version(AislStream stream);

Arguments

Return value

AislHttpVersion constant


Function aisl_set_context

Stores user-defined context pointer inside stream object. That pointer can be obtained from AislStream object during its life time. It is up to developer, how to use AislStream context.

void
aisl_set_context(AislStream stream, void *context);

Arguments

Return value

Returns no value.


Function aisl_get_context

Gets previously stored with aisl_set_context context pointer.

void *
aisl_get_context(AislStream stream);

Arguments

Return value

Previously stored context pointer


Function aisl_set_output_event

Switches triggering of AISL_EVENT_STREAM_OUTPUT on and off. Initial value for any AislStream is false, so event is not triggered by default. Developer may want to use that event for sending chunks of big files.

void
aisl_set_output_event(AislStream stream, bool value);

Arguments

Return value

Returns no value.


Function aisl_get_output_event

Gets current state of AISL_EVENT_STREAM_OUTPUT switch.

bool
aisl_get_output_event(AislStream stream);

Arguments

Return value


Function aisl_response

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 if AISL_AUTO_LENGTH passed, otherwise it is the best practice to provide content length in a very begining with this call.

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

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

Arguments

Return value


Function aisl_header

Writes HTTP header at the end of a stream buffer. This function should be called only before any data was written to a response body.

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

Arguments

Return value

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


Function aisl_header_printf

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.

This function works similar to printf standard library function.

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

Arguments

Return value

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


Function aisl_header_vprintf

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

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

This function works similar to vprintf standard library function.

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

Arguments

Return value

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


Function aisl_printf

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.

This function works similar to printf standard library function.

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

Arguments

Return value

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


Function aisl_vprintf

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

This function works similar to printf standard library function.

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

Arguments

Return value

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


Function aisl_write

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

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

Arguments

Return value

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


Function aisl_puts

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

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

Arguments

Return value

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


Function aisl_flush

AislStatus
aisl_flush(AislStream stream);

Initiates transmission of a stream buffer if it was not started before. 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

Return value


Function aisl_reject

Rejects the stream and closes client connection.

void
aisl_reject(AislStream stream);

Arguments

Return value

Returns no value.