Functions

Functions
int32_t	http_server_init (user_type *user, mmc_function_type *(*d8900_init_mmc)(void), int32_t max_connections)
	Initialize HTTP server. More...
void	http_define_callback (int32_t(*callback_func)(httpserv_type *))
	Define a user callback function for HTTP requests. More...
int32_t	http_interpreter (httpserv_type *http_server)
	User defined callback function. More...
void	websocket_define_callback (int32_t(*callback_func)(ws_socket_type *))
	Define a user callback function for websocket requests. More...
void	http_set_authentication (char *auth_name, char *auth_key, direntry_type *err401, direntry_type *dir_list,...)
	Initialize a secure web page. More...
int32_t	http_get_uri (httpserv_type *http_server)
	Search user defined Uniform Resource Identifiers (URI) list for requested uri. More...
int32_t	http_send_user_page (httpserv_type *http_info, user_type *puser, int32_t uri)
	Send user defined webpage. More...
int32_t	http_send_uri (httpserv_type *http_server, direntry_type *uri)
	Send URI using the specified URI without looking up in user list. More...
http_con_type *	http_set_up_page (httpserv_type *http_info, user_type *puser, int32_t uri)
	set up a page for later transmission More...
int32_t	http_send_page (http_con_type *con)
	start page transmission More...
int32_t	http_server (void)
	The main polling function for concurrent HTTP server. More...
void	http_set_index_page (uint32_t page)
	Define index page. More...
int32_t	http_add_page (direntry_type *uri)
	Dynamically add a webpage during runtime. More...
int32_t	http_send_websocket (ws_socket_type *ws, char *buffer, uint32_t length)
	send a message over connected websocket More...

Detailed Description

HTTP Server

Function Documentation

int32_t http_server_init	(	user_type *	user,
		mmc_function_type *(*)(void)	d8900_init_mmc,
		int32_t	max_connections
	)

This function is the main HTTP server initialization function. It must be called once after net_init() to install the HTTP service. The user list must contain the keyword "webserver" as user name for a valid service name. Any other or additional user names are not allowed. d8900_init_mmc() is an old and obsolete MMC initialization function for the D.Module.CS8900. Any webpage access can lead to a number of parallel opened connections. All sockets and all temporary information for each connection is taken from heap. If you want to limit the heap consumption, use parameter max_connection.

Parameters

*user	- used for authorize users for HTTP access
*d8900_init_mmc	- not available on DSK
max_connections	- specifies the maximum concurrent connections

Returns

• TRUE => HTTP server was successfully installed
• FALSE => out of memory

Library:

http.lib

Prototype:

httplib.h

Examples:

HTTPdynamic.c, HTTPjava.c, and HTTPsimple.c.

void http_define_callback

(

int32_t(*)(httpserv_type *)

callback_func

)

This function installs a user callback function. It must be called at least once or any time the callback function has to be changed.

Parameters

(*callback_func)()

- pointer to user callback function

Returns

-

Library:

http.lib

Prototype:

httplib.h

See also

http_interpreter()

Examples:

HTTPdynamic.c, HTTPjava.c, and HTTPsimple.c.

int32_t http_interpreter

(

httpserv_type *

http_server

)

This callback function must be implemented by user. It is called each time a web page is requested or data is received.

Parameters

http_server

- current http server connection

Returns

• _HTTP_CLOSE_CONNECTION => close connection
• _HTTP_KEEP_ALIVE => keep alive

Library:

http.lib

Prototype:

httplib.h

Note

Parameter *http_server is only valid within the context of this function. Don't use it for later transmission!

See also

httpserv_type

"http_define_callback ( http_interpreter);"

Skeleton function:

int32_t http_interpreter (httpserv_type *http_server)
{
    // ************************************************************************
    // locals
    // ************************************************************************
    int32_t  ret = _HTTP_CLOSE_CONNECTION;

    // ************************************************************************
    // Execute specific method
    // ************************************************************************
    switch (http_server -> method)
    {
        case _HTTP_GET:
            if ( http_server -> uri == -1 )
            {
                // ************************************************************
                // uri not found: send user defined not-found-message
                // ************************************************************

                http_send_uri (http_server, &e404);
            }
            else
            {
                // ************************************************************
                // send the requested page
                // ************************************************************
                if ( http_send_user_page (http_server,
                                          user,
                                          http_server -> uri ) <= 0)
                {
                   // *********************************************************
                   // page could not be sent immediately, keep connection alive
                   // and try again later
                   // *********************************************************
                   ret = _HTTP_KEEP_ALIVE;
                }
            }
            break;

        case _HTTP_UNKNOWN :                 // unknown method
            // ****************************************************************
            // method not implemented or syntax error
            // ****************************************************************
            http_send_uri (http_server, &e501);
            break;
    }

    // ************************************************************************
    // back to http server
    // ************************************************************************
    return (ret);
}

{
    /***************************************************************************
     locals
    ***************************************************************************/
    int32_t  ret = _HTTP_CLOSE_CONNECTION;
    int i;

    /***************************************************************************
     Execute specific method
    ***************************************************************************/
    switch (http_server-> method)
    {
        case _HTTP_GET:
            /*******************************************************************
             uri is the requested directory index
            *******************************************************************/
            if ( http_server-> uri == -1 )
            {
                /***************************************************************
                 uri not found: send user defined not-found-message
                ***************************************************************/
                http_send_uri (http_server, &e404);
            }
            else
            {
                if ( http_server-> uri == index.index)
                {
                /***************************************************************
                 If the requested page is the index page, parse form arguments
                 and toggle leds.
                 The form command in index.htm cause a request in the form:
                 GET index.htm?Led1=1&Led2=1&Led3=1&Led4=1 HTTP 1.1 ....
                 The http_server argument list holds all form parameters
                 including the requested form:
                     http_server-> argc = 9;
                     http_server-> argv[0] = "index.htm";
                     http_server-> argv[1] = "Led1";
                     http_server-> argv[2] = "1";
                     http_server-> argv[3] = "Led2";
                     http_server-> argv[4] = "1";
                     .
                     .
                     .
                ***************************************************************/
                    for ( i = 1; i<http_server-> argc;i++)
                    {
                        if ( !strncmp (http_server-> argv[i], "Led1", 4) )
                        {
                            toggle_led (&led1, 0);
                        }
                        if ( !strncmp (http_server-> argv[i], "Led2", 4) )
                        {
                            toggle_led (&led2, 1);
                        }
                        if ( !strncmp (http_server-> argv[i], "Led3", 4) )
                        {
                            toggle_led (&led3, 2);
                        }
                        if ( !strncmp (http_server-> argv[i], "Led4", 4) )
                        {
                            toggle_led (&led4, 3);
                        }
                    }

                    /***********************************************************
                     update led-status
                    ***********************************************************/
                    UpdateLedStates();
                } // if

                /***************************************************************
                 send the requested page
                ***************************************************************/
                if ( http_send_user_page (http_server,
                                          user,
                                          http_server-> uri ) <= INT32_C(0))
                {
                    /***********************************************************
                     page could not be sent immediately, keep connection alive
                     and try again later
                    ***********************************************************/
                    ret = _HTTP_KEEP_ALIVE;
                }
            }
            break;

        case _HTTP_UNKNOWN :                 /* unknown method                */
            /*******************************************************************
             method not implemented or syntax error
            *******************************************************************/
            http_send_uri (http_server, &e501);
            break;
    }

    /***************************************************************************
     back to http server
    ***************************************************************************/
    return (ret);
}

void websocket_define_callback

(

int32_t(*)(ws_socket_type *)

callback_func

)

This function installs a user callback function.

Parameters

(*callback_func)()

- pointer to user callback function

Returns

-

Library:

http.lib

Prototype:

httplib.h

void http_set_authentication	(	char *	auth_name,
		char *	auth_key,
		direntry_type *	err401,
		direntry_type *	dir_list,
			...
	)

If one or more webpages should be authenticated before the content is transmitted, use http_set_authentication(). The authentication name and key are case sensitive. The first page must be the user defined authentication failed message err401.

Parameters

auth_name	- web page name
auth_key	- authentication username and password
err401	- user defined 'Authentication required' message
dir_list	- list of secure web pages

Returns

nothing

Library:

http.lib

Prototype:

httplib.h

Note

The dir list must be terminated with a double zero:

See also

direntry_type

http_set_authentication ("Secure Webpage", authentication_key, &e401,
                         &secure_page, 0, 0 );

Examples:

HTTPsimple.c.

int32_t http_get_uri

(

httpserv_type *

http_server

)

Parameters

http_server

- current http connection referenced by user callback function

Returns

• (-1) the requested URI was not found
• (0..n) index of web page specified in urilist

Library:

http.lib

Prototype:

httplib.h

Note

The URI is index of the specified webpage in user list:

See also

httpserv_type

user_type user[] =
{
    {"webserver", "*" , &URI0, &URI1, &URI2, &URI3, .... , 0},
    //  index             0      1      2      3  ...
};

int32_t http_send_user_page	(	httpserv_type *	http_info,
		user_type *	puser,
		int32_t	uri
	)

This function starts the transmission of a requested webpage or element referenced by index. The index is used to access the requested webpage from the user list.

Parameters

http_info	- current http connection referenced by user callback function
puser	- is a pointer to current user directory
uri	- specifies the URI (referenced by index) to send

Returns

• (-1) if out of memory
• ( 0) the URI is invalid
• ( 1) on success

Library:

http.lib

Prototype:

httplib.h

Note

uri is the index of the specified webpage in user list:

use this function only in context of your http_interpreter

See also

user_type, httpserv_type

http_send_uri(), http_set_up_page()

user_type user[] =
{
    {"webserver", "*" , &URI0, &URI1, &URI2, &URI3, .... , 0},
    //  index             0      1      2      3  ...
};
...
   int32_t http_interpreter (httpserv_type *http_server)
   {
   ....
       if ( http_server -> uri == -1 )
       {
           // **************************************************************
           //  uri not found: send user defined not-found-message
           // **************************************************************
           http_send_uri (http_server, &e404);
       }
       else
       {
           // **************************************************************
           //  send the requested page
           // **************************************************************
           if ( http_send_user_page (http_server,
                                     user,
                                     http_server -> uri ) <= 0)
           {
               // **********************************************************
               // page could not be sent immediately, keep connection alive
               // and try again later
               // **********************************************************
               ret = _HTTP_KEEP_ALIVE;
           }
       }

Examples:

HTTPdynamic.c, HTTPjava.c, and HTTPsimple.c.

int32_t http_send_uri	(	httpserv_type *	http_server,
		direntry_type *	uri
	)

Use this function to send a webpage for a given direntry. It is also useful to send pages not included with the user list (e.g. error messages).

Parameters

http_server	- current http connection referenced by user callback function
*uri	- specifies the URI to send

Returns

• (-1) if out of memory
• ( 0) the URI is invalid
• ( 1) on success

Library:

http.lib

Prototype:

httplib.h

Note

Useful for sending error messages.

See also

direntry_type, httpserv_type

direntry_type E404 = {"e404" , "e404.htm" , sizeof(e404_c) ,
                      FTP_RW | FTP_RAM, 'A',
                      (uint32_t)e404_c };
.
.
http_send_uri (http_info, &E404);

Examples:

HTTPdynamic.c, HTTPjava.c, and HTTPsimple.c.

http_con_type* http_set_up_page	(	httpserv_type *	http_info,
		user_type *	puser,
		int32_t	uri
	)

On success this function returns a pointer to a new http_con structure. The memory for this structure is taken from heap and must be freed later by function http_send_page(). The HTTP interpreter callback function should return _HTTP_KEEP_ALIVE to deactivate the shutdown timer. Use function http_send_page() with parameter http_con later in your program to start transmission over this socket.

Parameters

http_info	- the current http connection referenced by user callback function
puser	- a pointer to current user directory
uri	- specifies the URI to send

Returns

• NULL - invalid page or out of memory
• !NULL - pointer to new http_con_type structure containing destination port and address

Note

use this function if the requested data is not yet available but should be transmitted later (e.g. after a DMA is ready)

Warning

this function requires a later call to http_send_page() to free memory

Library:

http.lib

Prototype:

httplib.h

See also

user_type, direntry_type, httpserv_type

http_send_page()

http_con = http_set_up_page (http_server,
                             user,
                             http_server-> uri );

if ( http_con == NULL )
{
    // *********************************************************************
    // out of memory
    // *********************************************************************

} // if
else
{
    // *********************************************************************
    // valid connection, use http_send_page(http_con) later to send data
    // *********************************************************************
}

int32_t http_send_page

(

http_con_type *

con

)

This function starts a page transmission. The transmission must have been set up before with function http_set_up_page(). All temporary allocated memory by function http_set_up_page() is freed.

Parameters

con	- the current http connection

Returns

• (1) connection invalid or not found
• (0) on success

Library:

http.lib

Prototype:

httplib.h

See also

http_send_page()

int32_t http_server

(

void

)

Parameters

-

Returns

• (< 0) server out of memory
• (>= 0) number of parallel connections

Library:

http.lib

Prototype:

httplib.h

Note

Must be called regularly with net_isq() in the main loop.

 int main ( void )
 {
    ...

    // *************************************************************************
    //  main program loop: set main_loop to 0 to exit loop
    // *************************************************************************
    while ( main_loop )
    {
        // *********************************************************************
        //  call net_isq() and http_server()
        // *********************************************************************
        net_isq ();
        http_server ();
    }

    // *************************************************************************
    //  exit program, shut down peripherals
    // *************************************************************************
    return(0);
}

Examples:

HTTPdynamic.c, HTTPjava.c, and HTTPsimple.c.

void http_set_index_page

(

uint32_t

page

)

Since revision 2.79 the index page is determined automatically. If another uri should be the default index page call http_set_index_page().

Parameters

page	- index page

Returns

nothing

Library:

http.lib

Prototype:

httplib.h

user_type user[] =
{
    {"webserver", "*" , &URI0, &URI1, &URI2, &URI3, .... , 0},
    //  index             0      1      2      3  ...
};
...
   // set URI2 as index page
   http_set_index_page(2);

int32_t http_add_page

(

direntry_type *

uri

)

Parameters

uri	- webpage or element to add

Returns

• (0) success
• (-1) error, no webserver available or max directory limit reached

Library:

http.lib

Prototype:

httplib.h

See also

direntry_type

direntry_type E404 = {"e404" , "e404.htm" , sizeof(e404_c) ,
                      FTP_RW | FTP_RAM, 'A',
                      (uint32_t)e404_c };
.
.
http_add_page (&E404);

Examples:

HTTPdynamic.c, and HTTPjava.c.

int32_t http_send_websocket	(	ws_socket_type *	ws,
		char *	buffer,
		uint32_t	length
	)

Parameters

ws	- connected websocket
buffer	- buffer to data to send
length	- size of data to send

Returns

• NET_SEND_SUCCESS (>0) - message was send immediately
• NET_SEND_PENDING (=0) - message could not be delivered immediately, it was passed to protocol stack for delivery, read socket_struct ->error_code for details
• NET_SEND_ERROR (<0) unrecoverable error

Library:

http.lib

Prototype:

httplib.h