3. Using AWS
3.1. Setting up environment
3.1.1. Using environment variables
After installing AWS you must set the build environment to
point the compiler to the right libraries. First let’s say that
AWS has been installed in awsroot directory.
Following are the instructions to set the environment yourself. Note that the preferred solution is to use project files. In this case there is no manual configuration.
spec files
The spec files are installed in
<awsroot>/include/aws. Add this path into ADA_INCLUDE_PATH or put it on the command line -aI<awsroot>/include/aws.
libraries
The GNAT library files (
.ali) and the AWS libraries (libaws.a) are installed into<awsroot>/lib/aws. Add this path into ADA_OBJECTS_PATH or put it on the command line -aO<awsroot>/lib/aws/static. Furthermore for gnatlink to find the libraries you must add the following library path option on the gnatmake command line -largs -L<awsroot>/lib/aws -laws.Note that to build SSL applications you need to add -lssl -lcrypto on gnatmake’s -largs section.
external libraries
You must do the same thing (setting ADA_INCLUDE_PATH and ADA_OBJECTS_PATH) for all external libraries that you will be using.
3.1.2. Using GNAT Project Files
The best solution is to use the installed GNAT Project File
aws.gpr. This is supported only for GNAT 5.01 or
above. You must have installed XML/Ada with project file
support too.
If this is the case just set the ADA_PROJECT_PATH variable to point to the AWS and XML/Ada install directories. From there you just have to with the AWS project file in your GNAT Project file, nothing else to set:
with "aws";
project Simple is
for Main use ("prog.adb");
for Source_Dirs use ("src");
for Object_Dir use "obj";
end Simple;
See the GNAT User’s Guide for more information about GNAT Project Files.
3.2. Basic notions
AWS is not a Web Server like IIS or Apache, it is a component to embedded HTTP protocol in an application. It means that it is possible to build an application which can also answer to a standard browser like Internet Explorer or Netscape Navigator. Since AWS provides support client and server HTTP protocol, applications can communicate through the HTTP channel. This give a way to build distributed applications, see AWS.Client.
An application using AWS can open many HTTP channels. Each channel will use a specific port. For example, it is possible to embedded many HTTP and/or many HTTPS channels in the same application.
3.2.1. Building an AWS server
To build a server you must:
declare the HTTP Web Server:
WS : AWS.Server.HTTP;
Start the server
You need to start the server before using it. This is done by calling AWS.Server.Start (see AWS.Server):
procedure Start (Web_Server : in out HTTP; Name : in String; Callback : in Response.Callback; Max_Connection : in Positive := Def_Max_Connect; Admin_URI : in String := Def_Admin_URI; Port : in Positive := Def_Port; Security : in Boolean := False; Session : in Boolean := False; Case_Sensitive_Parameters : in Boolean := True; Upload_Directory : in String := Def_Upload_Dir); -- Start the Web server. It initialize the Max_Connection connections -- lines. Name is just a string used to identify the server. This is used -- for example in the administrative page. Admin_URI must be set to enable -- the administrative status page. Callback is the procedure to call for -- each resource requested. Port is the Web server port. If Security is -- set to True the server will use an HTTPS/SSL connection. If Session is -- set to True the server will be able to get a status for each client -- connected. A session ID is used for that, on the client side it is a -- cookie. Case_Sensitive_Parameters if set to False it means that the CGI -- parameters name will be handled without case sensitivity. Upload -- directory point to a directory where uploaded files will be stored.
The procedure Start takes many parameters:
Web_Server
this is the Web server to start.
Name
This is a string to identify the server. This name will be used for example in the administrative status page.
Callback
This is the procedure to call for each requested resources. In this procedure you must handle all the possible URI that you want to support. (see below).
Max_Connection
This is the maximum number of simultaneous connections. It means that Max_Connection client’s browsers can gets answer at the same time. This parameter must be changed to match your needs. A medium Web server will certainly need something like 20 or 30 simultaneous connections.
Admin_URI
This is a special URI recognized internally by the server. If this URI is requested the server will return the administrative page. This page is built using a specific template page (default is ‘aws_status.thtml’), see Status page.
The administrative page returns many information about the server. It is possible to configure the server via two configuration files see Configuration options.
Port
This is the port to use for the Web server. You can use any free port on your computer. Note that on some OS specific range could be reserved or needs specials privileges (port 80 on Linux for example).
Security
If Security is set to True the server will use an HTTPS/SSL connection. This part uses the OpenSSL or GNUTLS library.
Session
If Session is set to true the server will keep a session ID for each client. The client will be able to save and get variables associated with this session ID.
Case_Sensitive_Parameters
If set to True the CGI name parameters will be handled without using the case.
Note that there is other Start routines which support other features. For example there is a Start routine which use a dispatcher routine instead of the simple callback procedure, see AWS.Server. And there is also the version using a Config.Object which is the most generic one.
provides a callback procedure
The callback procedure has the following prototype:
function Service (Request : in AWS.Status.Data) return AWS.Response.Data;
This procedure receive the request status. It is possible to retrieve information about the request through the AWS.Status API (see AWS.Status.).
For example, to know what URI has been asked:
URI : constant String := AWS.Status.URI (Request); if URI = "/whatever" then ... end if;
Then this function should return an answer using one of the constructors in AWS.Response (see AWS.Response.). For example, to return an HTML message:
AWS.Response.Build (Content_Type => "text/html", Message_Body => "<p>just a demo");
It is also possible to return a file. For example, here is the way to return a PNG image:
AWS.Response.File (Content_Type => "image/png", Filename => "adains.png");
Note that the main procedure should exit only when the server is terminated. For this you can use the AWS.Server.Wait service.
A better solution is to use a template engine like Templates_Parser to build the HTML Web Server answer. Templates_Parser module is distributed with this version of AWS.
3.2.2. Callback procedure
The callback procedure is the user’s code that will be called by the AWS component to get the right answer for the requested resource. In fact AWS just open the HTTP message, parsing the HTTP header and it builds an object of type AWS.Status.Data. At this point it calls the user’s callback procedure, passing the object. The callback procedure must returns the right response for the requested resources. Now AWS will just build up the HTTP response message and send it back to user’s browser.
But what is the resource ?
Indeed in a standard Web development a resource is either a static object - an HTML page, an XML or XSL document - or a CGI script. With AWS a resource is just a string to identify the resource, it does not represent the name of a static object or CGI script.
So this string is just an internal representation for the resource. The callback procedure must be implemented to handle each internal resource and return the right response.
Let’s have a small example. For example we want to build a Web server that will answer ‘Hello World’ if we ask for the internal resource /hello, and must answer ‘Hum…’ otherwise:
with AWS.Response;
with AWS.Server;
with AWS.Status;
procedure Hello_World is
WS : AWS.Server.HTTP;
function HW_CB (Request : in AWS.Status.Data)
return AWS.Response.Data
is
URI : constant String := AWS.Status.URI (Request);
begin
if URI = "/hello" then
return AWS.Response.Build ("text/html", "<p>Hello world !");
else
return AWS.Response.Build ("text/html", "<p>Hum...");
end if;
end HW_CB;
begin
AWS.Server.Start
(WS, "Hello World", Callback => HW_CB'Unrestricted_Access);
delay 30.0;
end Hello_World;
Now of course the resource internal name can represent a file on disk. It is not mandatory but it is possible. For example it is perfectly possible to build with AWS a simple page server.
As an example, let’s build a simple page server. This server will returns files in the current directory. Resources internal name represent an HTML page or a GIF or PNG image for example. This server will return a 404 message (Web Page Not Found) if the file does not exist. Here is the callback procedure that implements such simple page server:
function Get (Request : in AWS.Status.Data) return AWS.Response.Data is
URI : constant String := AWS.Status.URI (Request);
Filename : constant String := URI (2 .. URI'Last);
begin
if Utils.Is_Regular_File (Filename) then
return AWS.Response.File
(Content_Type => AWS.MIME.Content_Type (Filename),
Filename => Filename);
else
return AWS.Response.Acknowledge
(Messages.S404,
"<p>Page '" & URI & "' Not found.");
end if;
end Get;
3.2.3. Form parameters
Form parameters are stored into a table of key/value pair. The key is the form input tag name and the value is the content of the input field as filled by the user:
Enter your name
<FORM METHOD=GET ACTION=/get-form>"
<INPUT TYPE=TEXT NAME=name VALUE="<default>" size=15>
<INPUT TYPE=SUBMIT NAME=go VALUE="Ok">
</FORM>
Note that as explained above Callback procedure, the resource described in ACTION is just an internal string representation for the resource.
In this example there is two form parameters:
- name
The value is the content of this text field as filled by the client.
- go
The value is “Ok”.
There is many functions (in AWS.Parameters) to retrieve the tag name or value and the number of parameters. Here are some examples:
function Service (Request : in AWS.Status.Data) return AWS.Response.Data is
P : constant AWS.Parameters.List := AWS.Status.Parameters (Request);
...
AWS.Parameters.Get (P, “name”)
Returns the value for parameter named name
AWS.Parameters.Get_Name (P, 1)
Returns the string “name”.
AWS.Parameters.Get (P, 1)
Returns the value for parameter named name
AWS.Parameters.Get (P, “go”)
Returns the string “Ok”.
AWS.Parameters.Get_Name (P, 2)
Returns the string “go”.
AWS.Parameters.Get (P, 2)
Returns the string “Ok”.
Request is the AWS current connection status passed to the callback procedure. And P is the parameters list retrieved from the connection status data. For a discussion about the callback procedure see Building an AWS server.
3.2.4. Distribution of an AWS server
The directory containing the server program must contain the following files if you plan to use a status page see Status page.
aws_status.thtml
The template HTML file for the AWS status page.
aws_logo.png
The AWS logo displayed on the status page.
aws_up.png
The AWS hotplug table up arrow.
aws_down.png
The AWS hotplug table down arrow.
Note that these filenames are the current AWS default. But it is possible to change those defaults using the configuration files see Configuration options.
3.3. Building answers
We have already seen, in simple examples, how to build basic answers using AWS.Response API. In this section we present all ways to build answers from basic support to the more advanced support like the compressed memory stream response.
3.3.1. Redirection
A redirection is a way to redirect the client’s browser to another URL. Client’s won’t notice that a redirection has occurs. As soon as the browser has received the response from the server it will retrieve the page as pointed by the redirection:
return Response.URL (Location => "/use-this-one");
3.3.2. New location for a page
User will receive a Web page saying that this page has moved and eventually pointing to the new location:
return Response.Moved
(Location => "/use-this-one";
Message => "This page has moved, please update your reference");
3.3.3. Authentication required
For protected pages you need to ask user to enter a password. See Authentication.
3.3.4. Sending back an error message
Acknowledge can be used to send back error messages. There is many kind of status code, see Message.Status_Code definition. Together with the status code it is possible to pass textual error message in Message_Body parameter:
return Response.Acknowledge
(Status_Code => Messages.S503,
Message_Body => "Can't connect to the database, please retry later.",
Content_Type => MIME.Text_Plain);
3.3.5. Response from a string
This is the simplest way to build a response object. There is two constructors in AWS.Response, one based on a standard string and one for Unbounded_String:
return Response.Build (MIME.Text_HTML, "My answer");
The Build routine takes also a status code parameter to handle errors. By default this code is Messages.S200 which is the standard HTTP status (no error encountered). The other parameter can be used to control caches. See AWS.Response.
3.3.6. Response from a Stream_Element_Array
This is exactly as above but the Build routine takes a Stream_Element_Array instead of a string.
3.3.7. Response from a file
To build a File response there is a single constructor named File. This routine is very similar to the one above except that we specify a filename as the response:
return Response.File (MIME.Text_HTML, "index.html");
Again there parameters to control the status code and cache. No check
on the filename is done at this point, so if index.html does
not exit no exception is raised. The server is responsible to check
for the file and to properly send back the 404 message if necessary.
Note that this routine takes an optional parameter named Once that is to be used for temporary files created on the server side for the client. With Once set to True the file will be deleted by the server after sending it (this includes the case where the download is suspended).
3.3.8. Response from a stream
Sometimes it is not possible (or convenient) to build the response in memory as a string object for example. Streams can be used to workaround this. The constructor for such response is again very similar to the ones above except that instead of the data we pass an handle to a Resources.Streams.Stream_Type object.
The first step is to build the stream object. This is done by deriving a new type from Resources.Streams.Stream_Type and implementing three abstract procedures.
Read
Must return the next chunk of data from the stream. Note that initialization if needed are to be done there during the first call to read.
End_Of_File
Must return True when there is no more data on the stream.
Close
Must close the stream and for example release all memory used by the implementation.
The second step is to build the response object:
type SQL_Stream is new Resources.Streams.Stream_Type;
Stream_Object : SQL_Stream;
procedure Read (...) is ...
function End_Of_File (...) return Boolean is ...
procedure Close (...) is
...
return Response.Stream (MIME.Text_HTML, Stream_Object);
Note that in some cases it is needed to create a file containing the data for the client (for example a tar.gz or a zip archive). But there is no way to properly remove this file from the file system as we really don’t know when the upload is terminated when using the AWS.Response.File constructor. To solve this problem it is possible to use a stream as the procedure Close is called by the server when all data have been read. In this procedure it is trivial to do the necessary clean-up.
3.3.9. Response from a on-disk stream
An ready-to-use implementation of the stream API described above where the stream content is read from an on-disk file.
3.3.10. Response from a on-disk once stream
An ready-to-use implementation of the stream API described above where the stream content is read from an on-disk file. When the transfer is completed the file is removed from the file system.
3.3.11. Response from a memory stream
This is an implementation of the standard stream support described above. In this case the stream is in memory and built by adding data to it.
To create a memory stream just declare an object of type AWS.Resources.Streams.Memory.Stream_Type. When created, this memory stream is empty, using the Streams.Memory.Append routines it is possible to add chunk of data to it. It is of course possible to call Append as many times as needed. When done just return this object to the server:
Data : AWS.Resources.Streams.Memory.Stream_Type;
Append (Data, Translator.To_Stream_Element_Array ("First chunk"));
Append (Data, Translator.To_Stream_Element_Array ("Second chunk..."));
...
return Response.Stream (MIME.Text_HTML, Data);
Note that you do not have to take care of releasing the allocated memory, the default Close routine will do just that.
3.3.12. Response from a compressed memory stream
This is a slight variant of the standard memory stream described above. In this case the stream object must be declared as a AWS.Resources.Streams.Memory.ZLib.Stream_Type.
The ZLib stream object must be initialized to enable the compression and select the right parameters. This is done using the AWS.Resources.Streams.Memory.ZLib.Deflate_Initialize routine which takes many parameters to select the right options for the compression algorithm, all of them have good default values. When initialized the compressed stream object is used exactly as a standard stream:
Data : AWS.Resources.Streams.Memory.ZLib.Stream_Type;
Deflate_Initialize (Data);
Append (Data, Translator.To_Stream_Element_Array ("First chunk"));
Append (Data, Translator.To_Stream_Element_Array ("Second chunk..."));
...
return Response.Stream (MIME.Text_HTML, Data);
Note that there is the reverse implementation to decompress a stream. See AWS.Resources.Streams.Memory.ZLib. It’s usage is identical.
3.3.13. Split page
AWS has a specific high level service to split a large response into a set of pages. For more information see Split pages.
3.3.14. Response a from pipe stream
The response sent to the server is read from the output of an external application. This kind of stream can be used to avoid writing a temporary file into the hard disk. For example it is possible to return an archive created with the tar tool without writing the intermediate tar achive on the disk.
3.4. Configuration options
To configure an AWS server it is possible to use a configuration object. This object can be set using the AWS.Config.Set API or initialized using a configuration file.
Configuration files are a way to configure the server without recompiling it. Each application can be configured using two configurations files:
aws.ini
This file is parsed first and corresponds to the configuration for all AWS server runs in the same directory.
<program_name>.ini
This file is parsed after
aws.ini. It is possible with this initialization file to have specific settings for some servers.program_name.iniis looked first in the application’s directory and then in the current working directory. This is only supported on platforms where Ada.Command_Line is implemented. So, on VxWorks onlyaws.iniis parsed.
Furthermore, it is possible to read a specific configuration file using the AWS.Config.Ini.Read routine. See AWS.Config.Ini.
Current supported options are:
Accept_Queue_Size (positive)
This is the size of the queue for the incoming requests. Higher this value will be and less “connection refused” will be reported to the client. The default value is 64.
Admin_Password (string)
This is the password used to call the administrative page. The password can be generated with
aws_password(the module name must be admin):$ aws_password admin <password>
Admin_URI (string)
This is the URI to call the administrative page. This can be used when calling AWS.Server.Start. The default is <not-defined>.
Case_Sensitive_Parameters (boolean)
If set to True the HTTP parameters are case sensitive. The default value TRUE.
Certificate (string)
Set the certificate file to be used with the secure servers. The default is cert.pem. A single certificate or a certificate chain is supported. The certificates must be in PEM format and the chain must be sorted starting with the subject’s certificate, followed by intermediate CA certificates if applicable and ending at the highest level (root) CA certificate. If the file contains only a single certificate, it can be followed by a private key. In this case the Key parameter (see below) must empty.
Check_URL_Validity (boolean)
Server have to check URI for validity. For example it checks that an URL does not reference a resource above the Web root. The default is TRUE.
Cipher_Priorities
Values are dependent on the actual secure layer (OpenSSL or GNUTLS). It is used to specify the session’s handshake algorithms and options.
Cleaner_Wait_For_Client_Timeout (duration)
Number of seconds to timeout on waiting for a client request. This is a timeout for regular cleaning task. The default is 80.0 seconds.
Cleaner_Client_Header_Timeout (duration)
Number of seconds to timeout on waiting for client header. This is a timeout for regular cleaning task. The default is 7.0 seconds.
Cleaner_Client_Data_Timeout (duration)
Number of seconds to timeout on waiting for client message body. This is a timeout for regular cleaning task. The default is 28800.0 seconds.
Cleaner_Server_Response_Timeout (duration)
Number of seconds to timeout on waiting for client to accept answer. This is a timeout for regular cleaning task. The default is 28800.0 seconds.
Close_On_Exec (boolean)
Set the socket close on exec policy. If set to True the child process spawned from the server won’t get access to the server’s sockets (listening and connection with clients). That is, all inherited sockets are closed when a child process is executed. platforms. The default is |CLOSE_ONE_EXEC|.
Config_Directory (string)
The directory in which AWS keeps some configuration parameters. The default is .config/ada-web-srv.
CRL_File (string)
This configuration option must point to a filename containing a CRL (Certificate Revocation List). This will make it possible to control client connecting to the server. The default values is <not-defined>.
Directory_Browser_Page (string)
Specify the filename for the directory browser template page. The default value is aws_directory.thtml.
Disable_Program_Ini (boolean)
Specify whether the configuration file
program_name.inishould be parsed or not. If this option is set to FALSE the program specific configuration file won’t be parsed. This may be useful if another application is using such a file and cannot be shared. This setting is expected to be set inaws.inibefore theprogram_name.inifile is parsed. The default value is FALSE.
Down_Image (string)
The name of the down arrow image to use in the status page. The default is aws_down.png.
Error_Log_Activated (boolean)
A boolean to enable or disable the error log. By default the error log activation is set to FALSE.
Error_Log_Filename_Prefix (string)
This is to set the filename prefix for the error log file. By default the error log filename prefix is the program name (without extension) followed by “_error”.
Error_Log_Split_Mode [None/Each_Run/Daily/Monthly]
It indicates how to split the error logs. Each_Run means that a new log file is used each time the process is started. Daily and Monthly will use a new log file each day or month. The default is NONE.
Exchange_Certificate (boolean)
If set to True it means that the client will be asked to send its certificate to the server. The default value is FALSE.
Certificate_Required (boolean)
If set to True the server will reject all SSL connections if the client did not provide a certificate (be it valid or not). The Exchange_Certificate option must be set in this case. The default value is FALSE.
Force_Wait_For_Client_Timeout (duration)
Number of seconds to timeout on waiting for a client request. This is a timeout for urgent request when resources are missing. The default is 2.0 seconds.
Force_Client_Header_Timeout (duration)
Number of seconds to timeout on waiting for client header. This is a timeout for urgent request when resources are missing. The default is 2.0 seconds.
Force_Client_Data_Timeout (duration)
Number of seconds to timeout on waiting for client message body. This is a timeout for urgent request when resources are missing. The default is 10800.0 seconds.
Force_Server_Response_Timeout (duration)
Number of seconds to timeout on waiting for client to accept answer. This is a timeout for urgent request when resources are missing. The default is 10800.0 seconds.
Free_Slots_Keep_Alive_Limit (positive)
This is the minimum number of remaining free slots to enable keep-alive HTTP connections. For heavy-loaded HTTP servers, the Max_Connection parameter should be big enough, and Free_Slots_Keep_Alive_Limit should be about 1-10% of the Max_Connection parameter depending on the duration of the average server response. Longer is the average time to send back a response bigger Free_Slots_Keep_Alive_Limit should be. The default is 1.
Hotplug_Port (positive)
This is the hotplug communication port needed to register and un-register an hotplug module. The default value is 8888.
HTTP2_Activated (boolean)
Whether the HTTP2 protocol is to be activated for the server. The default value is TRUE.
Key (string)
Set the RSA key file to be used with the secure servers. The default file is <not-defined>.
Line_Stack_Size (positive)
The HTTP lines stack size. The stack size must be adjusted for each applications depending on the use of the stack done by the callback procedures. The default is 1376256.
Log_Activated (boolean)
A boolean to enable or disable the standard log. By default the standard log activation is set to FALSE.
Log_Extended_Fields (string list)
Comma separated list of the extended log field names. If this parameter is empty, the HTTP log would be in the apache compartible format, otherwise log file would be in Extended format. For more information see Server Log.
Log_File_Directory (string)
This is to set the directory where log file must be written. This parameter will be used automatically by AWS.Log if logging facility is enabled. By default log files are written in the current directory. The default is ./.
Log_Filename_Prefix (string)
This is to set the filename prefix for the log file. By default the log filename prefix is the program name (without extension).
Log_Split_Mode [None/Each_Run/Daily/Monthly]
It indicates how to split the logs. Each_Run means that a new log file is used each time the process is started. Daily and Monthly will use a new log file each day or month. The default is NONE.
Logo_Image (string).
The name of the logo image to use in the status page. The default is aws_logo.png.
Max_Concurrent_Download (positive)
Control the maximum number of parallel downloads accepted by the download manager. The default value is 25.
Max_Connection (positive)
This is the maximum number of simultaneous connections for the server. This can be used when calling the AWS.Server.Start. The default is 5.
Note that the total number of threads used by a server is:
N = <main server thread> + <max connections> [+ <session>]Note: […] means optional value Add 1 only if the session feature is activated. This is due to the session cleaner task.
Max_POST_Parameters (positive)
The maximum number of POST parameters supported by AWS. The default value is 100.
Max_WebSocket (positive)
The maximum number of WebSocket that can be opened simultaneously in AWS. Above this value AWS will try to close timed-out WebSockets (see WebSocket_Timeout). The default value is 512.
Max_WebSocket_Handler (positive)
The maximum number of message to handle simultaenously. The default value is 2.
MIME_Types (string)
The name of the file containing the MIME types associations. The default file name is aws.mime.
Receive_Timeout (duration)
Number of seconds to timeout when receiving chunk of data. The default is 30.0 seconds.
Reuse_Address (boolean)
Set the socket reuse address policy. If set to True the server will be able to bind to a socket that has just been released without the need of waiting. Enabling this feature may introduce security risks on some platforms. The default is FALSE.
Security_Mode (string)
Set the security mode to use for the secure connections. The default mode is TLS. See AWS.Net.SSL.
Send_Buffer_Size (positive)
This is the socket internal buffer used for sending data to the clients. The default is 0.
Send_Timeout (duration)
Number of seconds to timeout when sending chunk of data. The default is 40.0 seconds.
Server_Header (string)
The value to be used for the HTTP Server header. The default is AWS (Ada Web Server) v25.0w. If the value is set to the empty string, the server header is not sent.
Server_Host (string)
The name of the host machine. This can be used if a computer has more than one IP address, it is possible to have two servers at the same port on the same machine, both being binded on different IP addresses.
Server_Name (string)
The name of the server. This can be used when calling AWS.Server.Start. The default is AWS Module.
Server_Priority (natural)
Priority of the task handling the HTTP protocol. The default is Default_Priority.
Server_Port (integer)
The port where server will wait for incoming connections requests. This can be used when calling AWS.Server.Start. The default is 8080.
Service_Priority (natural)
Priority of the tasks used by optional services like SMTP Server, Server Push, Jabber and the Transient Page cleaner. The default is Default_Priority.
Session (boolean)
Whether the session support must be activated or not. The default is FALSE.
Session_Name (string)
The name of the cookie session. This can be used to support sessions for multiple servers embedded into the same executable. The default is AWS.
Session_Id_Length (positive)
The length of the session id in characters. The default is 11 characters.
Session_Lifetime (duration)
Number of seconds to keep session information. After this period a session is obsoleted and will be removed at next cleanup. The default is 600.0 seconds.
Session_Cleanup_Interval (duration)
Number of seconds between each run of the session cleanup task. This task will remove all session data that have been obsoleted. The default is 300.0 seconds.
Session_Cleaner_Priority (natural)
Priority of the task cleaning the session data. The default is Default_Priority.
Status_Page (string)
The name of the status page to used. The default is aws_status.thtml.
TCP_No_Delay (boolean)
This control the server’s socket delay/no-delay option. This option should be used for applications that require lower latency on every packet sent. The default is FALSE.
TLS_Ticket_Support (boolean)
Specify whether the TLS ticket support is activated or not. The default value is FALSE.
Transient_Cleanup_Interval (positive)
Specify the number of seconds between each run of the cleaner task to remove transient pages. The default value is 180.0 seconds.
Transient_Lifetime (duration)
Specify the number of seconds to keep a transient page. After this period the transient page is obsoleted and will be removed during next cleanup. The default value is 300.0 seconds.
Trusted_CA (string)
This must point to the file containing the list of trusted Certificate Authorities. The CA in this file will be used to verify the client certificate validity. The default values is <not-defined>.
Up_Image (string)
The name of the up arrow image to use in the status page. The default is aws_up.png.
Upload_Directory (string)
This is to set the directory where upload files must be stored. By default uploaded files are written in the current directory. The default is <not-defined>.
User_Agent (string)
The value to be used for the HTTP User_Agent header. The default value is AWS (Ada Web Server) v25.0w. If the value is set to the empty string, the User_Agent header is not sent.
WebSocket_Message_Queue_Size (positive)
This is the size of the queue containing incoming messages waiting to be handled by one of the task, see Max_WebSocket_Handler above. The default value is 10.
WebSocket_Origin (string)
This is a regular expression which can be used to handle WebSockets originating from a specific domain. By default AWS handles WebSockets from any origins.
WebSocket_Priority (natural)
Priority of the task handling the WebSockets. The default is Default_Priority.
WebSocket_Timeout (duration)
A number of seconds after which a WebSocket without activity is considered timed-out and can be elected to be closed if the maximum number of sockets opened has been reached. (see Max_WebSocket). The default is 28800.0.
WWW_Root (string)
This option sets the Web Server root directory. All Web resources are referenced from this root directory. The default value is ./.
Each option value can be retrieved using the AWS.Config unit or set using AWS.Config.Set.
For example to build a server where the port and the maximum number of
connection can be changed via a configuration file (either
aws.ini or <program_name>.ini):
WS : AWS.Server.HTTP;
Conf : constant AWS.Config.Object := AWS.Config.Get_Current;
Server.Start (WS, Service'Access, Conf);
3.5. Session handling
AWS provides a way to keep session data while users are browsing. It works by creating transparently a session ID where it is possible to insert, delete and retrieve session data using a standard Ada API (see AWS.Session.). Session data are key/value pair each of them being strings. These sessions data are kept on the server, for client side state management see HTTP state management.
First you declare and start an HTTP channel with session enabled:
WS : AWS.Server.HTTP; Server.Start (WS, Port => 1234, Callback => Service'Access, Session => True);
Here we have built an HTTP channel with a maximum of 3 simultaneous connections using the port 1234. A session ID will be created and sent inside a cookie to the client’s browser at the first request. This session ID will be sent back to the server each time the client will ask for a resource to the server.
Next, in the Service callback procedure that you have provided you must retrieve the Session ID. As we have seen, the callback procedure has the following prototype:
function Service (Request : in AWS.Status.Data) return AWS.Response.Data;
The Session ID is kept in the Request object and can be retrieved using:
Session_ID : constant AWS.Session.ID := AWS.Status.Session (Request);
From there it is quite easy to get or set some session data using the provided API. For example:
declare C : Integer; begin C := AWS.Session.Get (Session_ID, "counter"); C := C + 1; AWS.Session.Set (Session_ID, "counter", C); end;
This example first get the value (as an Integer) for session data whose key is “counter”, increment this counter and then set it back to the new value.
It is also possible to save and restore all session data. It means that the server can be shutdown and launched some time after and all client data are restored as they were at shutdown time. Client will just see nothing. With this feature it is possible to shutdown a server to update its look or because a bug has been fixed for example. It is then possible to restart it keeping the complete Web server context.
3.6. HTTP state management
AWS provides a full implementation of RFC 2109 via the AWS.Cookie package. Using this package you set, get and expire client-side HTTP cookies.
First we set a cookie:
declare
Content : AWS.Response.Data;
begin
AWS.Cookie.Set (Content,
Key => "hello",
Value => "world",
Max_Age => 86400.0);
end;
Here we set the cookie hello with the value world, and we tell the client to expire the cookie 86400 seconds into the future.
Getting the cookie value back is equally simple:
declare
Request : AWS.Status.Data
-- Assume that this object contain an actual HTTP request.
begin
Put_Line (AWS.Cookie.Get (Request, "hello"));
-- Output 'world'
end;
Had the cookie hello not existed, an empty String would’ve been returned.
In some cases it might be of value to know if a given cookie exists, and for that we have the Exists function available:
declare
Request : AWS.Status.Data
-- Assume that this object contain an actual HTTP request
begin
if AWS.Cookie.Exists ("hello") then
Put_Line ("The 'hello' cookie exists!");
end if;
end;
Note that Exists doesn’t care if the cookie contains an actual value or not. If a cookie with no value exists, Exists will return True.
And finally we might wish to tell the client to expire a cookie:
declare
Content : AWS.Response.Data;
begin
AWS.Cookie.Expire (Content,
Key => "hello");
end;
The Cookie package provide Get functions and Set procedures for String, Integer, Float and Boolean types, but since cookies are inherently strings, it’s important to understand what happens when the cookie String value can’t be converted properly to either Integer, Float or Boolean.
So if either conversion fails or the cookie simply doesn’t exist, the following happens:
For Integer, the value 0 is returned
For Float, the value 0.0 is returned.
For Boolean, the value False is returned. Note that only the string ‘True’ is True. Everything else is False.
For more information see AWS.Cookie.
3.7. Authentication
AWS supports Basic and Digest authentication. The authentication request can be sent at any time from the callback procedure. For this the AWS.Response.Authenticate message must be returned.
The authentication process is as follow:
Send authentication request
From the callback routine return an authentication request when needed:
function Service (Request : in Status.Data) return Response.Data is URI : constant String := Status.URI (Request); User : constant String := Status.Authorization_Name (Request); begin -- URI starting with "/prot/" are protected if URI (URI'First .. URI'First + 5) = "/prot/" and then User = "" then return Response.Authenticate ("AWS", Response.Basic);
The first parameter is the Realm, it is just a string that will be displayed (on the authentication dialog box) by the browser to indicate for which resource the authentication is needed.
Check authentication
When an authentication as been done the callback’s request data contain the user and password. Checks the values against an ACL for each protected resources:
function Protected_Service (Request : in AWS.Status.Data) return AWS.Response.Data is User : constant String := Status.Authorization_Name (Request); Pwd : constant String := Status.Authorization_Password (Request); begin if User = "xyz" and then Pwd = "azerty" then return ...;
Note that the Basic authentication is not secure at all. The password is sent unencoded by the browser to the server. If security is an issue it is better to use the Digest authentication and/or an SSL server.
3.8. File upload
File upload is the way to send a file from the client to the server. To enable file upload on the client side the Web page must contain a FORM with an INPUT tag of type FILE. The FORM must also contain the enctype attribute set to multipart/form-data:
<FORM enctype="multipart/form-data" ACTION=/whatever METHOD=POST>
File to process: <INPUT NAME=filename TYPE=FILE>
<INPUT TYPE=SUBMIT NAME=go VALUE="Send File">
</FORM>
On the server side, AWS will retrieve the file and put it into the upload directory. AWS add a prefix to the file to ensure that the filename will be unique on the server side. The upload directory can be changed using the configuration options. See Configuration options.
The uploaded files are removed after the user’s callback. This is done for security reasons, if files were not removed it would be possible to fill the server hard disk by uploading large files to the server. This means that uploaded files must be specifically handled by the users by either copying or renaming them.
AWS will also setup the form parameters as usual. In the above example there is two parameters (see Form parameters).
filename
This variable contains two values, one with the client side name and one with the server side name.
First value : Parameters.Get (P, “filename”)
The value is the full pathname of the file on the server. (i.e. the upload directory catenated with the prefix and filename).
Second value : Parameters.Get (P, “filename”, 2)
The value is the simple filename (no path information) of the file on the client side.
go
The value is “Send File”
3.9. Communication
This API is used to do communication between programs using the HTTP GET protocol. It is a very simple API not to be compared with GLADE or SOAP. This communication facility is to be used for simple request or when a light communication support is needed. For more complex communications or to achieve inter-operability with other modules it is certainly a good idea to have a look at the AWS/SOAP support, see SOAP.
In a communication there is a Client and a Server. Here is what is to be done on both sides to have programs talking together.
3.9.1. Communication - client side
On the client side it is quite simple. You just have to send a message using AWS.Communication.Client.Send_Message:
function Send_Message
(Server : in String;
Port : in Positive;
Name : in String;
Parameters : in Parameter_Set := Null_Parameter_Set)
return Response.Data;
The message is sent to the specified server using the given port. A message is composed of a name which is a string and a set of parameters. There is a parameter set constructor in AWS.Communication. This function return a response as for any callback procedure.
3.9.2. Communication - server side
On the server side things are a bit more complex but not that difficult. You must instantiate the AWS.Communication.Server generic package by providing a callback procedure. This callback procedure will must handle all kind of message that a client will send.
During instantiation you must also pass a context for the communication server. This context will be passed back to the callback procedure:
generic
type T (<>) is limited private;
type T_Access is access T;
with function Callback
(Server : in String;
Name : in String;
Context : in T_Access;
Parameters : in Parameter_Set := Null_Parameter_Set)
return Response.Data;
package AWS.Communication.Server is
...
A complete example can be found in the demos directory. Look for
com_1.adb and com_2.adb.
Note that this communication API is used by the Hotplug module facility, see Hotplug module.
3.10. Hotplug module
An Hotplug module is a module that can by dynamically binded to a running server. It is a Web server and the development process is very similar to what we have seen until now Building an AWS server. The Hotplug module will register itself into a Web server by sending a message using the communication API. The Hotplug module send to the server a regular expression and an URL. The main server will redirect all URL matching the regular expression to the Hotplug module.
Note that the main server will redirect the URL to the first matching regular expression.
3.10.1. Hotplug module - server activation
The first step is to properly create the main server hotplug module registration file. This file must list all hotplug modules that can register into the main server. Each line have the following format:
hotplug_module_name:password:server:port
hotplug_module_name
The name of the hotplug module. You can choose any name you want. This name will be use during the registration process and to generate the password.
password
The MD5 password, see below.
server
The name of the server where the redirection will be made. This is for security reasons, main server will not permit to redirect requests to any other server.
port
The port to use for the redirection on server.
You must create a password for each hotplug modules. The generated password depends on the hotplug module name. A tool named aws_password is provided with AWS to generate such password. Usage is simple:
$ aws_password <hotplug_module_name> <password>
Then, after starting the main server you must activate the Hotplug feature:
AWS.Server.Hotplug.Activate (WS'Unchecked_Access, 2222, "hotplug_conf.ini");
hotplug_conf.ini is the hotplug module registration file
described above.
3.10.2. Hotplug module - creation
Here is how to create an Hotplug module:
First you create a standard Web server, see Building an AWS server:
WS : AWS.Server.HTTP (3, 1235, False, Hotplug_CB.Hotplug'Access, False);
Here we have a server listening to the port 1235. This server can be used alone if needed as any Server developed with AWS.
Then you register the Hotplug module to the main server, see AWS.Client.Hotplug:
Response := AWS.Client.Hotplug.Register (Name => "Hotplug_Module_Demo", Password => "my_password", Server => "http://dieppe:2222", Regexp => ".*AWS.*", URL => "http://omsk:1235/");
The hotplug module Hotplug_Module_Demo must have been declared on the main server, the password and redirection must have been properly recorded too for security reasons, see Hotplug module - server activation. This command register Hotplug_Module_Demo into the server running on the machine dieppe and ask it to redirect all URL containing AWS to the server running on machine omsk on port 1235.
When the Hotplug module is stopped, you must unregister it:
Response := AWS.Client.Hotplug.Unregister (Name => "Hotplug_Module_Demo", Password => "my_password", Server => "http://dieppe:2222", Regexp => ".*AWS.*");
Here we ask to unregister Hotplug_Module_Demo from server dieppe. As for the registration process a proper password must be specified, see Hotplug module - server activation.
A complete example can be found in the demos directory. Look for
main.adb and hotplug.adb.
3.11. Server Push
This protocol is obsolescent, it is hightly recommended to use the WebSockets now. See WebSockets.
Server Push is a feature that let the Web Server send continuously data to client’s Web Browser or client applications. The client does not have to reload at periodic time (which is what is called client pull) to have the data updated, each time the server send a piece of data it gets displayed on the client.
To build a push server you need to build an instance of the AWS.Server.Push package. This package takes a set of formal parameters. Here are the step-by-step instructions to build a Push Server:
The data to be sent
First you must create a type that will contains the data to be sent to client’s browser except if it is a standard Ada type. See Client_Output_Type formal parameter.
The data that will be streamed
This is the representation of the data that will be sent to client’s browser. This will be either a String for Web pages or Stream_Element_Array for binary data like pictures. See Stream_Output_Type formal parameter.
The context
It is often nice to be able to configure each client with different parameters if needed. This can be achieved with the Context data type that will be passed as parameter of the conversion function described below. See Client_Environment formal parameter.
Provides a function to convert from the data type to be sent to the data that will be streamed.
This is a function that will transform the data described on point 1 above to the form described on point 2 above. See To_Stream_Output formal parameter.
Build the Push Server
To do so you just need to instantiate AWS.Server.Push with the above declarations.
Registering new clients
In the standard AWS procedure callback it is possible to register a client if requested. This is done by calling AWS.Server.Push.Register. It is possible to unregister a client using AWS.Server.Push.Unregister. Each client must be identified with a unique client ID. After registering a new client from the callback procedure you must return the AWS.Response.Socket_Taken message. This is very important, it tells the server to not close this socket.
Sending the data
At this point it is possible to send data to clients. To do so two routines are available.
AWS.Server.Push.Send_To
To send a piece of data to a specific client identified by its client ID.
AWS.Server.Push.Send
To send a piece of data to all clients registered on this server.
Very large Internet applications should use this feature carefully. A push server keeps a socket reserved for each registered clients and the number of available sockets per process is limited by the OS.
3.12. Working with Server sockets
With AWS is is possible to take out a socket from the server and give it back later. This feature must be used carefully but it gives a lot of flexibility. As the socket is taken away, the connection line (or slot) is released, AWS can then use it to handle other requests.
This can be used to better support heavy loaded servers when some requests need a long time to complete. Long time here means longer than most of the other requests which should be mostly interractives for a Web server. Of course in such a case a keep-alive connection is kept open.
The usage in such a case is to take out the socket and put it in a waiting line. This releases the connection for the server. When the data to prepare the answer is ready you give back the socket to the server.
Take a socket from the server
This first step is done form the callback function. A user instead of replying immediatly decides to take away the socket from the server. The first step is to record the connection socket socket by calling AWS.Status.Socket. The second step is to tell the server to not release this socket by returning AWS.Response.Socket_Taken from the callback function. At this point the server will continue to serve other clients.
Note that this feature is used by the server push implementation, see Server Push.
Give back the socket to the server
Calling AWS.Sever.Give_Back_Socket will register the socket for reuse. This socket will be placed into a spool, next time the server will check for incoming requests it will be picked up.
3.13. Server Log
It is possible to have the server activity logged into the file
<progname>-Y-M-D.log. To activate the logging you must call the
AWS.Server.Log.Start, and it is possible to stop logging by calling
AWS.Server.Log.Stop. Note that AWS.Server.Log.Start have
a parameter named Auto_Flush to control output buffering. This
parameter is False by default. If set to True, the log file will be
automatically flushed after each data. If the server logging is not
buffered, i.e. Auto_Flush is False, the log can still be flushed by
calling the AWS.Server.Log.Flush routine. See AWS.Log for
more information especially about the way rotating logs can be
setup. Using this feature it is possible to have automatic split of
the log file each day, each month or at every run. See AWS.Log
spec. This is very useful to avoid having very big log files.
The log format depend on Log_Extended_Fields configuration parameter. If this parameter is empty, the HTTP log would have fixed apache compartible format:
<client IP> - <auth name> - [<date and time>] "<request>" <status code> <size>
For example:
100.99.12.1 - - [22/Nov/2000:11:44:14] "GET /whatever HTTP/1.1" 200 1789
If the extended fields list is not empty, the log file format would have user defined fields set:
#Version: 1.0
#Date: 2006-01-09 00:00:01
#Fields: date time c-ip cs-method cs-uri cs-version sc-status sc-bytes
2006-01-09 00:34:23 100.99.12.1 GET /foo/bar.html HTTP/1.1 200 30
Fields in the comma separated Log_Extended_Fields list could be:
- date
Date at which transaction completed
- time
Time at which transaction completed
- time-taken
Time taken for transaction to complete in seconds
- c-ip
Client side connected IP address
- c-port
Client side connected port
- s-ip
Server side connected IP address
- s-port
Server side connected port
- cs-method
HTTP request method
- cs-username
Client authentication username
- cs-version
Client supported HTTP version
- cs-uri
Request URI
- cs-uri-stem
Stem portion alone of URI (omitting query)
- cs-uri-query
Query portion alone of URI
- sc-status
Responce status code
- sc-bytes
Length of response message body
- cs(<header>)
Any header field name sent from client to server
- sc(<header>)
Any header field name sent from server to client
- x-<appfield>
Any application defined field name
AWS also support error log files. If activated every internal error detected by AWS will gets logged into this special file. Log file for errors would be in simple apache compartible format. See AWS.Server.Log.Start_Error and AWS.Server.Log.Stop_Error.
For the full set of routines supporting the log facility see AWS.Server.Log .
3.14. Secure server
It is not much difficult to use a secure server (HTTPS) than a standard one. Here we describe only what is specific to an HTTPS server.
Before going further you must check that AWS has been configured with SSL support. See Building. You must also have installed the OpenSSL or GNUTLS libraries on your system. If this is done, you can continue reading this section.
3.14.1. Initialization
A server is configured as using the HTTPS protocol at the time it is started. The only thing to do is to set the Start’s Security parameter to True. This will start a server and activate the SSL layer by default. A secure server must use a valid certificate, the default one is cert.pem. This certificate has been created by the OpenSSL or GNUTLS tool and is valid until year 2008. Yet, this certificate has not been signed. To build a secure server user’s can rely on, you must have a valid certificate signed by one of the Certificate Authorities.
The certificate to be used must be specified before starting the secure server with AWS.Server.Set_Security:
With a key and certificate files:
AWS.Server.Set_Security
(WS,
Key_Filename => "server.key",
Certificate_Filename => "server.crt");
Or with a self-contained certificate:
AWS.Server.Set_Security (WS, Certificate_Filename => "aws.pem");
Or using the certificate configuration parameter, see Configuration options.
3.14.2. Verify callback
First note that it is not necessary to use such callback to verify the certificate validity, see Using a Certificate Authority.
This callback will receive the client certificate as sent during SSL handshake between the server and the client. The certificate information can be checked for logging purpose or to impose some restriction. Generally this callback should return the value from AWS.Net.SSL.Certificate.Verified, see AWS.Net.SSL.Certificate.
The Verified status of the certificate is the one that has been issued by the SSL implementation during certificate verification and can generally be trusted.
3.14.3. Self-signed certificate
3.14.3.1. Creating a server certificate
The goal here is not to replace the OpenSSL documentation but just to present one way to create a self signed certificate for an HTTPS test server. Note that GNUTLS offers similar tools to generate certificates.
Generate a RSA key:
$ openssl genrsa -rand <filename> -out aws-server.key
Filename must point to any file, this is used to initialized the random seed.
Generate the certificate:
$ openssl req -new -x509 -days 730 -key aws-server.key -out aws-server.cert
Create a single self contained file (optional):
$ cat aws-server.key aws-server.cert > aws.pem
A this point you can use aws.pem with your server or the separate
server.key and server.crt files.
It is also possible to sign the server’s key. In this case the key won’t be in plain text but will require to setup a password on the server code for the key to be decoded. See routine Set_Password_Callback in AWS.Net.SSL.Certificate.
Generate a crypted RSA key:
$ openssl genrsa -aes128 -passout pass:<PASSWORD> -out aws-server.key
3.14.3.2. Creating a client certificate
A certificate can also be used on a Web browser and passed to the server to have a strong client authentication. A client certificate must be PKCS12. The steps to generate such certificate are:
Generate a RSA key:
$ openssl genrsa -des3 -out aws-client.key
Filename must point to any file, this is used to initialized the random seed.
Generate the certificate:
$ openssl req -new -x509 -days 730 -key aws-client.key -out aws-client.cert
Create the corresponding PKCS12 certificate:
$ openssl pkcs12 -export -clcerts -in aws-client.cert -inkey aws-client.key -out client.p12
3.14.5. Security level
This table summarize the security level achieved with different settings of the security oriented configuration parameters.
Security |
SSL |
Exchange Certificate |
Certificate required |
Trusted CA |
|---|---|---|---|---|
Data between the client and the server are encrypted. |
Yes |
No |
No |
No |
Client can be identified, it is still possible to access the server without having a certificate. |
Yes |
Yes |
No |
No |
Client are identified, a certificate is required. The verification of the validity is up to the application using the verify callback. |
Yes |
Yes |
Yes |
No |
Client are identified and verified, the certificate must have been signed by a Certificate Authority. It is not possible to access the server without a valid certificate. |
Yes |
Yes |
Yes |
Yes |
3.14.6. Protocol
There are different security options, either SSLv2, SSLv3 or TLSv1. SSLv2 and SSLv3 are supported by most if not all Web browsers. These are the default protocol used by AWS.
TLSv1 is not supported at this point.
3.15. Unexpected exception handler
When AWS detects an internal problem, it calls a specific handler. This handler can be used to log the error, send an alert message or build the answer to be sent back to the client’s browser.
Here is the spec for this handler:
type Unexpected_Exception_Handler is access
procedure (E : in Ada.Exceptions.Exception_Occurrence;
Log : in out AWS.Log.Object;
Error : in Data;
Answer : in out Response.Data);
The handler can be called in two modes:
Non fatal error (Error.Fatal is False)
In this case AWS will continue working without problem. A bug has been detected but it was not fatal to the thread (slot in AWS’s terminology) handling. In this case it is possible to send back an application level message to the client’s browser. For that you just have to fill the unexpected handler’s Answer parameter with the right response message. The Error parameter receive information about the problem, see AWS.Exceptions.
Fatal error (Error.Fatal is True)
In this case AWS will continue working but a thread (slot number Error.Slot in AWS’s terminology) will be killed. It means that AWS will have lost one the simultaneous connection handler. The server will continue working unless it was the last slot handler available. Note that a Fatal error means an AWS internal bug and it should be reported if possible. In this mode there is no way to send back an answer to the client’s browser and Error value must be ignored.
The default handler for unexpected exceptions send a message to
standard error for fatal errors. For non fatal errors it log a message
(if the error log is activated for the server) and send back a message
back to the client. The message is either a built-in one or, if present
in the server’s directory, the content of the 500.tmplt file.
This templates can used the following tags:
AUTH_MODE
The authorization mode (Either NONE, BASIC or DIGEST).
EXCEPTION
Exception information with traceback if activated.
HTTP_VERSION
Either HTTP/1.0 or HTTP/1.1
METHOD
The request method (Either GET, HEAD, POST or PUT)
PAYLOAD
The full XML payload for SOAP request.
PEERNAME
The IP address of the client
SOAP_ACTION
Either True or False. Set to True for a SOAP request.
URI
The complete URI
For more information see AWS.Server and AWS.Exceptions.
3.16. Socket log
To ease AWS applications debugging it is possible to log all data sent/received to/from the sockets. For this you need to call the AWS.Net.Log.Start routine by passing a write procedure callback. You have to create such procedure or use one read-to-use provided in AWS.Net.Log.Callbacks package.
For more information see AWS.Net.Log and AWS.Net.Log.Callbacks.
3.17. Client side
AWS is not only a server it also implement the HTTP and HTTPS protocol from the client side. For example with AWS it is possible to get a Web page content using the AWS.Client API, see AWS.Client.
It also support client Keep-Alive connections. It is then possible to request many URI from the same server using the same connection (i.e. the same sockets).
AWS client API also support proxy, proxy authentication and Web server authentication. Only basic (and not digest) authentication is supported at this time.
Let’s say that you want to retrieve the contrib.html Web page from Pascal Obry’s homepage which is http://perso.wanadoo.fr/pascal.obry. The code to do so is:
Data := Client.Get
(URL => "http://perso.wanadoo.fr/pascal.obry/contrib.html");
From there you can ask for the result’s content type:
if Response.Content_Type (Data) = "text/html" then
...
end if;
Or using the MIME types defined in AWS.MIME unit:
if Response.Content_Type (Data) = MIME.Text_HTML then
...
end if;
And display the content if it is some kind of text data:
Text_IO.Put_Line (Response.Message_Body (Data));
If the content is some kind of binary data (executable, PNG image, Zip archive…), then it is possible to write the result to a file for example. Look at the agent program in the demos directory.
If the Web page is protected and you must pass the request through an authenticating proxy, the call will becomes:
Data := Client.Get
(URL => "http://www.mydomain.net/protected/index.html"
User => "me",
Pwd => "mypwd",
Proxy => "192.168.67.1",
Proxy_User => "puser",
Proxy_Pwd => "ppwd");
The client upload protocol is implemented. Using AWS.Client.Upload it is possible to send a file to a server which support the file upload protocol.