gcc/ada/g-cgi.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT COMPILER COMPONENTS                         --
   4 --                                                                          --
   5 --                             G N A T . C G I                              --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --           Copyright (C) 2000-2003 Ada Core Technologies, Inc.            --
  10 --                                                                          --
  11 -- GNAT is free software;  you can  redistribute it  and/or modify it under --
  12 -- terms of the  GNU General Public License as published  by the Free Soft- --
  13 -- ware  Foundation;  either version 2,  or (at your option) any later ver- --
  14 -- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --
  15 -- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
  16 -- or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License --
  17 -- for  more details.  You should have  received  a copy of the GNU General --
  18 -- Public License  distributed with GNAT;  see file COPYING.  If not, write --
  19 -- to  the Free Software Foundation,  59 Temple Place - Suite 330,  Boston, --
  20 -- MA 02111-1307, USA.                                                      --
  21 --                                                                          --
  22 -- As a special exception,  if other files  instantiate  generics from this --
  23 -- unit, or you link  this unit with other files  to produce an executable, --
  24 -- this  unit  does not  by itself cause  the resulting  executable  to  be --
  25 -- covered  by the  GNU  General  Public  License.  This exception does not --
  26 -- however invalidate  any other reasons why  the executable file  might be --
  27 -- covered by the  GNU Public License.                                      --
  28 --                                                                          --
  29 -- GNAT is maintained by Ada Core Technologies Inc (http://www.gnat.com).   --
  30 --                                                                          --
  31 ------------------------------------------------------------------------------
  32
  33 --  This is a package to interface a GNAT program with a Web server via the
  34 --  Common Gateway Interface (CGI).
  35
  36 --  Other related packages are:
  37
  38 --     GNAT.CGI.Cookie which deal with Web HTTP Cookies.
  39 --     GNAT.CGI.Debug  which output complete CGI runtime environment
  40
  41 --  Basically this package parse the CGI parameter which are a set of key/value
  42 --  pairs. It builds a table whose index is the key and provides some services
  43 --  to deal with this table.
  44
  45 --  Example:
  46
  47 --     Consider the following simple HTML form to capture a client name:
  48
  49 --        <!DOCTYPE HTML PUBLIC "-//W3C//DTD W3 HTML 3.2//EN">
  50 --        <html>
  51 --        <head>
  52 --        <title>My Web Page</title>
  53 --        </head>
  54
  55 --        <body>
  56 --        <form action="/cgi-bin/new_client" method="POST">
  57 --        <input type=text name=client_name>
  58 --        <input type=submit name="Enter">
  59 --        </form>
  60 --        </body>
  61 --        </html>
  62
  63 --     The following program will retrieve the client's name:
  64
  65 --        with GNAT.CGI;
  66
  67 --        procedure New_Client is
  68 --           use GNAT;
  69
  70 --           procedure Add_Client_To_Database (Name : in String) is
  71 --           begin
  72 --              ...
  73 --           end Add_Client_To_Database;
  74
  75 --        begin
  76 --           --  Check that we have 2 arguments (there is two inputs tag in
  77 --           --  the HTML form) and that one of them is called "client_name".
  78
  79 --           if CGI.Argument_Count = 2
  80 --             and the CGI.Key_Exists ("client_name")
  81 --           then
  82 --              Add_Client_To_Database (CGI.Value ("client_name"));
  83 --           end if;
  84
  85 --           ...
  86
  87 --           CGI.Put_Header;
  88 --           Text_IO.Put_Line ("<html><body>< ... Ok ... >");
  89
  90 --        exception
  91 --           when CGI.Data_Error =>
  92 --              CGI.Put_Header ("Location: /htdocs/error.html");
  93 --              --  This returns the address of a Web page to be displayed
  94 --              --  using a "Location:" header style.
  95 --        end New_Client;
  96
  97 --  Note that the names in this package interface have been designed so that
  98 --  they read nicely with the CGI prefix. The recommended style is to avoid
  99 --  a use clause for GNAT.CGI, but to include a use clause for GNAT.
 100
 101 --  This package builds up a table of CGI parameters whose memory is not
 102 --  released. A CGI program is expected to be a short lived program and
 103 --  so it is adequate to have the underlying OS free the program on exit.
 104
 105 package GNAT.CGI is
 106
 107    Data_Error : exception;
 108    --  This is raised when there is a problem with the CGI protocol. Either
 109    --  the data could not be retrieved or the CGI environment is invalid.
 110    --
 111    --  The package will initialize itself by parsing the runtime CGI
 112    --  environment during elaboration but we do not want to raise an
 113    --  exception at this time, so the exception Data_Error is deferred
 114    --  and will be raised when calling any services below (except for Ok).
 115
 116    Parameter_Not_Found : exception;
 117    --  This exception is raised when a specific parameter is not found.
 118
 119    Default_Header : constant String := "Content-type: text/html";
 120    --  This is the default header returned by Put_Header. If the CGI program
 121    --  returned data is not an HTML page, this header must be change to a
 122    --  valid MIME type.
 123
 124    type Method_Type is (Get, Post);
 125    --  The method used to pass parameter from the Web client to the
 126    --  server. With the GET method parameters are passed via the command
 127    --  line, with the POST method parameters are passed via environment
 128    --  variables. Others methods are not supported by this implementation.
 129
 130    type Metavariable_Name is
 131      (Auth_Type,
 132       Content_Length,
 133       Content_Type,
 134       Document_Root,          --  Web server dependent
 135       Gateway_Interface,
 136       HTTP_Accept,
 137       HTTP_Accept_Encoding,
 138       HTTP_Accept_Language,
 139       HTTP_Connection,
 140       HTTP_Cookie,
 141       HTTP_Extension,
 142       HTTP_From,
 143       HTTP_Host,
 144       HTTP_Referer,
 145       HTTP_User_Agent,
 146       Path,
 147       Path_Info,
 148       Path_Translated,
 149       Query_String,
 150       Remote_Addr,
 151       Remote_Host,
 152       Remote_Port,            --  Web server dependent
 153       Remote_Ident,
 154       Remote_User,
 155       Request_Method,
 156       Request_URI,            --  Web server dependent
 157       Script_Filename,        --  Web server dependent
 158       Script_Name,
 159       Server_Addr,            --  Web server dependent
 160       Server_Admin,           --  Web server dependent
 161       Server_Name,
 162       Server_Port,
 163       Server_Protocol,
 164       Server_Signature,       --  Web server dependent
 165       Server_Software);
 166    --  CGI metavariables that are set by the Web server during program
 167    --  execution. All these variables are part of the restricted CGI runtime
 168    --  environment and can be read using Metavariable service. The detailed
 169    --  meanings of these metavariables are out of the scope of this
 170    --  description. Please refer to http://www.w3.org/CGI/ for a description
 171    --  of the CGI specification. Some metavariables are Web server dependent
 172    --  and are not described in the cited document.
 173
 174    procedure Put_Header
 175      (Header : String  := Default_Header;
 176       Force  : Boolean := False);
 177    --  Output standard CGI header by default. The header string is followed by
 178    --  an empty line. This header must be the first answer sent back to the
 179    --  server. Do nothing if this function has already been called and Force
 180    --  is False.
 181
 182    function Ok return Boolean;
 183    --  Returns True if the CGI environment is valid and False otherwise.
 184    --  Every service used when the CGI environment is not valid will raise
 185    --  the exception Data_Error.
 186
 187    function Method return Method_Type;
 188    --  Returns the method used to call the CGI.
 189
 190    function Metavariable
 191      (Name     : Metavariable_Name;
 192       Required : Boolean := False)
 193       return     String;
 194    --  Returns parameter Name value. Returns the null string if Name
 195    --  environment variable is not defined or raises Data_Error if
 196    --  Required is set to True.
 197
 198    function Metavariable_Exists (Name : Metavariable_Name) return Boolean;
 199    --  Returns True if the environment variable Name is defined in
 200    --  the CGI runtime environment and False otherwise.
 201
 202    function URL return String;
 203    --  Returns the URL used to call this script without the parameters.
 204    --  The URL form is: http://<server_name>[:<server_port>]<script_name>
 205
 206    function Argument_Count return Natural;
 207    --  Returns the number of parameters passed to the client. This is the
 208    --  number of input tags in a form or the number of parameters passed to
 209    --  the CGI via the command line.
 210
 211    ---------------------------------------------------
 212    -- Services to retrieve key/value CGI parameters --
 213    ---------------------------------------------------
 214
 215    function Value
 216      (Key      : String;
 217       Required : Boolean := False)
 218       return     String;
 219    --  Returns the parameter value associated to the parameter named Key.
 220    --  If parameter does not exist, returns an empty string if Required
 221    --  is False and raises the exception Parameter_Not_Found otherwise.
 222
 223    function Value (Position : Positive) return String;
 224    --  Returns the parameter value associated with the CGI parameter number
 225    --  Position. Raises Parameter_Not_Found if there is no such parameter
 226    --  (i.e. Position > Argument_Count)
 227
 228    function Key_Exists (Key : String) return Boolean;
 229    --  Returns True if the parameter named Key existx and False otherwise.
 230
 231    function Key (Position : Positive) return String;
 232    --  Returns the parameter key associated with the CGI parameter number
 233    --  Position. Raises the exception Parameter_Not_Found if there is no
 234    --  such parameter (i.e. Position > Argument_Count)
 235
 236    generic
 237      with procedure
 238        Action
 239          (Key      : String;
 240           Value    : String;
 241           Position : Positive;
 242           Quit     : in out Boolean);
 243    procedure For_Every_Parameter;
 244    --  Iterate through all existing key/value pairs and call the Action
 245    --  supplied procedure. The Key and Value are set appropriately, Position
 246    --  is the parameter order in the list, Quit is set to True by default.
 247    --  Quit can be set to False to control the iterator termination.
 248
 249 private
 250
 251    function Decode (S : String) return String;
 252    --  Decode Web string S. A string when passed to a CGI is encoded,
 253    --  this function will decode the string to return the original
 254    --  string's content. Every triplet of the form %HH (where H is an
 255    --  hexadecimal number) is translated into the character such that:
 256    --  Hex (Character'Pos (C)) = HH.
 257
 258 end GNAT.CGI;