]>
Commit | Line | Data |
---|---|---|
38cbfe40 RK |
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 | -- -- | |
38cbfe40 RK |
9 | -- Copyright (C) 2000-2001 Ada Core Technologies, Inc. -- |
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 2, 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. See the GNU General Public License -- | |
17 | -- for more details. You should have received a copy of the GNU General -- | |
18 | -- Public License distributed with GNAT; see file COPYING. If not, write -- | |
19 | -- to the Free Software Foundation, 59 Temple Place - Suite 330, Boston, -- | |
20 | -- MA 02111-1307, USA. -- | |
21 | -- -- | |
22 | -- As a special exception, if other files instantiate generics from this -- | |
23 | -- unit, or you link this unit with other files to produce an executable, -- | |
24 | -- this unit does not by itself cause the resulting executable to be -- | |
25 | -- covered by the GNU General Public License. This exception does not -- | |
26 | -- however invalidate any other reasons why the executable file might be -- | |
27 | -- covered by the GNU Public License. -- | |
28 | -- -- | |
29 | -- GNAT is maintained by Ada Core Technologies Inc (http://www.gnat.com). -- | |
30 | -- -- | |
31 | ------------------------------------------------------------------------------ | |
32 | ||
33 | -- This is a package to interface a GNAT program with a Web server via the | |
34 | -- Common Gateway Interface (CGI). It exports services to deal with Web | |
35 | -- cookies (piece of information kept in the Web client software). | |
36 | ||
37 | -- The complete CGI Cookie specification can be found in the RFC2109 at: | |
38 | -- http://www.ics.uci.edu/pub/ietf/http/rfc2109.txt | |
39 | ||
40 | -- This package builds up data tables whose memory is not released. | |
41 | -- A CGI program is expected to be a short lived program and so it | |
42 | -- is adequate to have the underlying OS free the program on exit. | |
43 | ||
44 | package GNAT.CGI.Cookie is | |
45 | ||
46 | -- The package will initialize itself by parsing the HTTP_Cookie runtime | |
47 | -- CGI environment variable during elaboration but we do not want to raise | |
48 | -- an exception at this time, so the exception Data_Error is deferred and | |
49 | -- will be raised when calling any services below (except for Ok). | |
50 | ||
51 | Cookie_Not_Found : exception; | |
52 | -- This exception is raised when a specific parameter is not found. | |
53 | ||
54 | procedure Put_Header | |
55 | (Header : String := Default_Header; | |
56 | Force : Boolean := False); | |
57 | -- Output standard CGI header by default. This header must be returned | |
58 | -- back to the server at the very beginning and will be output only for | |
59 | -- the first call to Put_Header if Force is set to False. This procedure | |
60 | -- also outputs the Cookies that have been defined. If the program uses | |
61 | -- the GNAT.CGI.Put_Header service, cookies will not be set. | |
62 | -- | |
63 | -- Cookies are passed back to the server in the header, the format is: | |
64 | -- | |
65 | -- Set-Cookie: <key>=<value>; comment=<comment>; domain=<domain>; | |
66 | -- max_age=<max_age>; path=<path>[; secured] | |
67 | ||
68 | function Ok return Boolean; | |
69 | -- Returns True if the CGI cookie environment is valid and False | |
70 | -- otherwise. Every service used when the CGI environment is not valid | |
71 | -- will raise the exception Data_Error. | |
72 | ||
73 | function Count return Natural; | |
74 | -- Returns the number of cookies received by the CGI. | |
75 | ||
76 | function Value | |
77 | (Key : String; | |
78 | Required : Boolean := False) | |
79 | return String; | |
80 | -- Returns the cookie value associated with the cookie named Key. If | |
81 | -- cookie does not exist, returns an empty string if Required is | |
82 | -- False and raises the exception Cookie_Not_Found otherwise. | |
83 | ||
84 | function Value (Position : Positive) return String; | |
85 | -- Returns the value associated with the cookie number Position | |
86 | -- of the CGI. It raises Cookie_Not_Found if there is no such | |
87 | -- cookie (i.e. Position > Count) | |
88 | ||
89 | function Exists (Key : String) return Boolean; | |
90 | -- Returns True if the cookie named Key exist and False otherwise. | |
91 | ||
92 | function Key (Position : Positive) return String; | |
93 | -- Returns the key associated with the cookie number Position of | |
94 | -- the CGI. It raises Cookie_Not_Found if there is no such cookie | |
95 | -- (i.e. Position > Count) | |
96 | ||
97 | procedure Set | |
98 | (Key : String; | |
99 | Value : String; | |
100 | Comment : String := ""; | |
101 | Domain : String := ""; | |
102 | Max_Age : Natural := Natural'Last; | |
103 | Path : String := "/"; | |
104 | Secure : Boolean := False); | |
105 | -- Add a cookie to the list of cookies. This will be sent back | |
106 | -- to the server by the Put_Header service above. | |
107 | ||
108 | generic | |
109 | with procedure | |
110 | Action | |
111 | (Key : String; | |
112 | Value : String; | |
113 | Position : Positive; | |
114 | Quit : in out Boolean); | |
115 | procedure For_Every_Cookie; | |
116 | -- Iterate through all cookies received from the server and call | |
117 | -- the Action supplied procedure. The Key, Value parameters are set | |
118 | -- appropriately, Position is the cookie order in the list, Quit is set to | |
119 | -- True by default. Quit can be set to False to control the iterator | |
120 | -- termination. | |
121 | ||
122 | end GNAT.CGI.Cookie; |