Changeset 38753


Ignore:
Timestamp:
Aug 18, 2007, 2:40:33 PM (11 years ago)
Author:
Darren Garvey
Message:

Documentation update.

Location:
sandbox/SOC/2007/cgi
Files:
6 added
14 edited

Legend:

Unmodified
Added
Removed
  • sandbox/SOC/2007/cgi/boost/cgi/basic_request.hpp

    r38709 r38753  
    125125
    126126    /// Set a header
    127     void set_header(const std::string& name, const std::string& val)
    128     {
    129       this->service.set_header(this->impl, name, val);
     127    void set_header(const std::string& name, const std::string& val
     128                   , const std::string& expires)
     129    {
     130      this->service.set_header(this->impl, name, val, expires);
    130131    }
    131132
     
    134135    {
    135136      this->service.set_cookie(this->impl, name, val);
     137    }
     138
     139    /// Delete a cookie
     140    void del_cookie(const std::string& name)
     141    {
     142      this->service.set_cookie(this->impl, name, val
     143                              , "Mon, 01-Jan-1945 00:00:01 GMT");
     144    }
     145
     146    /// Delete all cookies
     147    void del_cookies()
     148    {
     149      this->service.del_cookies();
    136150    }
    137151
  • sandbox/SOC/2007/cgi/libs/cgi/doc/Jamfile.v2

    r38734 r38753  
    2626    [ glob ../../../boost/cgi/request_service/*.hpp ]
    2727  :
    28     <doxygen:param>HIDE_UNDOC_MEMBERS=YES
     28    <doxygen:param>HIDE_UNDOC_MEMBERS=NO
    2929    <doxygen:param>EXTRACT_PRIVATE=NO
    30     <doxygen:param>EXTRACT_ALL=YES
     30    #<doxygen:param>EXTRACT_ALL=YES
    3131    <doxygen:param>SEARCH_INCLUDES=YES
    3232    <doxygen:param>INCLUDE_PATH=$(BOOST_ROOT)
     
    4040    cgi_dox
    4141  :
    42     <xsl:param>boost.root=/usr/local/src/boost
     42    <xsl:param>boost.root=/usr/local/src/cgi/svn.boost.org/
    4343    <xsl:param>boost.libraries=/usr/local/src/boost/libs/libraries.htm
    44     <xsl:param>boost.images=http://beta.boost.org/images
    45     <xsl:param>toc.max.depth=0
     44#    <xsl:param>boost.images=http://beta.boost.org/images
     45    # the depth (of sub-pages) the TOC shows
     46    <xsl:param>toc.max.depth=1
     47
     48    #
    4649    <xsl:param>toc.section.depth=2
    47     <xsl:param>chunk.section.depth=10
     50
     51    # how many sections are on the first page
     52    <xsl:param>chunk.first.sections=1
     53
     54    # To chunk (together) or not to chunk (divide)
     55    <xsl:param>chunk.section.depth=1 # chunk
    4856        ;
    4957
  • sandbox/SOC/2007/cgi/libs/cgi/doc/src/cgi.qbk

    r38734 r38753  
    2525[def __fcgi__    [@http://en.wikipedia.org/wiki/FastCGI FastCGI]]
    2626
    27 [def __asio__    [@http://asio.sourceforge.net Asio]]
     27[def __FastCGI__ [link boost.cgi.reference.protocols.fcgi FastCGI]]
     28[def __SCGI__    [link boost.cgi.reference.protocols.scgi SCGI]]
     29
     30[def __boost__   [@http://boost.org/ Boost]]
     31[def __asio__    [@http://asio.sourceforge.net Boost.Asio]]
    2832
    2933[def __reading_the_docs__   [link boost.cgi.intro.reading_the_docs reading the docs]]
     
    5660
    5761[def __headers__   boost.cgi.ug.gs.headers]
    58 [def __accepting__ boost.cgi.ug.tut.accepting]
    59 [def __loading__   boost.cgi.ug.tut.loading]
     62[def __accepting__ boost.cgi.ug.tutorial.accepting]
     63[def __loading__   boost.cgi.ug.tutorial.loading]
    6064
     65[important
     66This manual does [*not] document a library that is a part of __Boost__. The major part of it has been developed this summer as part of the Google Summer of Code, '[@http://code.google.com/soc GSoC07]'. Everything from here on in is alpha-grade, some bits more than others; [link boost.cgi.preface.comments_and_support comments] are welcome.
     67
     68These documents are either hosted at [@http://sourceforge.net/projects/cgi/ sourceforge], or at [@http://svn.boost.org/svn/boost/browser/sandbox/SOC/2007/cgi svn.boost.org]. For free!
     69]
    6170
    6271[include preface.qbk]
    6372
    64 [include introduction.qbk]
     73[include:intro introduction.qbk]
    6574
    66 [include user_guide.qbk]
     75[section:gs Getting Started]
     76
     77This section of the documentation is probably best read before the [link __tutorial__ tutorial]. In a nutshell, this is a quick and dirty run-through of how to get and install the library [-and configure your server].
     78
     79[include:building user_guide/building.qbk]
     80
     81[include:server_config user_guide/server_configuration.qbk]
     82
     83[include:headers user_guide/headers.qbk]
     84
     85[endsect]
     86
     87[include:tutorial user_guide/tutorial.qbk]
     88
     89[include:protocols user_guide/protocols.qbk]
     90
     91[include:examples user_guide/examples.qbk]
     92
     93[/include:ug user_guide.qbk]
    6794
    6895[xinclude ../cgi_dox.boostbook]
    6996
    70 [include future_development.qbk]
     97[include:future future_development.qbk]
     98
     99[include:server_support user_guide/server_support.qbk]
    71100
    72101[/include acknowledgements.qbk]
  • sandbox/SOC/2007/cgi/libs/cgi/doc/src/future_development.qbk

    r38734 r38753  
    1818[h4 FastCGI support.]
    1919
    20 Complete FastCGI support is essential to any modern CGI library.
     20FastCGI support is essential to any modern CGI library. There is currently ['no] known FastCGI library for C or C++ that aims to implement the complete [@http://www.fastcgi.com/devkit/doc/fcgi-spec.html FastCGI 1.0] specification.
     21
     22There are a couple of issues that have yet to be worked out, but in general the new framework is known to 'fit' with all the details of FastCGI and lends itself to an efficient implementation (hopefully).
    2123
    2224[h4 Access to error output streams]
     
    4749Yet another possibility, is that a member function `as<>` can be provided as a shortcut to `boost::lexical_cast<>`. This could greatly improve readability of web programs, where lexical casting is very common and may make programs overly verbose.
    4850
     51Compare:
     52``
     53cgi::request req;
     54cgi::reply rep;
     55
     56cgi::map::iterator iter = req.meta_form().find("number");
     57if (iter != cgi::map::iterator::end())
     58{
     59  rep<< "You picked no numbers...";
     60}
     61else
     62{
     63  int sum(0);
     64  rep<< "Your numbers are: ";
     65  for(; iter != cgi::map::iterator::end(); ++iter)
     66  {
     67    rep<< iter->second << " ";
     68    sum +=  boost::lexical_cast<int>(iter->second);
     69  }
     70
     71  rep<< std::endl
     72     << "Your numbers add up to: " << sum;
     73}
     74
     75rep.send(req);
     76``
     77to:
     78``
     79cgi::request req;
     80cgi::reply rep;
     81
     82cgi::param parm = req.meta_form("number");
     83if (parm.empty())
     84{
     85  rep<< "You picked no numbers...";
     86}
     87else
     88{
     89  int sum(0);
     90  for(; parm != parm.end(); ++parm)
     91  {
     92    rep<< parm << " ";
     93    sum += parm.as<int>());
     94  }
     95
     96  rep<< std::endl
     97     << "Your numbers add up to: " << sum;
     98}
     99
     100rep.send(req);
     101``
     102
    49103[h4 Concept Documentation]
    50104
    51105Even though this library introduces very few new concepts, they are not currently documented. Links to Boost.Asio's concept documentation is also required (essentially as part of a reworking of the doxygen reference section).
    52106
     107[/h4 Support for wide characters]
     108
     109[/The library generally works on octets, but there should be some way to ]
     110
    53111[endsect]
  • sandbox/SOC/2007/cgi/libs/cgi/doc/src/introduction.qbk

    r38734 r38753  
    2424``
    2525
    26 This CGI library reasonably high-level library for web programming. Herein the controller portion of the Model-View-Controller idiom is implemented. The intricacies of dealing with the widely varying specifications of CGI, FastCGI and SCGI are abstracted into three main sub-parts:
     26This CGI library reasonably high-level library for web programming. Herein the controller portion of the Model-View-Controller idiom is implemented. The intricacies of dealing with the widely varying specifications of CGI, FastCGI and SCGI are abstracted into three main parts:
    2727
    2828* Accepting,
     
    3030* Loading, and
    3131
    32 * Handling
     32* Handling.
    3333
    34 This is all described in more detail in the [link __tutorial__ tutorial].
     34Sometimes all a problem calls for is a thin interface to request data and '''I/O''' streams, without any need to be hyper-efficient: in other words, like a short CGI script that you can with [@http://tinyurl.com/2ss4ae perl], [@http://tinyurl.com/39b37l python], [@http://tinyurl.com/3yg4m8 php], etc. To allow this, the library and documentation are split into two parts: 'scripting' and 'everything else'. The code excerpt above is an example of a 'script' which, as you can see, skips the 'accepting' and 'loading' stages.
    3535
    36 If a program's purpose is to serve the wider world, it should be written with scalability in mind. The `cgi::srequest` (the 's' is for 'synchronous' - ie. asynchronous operations cannot be used with it) that the [link __quickstart__ quickstart] introduces is simple to use and ideal for shorter, light-use programs, such as admin scripts. However when it comes to heavily used web applications CGI has an inherent limitation: there must be a complete heavyweight process for each client.
     36If a program's purpose is to serve the wider world, it should be written with scalability in mind. When it comes to heavily used web applications CGI has an inherent limitation: there must be a complete heavyweight process ['for every request].
    3737
    38 [note
    39 Even though a `cgi::srequest` is set up differently to asynchronous request types, the alternative `cgi::request` (or the explicit form `cgi::acgi_request`) can be used in exactly the same way as FastCGI and SCGI requests. This symmetry makes migrating code between different protocols trivial (see [link __interoperability__ interoperability] for more) and aids debugging of server configuration issues.
    40 ]
     38The __FastCGI__ and __SCGI__ protocols are essentially reworkings of CGI which remove this restriction. They offer other advantages too, the support of which - of widely varying quality and completeness ([-more [link __server_support__ here]]) - comes for most HTTP servers. These protocols add an extra layer to your CGI programs, as you now must manage the request queue.
    4139
    42 FastCGI and SCGI both remove this restriction and there is support for them - of widely varying quality and completeness (see [link __server_support__ here]) - in most HTTP servers. These protocols add an extra layer to your CGI programs, as you now must manage the request queue.
     40In return for the added complexity, your programs become complete servers, capable of handling arbitrary numbers of requests during each invocation (assuming they don't crash!). This gives you the freedom to keep database connections open between requests, or cache ready-parsed responses, for example. Processing of a client request can even be continued in the case of the client crashing - the reply can then be stored and given to them when they return - saving precious CPU cycles.
    4341
    44 In return for the added complexity, your programs become complete servers, capable of handling arbitrary numbers of requests during each invocation (assuming they don't crash!): Database connections can be kept open between requests; ready-parsed XML files can be cached; processing of a client request can even be continued in the case of the client crashing - the reply can be cached and returned to them when they return - saving precious CPU cycles.
    45 
    46 Parsing of request meta-data can be done at any point in the program, or not at all (eg. for a hit-counter). Reading and parsing of data is referred to as '[link __loading__ loading]' and this follows '[link __accepting__ accepting]' a request.
    47 
    48 Fortunately, this layer can be largely isolated from the rest of your program logic and development of both can continue in parallel. The two parts share a [link __ProtocolService__ ProtocolService], such as a `cgi::fcgi_service` (similar in use to an [link __asio_io_service__ asio::io_service] for those familiar with [link __asio__ Boost.Asio]).
    49 
    50 The [link __examples__ examples] are divided like this, to keep them concise.
    51 
    52 
     42It might sound like a handful but, fortunately, management of the request queue can be largely isolated from the handling of each request. That means that after you have set up a 'server' (ie. something that gathers requests), requests can be handled in the same way as they would be with a conventional CGI program.
    5343
    5444[endsect]
  • sandbox/SOC/2007/cgi/libs/cgi/doc/src/preface.qbk

    r38734 r38753  
    88[section Preface]
    99
    10 [: [*['All science is either Physics, or stamp collecting.]] [br] -- Ernest Rutherford.]
     10[: [*['All science is either Physics, or stamp collecting.]]
     11
     12-- Ernest Rutherford.]
    1113
    1214[h3 Overview]
    1315
    14 Boost.CGI is a library for writing CGI programs in Standard C++. It can be used to write anything from simple 'adming scripts' to full-fledged, scalable applications. This library rests on top of and should appear familiar to users of Boost.Asio. Currently the __cgi__, [-__scgi__ and __fcgi__] protocols are supported.
     16Boost.CGI is a library for writing CGI programs in Standard C++. It can be used to write anything from simple 'adming scripts' to full-fledged, scalable applications. This library rests on top of and should appear familiar to users of Boost.Asio, a cross-platform networking library in boost-style C++. Currently the __cgi__, [-__scgi__ and __fcgi__] protocols are supported, within a framework that should allow code to be reused with as-yet-unwritten protocols without any real modification.
    1517
    1618[h3 Motivation]
     
    5355As you are probably used to, it is assumed that code snippets in this manual have the correct `#include`s and "`using namespace cgi;`" prepended to them. Information about the correct headers to include can be found [link __headers__ here].
    5456
     57[h3 Comments and Support]
     58
     59Use cases, example requests, puzzles and problems should be sent to the mailing list:
     60
     61* ''' &#99;&#103;&#105;-&#116;&#97;&#108;&#107;&#32;&#64;&#32;&#108;&#105;&#115;&#116;&#115;&#46;&#115;&#102;&#32;&#92;&#46;\&#32;n&#101;&#116;''', or thereabouts.
     62
    5563[endsect]
  • sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide.qbk

    r38734 r38753  
    66 /]
    77
    8 [section:ug User's Guide]
    9 
    10 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.
    11 
    128[section:gs Getting Started]
    139
    14 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].
     10This section of the documentation is probably best read before the [link __tutorial__ tutorial]. In a nutshell, this is a quick and dirty run-through of how to get and install the library [-and configure your server].
    1511
    16 [include user_guide/building.qbk]
     12[include:building user_guide/building.qbk]
    1713
    18 [include user_guide/server_configuration.qbk]
     14[include:server_config user_guide/server_configuration.qbk]
    1915
    20 [include user_guide/server_support.qbk]
     16[include:headers user_guide/headers.qbk]
    2117
    2218[endsect]
    2319
    24 [include user_guide/protocols.qbk]
     20[/include:protocols user_guide/protocols.qbk]
    2521
    26 [include user_guide/tutorial.qbk]
     22[/include:tutorial user_guide/tutorial.qbk]
    2723
    28 [include user_guide/examples.qbk]
     24[/include:examples user_guide/examples.qbk]
    2925
    3026
    31 [endsect]
     27[/endsect]
  • sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/building.qbk

    r38734 r38753  
    2828   [Boost.System]
    2929   [No]
    30    [1. Download the latest Boost distro, 'boost'.[br][br]
     30   [1. Download the latest Boost distro, 'boost'.
     31
    3132   2. Set the environment variable BOOST_ROOT on your system to the download location.
    32    3. Go to the directory BOOST_ROOT and invoke `bjam` (see above). This should finish without any fails.]
     33
     34   3. Go to the directory BOOST_ROOT and invoke `bjam` (see above), passing it `--with-system install` on the command line. This should finish without any fails.]
    3335  ]
    3436  [
  • sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/headers.qbk

    r38734 r38753  
    1212
    1313``
    14 #include <boost/cgi.hpp> // include header files for any protocol
     14#include <boost/cgi.hpp>      // include header files for any protocol
    1515
    16 #include <boost/cgi/cgi.hpp> // include all headers required for (sync) CGI usage
     16#include <boost/cgi/cgi.hpp>  // include all headers required for (sync) CGI usage
    1717
    1818#include <boost/cgi/acgi.hpp> // include all headers required for aCGI usage
     
    2929#define BOOST_CGI_IMPLICIT_SCGI 1
    3030#include <boost/cgi.hpp>
    31 cgi::request req;
     31cgi::service service;           // implicit SCGI service
     32cgi::request req(service);      // implicit SCGI request
    3233``
    3334Is equivalent to:
    3435``
    3536#include <boost/cgi/scgi.hpp>
    36 cgi::request req;
     37cgi::service service;           // implicit SCGI service
     38cgi::request req(service);      // implicit SCGI request
    3739``
    3840Which is equivalent to:
    3941``
    40 #include <boost/cgi.hpp> // or <boost/cgi/scgi.hpp>, here
    41 cgi::scgi_request req;
     42#include <boost/cgi.hpp>
     43cgi::scgi_service service;      // SCGI service
     44cgi::scgi_request req(service); // SCGI request
     45``
     46and:
     47``
     48#include <boost/cgi/scgi.hpp>
     49cgi::scgi_service service;      // SCGI service
     50cgi::scgi_request req(service); // SCGI request
    4251``
    4352But:
    4453``
    4554#include <boost/cgi.hpp>
    46 cgi::request req; // error
     55cgi::service service;           // error: cgi::service does not name a type
     56cgi::request req(service);      // error: cgi::request does not name a type
    4757``
     58will not work.
    4859
    49 [endsect]
     60Note that the explicit form - `scgi_request`/`scgi_service` - is always valid, assuming you have (implicitly or otherwise) included, for example, `<boost/cgi/scgi/request.hpp>`.
     61
     62[endsect] [/ headers]
  • sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/protocols.qbk

    r38734 r38753  
    2626]
    2727
     28[section:comparison Feature Comparison]
     29
     30[table
     31    [[Feature                     ] [Protocol                     ]]
     32    [[                            ] [CGI] [aCGI] [FastCGI] [SCGI  ]]
     33    [[Requires __ProtocolService__] [No ] [Yes ] [Yes    ] [Yes   ]]
     34    [[Is natively asynchronous    ] [No ] [No  ] [Yes    ] [Yes   ]]
     35    [[Has native error stream     ] [Yes] [Yes ] [Yes    ] [Shared]]
     36]
     37
     38[endsect] [/ comparison]
     39
     40
    2841
    2942[section:cgi CGI and aCGI]
    3043
    31 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.
     44The 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 setup. 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. There is also currently a small speed gain to be had by not constructing an `io_service` when it isn't needed.
    3245
    3346[h4 Differences Between CGI and aCGI Programs]
     
    107120SCGI 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.
    108121
    109 Although far less optimized than FastCGI, SCGI is still a large step up from CGI
    110 
     122Although far less optimized than FastCGI, SCGI is still a significant step up from CGI.
    111123
    112124[endsect] [/ scgi]
    113125
    114 
    115 [section:comparison Feature Comparison]
    116 
    117 [table
    118     [[Feature                 ] [Protocol                     ]]
    119     [[                        ] [CGI] [aCGI] [FastCGI] [SCGI  ]]
    120     [[Requires io_service     ] [No ] [Yes ] [Yes    ] [Yes   ]]
    121     [[Is natively asynchronous] [No ] [No  ] [Yes    ] [Yes   ]]
    122     [[Has native error stream ] [Yes] [Yes ] [Yes    ] [Shared]]
    123 ]
    124 
    125 [endsect] [/ comparison]
    126 
    127 
    128126[endsect] [/ protocols]
  • sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial.qbk

    r38734 r38753  
    66 /]
    77
    8 [section:tut Tutorial]
     8[section Tutorial]
     9
     10As mentioned in the [link __intro__ introduction], there are two ways of using this library: for 'scripting' and everything else.
     11
     12The thing that differentiates 'scripts' from everything else is the [link __ProtocolService__ ProtocolService] (this is similar in use to an [link __asio_io_service__ `io_service`] for those familiar with __asio__).
    913
    1014Except for when using CGI synchronously, a typical program will have two fundamental parts:
     
    2024[h4 Handling requests]
    2125
    22 * Using the [link __meta_data__ meta-data];
     26* [link __meta_data__ Accessing the data] associated with a request;
    2327
    2428* [link __writing__ Writing] a reply;
    2529
    26 * [link boost.cgi.ug.handling_requests.wrapping_up Wrapping up];
     30* [link __wrapping_up__ Wrapping up];
    2731
    28 [include tutorial/accepting.qbk]
     32[include tutorial/quickstart.qbk]
    2933
    30 [include tutorial/loading.qbk]
     34[include:requests tutorial/requests.qbk]
    3135
    32 [include tutorial/meta_data.qbk]
     36[include:accepting tutorial/accepting.qbk]
    3337
    34 [include wrapping_up.qbk]
     38[include:wrapping_up wrapping_up.qbk]
    3539
    3640
  • sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/accepting.qbk

    r38734 r38753  
    88[section:accepting Accepting Requests]
    99
    10 A `basic_request_acceptor<>` is responsible for accepting requests. There are [link __naming_conventions__ common typedefs] 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 an `acgi_request` will work fine: ie. only the first accept will succeed.
     10A `basic_request_acceptor<>` is responsible for accepting requests. The following `typedefs` are provided for typical use:
     11``
     12acgi_acceptor // aCGI
     13fcgi_acceptor // FastCGI
     14scgi_acceptor // SCGI
     15``
    1116
    12 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.
     17Note: `cgi_request` cannot be used with an acceptor, but an `acgi_request` will work fine: ie. only the first accept will succeed. A program written for SCGI or FastCGI will generally have one acceptor running in a loop.
    1318
    14 All you need do is create an `*_acceptor` by passing an instance of a __ProtocolService__ to its constructor. The following member functions are available (take xcgi to imply one of fcgi/scgi/acgi):
     19Accepting 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 other protocols.
     20
     21A `basic_request_acceptor<>` takes an instance of a __ProtocolService__ in its constructor. The following member functions are available (take xcgi to imply one of fcgi/scgi/acgi):
    1522
    1623[table
  • sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/loading.qbk

    r38734 r38753  
    88[section:loading Loading Requests]
    99
    10 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:
     10After 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 call any `meta_*` function. 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:
    1111
    1212[table
     
    1414  [
    1515    [`void basic_request<>::load(bool parse_stdin = true)`]
    16     [Loads the request meta-data into internal `cgi::map`s.[br][br]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.]
     16    [Loads the request meta-data into internal `cgi::map`s.
     17
     18    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.]
    1719  ]
    1820  [
    1921    [`boost::system::error_code&
    2022    basic_request<>::load(boost::system::error_code& ec, bool parse_stdin = true)`]
    21     [Loads the request meta-data into internal `cgi::map`s.[br][br]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`.]
     23    [Loads the request meta-data into internal `cgi::map`s.
     24
     25    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`.]
    2226  ]
    2327  [
  • sandbox/SOC/2007/cgi/libs/cgi/doc/src/user_guide/tutorial/meta_data.qbk

    r38734 r38753  
    66 /]
    77
    8 [section:meta_data Request Meta-data]
     8[def __xss_footnote__ 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/HTTP_COOKIE ambiguities] In other words, since `meta_var` removes such distinctions, its use should be limited to places where the source of the variable doesn't matter. For example, a language toggle (like `"hl=en"`, as Google uses) could come from anywhere and doing so is not an issue.]
    99
    10 [note
    11 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.
     10
     11[section:variables Using Request Variables]
     12
     13[warning
     14A 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 won't work with FastCGI or SCGI requests.
    1215]
    1316
    14 There are six member functions of `basic_request<>` that provide access to the meta-data associated to that request.
     17There are six member functions of `basic_request<>` that provide access to the meta-variables associated to that request.
    1518
    16 [table Meta-data accessor functions
     19[table Meta-variable accessor functions
    1720  [[Function signature] [Purpose]]
    1821  [
     
    2629  [
    2730   [`std::string meta_post(const std::string&, bool greedy = true)`]
    28    [Takes the name of a __POST__ variable and returns the value associated with it (if any).[br][br]  If `greedy == true` - which it is by default - then more data is read from the request if required until all of the POST data has been read.]
     31   [Takes the name of a __POST__ variable and returns the value associated with it (if any).
     32
     33    If `greedy == true` - which it is by default - then more data is read from the request if required until all of the POST data has been read.]
    2934  ]
    3035  [
    3136   [`std::string meta_form(const std::string&, bool greedy = true)`]
    32    [Takes the name of either a __GET__ or __POST__ variable and returns the value associated with it (if any). Note that this will only search the type referred to by the environment variable `"REQUEST_METHOD"`, so it is generally safe to use.[br][br]If `greedy == true` - which it is by default - then more data is read from the request as required until all of the POST data has been read.]
     37   [Takes the name of either a __GET__ or __POST__ variable and returns the value associated with it (if any). Note that this will only search the type referred to by the environment variable `"REQUEST_METHOD"`, so it is generally safe to use.
     38
     39   If `greedy == true` - which it is by default - then more data is read from the request as required until all of the POST data has been read.]
    3340  ]
    3441  [
     
    3845  [
    3946   [`std::string meta_var(const std::string& name, bool greedy = true)`]
    40    [Takes the name of [*any] meta-variable and returns the value associated with it (if any).[br][br]  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.]
     47   [Takes the name of [*any] meta-variable and returns the value associated with it (if any).[footnote __xss_footnote__]
     48
     49   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.]
    4150  ]
    42 ]
    43 
    44 [warning
    45 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/HTTP_COOKIE ambiguities] In other words, since `meta_var` removes such distinctions, its use should be limited to places where the source of the variable doesn't matter. For example, a language toggle (like `"hl=en"`, as Google uses) could come from anywhere and doing so is not an issue.
    4651]
    4752
Note: See TracChangeset for help on using the changeset viewer.