File : g-cgicoo.ads
1 ------------------------------------------------------------------------------
2 -- --
3 -- GNAT COMPILER COMPONENTS --
4 -- --
5 -- G N A T . C G I . C O O K I E --
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). It exports services to deal with Web
34 -- cookies (piece of information kept in the Web client software).
35
36 -- The complete CGI Cookie specification can be found in the RFC2109 at:
37 -- http://www.ics.uci.edu/pub/ietf/http/rfc2109.txt
38
39 -- This package builds up data tables whose memory is not released. A CGI
40 -- program is expected to be a short lived program and so it is adequate to
41 -- have the underlying OS free the program on exit.
42
43 package GNAT.CGI.Cookie is
44
45 -- The package will initialize itself by parsing the HTTP_Cookie runtime
46 -- CGI environment variable during elaboration but we do not want to raise
47 -- an exception at this time, so the exception Data_Error is deferred and
48 -- will be raised when calling any services below (except for Ok).
49
50 Cookie_Not_Found : exception;
51 -- This exception is raised when a specific parameter is not found
52
53 procedure Put_Header
54 (Header : String := Default_Header;
55 Force : Boolean := False);
56 -- Output standard CGI header by default. This header must be returned
57 -- back to the server at the very beginning and will be output only for
58 -- the first call to Put_Header if Force is set to False. This procedure
59 -- also outputs the Cookies that have been defined. If the program uses
60 -- the GNAT.CGI.Put_Header service, cookies will not be set.
61 --
62 -- Cookies are passed back to the server in the header, the format is:
63 --
64 -- Set-Cookie: <key>=<value>; comment=<comment>; domain=<domain>;
65 -- max_age=<max_age>; path=<path>[; secured]
66
67 function Ok return Boolean;
68 -- Returns True if the CGI cookie environment is valid and False otherwise.
69 -- Every service used when the CGI environment is not valid will raise the
70 -- exception Data_Error.
71
72 function Count return Natural;
73 -- Returns the number of cookies received by the CGI
74
75 function Value
76 (Key : String;
77 Required : Boolean := False) return String;
78 -- Returns the cookie value associated with the cookie named Key. If cookie
79 -- does not exist, returns an empty string if Required is False and raises
80 -- the exception Cookie_Not_Found otherwise.
81
82 function Value (Position : Positive) return String;
83 -- Returns the value associated with the cookie number Position of the CGI.
84 -- It raises Cookie_Not_Found if there is no such cookie (i.e. Position >
85 -- Count)
86
87 function Exists (Key : String) return Boolean;
88 -- Returns True if the cookie named Key exist and False otherwise
89
90 function Key (Position : Positive) return String;
91 -- Returns the key associated with the cookie number Position of the CGI.
92 -- It raises Cookie_Not_Found if there is no such cookie (i.e. Position >
93 -- Count)
94
95 procedure Set
96 (Key : String;
97 Value : String;
98 Comment : String := "";
99 Domain : String := "";
100 Max_Age : Natural := Natural'Last;
101 Path : String := "/";
102 Secure : Boolean := False);
103 -- Add a cookie to the list of cookies. This will be sent back to the
104 -- server by the Put_Header service above.
105
106 generic
107 with procedure
108 Action
109 (Key : String;
110 Value : String;
111 Position : Positive;
112 Quit : in out Boolean);
113 procedure For_Every_Cookie;
114 -- Iterate through all cookies received from the server and call
115 -- the Action supplied procedure. The Key, Value parameters are set
116 -- appropriately, Position is the cookie order in the list, Quit is set to
117 -- True by default. Quit can be set to False to control the iterator
118 -- termination.
119
120 end GNAT.CGI.Cookie;