Package: GNAT.CGI

Description

This package builds up a table of CGI parameters whose memory is not released. A CGI program is expected to be a short lived program and so it is adequate to have the underlying OS free the program on exit.

Header

package GNAT.CGI is

Known child units

`GNAT.CGI.Cookie`	(package)
`GNAT.CGI.Debug`	(package)

Exceptions

Data_Error

This is raised when there is a problem with the CGI protocol. Either the data could not be retrieved or the CGI environment is invalid.

The package will initialize itself by parsing the runtime CGI environment during elaboration but we do not want to raise an exception at this time, so the exception Data_Error is deferred and will be raised when calling any services below (except for Ok).

Parameter_Not_Found

This exception is raised when a specific parameter is not found.

Type Summary

`Metavariable_Name`
`Method_Type`

Constants and Named Numbers

Default_Header : constant String := "Content-type: text/html";

This is the default header returned by Put_Header. If the CGI program returned data is not an HTML page, this header must be change to a valid MIME type.

Other Items:

type Method_Type is (Get, Post);

The method used to pass parameter from the Web client to the server. With the GET method parameters are passed via the command line, with the POST method parameters are passed via environment variables. Others methods are not supported by this implementation.

type Metavariable_Name is
  (Auth_Type,
   Content_Length,
   Content_Type,
   Document_Root,          --  Web server dependant
   Gateway_Interface,
   HTTP_Accept,
   HTTP_Accept_Encoding,
   HTTP_Accept_Language,
   HTTP_Connection,
   HTTP_Cookie,
   HTTP_Extension,
   HTTP_From,
   HTTP_Host,
   HTTP_Referer,
   HTTP_User_Agent,
   Path,
   Path_Info,
   Path_Translated,
   Query_String,
   Remote_Addr,
   Remote_Host,
   Remote_Port,            --  Web server dependant
   Remote_Ident,
   Remote_User,
   Request_Method,
   Request_URI,            --  Web server dependant
   Script_Filename,        --  Web server dependant
   Script_Name,
   Server_Addr,            --  Web server dependant
   Server_Admin,           --  Web server dependant
   Server_Name,
   Server_Port,
   Server_Protocol,
   Server_Signature,       --  Web server dependant
   Server_Software);

CGI metavariables that are set by the Web server during program execution. All these variables are part of the restricted CGI runtime environment and can be read using Metavariable service. The detailed meanings of these metavariables are out of the scope of this description. Please refer to http://www.w3.org/CGI/ for a description of the CGI specification. Some metavariables are Web server dependant and are not described in the cited document.

procedure Put_Header
  (Header : String  := Default_Header;
   Force  : Boolean := False);

Output standard CGI header by default. The header string is followed by an empty line. This header must be the first answer sent back to the server. Do nothing if this function has already been called and Force is False.

function Ok return Boolean;

Returns True if the CGI environment is valid and False otherwise. Every service used when the CGI environment is not valid will raise the exception Data_Error.

function Method return Method_Type;

Returns the method used to call the CGI.

function Metavariable
  (Name     : Metavariable_Name;
   Required : Boolean := False)
   return     String;

Returns parameter Name value. Returns the null string if Name environment variable is not defined or raises Data_Error if Required is set to True.

function Metavariable_Exists (Name : Metavariable_Name) return Boolean;

Returns True if the environment variable Name is defined in the CGI runtime environment and False otherwise.

function URL return String;

Returns the URL used to call this script without the parameters. The URL form is: http://<server_name>[:<server_port>]<script_name>

function Argument_Count return Natural;

Returns the number of parameters passed to the client. This is the number of input tags in a form or the number of parameters passed to the CGI via the command line.

function Value
  (Key      : String;
   Required : Boolean := False)
   return     String;

Returns the parameter value associated to the parameter named Key. If parameter does not exist, returns an empty string if Required is False and raises the exception Parameter_Not_Found otherwise.

function Value (Position : Positive) return String;

Returns the parameter value associated with the CGI parameter number Position. Raises Parameter_Not_Found if there is no such parameter (i.e. Position > Argument_Count)

function Key_Exists (Key : String) return Boolean;

Returns True if the parameter named Key existx and False otherwise.

function Key (Position : Positive) return String;

Returns the parameter key associated with the CGI parameter number Position. Raises the exception Parameter_Not_Found if there is no such parameter (i.e. Position > Argument_Count)

generic
  with procedure
    Action
      (Key      : String;
       Value    : String;
       Position : Positive;
       Quit     : in out Boolean);
procedure For_Every_Parameter;

Iterate through all existing key/value pairs and call the Action supplied procedure. The Key and Value are set appropriately, Position is the parameter order in the list, Quit is set to True by default. Quit can be set to False to control the iterator termination.

private

   --  Implementation-defined ...

end GNAT.CGI;