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
104package 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
246private
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
255end GNAT.CGI;
256