Package: GNAT.CGI.Cookie

Description

This package builds up data tables 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. The package will initialize itself by parsing the HTTP_Cookie runtime CGI environment variable 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).

Header

package GNAT.CGI.Cookie is

Exceptions

Cookie_Not_Found

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

Other Items:

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

Output standard CGI header by default. This header must be returned back to the server at the very beginning and will be output only for the first call to Put_Header if Force is set to False. This procedure also outputs the Cookies that have been defined. If the program uses the GNAT.CGI.Put_Header service, cookies will not be set.

Cookies are passed back to the server in the header, the format is:

Set-Cookie: <key>=<value>; comment=<comment>; domain=<domain>; max_age=<max_age>; path=<path>[; secured]

function Ok return Boolean;

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

function Count return Natural;

Returns the number of cookies received by the CGI.

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

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

function Value (Position : Positive) return String;

Returns the value associated with the cookie number Position of the CGI. It raises Cookie_Not_Found if there is no such cookie (i.e. Position > Count)

function Exists (Key : String) return Boolean;

Returns True if the cookie named Key exist and False otherwise.

function Key (Position : Positive) return String;

Returns the key associated with the cookie number Position of the CGI. It raises Cookie_Not_Found if there is no such cookie (i.e. Position > Count)

procedure Set
  (Key     : String;
   Value   : String;
   Comment : String   := "";
   Domain  : String   := "";
   Max_Age : Natural  := Natural'Last;
   Path    : String   := "/";
   Secure  : Boolean  := False);

Add a cookie to the list of cookies. This will be sent back to the server by the Put_Header service above.

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

Iterate through all cookies received from the server and call the Action supplied procedure. The Key, Value parameters are set appropriately, Position is the cookie order in the list, Quit is set to True by default. Quit can be set to False to control the iterator termination.

end GNAT.CGI.Cookie;