C API

C API - Core Library

Macro defined varables

These macros should be customized according to your application by yourself.

• MAX_HEADER_SIZE 1024

  It is the maximum buffer size in bytes for each HTTP message header.
  MAX_HEADER_SIZE + MAX_BODY_SIZE is the total buffer size in byes for each HTTP message.

• MAX_BODY_SIZE 2048

  It is the maximum buffer size in bytes for each HTTP message body.
  MAX_HEADER_SIZE + MAX_BODY_SIZE is the total buffer size in byes for each HTTP message.

• MHS_PORT 8001

  Default listening port of Micro HTTP Server.

• MAX_HTTP_CLIENT 5

  The maximum number of clients could connect at the same time.

• MAX_HEADER_FIELDS 20

  The maximum number of the HTTP message header feilds.

Datatypes & Structures

Declare socket datatype

typedef int SOCKET;

Define socket datatype.

Declare and define HTTP server basic structure

typedef struct _HTTPServer {
	SOCKET sock;
	SOCKET _max_sock;
	fd_set _read_sock_pool;
	fd_set _write_sock_pool;
} HTTPServer;

• sock: The HTTP server listening socket.
• _max_sock: This should always be the maximum file descriptor number of usable sockets in HTTP server application.
• _read_sock_pool: It is the file descriptor set that the HTTP server application may to read.
• _write_sock_pool: It is the file descriptor set that the HTTP server application may to write.

Declare and define the field structure of HTTP Header

typedef struct _HTTPHeaderField {
	char *key;
	char *value;
} HTTPHeaderField;

It is one HTTP message header key-value pair field.

• key: The character string pointer of one HTTP message header field name.
• value: The character string of one HTTP message header field value.

Enumerate HTTP methods

typedef enum {
	HTTP_GET,
	HTTP_POST,
	HTTP_PUT,
	HTTP_DELETE,
	HTTP_NUM_METHOD
} HTTPMethod;

List the HTTP request methods.
HTTP_NUM_MEHTOD will be the amount of kinds request method.

Declare and define HTTP request header structure

typedef struct _HTTPReqHeader {
	HTTPMethod Method;
	char *URI;
	char *Version;
	HTTPHeaderField Fields[MAX_HEADER_FIELDS];
	unsigned int Amount;
} HTTPReqHeader;

It is HTTP request message header.

• Method: Represents the method of this request.
• URI: The character string pointer of the URI of this request.
• Version: The character string pointer represents the HTTP version of this request.
• Fields: The HTTPHeaderField array records HTTP request message header fields one by one.
• Amount: The total amount of this HTTP request message header fields.

Declare and define HTTP request message structure

typedef struct _HTTPReqMessage {
	HTTPReqHeader Header;
	uint8_t *Body;
	uint8_t *_buf;
	uint16_t _index;
} HTTPReqMessage;

It is whole HTTP request message.

• Header: The HTTP request message header.
• Body: The character string pointer of this HTTP request message body.
• _buf: The real buffer where the HTTP request message located which is a character string pointer.
• _index: The length of the real buffer in bytes.

Declare and define HTTP response header structure

typedef struct _HTTPResHeader {
	char *Version;
	char *StatusCode;
	char *Description;
	HTTPHeaderField Fields[MAX_HEADER_FIELDS];
	unsigned int Amount;
} HTTPResHeader;

It is HTTP respnose message header.

• Version: The character string pointer represents the HTTP version of this response.
• StatusCode: The character string pointer of the HTTP status code of this response.
• Description: The character string pointer of the description of the status code of this response.
• Fields: The HTTPHeaderField array records HTTP response message header fields one by one.
• Amount: The total amount of this HTTP response message header fields.

PS. HTTPResHeader is not being used for now. Members in HTTPResHeader have not been mapped by teh Micro HTTP Server library, because ones may have the HTTP response string directly to have better performance.

Declare and define HTTP response message structure

typedef struct _HTTPResMessage {
	HTTPResHeader Header;
	uint8_t *Body;
	uint8_t *_buf;
	uint16_t _index;
} HTTPResMessage;

It is whole HTTP response message.

• Header: The HTTP response message header.
• Body: The character string pointer of this HTTP response message body.
• _buf: The real buffer where the HTTP response message located which is a character string pointer.
• _index: The length of the real buffer in bytes.

HTTP request callback function pointer type

typedef void (*HTTPREQ_CALLBACK)(HTTPReqMessage *req, HTTPResMessage *res);

The callback function pointer type of the HTTP request.

Arguments

• req: The parsed HTTP request message.
• res: The HTTP response message.

PS. Both req and res have allocated memory spaces for buffers by the Micro HTTP Server library.

Functions

Initial HTTP server

void HTTPServerInit(HTTPServer *srv, uint16_t port);

Initial Micro HTTP Server with designated listening port.

Arguments

• srv: The pointer of HTTP server instance.
• port: Server listening port number.

Make HTTP server being running

void HTTPServerRun(HTTPServer *srv, HTTPREQ_CALLBACK callback);

or

#define HTTPServerRunLoop(srv, callback) { \
	while(1) { \
		HTTPServerRun(srv, callback); \
	}}

HTTPServerRun will check the server socket and all of interesting client sockets, then parse the requests and send the responses one time.
HTTPServerRunLoop will do the works that HTTPServerRun does forever.

Arguments

• srv: The pointer of HTTP server instance.
• callback: The callback function will be executed when HTTP server gets a new HTTP request message.

Close HTTP server

void HTTPServerClose(HTTPServer *srv);

Close the HTTP server.

Arguments

• srv: The pointer of HTTP server instance.

C API - Middileware Library

Macro defined varables

These macros should be customized according to your application by yourself.

• MAX_HTTP_ROUTES 10

  Amount of HTTP URI routes.

• STATIC_FILE_FOLDER "static/"

  Static files' sub-directory path.

Datatypes

Declare server application function (SAF) datatype

typedef HTTPREQ_CALLBACK SAF;

Define server application function (SAF) datatype.

Functions

Add a HTTP Route

int AddRoute(HTTPMethod method, char *uri, SAF saf);

Add a request method, URI and the corresponding server application function (SAF) into the route table.

Arguments

• method: HTTP request method.
• uri: HTTP request URI.
• saf: The server application function (SAF) will be executed when HTTP server gets a matech HTTP request method and URI.

Dispatch the HTTP Method and URI

void Dispatch(HTTPReqMessage *req, HTTPResMessage *res);

Dispatch the HTTP method and URI according to the route table.

Arguments

• req: The parsed HTTP request message.
• res: The HTTP response message.