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