File : 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 -- --
19 -- --
20 -- --
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;