A C++ Embedded Web Server

Download source - 22.61 KB

Download demo - 305.07 KB

Introduction

Do you have a web page or two? Nothing fancy, perhaps, but a neat demonstration of what can be achieved with with a handful of HTML tags?  Do you have a sophisticated C++ windows desktop application which now needs to be controlled and monitored remotely? So, without learning a whole new technology, let's give your application its own web page!

Webem is a web server that you can embed in your C++ application. It makes it easy to implement a browser GUI accessible from anywhere.

Webem is based on a minimally modified version of the boost::asio web server, and permits html code to execute C++ methods.

Background

The available embedded C++ web servers are a challenge to use, and tend not to be Windows friendly. They are not the kind of thing you want to get into just to add the ability to monitor your lab application from your cell phone. 

I  have tried Wt ( http://www.webtoolkit.eu/wt ) but was defeated by the installation and learning curve.

I recently began using Webio by John Bartas . I liked the concept and it worked well.

However, I still found it overly complicated to use and the server code hard to understand. I wanted something easier to use, based on a well known web server that had only been slightly modified.

A lot of the complexity of Webio is caused by using an “HML compiler” to hide the HTML pages that control the appearance of the GUI inside a file system embedded inside the application code. I prefer to have the HTML pages outside in plain view where I can adjust the GUI without recompiling the application.

I learned a lot trying to adjust Webio to my taste, and eventually was ready to build my own exactly to my requirements.

Using the Code

You build your application's GUI exactly like you build a web site - create pages using HTML all starting from index.html.

Now you need to make the HTML invoke your C++ methods. There are two things you can do:

• create include methods which generate HTML to be included in the web pages,
• create action methods called by webem when the user clicks on buttons in the web page,
• create "web controls", a combination of the previous two where an include method generates a form which invokes an action method when the user clicks on a button - the "Calendar" example application shows how to create a control to display and update a database table.

"Hello, World"

Step1: Create the web page. This can be as elaborate as you like, but let's keep it simple for our first "hello, world" application

The Webem Embedded Web server says:  <!--#webem hello -->

The text in angle brackets tells webem where you want to include text from the application, and "hello" is the code for the particular application method that must be invoked to provide the included text

Step2:Create the class which says hello

/// An application class which says hello
class cHello
{
public:
	char * DisplayHTML()
	{
		return "Hello World";
	}
};

Step3:Initialise Webem, telling it the address and port to listen for browser requests and where to find the index.html that begins the web page.

	// Initialise web server.

    http::server::cWebem theServer(
		"0.0.0.0",				// address
               "1570",					// port
	         ".\\");					// document root

 

Step4: Register the application method with webem

	cHello hello;

	// register application method
	// Whenever server sees <!--#webem hello -->
	// call cHello::DisplayHTML() and include the HTML returned

	theServer.RegisterIncludeCode( "hello",
		boost::bind(
		&cHello::DisplayHTML,	// member function
		&hello ) );			// instance of class

Step4: Finally, you are ready to start the server running.

	// run the server
	theServer.Run();

A Formal Hello

Let's create a more polite program, which addresses the world by name. ( CodeProject is, after all, Canadian. )

Step1: Create the website

What is your name, please?
<form action=name.webem>
<input name=yourname /><input value="Enter" type=submit />
</form>

The Webem Embedded Web server says: <!--#webem hello -->

The form provide a field to enter the user's name, and a button to submit the entered name to the server. The form attribute "action=name.webem" ensures that the webem server will call the application method registered with "name" to process the input.

Step2: Create the application class

/// An application class which says hello to the identified user

class cHelloForm
{
string UserName;
http::server::cWebem& myWebem;

public:
	cHelloForm( http::server::cWebem& webem ) :
	  myWebem( webem )
	{
		myWebem.RegisterIncludeCode( "hello",
		boost::bind(
		&cHelloForm::DisplayHTML,	// member function
		this ) );			// instance of class
		myWebem.RegisterActionCode( "name",
		boost::bind(
		&cHelloForm::Action,	// member function
		this ) );			// instance of class
	}
	char * DisplayHTML()
	{
		static char buf[1000];
		if( UserName.length() )
		sprintf_s( buf, 999,
			"Hello, %s", UserName.c_str() );
		else
			buf[0] = '\0';
		return buf;
	}
	char * Action()
	{
		UserName = myWebem.FindValue("yourname");
		return "/index.html";
	}
};

The application class stores a reference to the webem server. This allows it to look after registering its own methods with the server when it is constructed, and to call the cWebem class FindValue() to extract the value of the field entered into the form.

The application class must register two methods, one to save the entered user name when the submit button is clicked, one to display the stored user name when the web page is assembled and sent to the browser.

The action methods must return the webpage which should be displayed in response to the click on the submit button.

Note that all action methods are invoked by Webem before the include methods, so that the web page always displays updated data.

Step3: Construct webem, construct the application class and run the server

	// Initialise web server.

    http::server::cWebem theServer(
		"0.0.0.0",						// address
		"1570",							// port
		".\\");							// document root

	// Initialize application code

	cHelloForm hello( theServer );

	// run the server

	theServer.Run();

You may need to run the server in another thread, perhaps so your application can continue logging data from a lab device. To do this, modify the call to server::run

		boost::thread* pThread = new boost::thread(
		boost::bind(
		&http::server::server::run,	// member function
		&theServer ) );			// instance of class

Webem Controls

Webem Controls are classes which look after the details of displaying and manipulating application data in standard ways, so that the application programmer does not need to be concerned with all the details of generating HTML text

The demo application uses a webem control to list the contents of a SQLITE database table with the ability to add or delete records. There is a screenshot at the top of this article.

More webem controls, detailed documentation and the latest code are available here.

Points of Interest

This section describes how webem is integrated with the server. It is not necessary to read this in order to use webem.

The boost::asio http server invokes the method request_handler::handle_request( const request& req, reply& rep). This is where the browser requests are parsed and the new page assembled to be sent back to the browser. We need to override this method in a specialization of the request handler so that, in turn, the registered application methods can be invoked.

void cWebemRequestHandler::handle_request( const request& req, reply& rep)
{
	// check for webem action request
	request req_modified = req;
	myWebem.CheckForAction( req_modified.uri );

	// call base method to do normal handling
	request_handler::handle_request( req_modified, rep);

	// Find and include any special cWebem strings
	myWebem.Include( rep.content );

}

Unfortunately, the boost::asio server, although otherwise very elegantly designed and implemented, has not been designed with inheritance in mind. In order to allow the server to invoke the webem request handler I have made the minimal changes to the boost code

• Made request_handler::handle_request method virtual so specialized override will be called
• Changed server constructor to accept a reference to the request_handler it will use.
• Changed order of server attributes, so that the connection handler will not be initialized before the the request handler.

Here is the patch

>hg diff -U1 -r 0 -r 1 --nodates
diff -r 32dc1a479036 -r 86a6e2a3ff58 src/webem/server/request_handler.hpp
--- a/src/webem/server/request_handler.hpp
+++ b/src/webem/server/request_handler.hpp
@@ -31,3 +31,3 @@
   /// Handle a request and produce a reply.
-  void handle_request(const request& req, reply& rep);
+  virtual void handle_request(const request& req, reply& rep);

diff -r 32dc1a479036 -r 86a6e2a3ff58 src/webem/server/server.cpp
--- a/src/webem/server/server.cpp
+++ b/src/webem/server/server.cpp
@@ -17,3 +17,3 @@
 server::server(const std::string& address, const std::string& port,
-    const std::string& doc_root)
+    request_handler& user_request_handler )
   : io_service_(),
@@ -23,3 +23,3 @@
           connection_manager_, request_handler_)),
-    request_handler_(doc_root)
+    request_handler_( user_request_handler)
 {
diff -r 32dc1a479036 -r 86a6e2a3ff58 src/webem/server/server.hpp
--- a/src/webem/server/server.hpp
+++ b/src/webem/server/server.hpp
@@ -31,3 +31,3 @@
   explicit server(const std::string& address, const std::string& port,
-      const std::string& doc_root);
+      request_handler& user_request_handler );

@@ -55,2 +55,5 @@

+  /// The handler for all incoming requests.
+  request_handler& request_handler_;
+
   /// The next connection to be accepted.
@@ -58,4 +61,2 @@

-  /// The handler for all incoming requests.
-  request_handler request_handler_;
 };
 

History

2008 Sep 12 - First release

2008 Sep 15 - Moved server construction into cWebem constructor, which simplifies application code
- Provided two simpler examples, "Hello World" and "Formal Hello"  

2008 Sep 29 - Fixed quotes in code fragments ( I hope! )

You must Sign In to use this message board.

FAQ  Noise Tolerance Very HighHighMediumLowVery Low  Search Messages    Layout Expand All MessagesThread ViewNo Javascript (slow)No Javascript Preview    Per page 102550

Msgs 1 to 13 of 13 (Total in Forum: 13) (Refresh) FirstPrevNext

webem rocks Brett Goldberg 17:36 24 Nov '08   Just a quick note of thanks for this amazing contribution. WEBEM opens up a whole new world of possibilities. It totally changes the architecture of an app that I am working on: instead of pumping gigs of data up to the web, we can now pull it via AJAX from the machine where it resides up to the web. What a perfect solution for web queries that involve huge amounts of data. For my level as a C++ coder, this is exactly what the doctor ordered. My hat's off to you sir. Brett Goldberg Sign In·View Thread·PermaLink Re: webem rocks ravenspoint 17:43 24 Nov '08   Thank you! Sign In·View Thread·PermaLink Boost Jerry Jeremiah 13:39 14 Sep '08   Assuming you haven't, you should submit the diff to Boost. The whole point of open source software is that it can be improved by its users. I don't see how the changes you have made would not be beneficial to the entire Boost community. Jerry Sign In·View Thread·PermaLink Re: Boost ravenspoint 2:40 15 Sep '08   It is nice to hear from New Zealand. I would like to submit my changes to the boost::asio example httpd server. Specializing the example code by inheriting it and over-riding the request handler without having to touch any of the asio communications code seems a much safer, and certainly faster, way of leveraging the boost code into new applications. I have been hesitating because I find the boost development community quite intimidating - those boys and girls are very, very technical. With your encouragement, I will certainly look into submitting my changes. Sign In·View Thread·PermaLink Wt -> webtoolkit.eu pgquiles 2:21 13 Sep '08   For supersimple web applications, developing your own C++ embedded web server is OK but if you need to do something "real", which needs scalability, ease of development (no need to write HTML, CSS or Javascript), multithread, etc, use Wt (there are packages available for Debian and Ubuntu under the name witty) Sign In·View Thread·PermaLink 5.00/5 (1 vote) Re: Wt -> webtoolkit.eu ravenspoint 3:39 13 Sep '08   Thank you for your comment, which is perfectly correct if you are aiming to develop web applications. Webem is intended to quickly provide an adequate web GUI for "real" desktop applications. I am thinking of the kind of application that is too compute intensive to run on the virtual machines offered by browsers on the client side. Web 2.0 applications are great when hundreds or thousands of clients each bring their own bit of compute power for some small task, such as editing and submitting a forum message. I also imagine using webem for an application that runs on some special hardware, for example connected to a laboratory analyser, and has one or two clients monitoring and configuring it from a remote location, perhaps using their cell phone. The neat thing is that the developer does not have to learn to use a new toolkit, merely add a little bit of familiar C++ and HTML. Thank you again for your provocative comment. I was thinking of adding a motivation section, "Why an embedded web server in a Web 2.0 world?" and now I am half way there! Sign In·View Thread·PermaLink Re: Wt -> webtoolkit.eu pgquiles 4:02 13 Sep '08   I also imagine using webem for an application that runs on some special hardware, for example connected to a laboratory analyser, and has one or two clients monitoring and configuring it from a remote location, perhaps using their cell phone. That's exactly the market Wt is addressed to: embedded. the developer does not have to learn to use a new toolkit, merely add a little bit of familiar C++ and HTML. In my experience (YMMV), C++ developers are more familiar with widgets than with HTML, and that's exactly what Wt provides: a widget toolkit (in fact it mimics the API of Trolltech's Qt). Sign In·View Thread·PermaLink Re: Wt -> webtoolkit.eu ravenspoint 4:49 13 Sep '08   I looked at Wt about a year ago, when I first realized that I wanted ( needed? ) something like this. I did not recognize the name at first: it is a cute name but not so distinctive. Perhaps I also misunderstood your first post, for you are perfectly right: Wt is designed to do exactly what webem is designed to do. Unfortunately, I found Wt to be incredibly complex and elaborate. The installation alone taxed me to the limit ( I assume you have improved this since then. ) I barely began on the learning curve before realizing that it was way longer than I cared for. Perhaps you need a gentle introduction, something with training wheels? Perhaps you already have done this, since I looked. ( The time was when Dr Dobbs published an article ) Webem is, I hope, extremely simple and quick to get going. Sign In·View Thread·PermaLink Re: Wt -> webtoolkit.eu pgquiles 4:59 13 Sep '08   The installation alone taxed me to the limit ( I assume you have improved this since then. ) I'm not a developer of Wt, just a happy user (I develop with Wt but I do not develop Wt itself) and the Debian and Ubuntu packager (but I'm not paid to do that). I agree installation on Windows and Mac is not that easy yet, as you need to build everything yourself. Prebuilt binaries on Windows and Mac would be nice. Building on Linux/BSD/Solaris is quite easy. With regard to documentation, Wt is easy if you know Qt ( http://doc.trolltech.com ). More documentation would be welcome, of course. Sign In·View Thread·PermaLink 2.00/5 (1 vote) Re: Wt -> webtoolkit.eu Iggy Natich 4:54 13 Sep '08   Wt is interesting beast, but embedded web server and widget toolkit for web applications are completely different things. If you want to help wt community - write articles about it for codeproject. Sign In·View Thread·PermaLink 5.00/5 (2 votes) Re: Wt -> webtoolkit.eu ravenspoint 4:59 13 Sep '08   I have added a link to Wt in the background section of the article. Sign In·View Thread·PermaLink Re: Wt -> webtoolkit.eu kdeforche 22:40 21 Sep '08   Hey all, As an author of Wt, I am probably biased . But anyway. I am at the same time not really surprised that you find Wt complicated to install (the dependency libraries boost and boost::asio are not straight forward and in many cases not well supported by distributions), but then again I am surprised that you also develop a library which has exactly the same dependencies, and at the same time provide this as one of your arguments for not using Wt. Perhaps we communicate it badly on our website, but Wt has as only required dependency boost >= 1.35 (which includes boost::asio). Alternatively, if you want to use an older boost library, you will need a standalone boost::asio. Obviously if you want compression you need zlib and if you want to support you'll want OpenSSL, but those libraries are optional. Secondly, I agree with Pau: "simple" or "steep learning curve" depends on your background. If your affinity for HTML/CSS (+JavaScript/AJAX) is sufficient for your project or if you do not have any experience with Qt or other desktop GUI APIs, then Wt may not seem straight forward. In all other situations, Wt is a library that will scale nicely with your application complexity. Finally, I do not agree that AJAX is only for the benefit of large scale internet web applications. On the contrary, in our experience AJAX is really well suited for deployment on low-powered embedded systems since you do not need to re-render the whole page anytime you communicate with the server. In this way, Wt applications can maintain a large screen complexity but still be well performing on embedded systems because the requests and responses are "to the point", allowing you to frequently communicate small bits of information for typical status update pages. koen Sign In·View Thread·PermaLink Re: Wt -> webtoolkit.eu ravenspoint 12:50 22 Sep '08   I want to thank the Wt project people for the interest they have shown in Webem. Last week I did a new install of Wt. It went much better this time. This seems to be due to the upgrade to boost v1.35 and Visual C++ 2008. The only remaining installation issue I have is that building Wt takes more than an hour, which seems excessive to me. The learning curve still seems intimidating. I could not find an introductory tutorial which describes how to create the example programs and the code is certainly not self explanatory. The Wt people say that it is easy to learn Wt if you know Qt. Perhaps so, but having decided that knowing Qt is a pre-requisite for adopting Wt, I do not think that it is reasonable for them to be surprised when non Qt experts look for something simpler to use. If I may offer some advice, perhaps Wt should provide a gentle introductory tutorial to using Wt for the non Qt programmer? Without such a tutorial, I believe they are cutting themselves off from a large number of potential users. IMHO many people will find Webem attractive for developing simple Web GUIs for C++ programs because the installation is trivial and the only knowledge required is C++ and a very little HTML. Sign In·View Thread·PermaLink 5.00/5 (1 vote)

Last Visit: Tuesday, December 2, 2008 2:22 AM     Last Update:Tuesday, December 2, 2008 2:22 AM