boahttpd Files

boahttpd Library Development Manual

Last Modified: 2014-07-12
1.	Introduction

The library, boahttpd, is designed to create a cgi-featured http server (normally called as boa-server)easy and fast. That means you can easily add CGI support to your server application. It support file downloading by default, like any other web servers.

Its written in C++ inside, but provides a C-Style API which you will find it to be Object-Oriented essentially. Multiple platforms are supported with a uqique set of interface, including Windows, Linux, or Embedded systems. It will take a few minutes to get to know how to use it. 

Features:
-	Web file downloading
-	CGI support
-	Multi-thread, Multi-instance
-	Cross-Platform (Windows, Linux, other Embedded Linux)
-	Filter & Authentication support
-	Cookie support

2.	Getting Started

First you have to decide which platform your application is running on. For windows you have to take  ¡® boahttpd.lib/.dll¡¯  into your project, plus the header file ¡®boahttpd.h¡¯.  For linux(x86),  a release built under Fedora14 is provided , which will work correctly under  those systems similar  (I mean the kernel version ) to Fedora 14. 

For embedded systems, such as linux (arm), your have to provide the specific toolchains and ask for a specific build for your target platform.

2.1	A ¡®helloworld¡¯ Application
A most simple usage of the library would be like this: (see sample code `ex1`)

#include <stdio.h>
#include <stdlib.h>

/* include boahttpd library */
#include "../boahttpd.h"
#pragma comment(lib, "../boahttpd.lib")

/* start a simple web server */
int main()
{
	boa_server_t server;
	if(boa_server_create(&server, NULL, 
		"wwwroot", 
		8888, "0.0.0.0",
		NULL, NULL) < 0)
	{
		printf("failed to create server!\n");
		return 0;
	}

	getchar();
	boa_server_destroy(&server);
	return 0;
}

The code above  sets up a http server running on port 8888, and the root directory of web pages is ¡®wwwroot¡¯ folder which should be located on the current directory.  So to make things right, your have to put some files in your ¡®wwwroot¡¯ folder, for example, a ¡®index.html¡¯ as the default home page.

Now run the program,  then try the following url in your web browser:
     http://127.0.0.1:8888
or
     http://127.0.0.1:8888/image/abc.jpg
if there is a picture file located in that sub-directory: wwwroot/image/abc.jpg.


2.2	Easy CGI Application
Now we get to the key feature of the library: CGI support.  It also easy to know and to use, see  the  following snippet : (see sample code `ex2`)

static int cgi_handler(void* context, void* userdata)
{
	¡­ handle the cgi request ¡­ 
	return 0;
}

int main()
{
	boa_cgi_t cgi ;
	boa_cgi_create(&cgi);
	boa_cgi_register(&cgi, "test", &cgi_handler, NULL);

	boa_server_t server;
	if(boa_server_create(&server, &cgi, 
		"wwwroot", 8888, "0.0.0.0", NULL, NULL) < 0)
	{
		printf("failed to create server!\n");
		return 0;
	}

	getchar();

	boa_cgi_destroy(&cgi);
	boa_server_destroy(&server);
	return 0;
}


By register a callback function , cgi_handler, you could have the chance to handle the CGI request. A number of such callbacks can be register to the single boa_cgi_t object .

You can register a default handler for all request , whose name is `*`:
	boa_cgi_register(&m_cgi, "*", &cgi_handler, this);  

(Note: each CGI request is called in a NEW thread, thus the callback handler is called in that NEW thread)

Take the follow request as an example.  When you type
   http://127.0.0.1:8888/cgi/mytest?name=shaofa&height=175
in your browser, your httpd server will got a CGI request with:

Name	Value	Meaning
method	GET	The HTTP method, ¡®GET¡¯ or ¡®POST¡¯
service	mytest	The name of the CGI service
argument	name=shaofa&height=175	The argument passed with the URL
content		Vaild if the method is ¡®POST¡¯
HTTP FIELD		Any other HTTP head field
Socket 		The socket handle

   The following snippet shows how to retrieve  those values:

static int cgi_handler(void* context, void* userdata)
{
	const char* service = boa_cgi_name(context);
	const char* method = boa_cgi_method(context);
	const char* argument = boa_cgi_args(context);
	const char* content = boa_cgi_content(context);

	const char* anyfield = boa_cgi_field(context,¡±Content-Length¡±);
      int sock = boa_cgi_socket(context);
}

If you want to reply an error message , just call:
     boa_cgi_send_error ( context, status, reason);
If you want to reply an 200 OK message with a text content, just call:
     boa_cgi_send_text(context, ¡°¡­¡­¡±, CONTENT_TYPE_TXT);

Keep in mind that the framework has already created a thread for each CGI request,  you need not to create a thread yourself. 

2.3	Advanced CGI Application
Now we are talking about how to use the API in C++ manner. Support we want to create a http server object,  the sample code would be like below. (see sample code `complex`)

////////////////  .h /////////////////////   
class MyHttpd  
{  
public:  
    int Open(int port, const char* ip);  
    void Close();  
    int HandleCgiRequest(void* context);  
private:      
    boa_cgi_t    m_cgi;  
    boa_server_t  m_server;  
}  
  
///////////////////////////// *.cpp /////////////////////////////   
static int cgi_handler(void* context, void* userdata)  
{  
    MyHttpd*  server = (MyHttpd*) userdata;                     
    server->HandleCgiRequest(context);   
    return 0;  
}  
int MyHttpd::Open(int port, const char* ip)  
{  
boa_cgi_create(&cgi);  
// set userdata to `this`   
boa_cgi_register(&cgi, "test", &cgi_handler, this);  
boa_server_create(&server,&cgi,  "wwwroot", 
8888, "0.0.0.0", NULL, NULL) ;     
    return 0;  
}  
int int MyHttpd::HandleCgiRequest(void* context)  
{   
    const char* service = boa_cgi_name(context);  
    ...  
}  
......

6.	Help Information

E-Mail:   1926583112@qq.com

Official Website:  http://sourceforge.net/projects/boahttpd/