OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [gnu-stable/] [gcc-4.5.1/] [gcc/] [ada/] [g-cgi.ads] - Blame information for rev 826

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 281 jeremybenn
------------------------------------------------------------------------------
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-2009, 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 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,  51  Franklin  Street,  Fifth  Floor, --
20
-- Boston, MA 02110-1301, 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 was originally developed  by the GNAT team at  New York University. --
30
-- Extensive contributions were provided by Ada Core Technologies Inc.      --
31
--                                                                          --
32
------------------------------------------------------------------------------
33
 
34
--  This is a package to interface a GNAT program with a Web server via the
35
--  Common Gateway Interface (CGI).
36
 
37
--  Other related packages are:
38
 
39
--     GNAT.CGI.Cookie which deal with Web HTTP Cookies.
40
--     GNAT.CGI.Debug  which output complete CGI runtime environment
41
 
42
--  Basically this package parse the CGI parameter which are a set of key/value
43
--  pairs. It builds a table whose index is the key and provides some services
44
--  to deal with this table.
45
 
46
--  Example:
47
 
48
--     Consider the following simple HTML form to capture a client name:
49
 
50
--        <!DOCTYPE HTML PUBLIC "-//W3C//DTD W3 HTML 3.2//EN">
51
--        <html>
52
--        <head>
53
--        <title>My Web Page</title>
54
--        </head>
55
 
56
--        <body>
57
--        <form action="/cgi-bin/new_client" method="POST">
58
--        <input type=text name=client_name>
59
--        <input type=submit name="Enter">
60
--        </form>
61
--        </body>
62
--        </html>
63
 
64
--     The following program will retrieve the client's name:
65
 
66
--        with GNAT.CGI;
67
 
68
--        procedure New_Client is
69
--           use GNAT;
70
 
71
--           procedure Add_Client_To_Database (Name : String) is
72
--           begin
73
--              ...
74
--           end Add_Client_To_Database;
75
 
76
--        begin
77
--           --  Check that we have 2 arguments (there is two inputs tag in
78
--           --  the HTML form) and that one of them is called "client_name".
79
 
80
--           if CGI.Argument_Count = 2
81
--             and then CGI.Key_Exists ("client_name")
82
--           then
83
--              Add_Client_To_Database (CGI.Value ("client_name"));
84
--           end if;
85
 
86
--           ...
87
 
88
--           CGI.Put_Header;
89
--           Text_IO.Put_Line ("<html><body>< ... Ok ... >");
90
 
91
--        exception
92
--           when CGI.Data_Error =>
93
--              CGI.Put_Header ("Location: /htdocs/error.html");
94
--              --  This returns the address of a Web page to be displayed
95
--              --  using a "Location:" header style.
96
--        end New_Client;
97
 
98
--  Note that the names in this package interface have been designed so that
99
--  they read nicely with the CGI prefix. The recommended style is to avoid
100
--  a use clause for GNAT.CGI, but to include a use clause for GNAT.
101
 
102
--  This package builds up a table of CGI parameters whose memory is not
103
--  released. A CGI program is expected to be a short lived program and
104
--  so it is adequate to have the underlying OS free the program on exit.
105
 
106
package GNAT.CGI is
107
 
108
   Data_Error : exception;
109
   --  This is raised when there is a problem with the CGI protocol. Either
110
   --  the data could not be retrieved or the CGI environment is invalid.
111
   --
112
   --  The package will initialize itself by parsing the runtime CGI
113
   --  environment during elaboration but we do not want to raise an
114
   --  exception at this time, so the exception Data_Error is deferred
115
   --  and will be raised when calling any services below (except for Ok).
116
 
117
   Parameter_Not_Found : exception;
118
   --  This exception is raised when a specific parameter is not found
119
 
120
   Default_Header : constant String := "Content-type: text/html";
121
   --  This is the default header returned by Put_Header. If the CGI program
122
   --  returned data is not an HTML page, this header must be change to a
123
   --  valid MIME type.
124
 
125
   type Method_Type is (Get, Post);
126
   --  The method used to pass parameter from the Web client to the
127
   --  server. With the GET method parameters are passed via the command
128
   --  line, with the POST method parameters are passed via environment
129
   --  variables. Others methods are not supported by this implementation.
130
 
131
   type Metavariable_Name is
132
     (Auth_Type,
133
      Content_Length,
134
      Content_Type,
135
      Document_Root,          --  Web server dependent
136
      Gateway_Interface,
137
      HTTP_Accept,
138
      HTTP_Accept_Encoding,
139
      HTTP_Accept_Language,
140
      HTTP_Connection,
141
      HTTP_Cookie,
142
      HTTP_Extension,
143
      HTTP_From,
144
      HTTP_Host,
145
      HTTP_Referer,
146
      HTTP_User_Agent,
147
      Path,
148
      Path_Info,
149
      Path_Translated,
150
      Query_String,
151
      Remote_Addr,
152
      Remote_Host,
153
      Remote_Port,            --  Web server dependent
154
      Remote_Ident,
155
      Remote_User,
156
      Request_Method,
157
      Request_URI,            --  Web server dependent
158
      Script_Filename,        --  Web server dependent
159
      Script_Name,
160
      Server_Addr,            --  Web server dependent
161
      Server_Admin,           --  Web server dependent
162
      Server_Name,
163
      Server_Port,
164
      Server_Protocol,
165
      Server_Signature,       --  Web server dependent
166
      Server_Software);
167
   --  CGI metavariables that are set by the Web server during program
168
   --  execution. All these variables are part of the restricted CGI runtime
169
   --  environment and can be read using Metavariable service. The detailed
170
   --  meanings of these metavariables are out of the scope of this
171
   --  description. Please refer to http://www.w3.org/CGI/ for a description
172
   --  of the CGI specification. Some metavariables are Web server dependent
173
   --  and are not described in the cited document.
174
 
175
   procedure Put_Header
176
     (Header : String  := Default_Header;
177
      Force  : Boolean := False);
178
   --  Output standard CGI header by default. The header string is followed by
179
   --  an empty line. This header must be the first answer sent back to the
180
   --  server. Do nothing if this function has already been called and Force
181
   --  is False.
182
 
183
   function Ok return Boolean;
184
   --  Returns True if the CGI environment is valid and False otherwise.
185
   --  Every service used when the CGI environment is not valid will raise
186
   --  the exception Data_Error.
187
 
188
   function Method return Method_Type;
189
   --  Returns the method used to call the CGI
190
 
191
   function Metavariable
192
     (Name     : Metavariable_Name;
193
      Required : Boolean := False) return String;
194
   --  Returns parameter Name value. Returns the null string if Name
195
   --  environment variable is not defined or raises Data_Error if
196
   --  Required is set to True.
197
 
198
   function Metavariable_Exists (Name : Metavariable_Name) return Boolean;
199
   --  Returns True if the environment variable Name is defined in
200
   --  the CGI runtime environment and False otherwise.
201
 
202
   function URL return String;
203
   --  Returns the URL used to call this script without the parameters.
204
   --  The URL form is: http://<server_name>[:<server_port>]<script_name>
205
 
206
   function Argument_Count return Natural;
207
   --  Returns the number of parameters passed to the client. This is the
208
   --  number of input tags in a form or the number of parameters passed to
209
   --  the CGI via the command line.
210
 
211
   ---------------------------------------------------
212
   -- Services to retrieve key/value CGI parameters --
213
   ---------------------------------------------------
214
 
215
   function Value
216
     (Key      : String;
217
      Required : Boolean := False) return String;
218
   --  Returns the parameter value associated to the parameter named Key.
219
   --  If parameter does not exist, returns an empty string if Required
220
   --  is False and raises the exception Parameter_Not_Found otherwise.
221
 
222
   function Value (Position : Positive) return String;
223
   --  Returns the parameter value associated with the CGI parameter number
224
   --  Position. Raises Parameter_Not_Found if there is no such parameter
225
   --  (i.e. Position > Argument_Count)
226
 
227
   function Key_Exists (Key : String) return Boolean;
228
   --  Returns True if the parameter named Key exists and False otherwise
229
 
230
   function Key (Position : Positive) return String;
231
   --  Returns the parameter key associated with the CGI parameter number
232
   --  Position. Raises the exception Parameter_Not_Found if there is no
233
   --  such parameter (i.e. Position > Argument_Count)
234
 
235
   generic
236
     with procedure
237
       Action
238
         (Key      : String;
239
          Value    : String;
240
          Position : Positive;
241
          Quit     : in out Boolean);
242
   procedure For_Every_Parameter;
243
   --  Iterate through all existing key/value pairs and call the Action
244
   --  supplied procedure. The Key and Value are set appropriately, Position
245
   --  is the parameter order in the list, Quit is set to True by default.
246
   --  Quit can be set to False to control the iterator termination.
247
 
248
private
249
 
250
   function Decode (S : String) return String;
251
   --  Decode Web string S. A string when passed to a CGI is encoded,
252
   --  this function will decode the string to return the original
253
   --  string's content. Every triplet of the form %HH (where H is an
254
   --  hexadecimal number) is translated into the character such that:
255
   --  Hex (Character'Pos (C)) = HH.
256
 
257
end GNAT.CGI;

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.