|
|
Boost-Commit : |
From: lists.drrngrvy_at_[hidden]
Date: 2007-08-03 22:53:09
Author: drrngrvy
Date: 2007-08-03 22:53:07 EDT (Fri, 03 Aug 2007)
New Revision: 38436
URL: http://svn.boost.org/trac/boost/changeset/38436
Log:
adding some docs
Added:
sandbox/SOC/2007/cgi/libs/cgi/doc/index.html (contents, props changed)
sandbox/SOC/2007/cgi/libs/cgi/doc/src/
sandbox/SOC/2007/cgi/libs/cgi/doc/src/acknowledgements.qbk (contents, props changed)
sandbox/SOC/2007/cgi/libs/cgi/doc/src/cgi.qbk (contents, props changed)
sandbox/SOC/2007/cgi/libs/cgi/doc/src/introduction.qbk (contents, props changed)
sandbox/SOC/2007/cgi/libs/cgi/doc/src/links.qbk (contents, props changed)
sandbox/SOC/2007/cgi/libs/cgi/doc/src/preface.qbk (contents, props changed)
sandbox/SOC/2007/cgi/libs/cgi/doc/src/reference.qbk (contents, props changed)
sandbox/SOC/2007/cgi/libs/cgi/doc/src/tips.qbk (contents, props changed)
sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/
sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/async_ops.qbk (contents, props changed)
sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/building.qbk (contents, props changed)
sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/getting_started.qbk (contents, props changed)
sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/handling_requests.qbk (contents, props changed)
sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/meta_data.qbk (contents, props changed)
sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/protocols.qbk (contents, props changed)
sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/request_objects.qbk (contents, props changed)
sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/
sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial.qbk (contents, props changed)
sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/accepting.qbk (contents, props changed)
sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/loading.qbk (contents, props changed)
sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/meta_data.qbk (contents, props changed)
sandbox/SOC/2007/cgi/libs/cgi/example/Jamfile.v2 (contents, props changed)
sandbox/SOC/2007/cgi/libs/cgi/index.html (contents, props changed)
sandbox/SOC/2007/cgi/libs/cgi/test/compile/cgi_header_check.cpp (contents, props changed)
Text files modified:
sandbox/SOC/2007/cgi/libs/cgi/doc/Jamfile.v2 | 6 ++++
sandbox/SOC/2007/cgi/libs/cgi/example/acgi/Jamfile.v2 | 3 --
sandbox/SOC/2007/cgi/libs/cgi/example/acgi/main.cpp | 55 ++++++++++++++++++++++++++++++++++++++++
sandbox/SOC/2007/cgi/libs/cgi/example/cgi/Jamfile.v2 | 3 --
sandbox/SOC/2007/cgi/libs/cgi/test/compile/reply.cpp | 4 ++
5 files changed, 64 insertions(+), 7 deletions(-)
Modified: sandbox/SOC/2007/cgi/libs/cgi/doc/Jamfile.v2
==============================================================================
--- sandbox/SOC/2007/cgi/libs/cgi/doc/Jamfile.v2 (original)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/Jamfile.v2 2007-08-03 22:53:07 EDT (Fri, 03 Aug 2007)
@@ -3,9 +3,15 @@
# subject to the Boost Software License, Version 1.0. (See accompanying
# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+<<<<<<< .mine
+project cgi/doc
+ : build-dir ../../../../bin.v2
+ ;
+=======
project cgi/doc
: build-dir ../../bin.v2
;
+>>>>>>> .r38435
import boostbook : boostbook ;
import quickbook ;
Added: sandbox/SOC/2007/cgi/libs/cgi/doc/index.html
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/index.html 2007-08-03 22:53:07 EDT (Fri, 03 Aug 2007)
@@ -0,0 +1,13 @@
+<!-- redirect for docs -->
+
+<html>
+<head>
+<meta http-equiv="refresh" content="0; URL=html/index.html">
+</head>
+<body>
+
+Automatic redirection failed, please go to
+html/index.html
+
+</body>
+</html>
\ No newline at end of file
Added: sandbox/SOC/2007/cgi/libs/cgi/doc/src/acknowledgements.qbk
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/acknowledgements.qbk 2007-08-03 22:53:07 EDT (Fri, 03 Aug 2007)
@@ -0,0 +1,12 @@
+[/
+ / Copyright (c) 2007 Darren Garvey
+ /
+ / Distributed under the Boost Software License, Version 1.0. (See accompanying
+ / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ /]
+
+[section Acknowledgements]
+
+Provided courtesy of the Google Summer of Code!
+
+[endsect]
Added: sandbox/SOC/2007/cgi/libs/cgi/doc/src/cgi.qbk
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/cgi.qbk 2007-08-03 22:53:07 EDT (Fri, 03 Aug 2007)
@@ -0,0 +1,73 @@
+[/
+ / Copyright (c) 2007 Darren Garvey
+ /
+ / Distributed under the Boost Software License, Version 1.0. (See accompanying
+ / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ /]
+
+[library CGI
+ [quickbook 1.3]
+ [version 0.01]
+ [id boost.cgi]
+ [dirname the_document_dir]
+ [copyright 2007 Darren Garvey]
+ [purpose Thoughts about CGI implementation]
+ [authors [Garvey, Darren]]
+ [license
+ Distributed under the Boost Software License, Version 1.0.
+ (See accompanying file LICENSE_1_0.txt or copy at
+ [@http://www.boost.org/LICENSE_1_0.txt])
+ ]
+]
+
+[def __cgi__ [@http://en.wikipedia.org/wiki/Common_Gateway_Interface CGI]]
+[def __scgi__ [@http://en.wikipedia.org/wiki/Simple_Common_Gateway_Interface SCGI]]
+[def __fcgi__ [@http://en.wikipedia.org/wiki/FastCGI FastCGI]]
+
+[def __asio__ [@http://asio.sourceforge.net Asio]]
+
+[def __reading_the_docs__ [link boost.cgi.intro.reading_the_docs reading the docs]]
+[def __naming conventions__ [link boost.cgi.intro.naming_conventions naming conventions]]
+
+[def __tutorial__ [link boost.cgi.tutorial tutorial]]
+
+[/
+[def __Service__ #link#to#service#concept#description#]
+
+[def __boost_thread__ #link#to#boost#thread#docs#]
+[def __IoService__ #link#to#io#service#docs#]
+[def __protocol__ #link#to#protocol#section# boost.user_guide.protocols]
+[def __ProtocolService__ boost.reference.concepts.protocol_service]
+[def __io_service__ #link#to#doxygen#reference#]
+[def __async_write__
+ __async_read__
+ __async_write_some__
+ __async_read_some__
+]
+]
+[def __accepting__ boost.cgi.user_guide.tutorial.accepting]
+[def __loading__ boost.cgi.user_guide.tutorial.loading]
+
+
+[include preface.qbk]
+
+[section User Guide]
+
+This section of the docs is for all users of the library. For details about the internals of the library see either the __sources__ or the __reference__ section.
+
+[include introduction.qbk]
+
+[include user_guide/getting_started.qbk]
+
+[include user_guide/protocols.qbk]
+
+[include user_guide/tutorial.qbk]
+
+[endsect]
+
+
+[xinclude ../cgi_dox.boostbook]
+
+[/xinclude ../output.boostbook]
+
+[include reference.qbk]
Added: sandbox/SOC/2007/cgi/libs/cgi/doc/src/introduction.qbk
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/introduction.qbk 2007-08-03 22:53:07 EDT (Fri, 03 Aug 2007)
@@ -0,0 +1,32 @@
+[/
+ / Copyright (c) 2007 Darren Garvey
+ /
+ / Distributed under the Boost Software License, Version 1.0. (See accompanying
+ / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ /]
+
+[section:intro Introduction]
+
+
+[section:reading_the_docs Structure of the Documentation]
+
+[tip Hopefully after reading this you'll be able to get through the docs and use the library quicker.]
+
+
+[endsect]
+
+[section Naming Conventions]
+
+CGI -> cgi
+async CGI -> acgi
+FastCGI -> fcgi
+SCGI -> scgi
+
+*_request
+*_acceptor
+*_service
+
+[endsect]
+
+
+[endsect]
Added: sandbox/SOC/2007/cgi/libs/cgi/doc/src/links.qbk
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/links.qbk 2007-08-03 22:53:07 EDT (Fri, 03 Aug 2007)
@@ -0,0 +1,8 @@
+
+
+
+[section Links]
+
+http://msdn2.microsoft.com/en-US/library/aa178138(sql.80).aspx
+
+[endsect]
Added: sandbox/SOC/2007/cgi/libs/cgi/doc/src/preface.qbk
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/preface.qbk 2007-08-03 22:53:07 EDT (Fri, 03 Aug 2007)
@@ -0,0 +1,14 @@
+[/
+ / Copyright (c) 2007 Darren Garvey
+ /
+ / Distributed under the Boost Software License, Version 1.0. (See accompanying
+ / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ /]
+
+[section Preface]
+
+Boost.CGI is a library to aid the creation of scalable CGI programs in Standard C++. This library rests on top of and should appear familiar to users of Boost.Asio. Currently the __cgi__, [-__scgi__ and __fcgi__] protocols are supported.
+
+[include acknowledgements.qbk]
+
+[endsect]
Added: sandbox/SOC/2007/cgi/libs/cgi/doc/src/reference.qbk
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/reference.qbk 2007-08-03 22:53:07 EDT (Fri, 03 Aug 2007)
@@ -0,0 +1,14 @@
+[/
+ / Copyright (c) 2007 Darren Garvey
+ /
+ / Distributed under the Boost Software License, Version 1.0. (See accompanying
+ / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ /]
+
+[section:ref Reference]
+
+Reference coming...
+
+[/include request_objects.qbk]
+
+[endsect]
Added: sandbox/SOC/2007/cgi/libs/cgi/doc/src/tips.qbk
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/tips.qbk 2007-08-03 22:53:07 EDT (Fri, 03 Aug 2007)
@@ -0,0 +1,10 @@
+
+[section:tips Tips]
+
+[section Making your programs less dependent on a protocol type]
+
+Since you have to be explicit when making a request, one simple way to make your programs *almost* protocol-independent
+
+[endsect]
+
+[endsect]
Added: sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/async_ops.qbk
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/async_ops.qbk 2007-08-03 22:53:07 EDT (Fri, 03 Aug 2007)
@@ -0,0 +1,23 @@
+[section:async Asynchronous Operations]
+
+Asynchronous functionality is inherited from __boost_asio__, which uses __IoService__s to manage I/O operations. Each program that uses an asynchronous __protocol__ requires a single __ProtocolService__ to service all requests in the program. Amongst other things, the ProtocolService uses an underlying IoService to run asynchronous operations.
+
+The asynchronous operations provided by the library are:
+
+* Async-I/O: free functions __async_read__ and __async_write__, and member functions __async_read_some__ and __async_write_some__;
+
+* Async __accepting__ of requests;
+
+* Async __loading__ of request meta-data.
+
+Using asynchronous operations takes a bit of getting used to, but after overcoming the initial Conceptual hurdles, use of the library should be relatively straight-forward.
+
+
+
+[endsect]
+
+[section Io Service]
+
+[/ link to the asio IoService concept docs; mention *briefly* what they are for; explain how the protocol services use an IoServiceProvider, linking to relevant examples in the examples section.]
+
+[endsect]
\ No newline at end of file
Added: sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/building.qbk
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/building.qbk 2007-08-03 22:53:07 EDT (Fri, 03 Aug 2007)
@@ -0,0 +1,24 @@
+[/
+ / Copyright (c) 2007 Darren Garvey
+ /
+ / Distributed under the Boost Software License, Version 1.0. (See accompanying
+ / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ /]
+
+[section:building Building Programs]
+
+For now the library is header-only (dependency on Boost.System?) so you can use the library by just including one of the following headers:
+
+``
+#include <boost/cgi.hpp> // include all header files
+
+#include <boost/cgi/cgi.hpp> // include all headers required for (sync) CGI usage
+
+#include <boost/cgi/acgi.hpp> // include all headers required for aCGI usage
+
+#include <boost/cgi/fcgi.hpp> // include all headers required for FastCGI usage
+
+#include <boost/cgi/scgi.hpp> // include all headers required for SCGI usage
+``
+
+[endsect]
Added: sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/getting_started.qbk
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/getting_started.qbk 2007-08-03 22:53:07 EDT (Fri, 03 Aug 2007)
@@ -0,0 +1,24 @@
+[/
+ / Copyright (c) 2007 Darren Garvey
+ /
+ / Distributed under the Boost Software License, Version 1.0. (See accompanying
+ / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ /]
+
+[section:getting_started Getting Started Guide]
+
+[tip Have you read __reading_the_docs__?]
+
+This section of the documentation is probably best read before the __tutorial__. In a nutshell, this is a quick and dirty run-through of how to get and install the library and configure your server. Following that is a short example of a CGI program and one of a FastCGI program, just to highlight the features of the library.
+
+Don't worry if you don't understand these examples, as the __tutorial__ that follows this section explains everything.
+
+[/include downloading.qbk]
+
+[/include installing.qbk]
+
+[/include cgi_example.qbk]
+
+[/include fastcgi_example.qbk]
+
+[endsect]
Added: sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/handling_requests.qbk
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/handling_requests.qbk 2007-08-03 22:53:07 EDT (Fri, 03 Aug 2007)
@@ -0,0 +1,31 @@
+[/
+ / Copyright (c) 2007 Darren Garvey
+ /
+ / Distributed under the Boost Software License, Version 1.0. (See accompanying
+ / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ /]
+
+[section Handling Requests]
+
+Except for when using CGI synchronously, handling a client request generally involves the following stages:
+
+# [link __accepting__ Accepting] requests;
+
+# [link __loading__ Loading] request meta-data;
+
+# Using the [link __meta_data__ meta-data];
+
+# [link __writing__ Writing] a reply;
+
+# [link boost.cgi.user_guide.handling_requests.wrapping_up Wrapping up];
+
+
+[include accepting.qbk]
+
+[include loading.qbk]
+
+[include meta_data.qbk]
+
+[include wrapping_up.qbk]
+
+[endsect]
Added: sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/meta_data.qbk
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/meta_data.qbk 2007-08-03 22:53:07 EDT (Fri, 03 Aug 2007)
@@ -0,0 +1,44 @@
+[/
+ / Copyright (c) 2007 Darren Garvey
+ /
+ / Distributed under the Boost Software License, Version 1.0. (See accompanying
+ / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ /]
+
+[section:meta_data Request Meta-data]
+
+[note
+A request [*must] be [link __loading__ loaded] before the meta-data can be accessed. The ['only] exception to this rule is calling `meta_env()` on CGI and aCGI request objects. These are (essentially) equivalent to a call to `::getenv()` and will always work. However, exploit this 'feature' cautiously as it will render a program unsuitable for use with the more scalable protocols on offer.
+]
+
+There are five member functions of `basic_request<>` that provide access to the meta-data associated to that request. These are:
+
+[/
+[table Meta-data accessor functions
+[[Function name] [Arguement(s)] [Return value]]
+]
+]
+
+* `std::string meta_env(const std::string& name)`
+ Takes the name of the environment variable wanted and returns the value associated with it.
+
+* `std::string meta_get(const std::string& name)`
+ Takes the name of the CGI GET variable and returns the value associated with it (if any).
+
+* `std::string meta_post(const std::string& name, bool greedy = true)`
+ Takes the name of the CGI POST variable and returns the value associated with it (if any). If `greedy == true` - which it is by default - then more data is read from the request if required until all of the POST data (ie. stdin) has been read.
+
+* `std::string meta_cookie(const std::string& name)`
+ Takes the name of the cookie variable and returns the value associated with it (if any).
+
+* `std::string meta_var(const std::String& name, bool greedy = true)`
+
+[note should this return a `std::pair<std::string, cgi::meta_type>` instead, where a `cgi::meta_type` is one of `get`, `post`, `env`, or `cookie`?]
+
+ Takes the name of [*any] meta-variable and returns the value associated with it (if any). If `greedy == true` - which it is by default - then more data is read from the request if required until either the requested variable is found or all of the POST data has been read, which ever comes first.
+
+[warning
+It is generally accepted that a CGI program should pay attention to where meta-data has come from.[footnote citations w.r.t. XSS and GET/POST/COOKIE ambiguities] In other words, since `meta_var` removes such distinctions, its use should be limited to places where origin of the variable doesn't matter. For example, a language setting (like `"hl=en"`, as Google uses) could come from anywhere and doing so is not an issue.
+]
+
+[endsect]
Added: sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/protocols.qbk
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/protocols.qbk 2007-08-03 22:53:07 EDT (Fri, 03 Aug 2007)
@@ -0,0 +1,128 @@
+[/
+ / Copyright (c) 2007 Darren Garvey
+ /
+ / Distributed under the Boost Software License, Version 1.0. (See accompanying
+ / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ /]
+
+[/ cgi.user_guide.protocols.qbk CGI Protocols]
+
+[section:protocols Supported Protocols]
+
+The protocols supported by this library are CGI (synchronous and asynchronous), FastCGI (aka. FCGI) and SCGI (aka. SimpleCGI).
+
+Purely to illustrate what each protocol offers, consider this list:
+
+* CGI is for short programs that won't be run very often, or those that will be used by only a very small number of clients, such as admin 'scripts'. Here, having a long-running process might be wasteful.
+
+* aCGI is for programs similar to the above that might block on I/O, wasting CPU time; CPU-intensive programs that use database and/or other IO extensively, such as a regression-testing framework, are a good target for aCGI. In these cases, a long-running process that keeps open file handles might be wasteful.
+
+* FastCGI is especially targetted to programs that are likely to serve lots of clients. Asynchronous operations come 'for free' with FastCGI. On some platforms however - even 10 years after the specification was published [footnote See [@http://www.fastcgi.com/devkit/doc/fcgi-spec.html FastCGI 1.0], published 29 April 1996] - FastCGI support in many servers is sub-standard (see __server_support__).
+
+* SCGI is essential where server-side support for FastCGI is either buggy (as it is with Apache + mod_fastcgi: use mod_fcgid instead if possible) or missing.
+
+[note
+Synchronous and asynchronous CGI support are considered distinct within the library for now (*more*), so the latter is referred to explicitly as aCGI. SimpleCGI is generally shortened to SCGI while FastCGI is used verbatim.
+]
+
+
+[section:cgi CGI and aCGI]
+
+The distinction between CGI and aCGI is that aCGI uses __asio__'s io_service to perform asynchronous operations - whereas CGI does not provide such operations - and is also more complicated to use. A distinction has been made with the sole purpose of lowering the entry barrier to the library and to provide a means of migrating programs over to use this library.
+
+[h4:differences Differences Between CGI and aCGI Programs]
+
+ ['See also: __hello_world__]
+
+The first use of an `cgi::acgi_request` (or the shortcut `cgi::arequest`) shows the main difference:
+
+``
+#include <cgi/cgi.hpp>
+
+int main()
+{
+ cgi::request req;
+
+ // use the request here
+
+ return 0;
+}
+``
+compares to:
+``
+#include <cgi/acgi.hpp>
+#include <boost/thread.hpp> // see __boost_thread__
+
+int main()
+{
+ // a __Service__ is needed to handle asynchronous operations
+ cgi::cgi_service service;
+
+ // possibly use an asynchronous acceptor here (see below)
+
+ // create a thread for async operations to be run in
+ boost::thread thread(boost::bind(&cgi::cgi_service::run, service));
+
+ // create a request from the cgi_service
+ cgi::arequest req(service);
+
+ // use the request here
+ // ...
+
+ // finally, make sure the async operations complete by 'joining' the other thread
+ thread.join();
+
+ return 0;
+}
+``
+
+As is obvious, the main difference of CGI over aCGI is that a `cgi::request` (or the more explicit `cgi::cgi_request`) doesn't use a `cgi::io_service`, so CGI
+
+exists purely within the library and may become transparent in the future. In other words, both methods will work in the same way, with CGI acting as a shortcut to using aCGI.
+
+[endsect]
+
+[section:fcgi FastCGI]
+
+FastCGI is a binary protocol that works very differently to CGI ['internally] and has many advantages. In bullet-point form, FastCGI programs:
+
+* are servers in themselves: they can persist indefinitely and can - at least in principle - handle any number of simultaneous requests.
+
+* communicate with an HTTP server with TCP sockets __ref_pipe_support__.
+
+One such advantage as allowing a single program handle an arbitrary number of requests, in any order, without having to stop and start between each.
+
+[h4 How it Works]
+
+Data is transported over TCP sockets or pipes (not implemented yet) in packets prepended with information about the packet. Packets belong to a particular request or are 'admin' requests that are handled by the library internally. Data is returned to the HTTP server in similar packets. This frees the program from handling requests sequentially, as data from any request can come in at any time, so a well-structured program can avoid being compromised by a dropped connection or a slow client, for instance.
+
+[endsect] [/ fcgi]
+
+[section:scgi SCGI (SimpleCGI)]
+
+SCGI is a more recent protocol than FastCGI and is essentially a halfway house between CGI and the more complex FastCGI. It has become popular as support for it is generally more consistent and widely available than FastCGI, due in part to its simplicity.
+
+[h4 How it Works]
+
+SCGI uses a connection-per-request approach. Environment data is sent first and the CGI POST data follows. All data sent back to the server over the connection is forwarded as is to the client. The connection is closed after the request has been handled.
+
+Although far less optimized than FastCGI, SCGI is still a large step up from CGI
+
+
+[endsect] [/ scgi]
+
+
+[section:comparison Feature Comparison]
+
+[table
+ [[ ] [Protocol ]]
+ [[Feature ] [CGI] [aCGI] [FastCGI] [SCGI ]]
+ [[Requires io_service ] [No ] [Yes ] [Yes ] [Yes ]]
+ [[Is natively asynchronous] [No ] [No ] [Yes ] [Yes ]]
+ [[Has native error stream ] [Yes] [Yes ] [Yes ] [Shared]]
+]
+
+[endsect] [/ comparison]
+
+
+[endsect] [/ protocols]
Added: sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/request_objects.qbk
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/request_objects.qbk 2007-08-03 22:53:07 EDT (Fri, 03 Aug 2007)
@@ -0,0 +1,23 @@
+[/
+ / Copyright (c) 2007 Darren Garvey
+ /
+ / Distributed under the Boost Software License, Version 1.0. (See accompanying
+ / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ /]
+
+[section `basic_request<>`: Request Objects]
+
+The template class `basic_request<>` is the most useful class in the library.
+
+There are `typedef`s for typical usage, following usual __naming_styles__:
+
+[table Request typedefs
+ [[Protocol] [`typedef` ]]
+ [[CGI ] [`cgi_request` ]]
+ [[aCGI ] [`acgi_request`]]
+ [[FastCGI ] [`fcgi_request`]]
+ [[SCGI ] [`scgi_request`]]
+]
+
+
+[endsect]
Added: sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial.qbk
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial.qbk 2007-08-03 22:53:07 EDT (Fri, 03 Aug 2007)
@@ -0,0 +1,42 @@
+[/
+ / Copyright (c) 2007 Darren Garvey
+ /
+ / Distributed under the Boost Software License, Version 1.0. (See accompanying
+ / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ /]
+
+[section Tutorial]
+
+[tip Have you read __reading_the_docs__?]
+
+Except for when using CGI synchronously, a typical program will have two fundamental parts:
+
+[/handling a client request generally involves the following stages:]
+
+[variablelist
+ [
+ [Gathering requests]
+ [ [link __accepting__ Accepting] requests;
+ [link __loading__ Loading] and parsing request meta-data;
+ ]
+ ]
+ [
+ [Handling requests]
+ [ Using the [link __meta_data__ meta-data];
+[link __writing__ Writing] a reply;
+[link boost.cgi.user_guide.handling_requests.wrapping_up Wrapping up];
+ ]
+ ]
+] [/variablelist]
+
+
+[include tutorial/accepting.qbk]
+
+[include tutorial/loading.qbk]
+
+[include tutorial/meta_data.qbk]
+
+[include wrapping_up.qbk]
+
+
+[endsect]
Added: sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/accepting.qbk
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/accepting.qbk 2007-08-03 22:53:07 EDT (Fri, 03 Aug 2007)
@@ -0,0 +1,67 @@
+[/
+ / Copyright (c) 2007 Darren Garvey
+ /
+ / Distributed under the Boost Software License, Version 1.0. (See accompanying
+ / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ /]
+
+[section:accepting Accepting Requests]
+
+A `basic_request_acceptor<>` is responsible for accepting requests. There are __common_typedef__s for ease of use, as with `basic_request<>`s. A program written for SCGI or FastCGI will generally have one acceptor running in a loop. A `cgi_request` cannot be used with an acceptor, but acgi_request`s will work fine: ie. only the first accept will succeed.
+
+Accepting requests is considered distinct to the [link __loading__ loading] stage for several reasons, the most significant of which is to allow for multiplexing protocols like FastCGI work with the library.
+
+All you need do is create an `*_acceptor` by passing an instance of a __ProtocolService__ to its constructor. The following member functions are available:
+
+[table xcgi_acceptor member functions
+ [[Function signature] [Purpose]]
+ [
+ [`void accept(xcgi_request& empty_request)`]
+ [Takes an empty request and blocks until a request is waiting to be handled. This will throw if the accept fails.]
+ ]
+ [
+ [`boost::system::error_code&
+ accept(xcgi_request& empty_request, boost::system::error_code& ec)`]
+ [Takes an empty request and blocks until a request is waiting to be handled. `ec` will be set such that `!ec == false` if the accept fails with an error code `ec`.]
+ ]
+ [
+ [`void async_accept(xcgi_request& empty_request, Handler handler)`]
+ [Takes an empty request and asynchronously accepts a request. `handler` must be a model of __Handler__ and will be invoked when a request is accepted or an error occurs. The function always returns immediately.]
+ ]
+ [
+ [`void cancel()`]
+ [Cancel all outstanding asynchronous accepts that are running]
+ ]
+] [/table]
+
+[h5 Example]
+
+``
+#include <boost/cgi/scgi.hpp>
+#include <boost/system/error_code.hpp>
+
+int main()
+{
+ // create a ProtocolService
+ cgi::scgi_service service;
+
+ // create an acceptor
+ cgi::scgi_acceptor acceptor(service);
+
+ // make an empty request
+ cgi::scgi_request req(service);
+
+ boost::system::error_code ec;
+ // accept a request
+ acceptor.accept(req, ec);
+
+ if (!ec)
+ {
+ // a request was accepted ok
+ }
+
+ return 0;
+}
+``
+
+[endsect]
Added: sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/loading.qbk
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/loading.qbk 2007-08-03 22:53:07 EDT (Fri, 03 Aug 2007)
@@ -0,0 +1,174 @@
+[/
+ / Copyright (c) 2007 Darren Garvey
+ /
+ / Distributed under the Boost Software License, Version 1.0. (See accompanying
+ / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ /]
+
+[section:loading Loading Requests]
+
+After a request has been accepted, it must also be 'loaded'. Before being loaded the request is in an undefined state and in general it is unsafe to try to do anything except read from/write to the client. For CGI, the request's constructor calls load implicitly (this is optional behaviour [footnote]), in most other situations, one of the following functions are used:
+
+[table
+ [[Function signature] [Purpose]]
+ [
+ [`void basic_request<>::load(bool parse_stdin = true)`]
+ [Loads the request meta-data into internal `cgi::map`s. If `parse_stdin == true`, which it is by default, CGI POST data is also read and parsed. If an error occurs, an exception is thrown.]
+ ]
+ [
+ [`boost::system::error_code&
+ basic_request<>::load(boost::system::error_code& ec, bool parse_stdin = true)`]
+ [Loads the request meta-data into internal `cgi::map`s. If `parse_stdin == true`, which it is by default, CGI POST data is also read and parsed. If an error occurs, ec is set to the value of the error such that `!ec == false`.]
+ ]
+ [
+ [`void basic_request<>::async_load(bool parse_stdin, Handler handler)`]
+ [Asynchronously loads the request meta-data into interal `cgi::map`s. `handler` must be a model of __Handler__ and will be invoked when the loading has completed. The function always returns immediately.]
+ ]
+] [/table]
+
+What the call does is aquire the request environment data as necessary and parse the CGI GET and HTTP_COOKIE variables. Also, if `parse_stdin == true` and the request method is POST, the CGI POST data will be read and parsed.
+
+[h5 CGI example]
+
+``
+#include <boost/cgi/cgi.hpp>
+
+int main()
+{
+ // Delay loading the request data
+ cgi::request req(false);
+
+ // ...
+
+ // Load the request now (including parsing stdin)
+ boost::system::error_code& ec;
+ req.load(ec);
+
+ if (!ec)
+ {
+ // The request loaded ok (and is valid)
+ }
+
+ return 0;
+}
+``
+
+[h5 Synchronous SCGI example]
+
+``
+#include <boost/cgi/scgi.hpp>
+
+int main()
+{
+ // create a ProtocolService
+ cgi::scgi_service service;
+
+ // create an acceptor
+ cgi::scgi_acceptor acceptor(service);
+
+ // make an empty request
+ cgi::scgi_request req(service);
+
+ boost::system::error_code ec;
+ // accept a request
+ acceptor.accept(req, ec);
+
+ if (!ec)
+ {
+ // a request was accepted ok
+ }
+
+ return 0;
+}
+``
+
+[h5 Asynchronous SCGI example]
+
+
+``
+#include <boost/cgi/scgi.hpp>
+#include <boost/bind.hpp>
+#include <boost/thread.hpp>
+#include <boost/system/error_code.hpp>
+#include <boost/enable_shared_from_this.hpp>
+
+
+void sub_main(scgi_request::pointer req)
+{
+ // handle the request in here, as you would expect to
+}
+
+class scgi_server
+ : public boost::enable_shared_from_this
+{
+public:
+ scgi_server(scgi_service& service)
+ : service_(service)
+ , acceptor_(service)
+ {
+ async_accept();
+ }
+
+ void async_accept()
+ {
+ scgi_request::pointer new_request(scgi_request::create(service_));
+ acceptor_.async_accept(new_request
+ , boost::bind(&scgi_server::handle_accept
+ , shared_from_this()
+ , new_request
+ , boost::arg<1>));
+ }
+
+ void handle_accept(scgi_request::pointer request, boost::system::error_code& ec)
+ {
+ if (!ec)
+ {
+ // request was accepted ok; load it asynchronously (parsing POST data)
+ request->async_load(true, boost::bind(&scgi_server::handle_load
+ , shared_from_this()
+ , request
+ , boost::arg<1>));
+ }
+ }
+
+ void handle_load(scgi_request::pointer request, boost::system::error_code& ec)
+ {
+ if (!ec)
+ {
+ // the request loaded ok; handle it asynchronously and accept another request
+ service_.post(boost::bind(&sub_main, request));
+
+ async_accept();
+ }
+ }
+private:
+ scgi_service& service_;
+ scgi_acceptor acceptor_;
+};
+
+int main()
+{
+ // create a ProtocolService
+ cgi::scgi_service service;
+
+ // create a server to accept and load requests
+ scgi_server server(service);
+
+ // create 5 background threads to run async operations *and* calls to sub_main
+ // that are invoked through scgi_service::post(). Essentially this means the
+ // program can handle at least 5 simultaneous requests: if asynchronous reads/
+ // writes are used then more requests may be being handled at any one time
+ boost::thread_group threads;
+ for(int i=5; i; i--)
+ {
+ threads.create_thread(boost::bind(&scgi_service::run, service));
+ }
+
+ // make sure the program doesn't return until all threads are finished working
+ threads.join_all();
+
+ return 0;
+}
+``
+
+[endsect]
Added: sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/meta_data.qbk
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/meta_data.qbk 2007-08-03 22:53:07 EDT (Fri, 03 Aug 2007)
@@ -0,0 +1,35 @@
+[/
+ / Copyright (c) 2007 Darren Garvey
+ /
+ / Distributed under the Boost Software License, Version 1.0. (See accompanying
+ / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ /]
+
+[section:meta_data Request Meta-data]
+
+[note
+A request [*must] be [link __loading__ loaded] before the meta-data can be accessed. The ['only] exception to this rule is calling `meta_env()` on CGI and aCGI request objects. These are (essentially) equivalent to a call to `::getenv()` and will always work. However, exploit this 'feature' cautiously as it will render a program unsuitable for use with the more scalable protocols on offer.
+]
+
+There are five member functions of `basic_request<>` that provide access to the meta-data associated to that request. These are:
+
+
+[table Meta-data accessor functions
+ [[Function signature] [Purpose]]
+ [[`std::string meta_env(const std::string& name)`] [Takes the name of the environment variable wanted and returns the value associated with it.]]
+ [[`std::string meta_get(const std::string& name)`][Takes the name of the CGI GET variable and returns the value associated with it (if any).]]
+ [[`std::string meta_post(const std::string& name, bool greedy = true)`][Takes the name of the CGI POST variable and returns the value associated with it (if any). If `greedy == true` - which it is by default - then more data is read from the request if required until all of the POST data (ie. stdin) has been read.
+]]
+ [[`std::string meta_cookie(const std::string& name)`][Takes the name of the cookie variable and returns the value associated with it (if any).]]
+ [[`std::string meta_var(const std::string& name, bool greedy = true)`][Takes the name of [*any] meta-variable and returns the value associated with it (if any). If `greedy == true` - which it is by default - then more data is read from the request if required until either the requested variable is found or all of the POST data has been read, which ever comes first.
+]]
+]
+
+[/ should this return a `std::pair<std::string, cgi::meta_type>` instead, where a `cgi::meta_type` is one of `get`, `post`, `env`, or `cookie`?]
+
+[warning
+It is generally accepted that a CGI program should pay attention to where meta-data has come from.[footnote citations w.r.t. XSS and GET/POST/COOKIE ambiguities] In other words, since `meta_var` removes such distinctions, its use should be limited to places where origin of the variable doesn't matter. For example, a language setting (like `"hl=en"`, as Google uses) could come from anywhere and doing so is not an issue.
+]
+
+
+[endsect]
Added: sandbox/SOC/2007/cgi/libs/cgi/example/Jamfile.v2
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/cgi/libs/cgi/example/Jamfile.v2 2007-08-03 22:53:07 EDT (Fri, 03 Aug 2007)
@@ -0,0 +1,24 @@
+# Copyright (c) 2007 Darren Garvey
+#
+# Distributed under the Boost Software License, Version 1.0.
+# (See accompanying file LICENSE_1_0.txt or copy
+# at http://www.boost.org/LICENSE_1_0.txt)
+
+
+import os ;
+
+local BOOST_ROOT = [ os.environ BOOST_ROOT ] ;
+
+project boost/cgi/examples
+ : build-dir ../../../bin.v2
+ ;
+
+
+install examples
+ : # the sources
+ cgi
+ acgi
+ reply
+ : <location>/var/www/cgi-bin
+ ;
+
\ No newline at end of file
Modified: sandbox/SOC/2007/cgi/libs/cgi/example/acgi/Jamfile.v2
==============================================================================
--- sandbox/SOC/2007/cgi/libs/cgi/example/acgi/Jamfile.v2 (original)
+++ sandbox/SOC/2007/cgi/libs/cgi/example/acgi/Jamfile.v2 2007-08-03 22:53:07 EDT (Fri, 03 Aug 2007)
@@ -25,6 +25,3 @@
<define>BOOST_ALL_NO_LIB=1
<toolset>gcc:<linkflags>-lpthread
;
-
-#install
-# :
\ No newline at end of file
Modified: sandbox/SOC/2007/cgi/libs/cgi/example/acgi/main.cpp
==============================================================================
--- sandbox/SOC/2007/cgi/libs/cgi/example/acgi/main.cpp (original)
+++ sandbox/SOC/2007/cgi/libs/cgi/example/acgi/main.cpp 2007-08-03 22:53:07 EDT (Fri, 03 Aug 2007)
@@ -1,12 +1,67 @@
#include <boost/cgi/acgi.hpp>
+#include <iostream>
+
+class handlerer
+{
+public:
+ handlerer(cgi::request_ostream& ros, cgi::acgi_request& req)
+ : ros_(ros)
+ , req_(req)
+ {
+ }
+
+ void operator()(boost::system::error_code& ec)
+ {
+ if (!ec)
+ {
+ ros_<< "All ok";
+ ros_.flush(req_);
+ }
+ }
+private:
+ cgi::request_ostream& ros_;
+ cgi::acgi_request& req_;
+};
+
int main()
{
cgi::cgi_service service;
cgi::acgi_request req(service);
+ req.load();
std::string buf("Content-type:text/html\r\n\r\nHello there, Universe.");
cgi::write(req, cgi::buffer(buf.c_str(), buf.size()));
+ cgi::reply rep;
+
+ rep<< "<br />Yuppers.";
+
+ rep<< "<form method='POST'>"
+ "<input name='name' type='text' value='"
+ << req.meta_get("name")
+ << "'></input>"
+ "<input type='submit'></input>"
+ "</form>"
+ ;
+
+
+
+ /*
+ for(cgi::streambuf::const_buffers_type::const_iterator
+ i = rep.rdbuf()->data().begin()
+ ; i != rep.rdbuf()->data().end(); ++i)
+ {
+ std::size_t buf_len = boost::asio::buffer_size(*i);
+ std::string s(boost::asio::buffer_cast<const char*>(*i)
+ , buf_len);
+
+ rep<< "s = " << s;
+ std::cerr<< "s = " << s;
+ }
+ */
+
+ rep.flush(req);
+
return 0;
}
Modified: sandbox/SOC/2007/cgi/libs/cgi/example/cgi/Jamfile.v2
==============================================================================
--- sandbox/SOC/2007/cgi/libs/cgi/example/cgi/Jamfile.v2 (original)
+++ sandbox/SOC/2007/cgi/libs/cgi/example/cgi/Jamfile.v2 2007-08-03 22:53:07 EDT (Fri, 03 Aug 2007)
@@ -24,6 +24,3 @@
<define>BOOST_ALL_NO_LIB=1
<toolset>gcc:<linkflags>-lpthread
;
-
-#install
-# :
\ No newline at end of file
Added: sandbox/SOC/2007/cgi/libs/cgi/index.html
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/cgi/libs/cgi/index.html 2007-08-03 22:53:07 EDT (Fri, 03 Aug 2007)
@@ -0,0 +1,13 @@
+<!-- redirect for docs -->
+
+<html>
+<head>
+<meta http-equiv="refresh" content="0; URL=doc/html/index.html">
+</head>
+<body>
+
+Automatic redirection failed, please go to
+doc/html/index.html
+
+</body>
+</html>
\ No newline at end of file
Added: sandbox/SOC/2007/cgi/libs/cgi/test/compile/cgi_header_check.cpp
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/cgi/libs/cgi/test/compile/cgi_header_check.cpp 2007-08-03 22:53:07 EDT (Fri, 03 Aug 2007)
@@ -0,0 +1,8 @@
+#include "boost/cgi/cgi.hpp"
+
+int main()
+{
+ cgi::cgi_request req;
+
+ return 0;
+}
Modified: sandbox/SOC/2007/cgi/libs/cgi/test/compile/reply.cpp
==============================================================================
--- sandbox/SOC/2007/cgi/libs/cgi/test/compile/reply.cpp (original)
+++ sandbox/SOC/2007/cgi/libs/cgi/test/compile/reply.cpp 2007-08-03 22:53:07 EDT (Fri, 03 Aug 2007)
@@ -1,8 +1,10 @@
#include "boost/cgi/reply.hpp"
-int main()
+int main(int, char**)
{
cgi::reply rep;
+ rep<< "blah";
+
return 0;
}
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk