src/pthr_cgi.h

   1 /* CGI library.
   2  * - by Richard W.M. Jones <rich@annexia.org>
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Library General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Library General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Library General Public
  15  * License along with this library; if not, write to the Free
  16  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  17  *
  18  * $Id: pthr_cgi.h,v 1.3 2002/08/23 13:53:02 rich Exp $
  19  */
  20
  21 #ifndef PTHR_CGI_H
  22 #define PTHR_CGI_H
  23
  24 #include <pool.h>
  25
  26 #include "pthr_http.h"
  27 #include "pthr_iolib.h"
  28
  29 struct cgi;
  30 typedef struct cgi *cgi;
  31
  32 /* Function: cgi_get_post_max - Get and set the internal POST_MAX parameter.
  33  * Function: cgi_set_post_max
  34  *
  35  * These functions get and set the internal POST_MAX parameter which
  36  * can be used to limit the size of @code{POST} method requests which
  37  * this library will handle. If set to a non-negative integer, then
  38  * POST requests will be limited to the number of bytes given. The
  39  * default is -1 (unlimited) which can leave the server open to denial
  40  * of service attacks.
  41  *
  42  * See also: @ref{new_cgi(3)}.
  43  */
  44 extern int cgi_get_post_max (void);
  45 extern int cgi_set_post_max (int new_post_max);
  46
  47 /* Function: new_cgi - Library for parsing CGI query strings.
  48  * Function: cgi_params
  49  * Function: cgi_param
  50  * Function: cgi_param_list
  51  * Function: cgi_erase
  52  * Function: copy_cgi
  53  *
  54  * @code{new_cgi} creates a new CGI object from an existing HTTP
  55  * request. It reads the query string or POSTed parameters and
  56  * parses them internally. CGI parameters are case sensitive, and
  57  * multiple parameters may be passed with the same name. Parameter
  58  * values are automatically unescaped by the library before you
  59  * get to see them.
  60  *
  61  * @code{cgi_params} returns a list of all the names of the parameters passed
  62  * to the script. The list is returned as a @code{vector} of
  63  * @code{char *}.
  64  *
  65  * @code{cgi_param} returns the value of a single named CGI parameter,
  66  * or @code{NULL} if there is no such parameter. If multiple parameters
  67  * were given with the same name, this returns one of them, essentially
  68  * at random.
  69  *
  70  * @code{cgi_param_list} returns the list of values of the named
  71  * CGI parameter. The list is returned as a @code{vector} of
  72  * @code{char *}.
  73  *
  74  * @code{cgi_erase} erases the named parameter. If a parameter
  75  * was erased, this returns true, else this returns false.
  76  *
  77  * @code{copy_cgi} copies @code{cgi} into pool @code{pool}.
  78  *
  79  * See also: @ref{cgi_get_post_max(3)}, @ref{cgi_escape(3)},
  80  * @ref{new_http_request(3)}.
  81  */
  82 extern cgi new_cgi (pool, http_request, io_handle);
  83 extern vector cgi_params (cgi);
  84 extern const char *cgi_param (cgi, const char *name);
  85 extern const vector cgi_param_list (cgi, const char *name);
  86 extern int cgi_erase (cgi, const char *name);
  87 extern cgi copy_cgi (pool, cgi);
  88
  89 /* Function: cgi_escape - %-escape and unescape CGI arguments.
  90  * Function: cgi_unescape
  91  *
  92  * These functions do %-escaping and unescaping on CGI arguments.
  93  * When %-escaping a string, @code{" "} is replaced by @code{"+"},
  94  * and non-printable
  95  * characters are replaced by @code{"%hh"} where @code{hh} is a
  96  * two-digit hex code. Unescaping a string reverses this process.
  97  *
  98  * See also: @ref{new_cgi(3)}, @ref{new_http_request(3)}.
  99  */
 100 extern char *cgi_escape (pool, const char *str);
 101 extern char *cgi_unescape (pool, const char *str);
 102
 103 #endif /* PTHR_CGI_H */