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