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