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