This is aws.info, produced by makeinfo version 4.8 from aws.texi.


File: aws.info,  Node: AWS.Config.Set,  Next: AWS.Containers.Tables,  Prev: AWS.Config.Ini,  Up: AWS API Reference

B.10 AWS.Config.Set
===================


     ------------------------------------------------------------------------------
     --                              Ada Web Server                              -
     --                                                                          -
     --                     Copyright (C) 2000-2013, AdaCore                     -
     --                                                                          -
     --  This library is free software;  you can redistribute it and/or modify   -
     --  it under terms of the  GNU General Public License  as published by the  -
     --  Free Software  Foundation;  either version 3,  or (at your  option) any -
     --  later version. This library is distributed in the hope that it will be  -
     --  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of -
     --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                    -
     --                                                                          -
     --  As a special exception under Section 7 of GPL version 3, you are        -
     --  granted additional permissions described in the GCC Runtime Library     -
     --  Exception, version 3.1, as published by the Free Software Foundation.   -
     --                                                                          -
     --  You should have received a copy of the GNU General Public License and   -
     --  a copy of the GCC Runtime Library Exception along with this program;    -
     --  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see   -
     --  <http://www.gnu.org/licenses/>.                                         -
     --                                                                          -
     --  As a special exception, if other files instantiate generics from this   -
     --  unit, or you link this unit with other files to produce an executable,  -
     --  this  unit  does not  by itself cause  the resulting executable to be   -
     --  covered by the GNU General Public License. This exception does not      -
     --  however invalidate any other reasons why the executable file  might be  -
     --  covered by the  GNU Public License.                                     -
     ------------------------------------------------------------------------------

     --  This package can be used to Set any AWS parameters

     package AWS.Config.Set is

        ------------------------
        -- Per Server Options -
        ------------------------

        ------------
        -- Server -
        ------------

        procedure Server_Name (O : in out Object; Value : String);
        --  This is the name of the server as set by AWS.Server.Start

        procedure Protocol_Family (O : in out Object; Value : String);
        --  Set the server protocol family. Family_Inet for IPv4, Family_Inet6 for
        --  IPv6 and Family_Unspec for unspecified protocol family.

        procedure Server_Host (O : in out Object; Value : String);
        --  This is the server host as set by the HTTP object declaration

        procedure Server_Port (O : in out Object; Value : Natural);
        --  This is the server port as set by the HTTP object declaration

        procedure Hotplug_Port (O : in out Object; Value : Positive);
        --  This is the hotplug communication port needed to register and
        --  un-register an hotplug module.

        procedure Session (O : in out Object; Value : Boolean);
        --  Enable session handling is Value is True

        procedure Case_Sensitive_Parameters (O : in out Object; Value : Boolean);
        --  Parameters are handled with the case if Value is True

        procedure Line_Stack_Size (O : in out Object; Value : Positive);
        --  HTTP lines stack size

        procedure MIME_Types (O : in out Object; Value : String);
        --  The name of the file containing the MIME types associations

        procedure Reuse_Address (O : in out Object; Value : Boolean);
        --  Set the reuse address policy allowing a bind without a dealy to the same
        --  address and port.

        procedure Session_Name (O : in out Object; Value : String);
        --  Name of the cookie session

        procedure Server_Priority (O : in out Object; Value : System.Any_Priority);
        --  Set the priority used by the HTTP and WebSockets servers

        ----------------
        -- Connection -
        ----------------

        procedure Max_Connection (O : in out Object; Value : Positive);
        --  This is the max simultaneous connections as set by the HTTP object
        --  declaration.

        procedure Send_Buffer_Size (O : in out Object; Value : Positive);
        --  This is the socket buffer size used for sending data. Increasing this
        --  value will give better performances on slow or long distances
        --  connections.

        procedure Free_Slots_Keep_Alive_Limit
          (O : in out Object; Value : Natural);
        --  The minimum number of free slots where keep-alive connections are still
        --  enabled. After this limit no more keep-alive connection will be
        --  accepted by the server. This parameter must be used for heavy-loaded
        --  servers to make sure the server will never run out of slots. This limit
        --  must be less than Max_Connection.

        procedure Keep_Alive_Force_Limit (O : in out Object; Value : Natural);
        --  Define maximum number of keep alive sockets where server process it with
        --  normal timeouts. If number of keep-alive sockets become more than
        --  Keep_Alive_Force_Limit, server start to use shorter force timeouts.
        --  If this parameter not defined in configuration or defined as 0 value
        --  server use calculated value Max_Connection * 2.

        procedure Accept_Queue_Size (O : in out Object; Value : 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.

        ----------
        -- Data -
        ----------

        procedure WWW_Root (O : in out Object; Value : String);
        --  This is the root directory name for the server. This variable is not
        --  used internally by AWS. It is supposed to be used by the callback
        --  procedures who want to retrieve physical objects (images, Web
        --  pages...). The default value is the current working directory.

        procedure Upload_Directory (O : in out Object; Value : String);
        --  This point to the directory where uploaded files will be stored. The
        --  directory returned will end with a directory separator.

        procedure Upload_Size_Limit (O : in out Object; Value : Positive);
        --  Set the maximum size accepted for uploaded files

        procedure Directory_Browser_Page (O : in out Object; Value : String);
        --  Filename for the directory browser template page

        procedure Max_POST_Parameters (O : in out Object; Value : Positive);
        --  Set the maximum number of POST parameters handled. Past this limit
        --  the exception Too_Many_Parameters is raised.

        ---------
        -- Log -
        ---------

        procedure Log_File_Directory (O : in out Object; Value : String);
        --  This point to the directory where log files will be written. The
        --  directory returned will end with a directory separator.

        procedure Log_Filename_Prefix (O : in out Object; Value : String);
        --  This is the prefix to use for the log filename

        procedure Log_Size_Limit (O : in out Object; Value : Natural);
        --  If Log_Size_Limit is more than zero and size of log file
        --  become more than Log_Size_Limit, log file is be split.

        procedure Log_Split_Mode (O : in out Object; Value : String);
        --  This is split mode for the log file. Possible values are : Each_Run,
        --  Daily, Monthly and None. Any other values will raise an exception.

        procedure Log_Extended_Fields (O : in out Object; Value : String);
        --  Comma separated list of the extended log field names. If this parameter
        --  is empty, the HTTP log would have fixed apache compartible format:
        --
        --  127.0.0.1 - - [25/Apr/1998:15:37:29 +0200] "GET / HTTP/1.0" 200 1363
        --
        --  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 cs-method cs-uri cs-version sc-status sc-bytes
        --  2006-01-09 00:34:23 GET /foo/bar.html HTTP/1.1 200 30
        --
        --  Fields in the list could be:
        --
        --  date         Date at which transaction completed
        --  time         Time at which transaction completed
        --  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

        procedure Error_Log_Filename_Prefix (O : in out Object; Value : String);
        --  This is the prefix to use for the log filename

        procedure Error_Log_Split_Mode (O : in out Object; Value : String);
        --  This is split mode for the log file. Possible values are : Each_Run,
        --  Daily, Monthly and None. Any other values will raise an exception.

        ------------
        -- Status -
        ------------

        procedure Admin_Password (O : in out Object; Value : String);
        --  This is the password for the admin server page as set by
        --  AWS.Server.Start. The password must be created with the aws_password
        --  tool.

        procedure Admin_URI (O : in out Object; Value : String);
        --  This is the name of the admin server page as set by AWS.Server.Start

        procedure Status_Page (O : in out Object; Value : String);
        --  Filename for the status template page

        procedure Up_Image (O : in out Object; Value : String);
        --  Filename for the up arrow image used in the status page

        procedure Down_Image (O : in out Object; Value : String);
        --  Filename for the down arrow image used in the status page

        procedure Logo_Image (O : in out Object; Value : String);
        --  Filename for the AWS logo image used in the status page

        --------------
        -- Timeouts -
        --------------

        procedure Cleaner_Wait_For_Client_Timeout
          (O     : in out Object;
           Value : Duration);
        --  Number of seconds to timout on waiting for a client request.
        --  This is a timeout for regular cleaning task.

        procedure Cleaner_Client_Header_Timeout
          (O     : in out Object;
           Value : Duration);
        --  Number of seconds to timout on waiting for client header.
        --  This is a timeout for regular cleaning task.

        procedure Cleaner_Client_Data_Timeout
          (O     : in out Object;
           Value : Duration);
        --  Number of seconds to timout on waiting for client message body.
        --  This is a timeout for regular cleaning task.

        procedure Cleaner_Server_Response_Timeout
          (O     : in out Object;
           Value : Duration);
        --  Number of seconds to timout on waiting for client to accept answer.
        --  This is a timeout for regular cleaning task.

        procedure Force_Wait_For_Client_Timeout
          (O     : in out Object;
           Value : Duration);
        --  Number of seconds to timout on waiting for a client request.
        --  This is a timeout for urgent request when resources are missing.

        procedure Force_Client_Header_Timeout
          (O     : in out Object;
           Value : Duration);
        --  Number of seconds to timout on waiting for client header.
        --  This is a timeout for urgent request when resources are missing.

        procedure Force_Client_Data_Timeout
          (O     : in out Object;
           Value : Duration);
        --  Number of seconds to timout on waiting for client message body.
        --  This is a timeout for urgent request when resources are missing.

        procedure Force_Server_Response_Timeout
          (O     : in out Object;
           Value : Duration);
        --  Number of seconds to timout on waiting for client to accept answer.
        --  This is a timeout for urgent request when resources are missing.

        procedure Send_Timeout (O  : in out Object; Value : Duration);
        --  Number of seconds to timeout when sending chunck of data

        procedure Receive_Timeout (O : in out Object; Value : Duration);
        --  Number of seconds to timeout when receiving chunck of data

        --------------
        -- Security -
        --------------

        procedure Check_URL_Validity (O : in out Object; Value : Boolean);
        --  Set the check URL validity flag. If True an URL that reference a
        --  resource above the Web root will be rejected.

        procedure Security (O : in out Object; Value : Boolean);
        --  Enable security (HTTPS/SSL) if Value is True

        procedure Certificate (O : in out Object; Filename : String);
        --  Set the certificate to be used with the secure server

        procedure Key (O : in out Object; Filename : String);
        --  Set the key to be used with the secure server

        procedure Security_Mode (O : in out Object; Mode : String);
        --  Set the security mode to be used with the secure server. Only values
        --  from AWS.Net.SSL.Method can be used.

        procedure Exchange_Certificate (O : in out Object; Value : Boolean);
        --  Set to True to request the client to send its certificate to the server

        procedure Certificate_Required (O : in out Object; Value : Boolean);
        --  Returns True if the server must abort the connection if the
        --  client did not provide a certificate. If this option is set
        --  the Exchange_Certificate must also be set.

        procedure Trusted_CA (O : in out Object; Filename : String);
        --  Returns the filename containing a list of trusted CA, this is to be used
        --  with the Exchange_Certificate option. The filename is on bundle of CAs
        --  that can be trusted. A client certificate signed with one of those CA
        --  will be accetped by the server.

        procedure CRL_File (O : in out Object; Filename : String);
        --  Returns the filename containing the Certificate Revocation List. This
        --  list is used by the server to check for revoked certificate.

        -------------------------
        -- Per Process Options -
        -------------------------

        procedure Session_Cleanup_Interval (Value : Duration);
        --  Number of seconds between each run of the cleaner task to remove
        --  obsolete session data.

        procedure Session_Lifetime (Value : Duration);
        --  Number of seconds to keep a session if not used. After this period the
        --  session data is obsoleted and will be removed during next cleanup.

        procedure Session_Id_Length (Value : Positive);
        --  Returns the length (number of characters) of the session id

        procedure Session_Cleaner_Priority (Value : System.Any_Priority);
        --  Set the priority used by the session cleaner task

        procedure Service_Priority (Value : System.Any_Priority);
        --  Set the priority used by the others services (SMTP server, Jabber
        --  server, Push server...).

        procedure Transient_Cleanup_Interval (Value : Duration);
        --  Number of seconds between each run of the cleaner task to remove
        --  transient pages.

        procedure Transient_Lifetime (Value : Duration);
        --  Number of seconds to keep a transient page. After this period the
        --  transient page is obsoleted and will be removed during next cleanup.

        procedure Context_Lifetime (Value : Duration);
        --  Number of seconds to keep a context if not used. After this period the
        --  context data is obsoleted and will be removed during next cleanup.

        procedure Max_Concurrent_Download (Value : Positive);
        --  Control the maximum number of parallel downloads accepted by the
        --  download manager.

        procedure Max_WebSocket_Handler (Value : Positive);
        --  This is the max simultaneous connections handling WebSocket's messages

        procedure WebSocket_Message_Queue_Size (Value : Positive);
        --  This is the size of the queue containing incoming messages

        procedure WebSocket_Origin (Value : String);
        --  This is regular expression to restrict WebSocket to a specific origin

        procedure WebSocket_Priority (Value : System.Any_Priority);
        --  Set the priority used by the WebSocket service

        procedure Input_Line_Size_Limit (Value : Positive);
        --  Maximum length of an HTTP parameter

        procedure Parameter
          (Config        : in out Object;
           Name          : String;
           Value         : String;
           Error_Context : String := "");
        --  Set one of the AWS HTTP per server parameters. Raises Constraint_Error
        --  in case of wrong parameter name or wrong parameter value.
        --  Error_Context may contain additional information about the parameter.
        --  This  message will be added to the Constraint_Error exception.
        --  One way to use Error_Context is to set it with information about
        --  where this parameter come form.

        procedure Parameter
          (Name          : String;
           Value         : String;
           Error_Context : String := "");
        --  Set one of the AWS HTTP per process parameters. See description above

     end AWS.Config.Set;


File: aws.info,  Node: AWS.Containers.Tables,  Next: AWS.Cookie,  Prev: AWS.Config.Set,  Up: AWS API Reference

B.11 AWS.Containers.Tables
==========================


     ------------------------------------------------------------------------------
     --                              Ada Web Server                              -
     --                                                                          -
     --                     Copyright (C) 2000-2012, AdaCore                     -
     --                                                                          -
     --  This library is free software;  you can redistribute it and/or modify   -
     --  it under terms of the  GNU General Public License  as published by the  -
     --  Free Software  Foundation;  either version 3,  or (at your  option) any -
     --  later version. This library is distributed in the hope that it will be  -
     --  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of -
     --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                    -
     --                                                                          -
     --  As a special exception under Section 7 of GPL version 3, you are        -
     --  granted additional permissions described in the GCC Runtime Library     -
     --  Exception, version 3.1, as published by the Free Software Foundation.   -
     --                                                                          -
     --  You should have received a copy of the GNU General Public License and   -
     --  a copy of the GCC Runtime Library Exception along with this program;    -
     --  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see   -
     --  <http://www.gnu.org/licenses/>.                                         -
     --                                                                          -
     --  As a special exception, if other files instantiate generics from this   -
     --  unit, or you link this unit with other files to produce an executable,  -
     --  this  unit  does not  by itself cause  the resulting executable to be   -
     --  covered by the GNU General Public License. This exception does not      -
     --  however invalidate any other reasons why the executable file  might be  -
     --  covered by the  GNU Public License.                                     -
     ------------------------------------------------------------------------------

     with Ada.Strings.Unbounded;

     private with Ada.Containers.Indefinite_Ordered_Maps;
     private with Ada.Containers.Indefinite_Vectors;
     private with Ada.Containers.Vectors;

     package AWS.Containers.Tables is

        use Ada.Strings.Unbounded;

        type Table_Type is tagged private;

        Empty_Table : constant Table_Type;

        type Element (Name_Length, Value_Length : Natural) is record
           Name  : String (1 .. Name_Length);
           Value : String (1 .. Value_Length);
        end record;
        --  Data type to store name/value pair retrieved from a Table_Type

        Null_Element : constant Element;

        type VString_Array is array (Positive range <>) of Unbounded_String;

        function Count (Table : Table_Type) return Natural;
        --  Returns the number of item in Table

        function Name_Count (Table : Table_Type) return Natural;
        --  Returns the number of unique key name in Table

        function Case_Sensitive (Table : Table_Type) return Boolean;
        pragma Inline (Case_Sensitive);
        --  Returns case sensitivity flag of the Table

        function Count (Table : Table_Type; Name : String) return Natural;
        --  Returns the number of value for Key Name in Table. It returns
        --  0 if Key does not exist.

        function Exist (Table : Table_Type; Name : String) return Boolean;
        --  Returns True if Key exist in Table

        function Get
          (Table : Table_Type;
           Name  : String;
           N     : Positive := 1) return String;
        --  Returns the Nth value associated with Key into Table. Returns
        --  the emptry string if key does not exist.

        function Get_Name
          (Table : Table_Type; N : Positive := 1) return String;
        --  Returns the Nth Name in Table or the empty string if there is
        --  no parameter with this number.

        function Get_Value
          (Table : Table_Type; N : Positive := 1) return String;
        --  Returns the Nth Value in Table or the empty string if there is
        --  no parameter with this number.

        function Get (Table : Table_Type; N : Positive) return Element;
        --  Returns N'th name/value pair. Returns Null_Element if there is no
        --  such item in the table.

        function Get_Names
          (Table : Table_Type; Sort : Boolean := False) return VString_Array;
        --  Returns array of unique key names. If Sort is True, the returned names
        --  array is sorted in alphabetical order. This is of course slightly
        --  slower than returning unsorted results.

        function Get_Values
          (Table : Table_Type; Name : String) return VString_Array;
        --  Returns all values for the specified parameter key name

        generic
           with procedure Process (Name, Value : String);
        procedure Generic_Iterate_Names
          (Table : Table_Type; Coupler : String);
        --  Iterates over all names in the table.
        --  All Values of the same name would be given Coupler separated.

        procedure Iterate_Names
          (Table   : Table_Type;
           Coupler : String;
           Process : not null access procedure (Name, Value : String));

     private
        --  implementation removed
     end AWS.Containers.Tables;


File: aws.info,  Node: AWS.Cookie,  Next: AWS.Default,  Prev: AWS.Containers.Tables,  Up: AWS API Reference

B.12 AWS.Cookie
===============


     ------------------------------------------------------------------------------
     --                              Ada Web Server                              -
     --                                                                          -
     --                     Copyright (C) 2010-2012, AdaCore                     -
     --                                                                          -
     --  This library is free software;  you can redistribute it and/or modify   -
     --  it under terms of the  GNU General Public License  as published by the  -
     --  Free Software  Foundation;  either version 3,  or (at your  option) any -
     --  later version. This library is distributed in the hope that it will be  -
     --  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of -
     --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                    -
     --                                                                          -
     --  As a special exception under Section 7 of GPL version 3, you are        -
     --  granted additional permissions described in the GCC Runtime Library     -
     --  Exception, version 3.1, as published by the Free Software Foundation.   -
     --                                                                          -
     --  You should have received a copy of the GNU General Public License and   -
     --  a copy of the GCC Runtime Library Exception along with this program;    -
     --  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see   -
     --  <http://www.gnu.org/licenses/>.                                         -
     --                                                                          -
     --  As a special exception, if other files instantiate generics from this   -
     --  unit, or you link this unit with other files to produce an executable,  -
     --  this  unit  does not  by itself cause  the resulting executable to be   -
     --  covered by the GNU General Public License. This exception does not      -
     --  however invalidate any other reasons why the executable file  might be  -
     --  covered by the  GNU Public License.                                     -
     ------------------------------------------------------------------------------

     --  A package for basic HTTP state management, ie. cookies. Tokens and
     --  attributes adhere to RFC-2109: http://tools.ietf.org/html/rfc2109

     with AWS.Default;
     with AWS.Response;
     with AWS.Status;

     package AWS.Cookie is

        Response_Data_Not_Initialized : exception;
        --  The Response_Data_Not_Initialized exception is raised when trying to add
        --  headers to an un-initialized AWS.Response.Data object.
        --  The AWS.Response.Data object is initialized using the
        --  AWS.Response.Build function.

        No_Max_Age : constant Duration;
        --  When no Max-Age is required, this value can be passed to the Set
        --  routines below.

        function Exists
          (Request        : Status.Data;
           Key            : String;
           Case_Sensitive : Boolean := True) return Boolean;
        --  Check if the 'Key' cookie exists in AWS.Headers.List. Return Boolean
        --  True of the cookie exists, else Boolean False.

        procedure Expire
          (Content : in out Response.Data;
           Key     : String;
           Path    : String := "/");
        --  Expire the 'Key' cookie. This is done by setting the Max-Age attribute
        --  to 0. The Value of the cookie is also set to "", in case a browser does
        --  not honor the Max-Age attribute.

        function Get
          (Request        : Status.Data;
           Key            : String;
           Case_Sensitive : Boolean := True) return String;
        --  Return the 'Key' cookie from AWS.Headers.List. If the cookie does not
        --  exist, return an empty string, ie. ""

        function Get
          (Request        : Status.Data;
           Key            : String;
           Case_Sensitive : Boolean := True) return Integer;
        --  Return the 'Key' cookie from AWS.Headers.List. If the cookie does not
        --  exist or can't be converted from String to Integer then return 0.

        function Get
          (Request        : Status.Data;
           Key            : String;
           Case_Sensitive : Boolean := True) return Float;
        --  Return the 'Key' cookie from AWS.Headers.List. If the cookie does not
        --  exist or can't be converted from String to Float then return 0.0.

        function Get
          (Request        : Status.Data;
           Key            : String;
           Case_Sensitive : Boolean := True) return Boolean;
        --  Return the 'Key' cookie from AWS.Headers.List. Only if the cookie value
        --  equals "True" is Boolean True returned, else Boolean False is returned.

        procedure Set
          (Content : in out Response.Data;
           Key     : String;
           Value   : String;
           Comment : String := "";
           Domain  : String := "";
           Max_Age : Duration := Default.Ten_Years;
           Path    : String := "/";
           Secure  : Boolean := False);
        --  Set a new cookie named 'Key' with value 'Value'. See RFC 2109 for more
        --  information about the individual cookie attributes:
        --    http://tools.ietf.org/html/rfc2109
        --
        --  Exceptions:
        --    Response_Data_Not_Initialized
        --      Is raised if AWS.Cookie.Set is called before the Content object has
        --      been initialized by a call to AWS.Response.Build

        procedure Set
          (Content : in out Response.Data;
           Key     : String;
           Value   : Integer;
           Comment : String := "";
           Domain  : String := "";
           Max_Age : Duration := Default.Ten_Years;
           Path    : String := "/";
           Secure  : Boolean := False);
        --  Set a new cookie named 'Key' with Integer value 'Value'. The Integer is
        --  converted to a String, as both cookie keys and values are inherently
        --  strings.
        --
        --  Exceptions:
        --    Response_Data_Not_Initialized
        --      Is raised if AWS.Cookie.Set is called before the Content object has
        --      been initialized by a call to AWS.Response.Build

        procedure Set
          (Content : in out Response.Data;
           Key     : String;
           Value   : Float;
           Comment : String := "";
           Domain  : String := "";
           Max_Age : Duration := Default.Ten_Years;
           Path    : String := "/";
           Secure  : Boolean := False);
        --  Set a new cookie named 'Key' with Float value 'Value'. The Float is
        --  converted to a String, as both cookie keys and values are inherently
        --  strings.
        --
        --  Exceptions:
        --    Response_Data_Not_Initialized
        --      Is raised if AWS.Cookie.Set is called before the Content object has
        --      been initialized by a call to AWS.Response.Build

        procedure Set
          (Content : in out Response.Data;
           Key     : String;
           Value   : Boolean;
           Comment : String := "";
           Domain  : String := "";
           Max_Age : Duration := Default.Ten_Years;
           Path    : String := "/";
           Secure  : Boolean := False);
        --  Set a new cookie named 'Key' with Boolean value 'Value'. The Boolean is
        --  converted to a String ("False" or "True"), as both cookie keys and
        --  values are inherently strings.
        --
        --  Exceptions:
        --    Response_Data_Not_Initialized
        --      Is raised if AWS.Cookie.Set is called before the Content object has
        --      been initialized by a call to AWS.Response.Build

     private
        --  implementation removed
     end AWS.Cookie;


File: aws.info,  Node: AWS.Default,  Next: AWS.Dispatchers,  Prev: AWS.Cookie,  Up: AWS API Reference

B.13 AWS.Default
================


     ------------------------------------------------------------------------------
     --                              Ada Web Server                              -
     --                                                                          -
     --                     Copyright (C) 2000-2013, AdaCore                     -
     --                                                                          -
     --  This library is free software;  you can redistribute it and/or modify   -
     --  it under terms of the  GNU General Public License  as published by the  -
     --  Free Software  Foundation;  either version 3,  or (at your  option) any -
     --  later version. This library is distributed in the hope that it will be  -
     --  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of -
     --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                    -
     --                                                                          -
     --  As a special exception under Section 7 of GPL version 3, you are        -
     --  granted additional permissions described in the GCC Runtime Library     -
     --  Exception, version 3.1, as published by the Free Software Foundation.   -
     --                                                                          -
     --  You should have received a copy of the GNU General Public License and   -
     --  a copy of the GCC Runtime Library Exception along with this program;    -
     --  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see   -
     --  <http://www.gnu.org/licenses/>.                                         -
     --                                                                          -
     --  As a special exception, if other files instantiate generics from this   -
     --  unit, or you link this unit with other files to produce an executable,  -
     --  this  unit  does not  by itself cause  the resulting executable to be   -
     --  covered by the GNU General Public License. This exception does not      -
     --  however invalidate any other reasons why the executable file  might be  -
     --  covered by the  GNU Public License.                                     -
     ------------------------------------------------------------------------------

     --  This package contains the default AWS configuration values. These values
     --  are used to initialize the configuration objects. Users should not modify
     --  the values here, see AWS.Config.* API.

     with System;

     package AWS.Default is

        pragma Pure;

        use System;

        --  All times are in seconds

        Ten_Years     : constant := 86_400.0 * 365 * 10;

        One_Hour      : constant := 3_600.0;
        One_Minute    : constant :=    60.0;

        Eight_Hours   : constant :=  8.0 * One_Hour;
        Three_Hours   : constant :=  3.0 * One_Hour;

        Three_Minutes : constant :=  3.0 * One_Minute;
        Five_Minutes  : constant :=  5.0 * One_Minute;
        Ten_Minutes   : constant := 10.0 * One_Minute;

        --  Server configuration

        Server_Name                     : constant String  := "AWS Module";
        WWW_Root                        : constant String  := "./";
        Admin_URI                       : constant String  := "";
        Admin_Password                  : constant String  := "";
        Admin_Realm                     : constant String  := "AWS Admin Page";
        Protocol_Family                 : constant String  := "FAMILY_UNSPEC";
        Server_Port                     : constant         := 8080;
        Hotplug_Port                    : constant         := 8888;
        Max_Connection                  : constant         := 5;
        Max_WebSocket_Handler           : constant         := 2;
        WebSocket_Message_Queue_Size    : constant         := 10;
        Send_Buffer_Size                : constant         := 0;
        Free_Slots_Keep_Alive_Limit     : constant         := 1;
        Keep_Alive_Force_Limit          : constant         := 0;
        Keep_Alive_Close_Limit          : constant         := 0;
        Accept_Queue_Size               : constant         := 64;
        Upload_Directory                : constant String  := "";
        Upload_Size_Limit               : constant         := 16#500_000#;
        Line_Stack_Size                 : constant         := 16#150_000#;
        Case_Sensitive_Parameters       : constant Boolean := True;
        Input_Line_Size_Limit           : constant         := 16#4000#;
        Max_POST_Parameters             : constant         := 100;
        Max_Concurrent_Download         : constant         := 25;
        Reuse_Address                   : constant Boolean := False;
        MIME_Types                      : constant String  := "aws.mime";

        --  Client configuration

        User_Agent                      : constant String :=
                                            "AWS (Ada Web Server) v" & Version;

        --  Log values. The character '@' in the error log filename prefix is
        --  replaced by the running program name.

        Log_File_Directory              : constant String := "./";

        Log_Split_Mode                  : constant String := "NONE";
        Log_Filename_Prefix             : constant String := "@";

        Error_Log_Split_Mode            : constant String := "NONE";
        Error_Log_Filename_Prefix       : constant String := "@_error";

        Log_Size_Limit                  : constant Natural := 0;

        --  Session

        Session                         : constant Boolean  := False;
        Session_Name                    : constant String   := "AWS";
        Session_Cleanup_Interval        : constant Duration := Five_Minutes;
        Session_Lifetime                : constant Duration := Ten_Minutes;
        Session_Id_Length               : constant Positive := 11;

        --  Context

        Context_Lifetime                : constant Duration := Eight_Hours;

        --  Transient pages

        Transient_Cleanup_Interval      : constant Duration := Three_Minutes;
        Transient_Lifetime              : constant Duration := Five_Minutes;

        --  Server's timeouts

        Cleaner_Wait_For_Client_Timeout : constant Duration := 80.0;
        Cleaner_Client_Header_Timeout   : constant Duration := 7.0;
        Cleaner_Client_Data_Timeout     : constant Duration := Eight_Hours;
        Cleaner_Server_Response_Timeout : constant Duration := Eight_Hours;

        Force_Wait_For_Client_Timeout   : constant Duration := 2.0;
        Force_Client_Header_Timeout     : constant Duration := 2.0;
        Force_Client_Data_Timeout       : constant Duration := Three_Hours;
        Force_Server_Response_Timeout   : constant Duration := Three_Hours;

        Send_Timeout                    : constant Duration := 40.0;
        Receive_Timeout                 : constant Duration := 30.0;

        --  Directory template

        Directory_Browser_Page          : constant String := "aws_directory.thtml";

        --  Status page

        Status_Page                     : constant String := "aws_status.thtml";
        Up_Image                        : constant String := "aws_up.png";
        Down_Image                      : constant String := "aws_down.png";
        Logo_Image                      : constant String := "aws_logo.png";

        --  Security

        Security                        : constant Boolean := False;
        Security_Mode                   : constant String  := "SSLv23";
        Certificate                     : constant String  := "cert.pem";
        Key                             : constant String  := "";
        Client_Certificate              : constant String  := "";
        Exchange_Certificate            : constant Boolean := False;
        Certificate_Required            : constant Boolean := False;
        Trusted_CA                      : constant String  := "";
        CRL_File                        : constant String  := "";
        Check_URL_Validity              : constant Boolean := True;

        --  Priorities

        Server_Priority                 : constant Any_Priority := Default_Priority;
        WebSocket_Priority              : constant Any_Priority := Default_Priority;
        Session_Cleaner_Priority        : constant Any_Priority := Default_Priority;
        Service_Priority                : constant Any_Priority := Default_Priority;

     end AWS.Default;


File: aws.info,  Node: AWS.Dispatchers,  Next: AWS.Dispatchers.Callback,  Prev: AWS.Default,  Up: AWS API Reference

B.14 AWS.Dispatchers
====================


     ------------------------------------------------------------------------------
     --                              Ada Web Server                              -
     --                                                                          -
     --                     Copyright (C) 2000-2012, AdaCore                     -
     --                                                                          -
     --  This library is free software;  you can redistribute it and/or modify   -
     --  it under terms of the  GNU General Public License  as published by the  -
     --  Free Software  Foundation;  either version 3,  or (at your  option) any -
     --  later version. This library is distributed in the hope that it will be  -
     --  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of -
     --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                    -
     --                                                                          -
     --  As a special exception under Section 7 of GPL version 3, you are        -
     --  granted additional permissions described in the GCC Runtime Library     -
     --  Exception, version 3.1, as published by the Free Software Foundation.   -
     --                                                                          -
     --  You should have received a copy of the GNU General Public License and   -
     --  a copy of the GCC Runtime Library Exception along with this program;    -
     --  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see   -
     --  <http://www.gnu.org/licenses/>.                                         -
     --                                                                          -
     --  As a special exception, if other files instantiate generics from this   -
     --  unit, or you link this unit with other files to produce an executable,  -
     --  this  unit  does not  by itself cause  the resulting executable to be   -
     --  covered by the GNU General Public License. This exception does not      -
     --  however invalidate any other reasons why the executable file  might be  -
     --  covered by the  GNU Public License.                                     -
     ------------------------------------------------------------------------------

     --  This package provides a service to build Callbacks which can support
     --  user's data. It is possible to build a new dispatcher by inheriting the
     --  handler type and to provides the Dispatch routine.

     with Ada.Finalization;

     with AWS.Response;
     with AWS.Status;
     with AWS.Utils;

     package AWS.Dispatchers is

        type Handler is abstract new Ada.Finalization.Controlled
          and AWS.Utils.Clonable with private;

        overriding procedure Initialize (Dispatcher : in out Handler);
        overriding procedure Adjust     (Dispatcher : in out Handler);
        overriding procedure Finalize   (Dispatcher : in out Handler);
        --  Initialize/Adjust/Finalize is doing the reference counting, children
        --  should just call these routines if possible. It is possible to know if
        --  no more object are referenced by calling Ref_Counter below.

        function Dispatch
          (Dispatcher : Handler;
           Request    : Status.Data) return Response.Data is abstract;
        --  Call the appropriate inherited dispatcher

        function Ref_Counter (Dispatcher : Handler) return Natural;
        --  Returns the reference counter for Handler. If 0 is returned then this
        --  object is not referenced anymore, it is safe to deallocate resources.

        type Handler_Class_Access is access all Handler'Class;

        procedure Free (Dispatcher : in out Handler_Class_Access);
        pragma Inline (Free);
        --  Release memory associated with the dispatcher

     private
        --  implementation removed
     end AWS.Dispatchers;


File: aws.info,  Node: AWS.Dispatchers.Callback,  Next: AWS.Exceptions,  Prev: AWS.Dispatchers,  Up: AWS API Reference

B.15 AWS.Dispatchers.Callback
=============================


     ------------------------------------------------------------------------------
     --                              Ada Web Server                              -
     --                                                                          -
     --                     Copyright (C) 2000-2012, AdaCore                     -
     --                                                                          -
     --  This library is free software;  you can redistribute it and/or modify   -
     --  it under terms of the  GNU General Public License  as published by the  -
     --  Free Software  Foundation;  either version 3,  or (at your  option) any -
     --  later version. This library is distributed in the hope that it will be  -
     --  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of -
     --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                    -
     --                                                                          -
     --  As a special exception under Section 7 of GPL version 3, you are        -
     --  granted additional permissions described in the GCC Runtime Library     -
     --  Exception, version 3.1, as published by the Free Software Foundation.   -
     --                                                                          -
     --  You should have received a copy of the GNU General Public License and   -
     --  a copy of the GCC Runtime Library Exception along with this program;    -
     --  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see   -
     --  <http://www.gnu.org/licenses/>.                                         -
     --                                                                          -
     --  As a special exception, if other files instantiate generics from this   -
     --  unit, or you link this unit with other files to produce an executable,  -
     --  this  unit  does not  by itself cause  the resulting executable to be   -
     --  covered by the GNU General Public License. This exception does not      -
     --  however invalidate any other reasons why the executable file  might be  -
     --  covered by the  GNU Public License.                                     -
     ------------------------------------------------------------------------------

     --  Dispatch on a Callback procedure

     with AWS.Dispatchers;
     with AWS.Response;
     with AWS.Status;

     package AWS.Dispatchers.Callback is

        type Handler is new Dispatchers.Handler with private;
        --  This is a simple wrapper around standard callback procedure (access to
        --  function). It will be used to build dispatchers services and for the
        --  main server callback.

        function Create (Callback : Response.Callback) return Handler;
        pragma Inline (Create);
        --  Build a dispatcher for the specified callback

     private
        --  implementation removed
     end AWS.Dispatchers.Callback;


File: aws.info,  Node: AWS.Exceptions,  Next: AWS.Headers,  Prev: AWS.Dispatchers.Callback,  Up: AWS API Reference

B.16 AWS.Exceptions
===================


     ------------------------------------------------------------------------------
     --                              Ada Web Server                              -
     --                                                                          -
     --                     Copyright (C) 2003-2012, AdaCore                     -
     --                                                                          -
     --  This library is free software;  you can redistribute it and/or modify   -
     --  it under terms of the  GNU General Public License  as published by the  -
     --  Free Software  Foundation;  either version 3,  or (at your  option) any -
     --  later version. This library is distributed in the hope that it will be  -
     --  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of -
     --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                    -
     --                                                                          -
     --  As a special exception under Section 7 of GPL version 3, you are        -
     --  granted additional permissions described in the GCC Runtime Library     -
     --  Exception, version 3.1, as published by the Free Software Foundation.   -
     --                                                                          -
     --  You should have received a copy of the GNU General Public License and   -
     --  a copy of the GCC Runtime Library Exception along with this program;    -
     --  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see   -
     --  <http://www.gnu.org/licenses/>.                                         -
     --                                                                          -
     --  As a special exception, if other files instantiate generics from this   -
     --  unit, or you link this unit with other files to produce an executable,  -
     --  this  unit  does not  by itself cause  the resulting executable to be   -
     --  covered by the GNU General Public License. This exception does not      -
     --  however invalidate any other reasons why the executable file  might be  -
     --  covered by the  GNU Public License.                                     -
     ------------------------------------------------------------------------------

     with Ada.Exceptions;

     with AWS.Log;
     with AWS.Response;
     with AWS.Status;

     package AWS.Exceptions is

        type Data is record
           Fatal   : Boolean;
           --  If True it means that we go a fatal error. The slot will be
           --  terminated so AWS will loose one of it's simultaneous connection.
           --  This is clearly an AWS internal error that should be fixed in AWS.

           Slot    : Positive;
           --  The failing slot number

           Request : Status.Data;
           --  The complete request information that was served when the slot has
           --  failed. This variable is set only when Fatal is False.
        end record;

        type Unexpected_Exception_Handler is access
          procedure (E      : Ada.Exceptions.Exception_Occurrence;
                     Log    : in out AWS.Log.Object;
                     Error  : Data;
                     Answer : in out Response.Data);
        --  Unexpected exception handler can be set to monitor server errors.
        --  Answer can be set with the answer to send back to the client's
        --  browser. Note that this is possible only for non fatal error
        --  (i.e. Error.Fatal is False).
        --  Log is the error log object for the failing server, it can be used
        --  to log user's information (if error log is activated for this
        --  server). Note that the server will have already logged information
        --  about the problem.

     end AWS.Exceptions;


File: aws.info,  Node: AWS.Headers,  Next: AWS.Headers.Values,  Prev: AWS.Exceptions,  Up: AWS API Reference

B.17 AWS.Headers
================


     ------------------------------------------------------------------------------
     --                              Ada Web Server                              -
     --                                                                          -
     --                     Copyright (C) 2000-2012, AdaCore                     -
     --                                                                          -
     --  This library is free software;  you can redistribute it and/or modify   -
     --  it under terms of the  GNU General Public License  as published by the  -
     --  Free Software  Foundation;  either version 3,  or (at your  option) any -
     --  later version. This library is distributed in the hope that it will be  -
     --  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of -
     --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                    -
     --                                                                          -
     --  As a special exception under Section 7 of GPL version 3, you are        -
     --  granted additional permissions described in the GCC Runtime Library     -
     --  Exception, version 3.1, as published by the Free Software Foundation.   -
     --                                                                          -
     --  You should have received a copy of the GNU General Public License and   -
     --  a copy of the GCC Runtime Library Exception along with this program;    -
     --  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see   -
     --  <http://www.gnu.org/licenses/>.                                         -
     --                                                                          -
     --  As a special exception, if other files instantiate generics from this   -
     --  unit, or you link this unit with other files to produce an executable,  -
     --  this  unit  does not  by itself cause  the resulting executable to be   -
     --  covered by the GNU General Public License. This exception does not      -
     --  however invalidate any other reasons why the executable file  might be  -
     --  covered by the  GNU Public License.                                     -
     ------------------------------------------------------------------------------

     with AWS.Containers.Tables;
     with AWS.Net;

     package AWS.Headers is

        type List is new AWS.Containers.Tables.Table_Type with private;
        --  Header container. This set handles a set of HTTP header line, each new
        --  header line is inserted at the end of the list (see AWS.Headers.Set API)
        --  and can be retrieved by the following services. Header lines are
        --  numbered from 1 to N.

        Empty_List : constant List;

        subtype VString_Array is AWS.Containers.Tables.VString_Array;

        subtype Element is AWS.Containers.Tables.Element;

        Format_Error : exception;
        --  Raised when header line format is wrong

        procedure Send_Header
          (Socket : Net.Socket_Type'Class; Headers : List);
        --  Send all header lines in Headers list to the socket

        function Get_Line (Headers : List; N : Positive) return String;
        --  Returns the Nth header line in Headers container. The returned value is
        --  formatted as a correct header line:
        --
        --     message-header = field-name ":" [ field-value ]
        --
        --  That is the header-name followed with character ':' and the header
        --  values. If there is less than Nth header line it returns the empty
        --  string. Note that this routine does returns all header line values, for
        --  example it would return:
        --
        --     Content_Type: multipart/mixed; boundary="0123_The_Boundary_Value_"
        --
        --  For a file upload content type header style.

        function Get_Values (Headers : List; Name : String) return String;
        --  Returns all values for the specified header field Name in a
        --  comma-separated string. This format is conformant to [RFC 2616 - 4.2]
        --  (see last paragraph).

        function Length (Headers : AWS.Headers.List) return Natural;
        --  Returns the length (in bytes) of the header, including the ending
        --  empty line.

        --  See AWS.Containers.Tables for inherited routines

     private
        --  implementation removed
     end AWS.Headers;


File: aws.info,  Node: AWS.Headers.Values,  Next: AWS.Jabber,  Prev: AWS.Headers,  Up: AWS API Reference

B.18 AWS.Headers.Values
=======================


     ------------------------------------------------------------------------------
     --                              Ada Web Server                              -
     --                                                                          -
     --                     Copyright (C) 2002-2012, AdaCore                     -
     --                                                                          -
     --  This library is free software;  you can redistribute it and/or modify   -
     --  it under terms of the  GNU General Public License  as published by the  -
     --  Free Software  Foundation;  either version 3,  or (at your  option) any -
     --  later version. This library is distributed in the hope that it will be  -
     --  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of -
     --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                    -
     --                                                                          -
     --  As a special exception under Section 7 of GPL version 3, you are        -
     --  granted additional permissions described in the GCC Runtime Library     -
     --  Exception, version 3.1, as published by the Free Software Foundation.   -
     --                                                                          -
     --  You should have received a copy of the GNU General Public License and   -
     --  a copy of the GCC Runtime Library Exception along with this program;    -
     --  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see   -
     --  <http://www.gnu.org/licenses/>.                                         -
     --                                                                          -
     --  As a special exception, if other files instantiate generics from this   -
     --  unit, or you link this unit with other files to produce an executable,  -
     --  this  unit  does not  by itself cause  the resulting executable to be   -
     --  covered by the GNU General Public License. This exception does not      -
     --  however invalidate any other reasons why the executable file  might be  -
     --  covered by the  GNU Public License.                                     -
     ------------------------------------------------------------------------------

     with Ada.Strings.Unbounded;

     package AWS.Headers.Values is

        use Ada.Strings.Unbounded;

        Format_Error : exception renames Headers.Format_Error;

        --  Data represent a token from an header line. There is two kinds of
        --  token, either named or un-named.
        --
        --     Content-Type: xyz boundary="uvt"
        --
        --  Here xyz is an un-named value and uvt a named value the name is
        --  boundary.

        type Data (Named_Value : Boolean := True) is record
           Value : Unbounded_String;
           case Named_Value is
              when True =>
                 Name : Unbounded_String;
              when False =>
                 null;
           end case;
        end record;

        type Set is array (Positive range <>) of Data;

        -----------
        -- Parse -
        -----------

        generic

           with procedure Value
             (Item : String;
              Quit : in out Boolean);
           --  Called for every un-named value read from the header value

           with procedure Named_Value
             (Name  : String;
              Value : String;
              Quit  : in out Boolean);
           --  Called for every named value read from the header value

        procedure Parse (Header_Value : String);
        --  Look for un-named values and named ones (Name="Value" pairs) in the
        --  header line, and call appropriate routines when found. Quit is set to
        --  False before calling Value or Named_Value, the parsing can be stopped
        --  by setting Quit to True.

        -------------------
        -- Split / Index -
        -------------------

        function Split (Header_Value : String) return Set;
        --  Returns a Set with each named and un-named values splited from Data

        function Index
          (Set            : Values.Set;
           Name           : String;
           Case_Sensitive : Boolean := True) return Natural;
        --  Returns index for Name in the set or 0 if Name not found.
        --  If Case_Sensitive is false the find is case_insensitive.

        ---------------------------
        -- Other search routines -
        ---------------------------

        function Search
          (Header_Value   : String;
           Name           : String;
           Case_Sensitive : Boolean := True) return String;
        --  Returns Value for Name in Header_Value or the empty string if Name not
        --  found. If Case_Sensitive is False the search is case insensitive.

        function Get_Unnamed_Value
          (Header_Value : String;
           N            : Positive := 1) return String;
        --  Returns N-th un-named value from Header_Value

        function Unnamed_Value_Exists
          (Header_Value   : String;
           Value          : String;
           Case_Sensitive : Boolean := True) return Boolean;
        --  Returns True if the unnamed value specified has been found in
        --  Header_Value.

     end AWS.Headers.Values;


File: aws.info,  Node: AWS.Jabber,  Next: AWS.LDAP.Client,  Prev: AWS.Headers.Values,  Up: AWS API Reference

B.19 AWS.Jabber
===============


     ------------------------------------------------------------------------------
     --                              Ada Web Server                              -
     --                                                                          -
     --                    Copyright (C) 2002-2012, AdaCore                      -
     --                                                                          -
     --  This library is free software;  you can redistribute it and/or modify   -
     --  it under terms of the  GNU General Public License  as published by the  -
     --  Free Software  Foundation;  either version 3,  or (at your  option) any -
     --  later version. This library is distributed in the hope that it will be  -
     --  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of -
     --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                    -
     --                                                                          -
     --  As a special exception under Section 7 of GPL version 3, you are        -
     --  granted additional permissions described in the GCC Runtime Library     -
     --  Exception, version 3.1, as published by the Free Software Foundation.   -
     --                                                                          -
     --  You should have received a copy of the GNU General Public License and   -
     --  a copy of the GCC Runtime Library Exception along with this program;    -
     --  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see   -
     --  <http://www.gnu.org/licenses/>.                                         -
     --                                                                          -
     --  As a special exception, if other files instantiate generics from this   -
     --  unit, or you link this unit with other files to produce an executable,  -
     --  this  unit  does not  by itself cause  the resulting executable to be   -
     --  covered by the GNU General Public License. This exception does not      -
     --  however invalidate any other reasons why the executable file  might be  -
     --  covered by the  GNU Public License.                                     -
     ------------------------------------------------------------------------------

     package AWS.Jabber is

        pragma Pure;

     end AWS.Jabber;


File: aws.info,  Node: AWS.LDAP.Client,  Next: AWS.Log,  Prev: AWS.Jabber,  Up: AWS API Reference

B.20 AWS.LDAP.Client
====================


     ------------------------------------------------------------------------------
     --                              Ada Web Server                              -
     --                                                                          -
     --                     Copyright (C) 2003-2012, AdaCore                     -
     --                                                                          -
     --  This library is free software;  you can redistribute it and/or modify   -
     --  it under terms of the  GNU General Public License  as published by the  -
     --  Free Software  Foundation;  either version 3,  or (at your  option) any -
     --  later version. This library is distributed in the hope that it will be  -
     --  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of -
     --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                    -
     --                                                                          -
     --  As a special exception under Section 7 of GPL version 3, you are        -
     --  granted additional permissions described in the GCC Runtime Library     -
     --  Exception, version 3.1, as published by the Free Software Foundation.   -
     --                                                                          -
     --  You should have received a copy of the GNU General Public License and   -
     --  a copy of the GCC Runtime Library Exception along with this program;    -
     --  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see   -
     --  <http://www.gnu.org/licenses/>.                                         -
     --                                                                          -
     --  As a special exception, if other files instantiate generics from this   -
     --  unit, or you link this unit with other files to produce an executable,  -
     --  this  unit  does not  by itself cause  the resulting executable to be   -
     --  covered by the GNU General Public License. This exception does not      -
     --  however invalidate any other reasons why the executable file  might be  -
     --  covered by the  GNU Public License.                                     -
     ------------------------------------------------------------------------------

     --  Provides an API to add, read, modify and delete information from a LDAP
     --  server. It is a thick binding, see AWS.LDAP.Thin for a thin binding.
     --
     --  This API has been tested on Windows and Linux (OpenLDAP).

     with Ada.Containers.Indefinite_Vectors;
     with Ada.Exceptions;
     with Ada.Strings.Unbounded;

     with AWS.LDAP.Thin;

     package AWS.LDAP.Client is

        use Ada.Strings.Unbounded;

        LDAP_Error : exception renames LDAP.LDAP_Error;

        Default_Port : constant Positive := Positive (Thin.LDAP_PORT);

        subtype Directory    is Thin.LDAP_Type;
        --  An LDAP directory. This object must be initialized with Init and Bind
        --  and terminated with Unbind.

        subtype LDAP_Message is Thin.LDAPMessage;
        --  An LDAP message or set of messages. There is a set of iterators to
        --  access all messages returned by the search procedure.

        subtype BER_Element  is Thin.BerElement;
        --  An iterator structure. Initialized and used to iterate through all the
        --  attributes for a specific message.

        Null_Directory    : constant Directory    := Thin.Null_LDAP_Type;

        Null_LDAP_Message : constant LDAP_Message := Thin.Null_LDAPMessage;

        type Scope_Type is
          (LDAP_Scope_Default, LDAP_Scope_Base,
           LDAP_Scope_One_Level, LDAP_Scope_Subtree);
        --  LDAP scope for the search

        type String_Set is array (Positive range <>) of Unbounded_String;
        --  A set of strings, this is used to map C array of strings (a char **)
        --  from the thin binding.

        Null_Set : constant String_Set;

        function Get_Error
          (E : Ada.Exceptions.Exception_Occurrence) return Thin.Return_Code;
        --  Returns the error code in the LDAP_Error exception occurence E. Returns
        --  Think.LDAP_SUCCESS if no error code has been found.

        ----------------
        -- Attributes -
        ----------------

        subtype Attribute_Set is String_Set;
        --  Used to represent the set of attributes to retrieve from the LDAP server

        function Attributes
          (S1, S2, S3, S4, S5, S6, S7, S8, S9, S10 : String := "")
           return Attribute_Set;
        --  Returns a String_Set object containing only none empty values. Values
        --  for S1 through S10 must be set in the order of the parameters. This is
        --  an helper routine to help building an array of unbounded string from a
        --  set of string.

        function uid (Val : String := "") return String;
        --  Returns the uid attribute, if Val is specified "=<Val>" is
        --  added after the attribute name.

        function givenName (Val : String := "") return String;
        --  Returns the given name (firstname) attribute. if Val is specified
        --  "=<Val>" is added after the attribute name.

        function cn (Val : String := "") return String;
        function commonName (Val : String := "") return String renames cn;
        --  Returns the common Name attribute, if Val is specified "=<Val>" is
        --  added after the attribute name.

        function sn (Val : String := "") return String;
        function surname (Val : String := "") return String renames sn;
        --  Returns the surname attribute, if Val is specified "=<Val>" is
        --  added after the attribute name.

        function telephoneNumber (Val : String := "") return String;
        --  Returns the phone number. if Val is specified "=<Val>" is
        --  added after the attribute name. Val must use the international notation
        --  according to CCITT E.123.

        function mail (Val : String := "") return String;
        --  Returns the mail attribute. if Val is specified "=<Val>" is added after
        --  the attribute name.

        function l (Val : String := "") return String;
        function localityName (Val : String := "") return String renames l;
        --  Returns the locality attribute, if Val is specified "=<Val>" is
        --  added after the attribute name.

        function o (Val : String := "") return String;
        function organizationName (Val : String := "") return String renames o;
        --  Returns the organization attribute, if Val is specified "=<Val>" is
        --  added after the attribute name.

        function ou (Val : String := "") return String;
        function organizationalUnitName (Val : String := "") return String
          renames ou;
        --  Returns the organizational unit attribute, if Val is specified "=<Val>"
        --  is added after the attribute name.

        function st (Val : String := "") return String;
        function stateOrProvinceName (Val : String := "") return String
          renames st;
        --  Returns the state name attribute, if Val is specified "=<Val>" is
        --  added after the attribute name.

        function c (Val : String := "") return String;
        function countryName (Val : String) return String renames c;
        --  Returns country code attribute, if Val is specified "=<Val>" is
        --  added after the attribute name. Val must be a two-letter ISO 3166
        --  country code.

        function dc (Val : String := "") return String;
        function domainComponent (Val : String := "") return String renames dc;
        --  Returns a domain component attribute, if Val is specified "=<Val>" is
        --  added after the attribute name.

        function Cat
          (S1, S2, S3, S4, S5, S6, S7, S8, S9, S10 : String := "") return String;
        --  Returns a string object containing only none empty values. Values for
        --  S1 through S10 must be set in the order of the parameters. All values
        --  are catenated and separated with a coma. This is an helper routine to
        --  help building a filter objects or base distinguished name.

        ----------------
        -- Initialize -
        ----------------

        function Init
          (Host : String;
           Port : Positive := Default_Port) return Directory;
        --  Must be called first, to initialize the LDAP communication with the
        --  server. Returns Null_Directory in case of error.

        procedure Bind
          (Dir      : Directory;
           Login    : String;
           Password : String);
        --  Bind to the server by providing a login and password

        procedure Unbind (Dir : in out Directory);
        --  Must be called to release resources associated with the Directory. Does
        --  nothing if Dir is Null_Directory.

        function Is_Open (Dir : Directory) return Boolean;
        --  Returns True if the directory has correctly been initialized and binded
        --  with the server.

        ------------
        -- Search -
        ------------

        function Search
          (Dir        : Directory;
           Base       : String;
           Filter     : String;
           Scope      : Scope_Type    := LDAP_Scope_Default;
           Attrs      : Attribute_Set := Null_Set;
           Attrs_Only : Boolean       := False) return LDAP_Message;
        --  Do a search on the LDAP server. Base is the name of the database.
        --  Filter can be used to retrieve a specific set of entries. Attrs specify
        --  the set of attributes to retrieve. If Attrs_Only is set to True only
        --  the types are returned. Raises LDAP_Error in case of problem.

        -----------------------
        -- Add/Modify/Delete -
        -----------------------

        type Mod_Type is (LDAP_Mod_Add, LDAP_Mod_Replace, LDAP_Mod_BValues);
        --  Modification types: Add, Replace and BER flag

        type Mod_Element (Values_Size : Natural) is record
           Mod_Op     : Mod_Type;
           Mod_Type   : Unbounded_String;
           Mod_Values : Attribute_Set (1 .. Values_Size);
        end record;
        --  Holds modification elements. 'Abstraction' of the LDAPMod_Element type
        --  used in the thin-binding. Mod_Values is static to make it less complex.

        package LDAP_Mods is
          new Ada.Containers.Indefinite_Vectors (Positive, Mod_Element);
        --  Vector-based Storage for all modification elements. Will be
        --  mapped to C LDAPMod **.

        procedure Add
          (Dir  : Directory;
           DN   : String;
           Mods : LDAP_Mods.Vector);
        --  Add an entry specified by 'DN' to the LDAP server. The Mods-Vector
        --  contains the attributes for the entry.

        procedure Modify
          (Dir  : Directory;
           DN   : String;
           Mods : LDAP_Mods.Vector);
        --  Modify an attribute of entry specified by 'DN'. The Mods-Vector
        --  contains the attributes to add/replace/delete for the entry.

        procedure Delete (Dir : Directory; DN : String);
        --  Delete an entry specified by 'DN' from the LDAP server

        ---------------
        -- Iterators -
        ---------------

        function First_Entry
          (Dir   : Directory;
           Chain : LDAP_Message) return LDAP_Message;
        --  Returns the first entry (or Node) for the search result (Chain)

        function Next_Entry
          (Dir     : Directory;
           Entries : LDAP_Message) return LDAP_Message;
        --  Returns next entry (or Node) for Entries

        function Count_Entries
          (Dir   : Directory;
           Chain : LDAP_Message) return Natural;
        --  Returns the number of entries in the search result (Chain)

        procedure Free (Chain : LDAP_Message);
        --  Release memory associated with the search result Chain

        generic
           with procedure Action
             (Node : LDAP_Message;
              Quit : in out Boolean);
        procedure For_Every_Entry (Dir : Directory; Chain : LDAP_Message);
        --  This iterator call Action for each entry (Node) found in the LDAP result
        --  set as returned by the search procedure. Quit can be set to True to
        --  stop iteration; its initial value is False.

        function First_Attribute
          (Dir  : Directory;
           Node : LDAP_Message;
           BER  : not null access BER_Element) return String;
        --  Returns the first attribute for the entry. It initialize an iteraror
        --  (the BER structure). The BER structure must be released after used by
        --  using the Free routine below.

        function Next_Attribute
          (Dir  : Directory;
           Node : LDAP_Message;
           BER  : BER_Element) return String;
        --  Returns next attribute for iterator BER. First_Attribute must have been
        --  called to initialize this iterator.

        procedure Free (BER : BER_Element);
        --  Releases memory associated with the BER structure which has been
        --  allocated by the First_Attribute routine.

        generic
           with procedure Action
             (Attribute : String;
              Quit      : in out Boolean);
        procedure For_Every_Attribute
          (Dir  : Directory;
           Node : LDAP_Message);
        --  This iterator call action for each attribute found in the LDAP Entries
        --  Node as returned by First_Entry or Next_Entry. Quit can be set to True
        --  to stop iteration; its initial value is False.

        ---------------
        -- Accessors -
        ---------------

        function Get_DN
          (Dir  : Directory;
           Node : LDAP_Message) return String;
        --  Returns the distinguished name for the given entry Node

        function DN2UFN (DN : String) return String;
        --  Returns a distinguished name converted to a user-friendly format

        function Get_Values
          (Dir    : Directory;
           Node   : LDAP_Message;
           Target : String) return String_Set;
        --  Returns the list of values of a given attribute (Target) found in entry
        --  Node.

        function Explode_DN
          (DN       : String;
           No_Types : Boolean := True) return String_Set;
        --  Breaks up an entry name into its component parts. If No_Types is set to
        --  True the types information ("cn=") won't be included.

     private
        --  implementation removed
     end AWS.LDAP.Client;


File: aws.info,  Node: AWS.Log,  Next: AWS.Messages,  Prev: AWS.LDAP.Client,  Up: AWS API Reference

B.21 AWS.Log
============


     ------------------------------------------------------------------------------
     --                              Ada Web Server                              -
     --                                                                          -
     --                     Copyright (C) 2000-2012, AdaCore                     -
     --                                                                          -
     --  This library is free software;  you can redistribute it and/or modify   -
     --  it under terms of the  GNU General Public License  as published by the  -
     --  Free Software  Foundation;  either version 3,  or (at your  option) any -
     --  later version. This library is distributed in the hope that it will be  -
     --  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of -
     --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                    -
     --                                                                          -
     --  As a special exception under Section 7 of GPL version 3, you are        -
     --  granted additional permissions described in the GCC Runtime Library     -
     --  Exception, version 3.1, as published by the Free Software Foundation.   -
     --                                                                          -
     --  You should have received a copy of the GNU General Public License and   -
     --  a copy of the GCC Runtime Library Exception along with this program;    -
     --  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see   -
     --  <http://www.gnu.org/licenses/>.                                         -
     --                                                                          -
     --  As a special exception, if other files instantiate generics from this   -
     --  unit, or you link this unit with other files to produce an executable,  -
     --  this  unit  does not  by itself cause  the resulting executable to be   -
     --  covered by the GNU General Public License. This exception does not      -
     --  however invalidate any other reasons why the executable file  might be  -
     --  covered by the  GNU Public License.                                     -
     ------------------------------------------------------------------------------

     --  This package handle the logging facility for AWS. The log file is named
     --  '<progname>-Y-M-D.log' and is written by default in the directory where
     --  the server is launched, see configuration file.
     --
     --  Note that this package is used internally by AWS to log server requests
     --  but it can also be used by users to handle application's log.
     --
     --  This package is thread safe.

     with Ada.Finalization;
     with Ada.Strings.Unbounded;
     with Ada.Text_IO;

     with AWS.Containers.String_Vectors;
     with AWS.Headers;
     with AWS.Messages;
     with AWS.Response;
     with AWS.Status;

     private with Ada.Containers.Indefinite_Ordered_Maps;
     private with AWS.Utils;

     package AWS.Log is

        type Object is limited private;
        --  A log object. It must be activated by calling Start below

        type Callback is access procedure (Message : String);
        --  Access to a procedure that handles AWS access and/or error log data.
        --  If the access and/or error logs are started with a Callback procedure
        --  set, then AWS will no longer handle writing the log data to file, nor
        --  will it rotate or split the data. In short : If you set a Callback, it's
        --  up to you to handle these things.
        --  The raw log data generated by AWS is simply handed verbatim to the
        --  Callback procedure.

        type Split_Mode is (None, Each_Run, Daily, Monthly);
        --  It specifies when to create a new log file.
        --  None     : all log info gets accumulated into the same file.
        --  Each_Run : a new log file is created each time the server is started.
        --  Daily    : a new log file is created each day.
        --  Monthly  : a new log file is created each month.

        type Fields_Table is private;
        --  Type to keep record for Extended Log File Format

        Empty_Fields_Table : constant Fields_Table;

        Not_Specified : constant String;

        procedure Start
          (Log             : in out Object;
           Split           : Split_Mode := None;
           Size_Limit      : Natural    := 0;
           File_Directory  : String     := Not_Specified;
           Filename_Prefix : String     := Not_Specified;
           Auto_Flush      : Boolean    := False);
        --  Activate server's activity logging. Split indicate the way the log file
        --  should be created. If Size_Limit more than zero and size of log file
        --  become more than Size_Limit, log file would be splitted. Filename_Prefix
        --  is the log filename prefix. If it is not specified the default prefix is
        --  the program name. Set Auto_Flush to True if you want every write to the
        --  log to be flushed (not buffered). Auto_Flush should be set to True only
        --  for logs with few entries per second as the flush has a performance
        --  penalty.

        procedure Start
          (Log    : in out Object;
           Writer : Callback;
           Name   : String);
        --  Activate server's activity logging and send all log data to Callback.
        --  When the logging object is started with a Callback no splitting or size
        --  limits are imposed on the logging data. This will all have to be handled
        --  in the Callback.
        --  When a log is started with a Callback, all log data is passed verbatim
        --  to the Callback.
        --  The Name String is returned when the Filename function is called. This
        --  serves no other function than to label the Callback procedure.

        procedure Register_Field (Log : in out Object; Id : String);
        --  Register field to be written into extended log format

        procedure Set_Field
          (Log : Object; Data : in out Fields_Table; Id, Value : String);
        --  Set field value into the extended log record. Data could be used only
        --  in one task and with one log file. Different tasks could write own Data
        --  using the Write routine with Fields_Table parameter type.

        procedure Set_Header_Fields
          (Log    : Object;
           Data   : in out Fields_Table;
           Prefix : String;
           Header : AWS.Headers.List);
        --  Set header fields into extended log record.
        --  Name of the header fields would be <Prefix>(<Header_Name>).
        --  Prefix should be "cs" - Client to Server or "sc" - Server to Client.

        procedure Write (Log : in out Object; Data : in out Fields_Table);
        --  Write extended format record to log file and prepare record for the next
        --  data. It is not allowed to use same Fields_Table with different extended
        --  logs.

        procedure Write
          (Log          : in out Object;
           Connect_Stat : Status.Data;
           Answer       : Response.Data);
        --  Write log info if activated (i.e. Start routine above has been called)

        procedure Write
          (Log            : in out Object;
           Connect_Stat   : Status.Data;
           Status_Code    : Messages.Status_Code;
           Content_Length : Response.Content_Length_Type);
        --  Write log info if activated (i.e. Start routine above has been called).
        --  This version separated the Content_Length from Status.Data, this is
        --  required for example in the case of a user defined stream content. See
        --  AWS.Resources.Stream.

        procedure Write
          (Log          : in out Object;
           Connect_Stat : Status.Data;
           Data         : String);
        --  Write user's log info if activated.  (i.e. Start routine above has been
        --  called).

        procedure Write (Log : in out Object; Data : String);
        --  Write Data into the log file. This Data is unstructured, only a time
        --  tag prefix is prepended to Data. This routine is designed to be used
        --  for user's info in error log file.

        procedure Flush (Log : in out Object);
        --  Flush the data to the Log file, for be able to see last logged
        --  messages.
        --  If a Callback procedure is used to handle the log data, then calling
        --  Flush does nothing.

        procedure Stop (Log : in out Object);
        --  Stop logging activity

        function Is_Active (Log : Object) return Boolean;
        --  Returns True if Log is activated

        function Filename (Log : Object) return String;
        --  Returns current log filename or the empty string if the log is not
        --  activated.
        --  If a Callback is used to handle the log, then the name given in the
        --  Start procedure is returned. See the Start procedure for starting logs
        --  with a Callback.

        function Mode (Log : Object) return Split_Mode;
        --  Returns the split mode. None will be returned if log is not activated or
        --  a Callback procedure is used to handle the log data.

     private
        --  implementation removed
     end AWS.Log;


File: aws.info,  Node: AWS.Messages,  Next: AWS.MIME,  Prev: AWS.Log,  Up: AWS API Reference

B.22 AWS.Messages
=================


     ------------------------------------------------------------------------------
     --                              Ada Web Server                              -
     --                                                                          -
     --                     Copyright (C) 2000-2012, AdaCore                     -
     --                                                                          -
     --  This library is free software;  you can redistribute it and/or modify   -
     --  it under terms of the  GNU General Public License  as published by the  -
     --  Free Software  Foundation;  either version 3,  or (at your  option) any -
     --  later version. This library is distributed in the hope that it will be  -
     --  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of -
     --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                    -
     --                                                                          -
     --  As a special exception under Section 7 of GPL version 3, you are        -
     --  granted additional permissions described in the GCC Runtime Library     -
     --  Exception, version 3.1, as published by the Free Software Foundation.   -
     --                                                                          -
     --  You should have received a copy of the GNU General Public License and   -
     --  a copy of the GCC Runtime Library Exception along with this program;    -
     --  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see   -
     --  <http://www.gnu.org/licenses/>.                                         -
     --                                                                          -
     --  As a special exception, if other files instantiate generics from this   -
     --  unit, or you link this unit with other files to produce an executable,  -
     --  this  unit  does not  by itself cause  the resulting executable to be   -
     --  covered by the GNU General Public License. This exception does not      -
     --  however invalidate any other reasons why the executable file  might be  -
     --  covered by the  GNU Public License.                                     -
     ------------------------------------------------------------------------------

     with Ada.Calendar;
     with Ada.Streams;
     with Ada.Strings.Unbounded;

     package AWS.Messages is

        use Ada;
        use Ada.Streams;
        use Ada.Strings.Unbounded;

        -----------------
        -- HTTP tokens -
        -----------------

        HTTP_Token    : constant String := "HTTP/";
        Options_Token : constant String := "OPTIONS";
        Get_Token     : constant String := "GET";
        Head_Token    : constant String := "HEAD";
        Post_Token    : constant String := "POST";
        Put_Token     : constant String := "PUT";
        Delete_Token  : constant String := "DELETE";
        Trace_Token   : constant String := "TRACE";
        Connect_Token : constant String := "CONNECT";
        --  Sorted like in RFC 2616 Method definition

        ------------------------
        -- HTTP header tokens -
        ------------------------

        --  General header tokens RFC 2616
        Cache_Control_Token       : constant String := "Cache-Control";
        Connection_Token          : constant String := "Connection";
        Date_Token                : constant String := "Date";
        Pragma_Token              : constant String := "Pragma";
        Trailer_Token             : constant String := "Trailer";
        Transfer_Encoding_Token   : constant String := "Transfer-Encoding";
        Upgrade_Token             : constant String := "Upgrade";
        Via_Token                 : constant String := "Via";
        Warning_Token             : constant String := "Warning";

        --  Request header tokens RFC 2616
        Accept_Token              : constant String := "Accept";
        Accept_Charset_Token      : constant String := "Accept-Charset";
        Accept_Encoding_Token     : constant String := "Accept-Encoding";
        Accept_Language_Token     : constant String := "Accept-Language";
        Authorization_Token       : constant String := "Authorization";
        Expect_Token              : constant String := "Expect";
        From_Token                : constant String := "From";
        Host_Token                : constant String := "Host";
        If_Match_Token            : constant String := "If-Match";
        If_Modified_Since_Token   : constant String := "If-Modified-Since";
        If_None_Match_Token       : constant String := "If-None-Match";
        If_Range_Token            : constant String := "If-Range";
        If_Unmodified_Since_Token : constant String := "If-Unmodified-Since";
        Max_Forwards_Token        : constant String := "Max-Forwards";
        Proxy_Authorization_Token : constant String := "Proxy-Authorization";
        Range_Token               : constant String := "Range";
        Referer_Token             : constant String := "Referer";
        TE_Token                  : constant String := "TE";
        User_Agent_Token          : constant String := "User-Agent";

        --  Cross-Origin Resource Sharing request header tokens
        Access_Control_Request_Headers_Token : constant String
          := "Access-Control-Request-Headers";
        Access_Control_Request_Method_Token  : constant String
          := "Access-Control-Request-Method";
        Origin_Token                         : constant String := "Origin";

        --  Response header tokens RFC 2616
        Accept_Ranges_Token       : constant String := "Accept-Ranges";
        Age_Token                 : constant String := "Age";
        ETag_Token                : constant String := "ETag";
        Location_Token            : constant String := "Location";
        Proxy_Authenticate_Token  : constant String := "Proxy-Authenticate";
        Retry_After_Token         : constant String := "Retry-After";
        Server_Token              : constant String := "Server";
        Vary_Token                : constant String := "Vary";
        WWW_Authenticate_Token    : constant String := "WWW-Authenticate";

        --  Cross-Origin Resource Sharing response header tokens
        Access_Control_Allow_Credentials_Token : constant String
          := "Access-Control-Allow-Credentials";
        Access_Control_Allow_Headers_Token     : constant String
          := "Access-Control-Allow-Headers";
        Access_Control_Allow_Methods_Token     : constant String
          := "Access-Control-Allow-Methods";
        Access_Control_Allow_Origin_Token      : constant String
          := "Access-Control-Allow-Origin";
        Access_Control_Expose_Headers_Token    : constant String
          := "Access-Control-Expose-Headers";
        Access_Control_Max_Age_Token           : constant String
          := "Access-Control-Max-Age";

        --  Entity header tokens RFC 2616
        Allow_Token               : constant String := "Allow";
        Content_Encoding_Token    : constant String := "Content-Encoding";
        Content_Language_Token    : constant String := "Content-Language";
        Content_Length_Token      : constant String := "Content-Length";
        Content_Location_Token    : constant String := "Content-Location";
        Content_MD5_Token         : constant String := "Content-MD5";
        Content_Range_Token       : constant String := "Content-Range";
        Content_Type_Token        : constant String := "Content-Type";
        Expires_Token             : constant String := "Expires";
        Last_Modified_Token       : constant String := "Last-Modified";

        --  Cookie token RFC 2109
        Cookie_Token              : constant String := "Cookie";
        Set_Cookie_Token          : constant String := "Set-Cookie";
        Comment_Token             : constant String := "Comment";
        Domain_Token              : constant String := "Domain";
        Max_Age_Token             : constant String := "Max-Age";
        Path_Token                : constant String := "Path";
        Secure_Token              : constant String := "Secure";

        --  Other tokens
        Proxy_Connection_Token    : constant String := "Proxy-Connection";
        Content_Disposition_Token : constant String := "Content-Disposition";
        SOAPAction_Token          : constant String := "SOAPAction";
        Content_Id_Token          : constant String := "Content-ID";
        Content_Transfer_Encoding_Token : constant String
          := "Content-Transfer-Encoding";

        --  WebSockets tokens
        Websocket_Token              : constant String := "WebSocket";
        Sec_WebSocket_Accept_Token   : constant String := "Sec-WebSocket-Accept";
        Sec_WebSocket_Protocol_Token : constant String := "Sec-WebSocket-Protocol";
        Sec_WebSocket_Key_Token      : constant String := "Sec-WebSocket-Key";
        Sec_WebSocket_Key1_Token     : constant String := "Sec-WebSocket-Key1";
        Sec_WebSocket_Key2_Token     : constant String := "Sec-WebSocket-Key2";
        Sec_WebSocket_Version_Token  : constant String := "Sec-WebSocket-Version";
        Sec_WebSocket_Origin_Token   : constant String := "Sec-WebSocket-Origin";
        Sec_WebSocket_Location_Token : constant String := "Sec-WebSocket-Location";
        Chat_Token                   : constant String := "chat";

        S100_Continue : constant String := "100-continue";
        --  Supported expect header value

        -----------------
        -- Status Code -
        -----------------

        type Status_Code is
          (S100, S101, S102,
           --  1xx : Informational - Request received, continuing process

           S200, S201, S202, S203, S204, S205, S206, S207,
           --  2xx : Success - The action was successfully received, understood and
           --  accepted

           S300, S301, S302, S303, S304, S305, S307,
           --  3xx : Redirection - Further action must be taken in order to
           --  complete the request

           S400, S401, S402, S403, S404, S405, S406, S407, S408, S409,
           S410, S411, S412, S413, S414, S415, S416, S417, S422, S423, S424,
           --  4xx : Client Error - The request contains bad syntax or cannot be
           --  fulfilled

           S500, S501, S502, S503, S504, S505, S507
           --  5xx : Server Error - The server failed to fulfill an apparently
           --  valid request
           );

        subtype Informational is Status_Code range S100 .. S102;
        subtype Success       is Status_Code range S200 .. S207;
        subtype Redirection   is Status_Code range S300 .. S307;
        subtype Client_Error  is Status_Code range S400 .. S424;
        subtype Server_Error  is Status_Code range S500 .. S507;

        function Image (S : Status_Code) return String;
        --  Returns Status_Code image. This value does not contain the leading S

        function Reason_Phrase (S : Status_Code) return String;
        --  Returns the reason phrase for the status code S, see [RFC 2616 - 6.1.1]

        ----------------------
        -- Content encoding -
        ----------------------

        type Content_Encoding is (Identity, GZip, Deflate);
        --  Encoding mode for the response, Identity means that no encoding is
        --  done, Gzip/Deflate to select the Gzip or Deflate encoding algorithm.

        -------------------
        -- Cache_Control -
        -------------------

        type Cache_Option is new String;
        --  Cache_Option is a string and any specific option can be specified. We
        --  define four options:
        --
        --  Unspecified   : No cache option will used.
        --  No_Cache      : Ask browser and proxy to not cache data (no-cache,
        --                  max-age, and s-maxage are specified).
        --  No_Store      : Ask browser and proxy to not store any data. This can be
        --                  used to protect sensitive data.
        --  Prevent_Cache : Equivalent to No_Store + No_Cache

        Unspecified   : constant Cache_Option;
        No_Cache      : constant Cache_Option;
        No_Store      : constant Cache_Option;
        Prevent_Cache : constant Cache_Option;

        type Cache_Kind is (Request, Response);

        type Delta_Seconds is new Integer range -1 .. Integer'Last;
        --  Represents a delta-seconds parameter for some Cache_Data fields like
        --  max-age, max-stale (value -1 is used for Unset).

        Unset         : constant Delta_Seconds;
        No_Max_Stale  : constant Delta_Seconds;
        Any_Max_Stale : constant Delta_Seconds;

        type Private_Option is new Unbounded_String;

        All_Private   : constant Private_Option;
        Private_Unset : constant Private_Option;

        --  Cache_Data is a record that represents cache control information

        type Cache_Data (CKind : Cache_Kind) is record
           No_Cache       : Boolean       := False;
           No_Store       : Boolean       := False;
           No_Transform   : Boolean       := False;
           Max_Age        : Delta_Seconds := Unset;

           case CKind is
              when Request =>
                 Max_Stale      : Delta_Seconds := Unset;
                 Min_Fresh      : Delta_Seconds := Unset;
                 Only_If_Cached : Boolean       := False;

              when Response =>
                 S_Max_Age        : Delta_Seconds  := Unset;
                 Public           : Boolean        := False;
                 Private_Field    : Private_Option := Private_Unset;
                 Must_Revalidate  : Boolean        := False;
                 Proxy_Revalidate : Boolean        := False;
           end case;
        end record;

        function To_Cache_Option (Data : Cache_Data) return Cache_Option;
        --  Returns a cache control value for an HTTP request/response, fields are
        --  described into RFC 2616 [14.9 Cache-Control].

        function To_Cache_Data
          (Kind : Cache_Kind; Value : Cache_Option) return Cache_Data;
        --  Returns a Cache_Data record parsed out of Cache_Option

        ----------
        -- ETag -
        ----------

        type ETag_Value is new String;

        function Create_ETag
          (Name : String; Weak : Boolean := False) return ETag_Value;
        --  Returns an ETag value (strong by default and Weak if specified). For a
        --  discussion about ETag see RFC 2616 [3.11 Entity Tags] and [14.19 ETag].

        -------------------------------
        -- HTTP message constructors -
        -------------------------------

        function Accept_Encoding (Encoding : String) return String;
        pragma Inline (Accept_Encoding);

        function Accept_Type (Mode : String) return String;
        pragma Inline (Accept_Type);

        function Accept_Language (Mode : String) return String;
        pragma Inline (Accept_Language);

        function Authorization (Mode, Password : String) return String;
        pragma Inline (Authorization);

        function Connection (Mode : String) return String;
        pragma Inline (Connection);

        function Content_Length (Size : Stream_Element_Offset) return String;
        pragma Inline (Content_Length);

        function Cookie (Value : String) return String;
        pragma Inline (Cookie);

        function Content_Type
          (Format : String; Boundary : String := "") return String;
        pragma Inline (Content_Type);

        function Cache_Control (Option : Cache_Option) return String;
        pragma Inline (Cache_Control);

        function Cache_Control (Data : Cache_Data) return String;
        pragma Inline (Cache_Control);

        function Content_Disposition
          (Format, Name, Filename : String) return String;
        pragma Inline (Content_Disposition);
        --  Note that this is not part of HTTP/1.1 standard, it is there because
        --  there is a lot of implementation around using it. This header is used
        --  in multipart data.

        function ETag (Value : ETag_Value) return String;
        pragma Inline (ETag);

        function Expires (Date : Calendar.Time) return String;
        pragma Inline (Expires);
        --  The date should not be more than a year in the future, see RFC 2616
        --  [14.21 Expires].

        function Host (Name : String) return String;
        pragma Inline (Host);

        function Last_Modified (Date : Calendar.Time) return String;
        pragma Inline (Last_Modified);

        function Location (URL : String) return String;
        pragma Inline (Location);

        function Proxy_Authorization (Mode, Password : String) return String;
        pragma Inline (Proxy_Authorization);

        function Proxy_Connection (Mode : String) return String;
        pragma Inline (Proxy_Connection);

        function Data_Range (Value : String) return String;
        pragma Inline (Data_Range);

        function SOAPAction (URI : String) return String;
        pragma Inline (SOAPAction);

        function Status_Line (Code : Status_Code) return String;
        pragma Inline (Status_Line);

        function Transfer_Encoding (Encoding : String) return String;
        pragma Inline (Transfer_Encoding);

        function User_Agent (Name : String) return String;
        pragma Inline (User_Agent);

        function WWW_Authenticate (Realm : String) return String;
        pragma Inline (WWW_Authenticate);
        --  Basic authentication request

        function WWW_Authenticate
          (Realm, Nonce : String; Stale : Boolean) return String;
        pragma Inline (WWW_Authenticate);
        --  Digest authentication request

        function Sec_WebSocket_Accept (Key : String) return String;
        pragma Inline (Sec_WebSocket_Accept);

        -----------------------
        --  helper functions -
        -----------------------

        function To_HTTP_Date (Time : Calendar.Time) return String;
        --  Returns an Ada time as a string using the HTTP normalized format.
        --  Format is RFC 822, updated by RFC 1123.

        function To_Time (HTTP_Date : String) return Calendar.Time;
        --  Returns an Ada time from an HTTP one. This is To_HTTP_Date opposite
        --  function.

     private
        --  implementation removed
     end AWS.Messages;


File: aws.info,  Node: AWS.MIME,  Next: AWS.Net,  Prev: AWS.Messages,  Up: AWS API Reference

B.23 AWS.MIME
=============


     ------------------------------------------------------------------------------
     --                              Ada Web Server                              -
     --                                                                          -
     --                     Copyright (C) 2000-2012, AdaCore                     -
     --                                                                          -
     --  This library is free software;  you can redistribute it and/or modify   -
     --  it under terms of the  GNU General Public License  as published by the  -
     --  Free Software  Foundation;  either version 3,  or (at your  option) any -
     --  later version. This library is distributed in the hope that it will be  -
     --  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of -
     --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                    -
     --                                                                          -
     --  As a special exception under Section 7 of GPL version 3, you are        -
     --  granted additional permissions described in the GCC Runtime Library     -
     --  Exception, version 3.1, as published by the Free Software Foundation.   -
     --                                                                          -
     --  You should have received a copy of the GNU General Public License and   -
     --  a copy of the GCC Runtime Library Exception along with this program;    -
     --  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see   -
     --  <http://www.gnu.org/licenses/>.                                         -
     --                                                                          -
     --  As a special exception, if other files instantiate generics from this   -
     --  unit, or you link this unit with other files to produce an executable,  -
     --  this  unit  does not  by itself cause  the resulting executable to be   -
     --  covered by the GNU General Public License. This exception does not      -
     --  however invalidate any other reasons why the executable file  might be  -
     --  covered by the  GNU Public License.                                     -
     ------------------------------------------------------------------------------

     package AWS.MIME is

        --  Some content type constants. All of them will be defined into this
        --  package and associated with the right extensions. It is possible to
        --  add new MIME types with the routines below or by placing a file named
        --  aws.mime into the startup directory.
        --
        --  A MIME type is written in two parts: type/format

        ----------
        -- Text -
        ----------

        Text_CSS                    : constant String := "text/css";
        Text_Javascript             : constant String := "text/javascript";
        Text_HTML                   : constant String := "text/html";
        Text_Plain                  : constant String := "text/plain";
        Text_XML                    : constant String := "text/xml";
        Text_X_SGML                 : constant String := "text/x-sgml";

        -----------
        -- Image -
        -----------

        Image_Gif                   : constant String := "image/gif";
        Image_Jpeg                  : constant String := "image/jpeg";
        Image_Png                   : constant String := "image/png";
        Image_Tiff                  : constant String := "image/tiff";
        Image_Icon                  : constant String := "image/x-icon";
        Image_X_Portable_Anymap     : constant String := "image/x-portable-anymap";
        Image_X_Portable_Bitmap     : constant String := "image/x-portable-bitmap";
        Image_X_Portable_Graymap    : constant String := "image/x-portable-graymap";
        Image_X_Portable_Pixmap     : constant String := "image/x-portable-pixmap";
        Image_X_RGB                 : constant String := "image/x-rgb";
        Image_X_Xbitmap             : constant String := "image/x-xbitmap";
        Image_X_Xpixmap             : constant String := "image/x-xpixmap";
        Image_X_Xwindowdump         : constant String := "image/x-xwindowdump";

        -----------------
        -- Application -
        -----------------

        Application_Postscript      : constant String := "application/postscript";
        Application_Pdf             : constant String := "application/pdf";
        Application_Zip             : constant String := "application/zip";
        Application_Octet_Stream    : constant String := "application/octet-stream";
        Application_Form_Data       : constant String
          := "application/x-www-form-urlencoded";
        Application_Mac_Binhex40    : constant String := "application/mac-binhex40";
        Application_Msword          : constant String := "application/msword";
        Application_Powerpoint      : constant String := "application/powerpoint";
        Application_Rtf             : constant String := "application/rtf";
        Application_XML             : constant String := "application/xml";
        Application_X_Compress      : constant String := "application/x-compress";
        Application_X_GTar          : constant String := "application/x-gtar";
        Application_X_GZip          : constant String := "application/x-gzip";
        Application_X_Latex         : constant String := "application/x-latex";
        Application_X_Sh            : constant String := "application/x-sh";
        Application_X_Shar          : constant String := "application/x-shar";
        Application_X_Tar           : constant String := "application/x-tar";
        Application_X_Tcl           : constant String := "application/x-tcl";
        Application_X_Tex           : constant String := "application/x-tex";
        Application_X_Texinfo       : constant String := "application/x-texinfo";
        Application_X_Troff         : constant String := "application/x-troff";
        Application_X_Troff_Man     : constant String := "application/x-troff-man";

        -----------
        -- Audio -
        -----------

        Audio_Basic                 : constant String := "audio/basic";
        Audio_Mpeg                  : constant String := "audio/mpeg";
        Audio_X_Wav                 : constant String := "audio/x-wav";
        Audio_X_Pn_Realaudio        : constant String := "audio/x-pn-realaudio";
        Audio_X_Pn_Realaudio_Plugin : constant String
          := "audio/x-pn-realaudio-plugin";
        Audio_X_Realaudio           : constant String := "audio/x-realaudio";

        -----------
        -- Video -
        -----------

        Video_Mpeg                  : constant String := "video/mpeg";
        Video_Quicktime             : constant String := "video/quicktime";
        Video_X_Msvideo             : constant String := "video/x-msvideo";

        ---------------
        -- Multipart -
        ---------------

        Multipart_Form_Data         : constant String := "multipart/form-data";
        Multipart_Byteranges        : constant String := "multipart/byteranges";
        Multipart_Related           : constant String := "multipart/related";
        Multipart_X_Mixed_Replace   : constant String
          := "multipart/x-mixed-replace";

        -------------
        -- Setting -
        -------------

        procedure Add_Extension (Ext : String; MIME_Type : String);
        --  Add extension Ext (file extension without the dot, e.g. "txt") to the
        --  set of MIME type extension handled by this API. Ext will be mapped to
        --  the MIME_Type string.

        procedure Add_Regexp (Filename : String; MIME_Type : String);
        --  Add a specific rule to the MIME type table. Filename is a regular
        --  expression and will be mapped to the MIME_Type string.

        ---------------
        -- MIME Type -
        ---------------

        function Content_Type
           (Filename : String;
            Default  : String := Application_Octet_Stream) return String;
        --  Returns the MIME Content Type based on filename's extension or if not
        --  found the MIME Content type where Filename matches one of the specific
        --  rules set by Add_Regexp (see below).
        --  Returns Default if the file type is unknown (i.e. no extension and
        --  no regular expression match filename).

        function Extension (Content_Type : String) return String;
        --  Returns the best guess of the extension to use for the Content Type.
        --  Note that extensions added indirectly by Add_Regexp are not searched.

        function Is_Text (MIME_Type : String) return Boolean;
        --  Returns True if the MIME_Type is a text data

        function Is_Audio (MIME_Type : String) return Boolean;
        --  Returns True if the MIME_Type is an audio data

        function Is_Image (MIME_Type : String) return Boolean;
        --  Returns True if the MIME_Type is an image data

        function Is_Video (MIME_Type : String) return Boolean;
        --  Returns True if the MIME_Type is a video data

        function Is_Application (MIME_Type : String) return Boolean;
        --  Returns True if the MIME_Type is an application data

        procedure Load (MIME_File : String);
        --  Load MIME_File, record every MIME type. Note that the format of this
        --  file follows the common standard format used by Apache mime.types.

     end AWS.MIME;


File: aws.info,  Node: AWS.Net,  Next: AWS.Net.Buffered,  Prev: AWS.MIME,  Up: AWS API Reference

B.24 AWS.Net
============


     ------------------------------------------------------------------------------
     --                              Ada Web Server                              -
     --                                                                          -
     --                     Copyright (C) 2000-2012, AdaCore                     -
     --                                                                          -
     --  This library is free software;  you can redistribute it and/or modify   -
     --  it under terms of the  GNU General Public License  as published by the  -
     --  Free Software  Foundation;  either version 3,  or (at your  option) any -
     --  later version. This library is distributed in the hope that it will be  -
     --  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of -
     --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                    -
     --                                                                          -
     --  As a special exception under Section 7 of GPL version 3, you are        -
     --  granted additional permissions described in the GCC Runtime Library     -
     --  Exception, version 3.1, as published by the Free Software Foundation.   -
     --                                                                          -
     --  You should have received a copy of the GNU General Public License and   -
     --  a copy of the GCC Runtime Library Exception along with this program;    -
     --  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see   -
     --  <http://www.gnu.org/licenses/>.                                         -
     --                                                                          -
     --  As a special exception, if other files instantiate generics from this   -
     --  unit, or you link this unit with other files to produce an executable,  -
     --  this  unit  does not  by itself cause  the resulting executable to be   -
     --  covered by the GNU General Public License. This exception does not      -
     --  however invalidate any other reasons why the executable file  might be  -
     --  covered by the  GNU Public License.                                     -
     ------------------------------------------------------------------------------

     --  There is two implementations for this spec. One for standard sockets and
     --  one for SSL socket. Note that the SSL implementation does support standard
     --  socket too, this is controlled with the Security boolean on rountine
     --  below. The corresponding implementation will be selected at build time.

     with Ada.Exceptions;
     with Ada.Finalization;
     with Ada.Streams;

     with AWS.Utils;

     package AWS.Net is

        use Ada;
        use Ada.Exceptions;
        use Ada.Streams;

        Socket_Error : exception;
        --  Raised by all routines below, a message will indicate the nature of
        --  the error.

        type Socket_Type is abstract new Finalization.Controlled with private;
        type Socket_Access is access all Socket_Type'Class;

        type Socket_Set is array (Positive range <>) of Socket_Access;

        subtype FD_Type is Integer;
        --  Represents an external socket file descriptor

        type FD_Set (Size : Natural) is abstract tagged private;
        --  Abstract type for waiting of network events on group of sockets FD

        type Event_Type is (Error, Input, Output);
        --  Error  - socket is in error state.
        --  Input  - socket ready for read.
        --  Output - socket available for write.

        type Event_Set is array (Event_Type) of Boolean;
        --  Type for get result of events waiting

        subtype Wait_Event_Type is Event_Type range Input .. Output;
        type Wait_Event_Set is array (Wait_Event_Type) of Boolean;
        --  Type for set events to wait, note that Error event would be waited
        --  anyway.

        type Family_Type is (Family_Inet, Family_Inet6, Family_Unspec);

        type Shutmode_Type is (Shut_Read, Shut_Write, Shut_Read_Write);

        Forever : constant Duration;
        --  The longest delay possible on the implementation

        ----------------
        -- Initialize -
        ----------------

        function Socket (Security : Boolean) return Socket_Type'Class;
        --  Create an uninitialized socket

        function Socket (Security : Boolean) return Socket_Access;
        --  Create a dynamically allocated uninitialized socket

        procedure Bind
          (Socket        : in out Socket_Type;
           Port          : Natural;
           Host          : String      := "";
           Reuse_Address : Boolean     := False;
           Family        : Family_Type := Family_Unspec) is abstract;
        --  Create the server socket and bind it on the given port.
        --  Using 0 for the port will tell the OS to allocate a non-privileged
        --  free port. The port can be later retrieved using Get_Port on the
        --  bound socket.

        procedure Listen
          (Socket : Socket_Type; Queue_Size : Positive := 5) is abstract;
        --  Set the queue size of the socket

        procedure Accept_Socket
          (Socket : Socket_Type'Class; New_Socket : in out Socket_Type) is abstract;
        --  Accept a connection on a socket. If it raises Socket_Error, all
        --  resources used by new_Socket have been released.
        --  There is not need to call Free or Shutdown.

        type Socket_Constructor is access
          function (Security : Boolean) return Socket_Type'Class;

        procedure Connect
          (Socket : in out Socket_Type;
           Host   : String;
           Port   : Positive;
           Wait   : Boolean     := True;
           Family : Family_Type := Family_Unspec) is abstract;
        --  Connect a socket on a given host/port. If Wait is True Connect will wait
        --  for the connection to be established for timeout seconds, specified by
        --  Set_Timeout routine. If Wait is False Connect will return immediately,
        --  not waiting for the connection to be establised. It is possible to wait
        --  for the Connection completion by calling Wait routine with Output set to
        --  True in Events parameter.

        procedure Socket_Pair (S1, S2 : out Socket_Type);
        --  Create 2 sockets and connect them together

        procedure Shutdown
          (Socket : Socket_Type;
           How    : Shutmode_Type := Shut_Read_Write) is abstract;
        --  Shutdown the read, write or both side of the socket.
        --  If How is Both, close it. Does not raise Socket_Error if the socket is
        --  not connected or already shutdown.

        procedure Free (Socket : in out Socket_Access);
        --  Release memory associated with the socket

        --------
        -- IO -
        --------

        procedure Send
          (Socket : Socket_Type'Class; Data : Stream_Element_Array);
        --  Send Data chunk to the socket

        procedure Send
          (Socket : Socket_Type;
           Data   : Stream_Element_Array;
           Last   : out Stream_Element_Offset) is abstract;
        --  Try to place data to Socket's output buffer. If all data cannot be
        --  placed to the socket output buffer, Last will be lower than Data'Last,
        --  if no data has been placed into the output buffer, Last is set to
        --  Data'First - 1. If Data'First is equal to Stream_Element_Offset'First
        --  then constraint error is raised to follow advice in AI95-227.

        procedure Receive
          (Socket : Socket_Type;
           Data   : out Stream_Element_Array;
           Last   : out Stream_Element_Offset) is abstract;
        --  Read a chunk of data from the socket and set appropriate Last value.
        --  This call always returns some data and will wait for incoming data only
        --  if necessary.

        function Receive
          (Socket : Socket_Type'Class;
           Max    : Stream_Element_Count := 4096) return Stream_Element_Array;
        --  Read a chunk of data from the socket and returns it. This call always
        --  returns some data and will wait for incoming data only if necessary.

        function Pending (Socket : Socket_Type) return Stream_Element_Count
           is abstract;
        --  Returns the number of bytes which are available inside socket
        --  for immediate read.

        ------------
        -- Others -
        ------------

        function Get_FD (Socket : Socket_Type) return FD_Type is abstract;
        --  Returns the file descriptor associated with the socket

        function Peer_Addr (Socket : Socket_Type) return String is abstract;
        --  Returns the peer name/address

        function Peer_Port (Socket : Socket_Type) return Positive is abstract;
        --  Returns the port of the peer socket

        function Get_Addr (Socket : Socket_Type) return String is abstract;
        --  Returns the name/address of the socket

        function Get_Port (Socket : Socket_Type) return Positive is abstract;
        --  Returns the port of the socket

        function Is_Any_Address (Socket : Socket_Type) return Boolean;
        --  Return true if the socket accepts connections on any of the hosts's
        --  network addresses.

        function Is_IPv6 (Socket : Socket_Type) return Boolean;

        function Is_Listening (Socket : Socket_Type) return Boolean;
        --  Returns true if the socket has been marked to accept connections with
        --  listen.

        function IPv6_Available return Boolean;
        --  Returns True if IPv6 available in OS and in AWS socket implementation

        function Host_Name return String;
        --  Returns the running host name

        procedure Set_Send_Buffer_Size
          (Socket : Socket_Type; Size : Natural) is abstract;
        --  Set the internal socket send buffer size.
        --  Do not confuse with buffers for the AWS.Net.Buffered operations.

        procedure Set_Receive_Buffer_Size
          (Socket : Socket_Type; Size : Natural) is abstract;
        --  Set the internal socket receive buffer size.
        --  Do not confuse with buffers for the AWS.Net.Buffered operations.

        function Get_Send_Buffer_Size (Socket : Socket_Type) return Natural
           is abstract;
        --  Returns the internal socket send buffer size.
        --  Do not confuse with buffers for the AWS.Net.Buffered operations.

        function Get_Receive_Buffer_Size (Socket : Socket_Type) return Natural
           is abstract;
        --  Returns the internal socket receive buffer size.
        --  Do not confuse with buffers for the AWS.Net.Buffered operations.

        procedure Set_Blocking_Mode
          (Socket : in out Socket_Type; Blocking : Boolean);
        pragma Obsolescent ("Use Set_Timeout instead");
        --  Set the blocking mode for the socket

        procedure Set_Timeout (Socket : in out Socket_Type; Timeout : Duration);
        pragma Inline (Set_Timeout);
        --  Sets the timeout for the socket read/write operations

        procedure Set_No_Delay
          (Socket : Socket_Type; Value : Boolean := True) is null;
        --  Set/clear TCP_NODELAY option on socket

        function Wait
          (Socket : Socket_Type'Class;
           Events : Wait_Event_Set) return Event_Set;
        --  Waiting for Input/Output/Error events.
        --  Waiting time is defined by Set_Timeout.
        --  Empty event set in result mean that timeout occured.

        function Check
          (Socket : Socket_Type'Class;
           Events : Wait_Event_Set) return Event_Set;
        --  Check for Input/Output/Error events availability.
        --  No wait for socket timeout.

        function Poll
          (Socket  : Socket_Type'Class;
           Events  : Wait_Event_Set;
           Timeout : Duration) return Event_Set;
        --  Wait events on socket descriptor for specified Timeout

        function Errno (Socket : Socket_Type) return Integer is abstract;
        --  Returns and clears error state in socket

        function Is_Timeout
          (Socket : Socket_Type;
           E      : Exception_Occurrence) return Boolean;
        --  Returns True if the message associated with the Exception_Occurence for
        --  a Socket_Error is a timeout.

        function Is_Timeout (E : Exception_Occurrence) return Boolean;
        --  As above but without Socket parameter

        function Is_Peer_Closed
          (Socket : Socket_Type;
           E      : Exception_Occurrence) return Boolean;
        --  Returns True if the message associated with the Exception_Occurence for
        --  a Socket_Error is a "socket closed by peer".

        function To_FD_Set
          (Socket : Socket_Type;
           Events : Wait_Event_Set;
           Size   : Positive := 1) return FD_Set'Class;
        --  Create appropriate socket FD set and put Socket fd there

        --------------------
        -- Socket FD sets -
        --------------------

        type FD_Set_Access is access all FD_Set'Class;

        procedure Add
          (FD_Set : in out FD_Set_Access;
           FD     : FD_Type;
           Event  : Wait_Event_Set);
        --  Add FD to the end of FD_Set

        procedure Free (FD_Set : in out FD_Set_Access);
        pragma Inline (Free);
        --  Deallocate the socket FD set

        procedure Add
          (FD_Set : in out Net.FD_Set;
           FD     : FD_Type;
           Event  : Wait_Event_Set) is abstract;
        --  Add FD to the end of FD_Set

        procedure Replace
          (FD_Set : in out Net.FD_Set;
           Index  : Positive;
           FD     : FD_Type) is abstract;
        --  Replaces the socket FD in FD_Set

        procedure Set_Mode
          (FD_Set : in out Net.FD_Set;
           Index  : Positive;
           Mode   : Wait_Event_Set) is abstract;
        --  Sets the kind of network events to wait for

        function Copy
          (FD_Set : not null access Net.FD_Set;
           Size   : Natural) return FD_Set_Access is abstract;
        --  Allocates and copy the given FD_Set with different size

        procedure Remove
          (FD_Set : in out Net.FD_Set; Index : Positive) is abstract;
        --  Removes socket FD from Index position.
        --  Last socket FD in FD_Set is placed at position Index.

        function Length (FD_Set : Net.FD_Set) return Natural is abstract;
        --  Returns number of socket FD elements in FD_Set

        procedure Wait
          (FD_Set  : in out Net.FD_Set;
           Timeout : Duration;
           Count   : out Natural) is abstract;
        --  Wait for network events on the sockets FD set. Count value is the
        --  number of socket FDs with non empty event set.

        procedure Next
          (FD_Set : Net.FD_Set; Index : in out Positive) is abstract;
        --  Looking for an active (for which an event has been detected by routine
        --  Wait above) socket FD starting from Index and return Index of the found
        --  active socket FD. Use functions Status to retreive the kind of network
        --  events for this socket.

        function Status
          (FD_Set : Net.FD_Set;
           Index  : Positive) return Event_Set is abstract;
        --  Returns events for the socket FD at position Index

        procedure Free (Socket : in out Socket_Type) is null;
        --  Release memory associated with the socket object. This default version
        --  can be overriden to properly release the memory for the derived
        --  implementation. The controlled Finalize routine is in charge of calling
        --  Free. We could not have it in the private part because we could not make
        --  AWS.Net.SSL.Free overriding this way.

        function Localhost (IPv6 : Boolean) return String;
        --  Returns "::1" if IPv6 is true or "127.0.0.1" otherwise

     private
        --  implementation removed
     end AWS.Net;


File: aws.info,  Node: AWS.Net.Buffered,  Next: AWS.Net.Log,  Prev: AWS.Net,  Up: AWS API Reference

B.25 AWS.Net.Buffered
=====================


     ------------------------------------------------------------------------------
     --                              Ada Web Server                              -
     --                                                                          -
     --                     Copyright (C) 2002-2012, AdaCore                     -
     --                                                                          -
     --  This library is free software;  you can redistribute it and/or modify   -
     --  it under terms of the  GNU General Public License  as published by the  -
     --  Free Software  Foundation;  either version 3,  or (at your  option) any -
     --  later version. This library is distributed in the hope that it will be  -
     --  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of -
     --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                    -
     --                                                                          -
     --  As a special exception under Section 7 of GPL version 3, you are        -
     --  granted additional permissions described in the GCC Runtime Library     -
     --  Exception, version 3.1, as published by the Free Software Foundation.   -
     --                                                                          -
     --  You should have received a copy of the GNU General Public License and   -
     --  a copy of the GCC Runtime Library Exception along with this program;    -
     --  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see   -
     --  <http://www.gnu.org/licenses/>.                                         -
     --                                                                          -
     --  As a special exception, if other files instantiate generics from this   -
     --  unit, or you link this unit with other files to produce an executable,  -
     --  this  unit  does not  by itself cause  the resulting executable to be   -
     --  covered by the GNU General Public License. This exception does not      -
     --  however invalidate any other reasons why the executable file  might be  -
     --  covered by the  GNU Public License.                                     -
     ------------------------------------------------------------------------------

     --  All routines below are buffered both ways (input and output) for better
     --  performances.

     package AWS.Net.Buffered is

        ------------
        -- Output -
        ------------

        procedure Put (Socket : Socket_Type'Class; Item : String);
        --  Write Item into Socket's buffer. Send the buffer to the socket if full

        procedure Put_Line (Socket : Socket_Type'Class; Item : String);
        --  Write Item & CRLF into Socket's buffer. Send the buffer to the socket
        --  if full.

        procedure New_Line (Socket : Socket_Type'Class);
        pragma Inline (New_Line);
        --  Write CRLF into Socket's buffer. Send the buffer to the socket if full

        procedure Write
          (Socket : Socket_Type'Class; Item : Stream_Element_Array);
        --  Write Item into Socket's buffer. Send the buffer to the socket if full

        procedure Flush (Socket : Socket_Type'Class);
        --  Send the buffer to the socket

        -----------
        -- Input -
        -----------

        Data_Overflow : exception;
        --  Raised from Get_Line and Read_Until routines when size of receiving data
        --  exceeds the limit defined by Set_Input_Limit. It avoid unlimited dynamic
        --  memory allocation inside of Get_Line and Read_Until when client trying
        --  to attack the server by the very long lines in request. Moreover it
        --  avoid stack overflow on very long data returned from Get_Line and
        --  Read_Until.

        procedure Set_Input_Limit (Limit : Positive);
        pragma Inline (Set_Input_Limit);
        --  Set the input size limit for Get_Line and Read_Until routines

        function Get_Input_Limit return Stream_Element_Offset;
        pragma Inline (Get_Input_Limit);
        --  Get the input size limit for Get_Line and Read_Until routines

        procedure Read
          (Socket : Socket_Type'Class; Data : out Stream_Element_Array);
        pragma Inline (Read);
        --  Returns Data array read from the socket

        function Read
          (Socket : Socket_Type'Class;
           Max    : Stream_Element_Count := 4096) return Stream_Element_Array;
        pragma Inline (Read);
        --  Returns an array of bytes read from the socket

        procedure Read
          (Socket : Socket_Type'Class;
           Data   : out Stream_Element_Array;
           Last   : out Stream_Element_Offset);
        --  Read any available data from buffered socket.
        --  Wait if no data available.
        --  Same semantic with Net.Receive procedure.

        function Get_Line (Socket : Socket_Type'Class) return String;
        --  Returns a line read from Socket. A line is a set of character
        --  terminated by CRLF.

        function Get_Char (Socket : Socket_Type'Class) return Character;
        pragma Inline (Get_Char);
        --  Returns a single character read from socket

        function Peek_Char (Socket : Socket_Type'Class) return Character;
        pragma Inline (Peek_Char);
        --  Returns next character that will be read from Socket. It does not
        --  actually consume the character, this character will be returned by
        --  the next read operation on the socket.

        procedure Read_Buffer
          (Socket : Socket_Type'Class;
           Data   : out Stream_Element_Array;
           Last   : out Stream_Element_Offset);
        --  Returns data read from the internal socket's read buffer. No data are
        --  read from the socket. This can be useful when switching to non buffered
        --  mode.

        function Read_Until
          (Socket    : Socket_Type'Class;
           Delimiter : Stream_Element_Array;
           Wait      : Boolean := True) return Stream_Element_Array;
        --  Read data on the Socket until the delimiter (including the delimiter).
        --  If Wait is False the routine looking for the delimiter only in the
        --  cache buffer, if delimiter not found in the cache buffer, empty array
        --  is be returned.
        --  If returned data is without delimiter at the end, it means that socket
        --  is closed from peer or socket error occured and rest of data returned.

        function Read_Until
          (Socket    : Socket_Type'Class;
           Delimiter : String;
           Wait      : Boolean := True) return String;
        --  Same as above but returning a standard string

        -------------
        -- Control -
        -------------

        procedure Shutdown (Socket : Socket_Type'Class);
        --  Shutdown and close the socket. Release all memory and resources
        --  associated with it.

     end AWS.Net.Buffered;


File: aws.info,  Node: AWS.Net.Log,  Next: AWS.Net.Log.Callbacks,  Prev: AWS.Net.Buffered,  Up: AWS API Reference

B.26 AWS.Net.Log
================


     ------------------------------------------------------------------------------
     --                              Ada Web Server                              -
     --                                                                          -
     --                     Copyright (C) 2004-2012, AdaCore                     -
     --                                                                          -
     --  This library is free software;  you can redistribute it and/or modify   -
     --  it under terms of the  GNU General Public License  as published by the  -
     --  Free Software  Foundation;  either version 3,  or (at your  option) any -
     --  later version. This library is distributed in the hope that it will be  -
     --  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of -
     --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                    -
     --                                                                          -
     --  As a special exception under Section 7 of GPL version 3, you are        -
     --  granted additional permissions described in the GCC Runtime Library     -
     --  Exception, version 3.1, as published by the Free Software Foundation.   -
     --                                                                          -
     --  You should have received a copy of the GNU General Public License and   -
     --  a copy of the GCC Runtime Library Exception along with this program;    -
     --  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see   -
     --  <http://www.gnu.org/licenses/>.                                         -
     --                                                                          -
     --  As a special exception, if other files instantiate generics from this   -
     --  unit, or you link this unit with other files to produce an executable,  -
     --  this  unit  does not  by itself cause  the resulting executable to be   -
     --  covered by the GNU General Public License. This exception does not      -
     --  however invalidate any other reasons why the executable file  might be  -
     --  covered by the  GNU Public License.                                     -
     ------------------------------------------------------------------------------

     --  This package handles the Net logging facility for AWS.
     --
     --  AWS calls the Write procedure which in turn calls the callback routine
     --  provided by the user when starting the logging. This feature can help
     --  greatly to debug an application.
     --
     --  This package is thread safe. There will never be two simultaneous calls
     --  to the callback routine.

     package AWS.Net.Log is

        type Data_Direction is (Sent, Received);
        --  The direction of the data, sent or received to/from the socket

        type Event_Type is (Connect, Accept_Socket, Shutdown);

        type Write_Callback is access procedure
          (Direction : Data_Direction;
           Socket    : Socket_Type'Class;
           Data      : Stream_Element_Array;
           Last      : Stream_Element_Offset);
        --  The callback procedure which is called for each incoming/outgoing data

        type Event_Callback is access procedure
          (Action : Event_Type; Socket : Socket_Type'Class);
        --  The callback procedure which is called for every socket creation,
        --  connect and accept.

        type Error_Callback is access procedure
          (Socket : Socket_Type'Class; Message : String);
        --  The callback procedure which is called for every socket error

        procedure Start
          (Write : Write_Callback;
           Event : Event_Callback := null;
           Error : Error_Callback := null);
        --  Activate the logging

        function Is_Active return Boolean;
        pragma Inline (Is_Active);
        --  Returns True if Log is activated and False otherwise

        function Is_Write_Active return Boolean;
        pragma Inline (Is_Write_Active);
        --  Returns True if Write Log is activated and False otherwise

        function Is_Event_Active return Boolean;
        pragma Inline (Is_Event_Active);
        --  Returns True if Event Log is activated and False otherwise

        procedure Write
          (Direction : Data_Direction;
           Socket    : Socket_Type'Class;
           Data      : Stream_Element_Array;
           Last      : Stream_Element_Offset);
        --  Write sent/received data indirectly through the callback routine,
        --  if activated (i.e. Start routine above has been called). Otherwise this
        --  call does nothing.

        procedure Event (Action : Event_Type; Socket : Socket_Type'Class);
        --  Call Event callback if activated (i.e. Start routine above has been
        --  called). Otherwise this call does nothing.

        procedure Error (Socket : Socket_Type'Class; Message : String);
        --  Call Error callback if activated (i.e. Start routine above has been
        --  called). Otherwise this call does nothing.

        procedure Stop;
        --  Stop logging activity

     end AWS.Net.Log;


File: aws.info,  Node: AWS.Net.Log.Callbacks,  Next: AWS.Net.SSL,  Prev: AWS.Net.Log,  Up: AWS API Reference

B.27 AWS.Net.Log.Callbacks
==========================


     ------------------------------------------------------------------------------
     --                              Ada Web Server                              -
     --                                                                          -
     --                     Copyright (C) 2004-2012, AdaCore                     -
     --                                                                          -
     --  This library is free software;  you can redistribute it and/or modify   -
     --  it under terms of the  GNU General Public License  as published by the  -
     --  Free Software  Foundation;  either version 3,  or (at your  option) any -
     --  later version. This library is distributed in the hope that it will be  -
     --  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of -
     --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                    -
     --                                                                          -
     --  As a special exception under Section 7 of GPL version 3, you are        -
     --  granted additional permissions described in the GCC Runtime Library     -
     --  Exception, version 3.1, as published by the Free Software Foundation.   -
     --                                                                          -
     --  You should have received a copy of the GNU General Public License and   -
     --  a copy of the GCC Runtime Library Exception along with this program;    -
     --  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see   -
     --  <http://www.gnu.org/licenses/>.                                         -
     --                                                                          -
     --  As a special exception, if other files instantiate generics from this   -
     --  unit, or you link this unit with other files to produce an executable,  -
     --  this  unit  does not  by itself cause  the resulting executable to be   -
     --  covered by the GNU General Public License. This exception does not      -
     --  however invalidate any other reasons why the executable file  might be  -
     --  covered by the  GNU Public License.                                     -
     ------------------------------------------------------------------------------

     --  Some ready to use write procedures

     package AWS.Net.Log.Callbacks is

        procedure Initialize
          (Filename : String;
           Callback : Write_Callback);
        --  Initialize the logging, must be called before using the callbacks below

        procedure Finalize;
        --  Stop logging, close log file

        procedure Text
          (Direction : Data_Direction;
           Socket    : Socket_Type'Class;
           Data      : Stream_Element_Array;
           Last      : Stream_Element_Offset);
        --  A text output, each chunk is output with an header and footer:
        --     Data sent/received to/from socket <FD> (<size>/<buffer size>)
        --     <data>
        --     Total data sent: <nnn> received: <nnn>

        procedure Binary
          (Direction : Data_Direction;
           Socket    : Socket_Type'Class;
           Data      : Stream_Element_Array;
           Last      : Stream_Element_Offset);
        --  A binary output, each chunk is output with an header and footer. The
        --  data itself is written using a format close to the Emacs hexl-mode:
        --     Data sent/received to/from socket <FD> (<size>/<buffer size>)
        --     HH HH HH HH HH HH HH HH HH HH HH HH   az.rt.mpl..q
        --     Total data sent: <nnn> received: <nnn>
        --
        --  HH is the hex character number, if the character is not printable a dot
        --  is written.

     end AWS.Net.Log.Callbacks;


File: aws.info,  Node: AWS.Net.SSL,  Next: AWS.Net.SSL.Certificate,  Prev: AWS.Net.Log.Callbacks,  Up: AWS API Reference

B.28 AWS.Net.SSL
================


     ------------------------------------------------------------------------------
     --                              Ada Web Server                              -
     --                                                                          -
     --                     Copyright (C) 2002-2012, AdaCore                     -
     --                                                                          -
     --  This library is free software;  you can redistribute it and/or modify   -
     --  it under terms of the  GNU General Public License  as published by the  -
     --  Free Software  Foundation;  either version 3,  or (at your  option) any -
     --  later version. This library is distributed in the hope that it will be  -
     --  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of -
     --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                    -
     --                                                                          -
     --  As a special exception under Section 7 of GPL version 3, you are        -
     --  granted additional permissions described in the GCC Runtime Library     -
     --  Exception, version 3.1, as published by the Free Software Foundation.   -
     --                                                                          -
     --  You should have received a copy of the GNU General Public License and   -
     --  a copy of the GCC Runtime Library Exception along with this program;    -
     --  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see   -
     --  <http://www.gnu.org/licenses/>.                                         -
     --                                                                          -
     --  As a special exception, if other files instantiate generics from this   -
     --  unit, or you link this unit with other files to produce an executable,  -
     --  this  unit  does not  by itself cause  the resulting executable to be   -
     --  covered by the GNU General Public License. This exception does not      -
     --  however invalidate any other reasons why the executable file  might be  -
     --  covered by the  GNU Public License.                                     -
     ------------------------------------------------------------------------------

     --  This is the SSL based implementation of the Net package. The implementation
     --  should depend only on AWS.Net.Std and the SSL library. It is important to
     --  not call directly a socket binding here to ease porting.

     with System;

     with AWS.Net.Std;
     with SSL.Thin;

     package AWS.Net.SSL is

        Socket_Error : exception renames Net.Socket_Error;

        type Socket_Type is new Net.Std.Socket_Type with private;

        Is_Supported : constant Boolean;
        --  True if SSL supported in the current runtime

        ----------------
        -- Initialize -
        ----------------

        overriding procedure Accept_Socket
          (Socket : Net.Socket_Type'Class; New_Socket : in out Socket_Type);
        --  Accept a connection on a socket

        overriding procedure Connect
          (Socket : in out Socket_Type;
           Host   : String;
           Port   : Positive;
           Wait   : Boolean     := True;
           Family : Family_Type := Family_Unspec);
        --  Connect a socket on a given host/port. If Wait is True Connect will wait
        --  for the connection to be established for timeout seconds, specified by
        --  Set_Timeout routine. If Wait is False Connect will return immediately,
        --  not waiting for the connection to be establised and it does not make the
        --  SSL handshake. It is possible to wait for the Connection completion by
        --  calling Wait routine with Output set to True in Events parameter.

        overriding procedure Socket_Pair (S1, S2 : out Socket_Type);
        --  Create 2 sockets and connect them together

        overriding procedure Shutdown
          (Socket : Socket_Type; How : Shutmode_Type := Shut_Read_Write);
        --  Shutdown the read, write or both side of the socket.
        --  If How is Both, close it. Does not raise Socket_Error if the socket is
        --  not connected or already shutdown.

        --------
        -- IO -
        --------

        overriding procedure Send
          (Socket : Socket_Type;
           Data   : Stream_Element_Array;
           Last   : out Stream_Element_Offset);

        overriding procedure Receive
          (Socket : Socket_Type;
           Data   : out Stream_Element_Array;
           Last   : out Stream_Element_Offset);
        pragma Inline (Receive);

        overriding function Pending
          (Socket : Socket_Type) return Stream_Element_Count;
        --  Returns the number of bytes which are available inside socket
        --  for immediate read.

        --------------------
        -- Initialization -
        --------------------

        type Method is
          (SSLv23, SSLv23_Server, SSLv23_Client,
           TLSv1,  TLSv1_Server,  TLSv1_Client,
           SSLv3,  SSLv3_Server,  SSLv3_Client);

        type Config is private;

        Null_Config : constant Config;

        procedure Initialize
          (Config               : in out SSL.Config;
           Certificate_Filename : String;
           Security_Mode        : Method     := SSLv23;
           Key_Filename         : String     := "";
           Exchange_Certificate : Boolean    := False;
           Certificate_Required : Boolean    := False;
           Trusted_CA_Filename  : String     := "";
           CRL_Filename         : String     := "";
           Session_Cache_Size   : Positive   := 16#4000#);
        --  Initialize the SSL layer into Config. Certificate_Filename must point
        --  to a valid certificate. Security mode can be used to change the
        --  security method used by AWS. Key_Filename must be specified if the key
        --  is not in the same file as the certificate. The Config object can be
        --  associated with all secure sockets sharing the same options. If
        --  Exchange_Certificate is True the client will send it's certificate to
        --  the server, if False only the server will send its certificate.

        procedure Release (Config : in out SSL.Config);
        --  Release memory associated with the Config object

        procedure Set_Config
          (Socket : in out Socket_Type; Config : SSL.Config);
        --  Set the SSL configuration object for the secure socket

        function Secure_Client
          (Socket : Net.Socket_Type'Class;
           Config : SSL.Config := Null_Config) return Socket_Type;
        --  Make client side SSL connection from plain socket.
        --  SSL handshake does not performed. SSL handshake would be made
        --  automatically on first Read/Write, or explicitly by the Do_Handshake
        --  call. Do not free or close source socket after this call.

        function Secure_Server
          (Socket : Net.Socket_Type'Class;
           Config : SSL.Config := Null_Config) return Socket_Type;
        --  Make server side SSL connection from plain socket.
        --  SSL handshake does not performed. SSL handshake would be made
        --  automatically on first Read/Write, or explicitly by the Do_Handshake
        --  call. Do not free or close source socket after this call.

        procedure Do_Handshake (Socket : in out Socket_Type);
        --  Wait for a SSL/TLS handshake to take place. You need to call this
        --  routine if you have converted a standard socket to secure one and need
        --  to get the peer certificate.

        function Version (Build_Info : Boolean := False) return String;
        --  Returns version information

        procedure Clear_Session_Cache (Config : SSL.Config := Null_Config);
        --  Remove all sessions from SSL session cache from the SSL context.
        --  Null_Config mean default context.

        procedure Set_Session_Cache_Size
          (Size : Natural; Config : SSL.Config := Null_Config);
        --  Set session cache size in the SSL context.
        --  Null_Config mean default context.

     private
        --  implementation removed
     end AWS.Net.SSL;


File: aws.info,  Node: AWS.Net.SSL.Certificate,  Next: AWS.Net.WebSocket,  Prev: AWS.Net.SSL,  Up: AWS API Reference

B.29 AWS.Net.SSL.Certificate
============================


     ------------------------------------------------------------------------------
     --                              Ada Web Server                              -
     --                                                                          -
     --                     Copyright (C) 2003-2013, AdaCore                     -
     --                                                                          -
     --  This library is free software;  you can redistribute it and/or modify   -
     --  it under terms of the  GNU General Public License  as published by the  -
     --  Free Software  Foundation;  either version 3,  or (at your  option) any -
     --  later version. This library is distributed in the hope that it will be  -
     --  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of -
     --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                    -
     --                                                                          -
     --  As a special exception under Section 7 of GPL version 3, you are        -
     --  granted additional permissions described in the GCC Runtime Library     -
     --  Exception, version 3.1, as published by the Free Software Foundation.   -
     --                                                                          -
     --  You should have received a copy of the GNU General Public License and   -
     --  a copy of the GCC Runtime Library Exception along with this program;    -
     --  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see   -
     --  <http://www.gnu.org/licenses/>.                                         -
     --                                                                          -
     --  As a special exception, if other files instantiate generics from this   -
     --  unit, or you link this unit with other files to produce an executable,  -
     --  this  unit  does not  by itself cause  the resulting executable to be   -
     --  covered by the GNU General Public License. This exception does not      -
     --  however invalidate any other reasons why the executable file  might be  -
     --  covered by the  GNU Public License.                                     -
     ------------------------------------------------------------------------------

     with Ada.Calendar;
     with Ada.Strings.Unbounded;

     private with AWS.Utils;

     package AWS.Net.SSL.Certificate is

        use Ada.Strings.Unbounded;

        type Object is private;

        Undefined : constant Object;

        function Get (Socket : Socket_Type) return Object;
        --  Returns the certificate used by the SSL

        function Subject (Certificate : Object) return String;
        --  Returns the certificate's subject

        function Issuer (Certificate : Object) return String;
        --  Returns the certificate's issuer

        function Serial_Number (Certificate : Object) return String;
        --  Returns the certificate's serial number

        function Activation_Time (Certificate : Object) return Calendar.Time;
        --  Certificate validity starting date

        function Expiration_Time (Certificate : Object) return Calendar.Time;
        --  Certificate validity ending date

        function Verified (Certificate : Object) return Boolean;
        --  Returns True if the certificate has already been verified, this is
        --  mostly interresting when used from the Verify_Callback below. If this
        --  routine returns True it means that the certificate has already been
        --  properly checked. If checked the certificate can be trusted and the
        --  Verify_Callback should return True also. If it is False it is up to
        --  the application to check the certificate into the Verify_Callback and
        --  returns the appropriate status.

        function Status (Certificate : Object) return Long_Integer;
        --  Returns the status for the certificate. This is to be used inside the
        --  verify callback to know why the certificate has been rejected.

        function Status_Message (Certificate : Object) return String;
        --  Returns the error message for the current certificate status (as
        --  returned by Status above).

        --
        --  Client verification support
        --

        type Verify_Callback is
          access function (Cert : SSL.Certificate.Object) return Boolean;
        --  Client certificate verification callback, must return True if Cert can
        --  be accepted or False otherwise. Such callback should generally return
        --  the value returned by Verified above.

        procedure Set_Verify_Callback
          (Config : in out SSL.Config; Callback : Verify_Callback);
        --  Register the callback to use to verify client's certificates

     private
        --  implementation removed
     end AWS.Net.SSL.Certificate;


File: aws.info,  Node: AWS.Net.WebSocket,  Next: AWS.Net.WebSocket.Registry,  Prev: AWS.Net.SSL.Certificate,  Up: AWS API Reference

B.30 AWS.Net.WebSocket
======================


     ------------------------------------------------------------------------------
     --                              Ada Web Server                              -
     --                                                                          -
     --                     Copyright (C) 2012-2013, AdaCore                     -
     --                                                                          -
     --  This library is free software;  you can redistribute it and/or modify   -
     --  it under terms of the  GNU General Public License  as published by the  -
     --  Free Software  Foundation;  either version 3,  or (at your  option) any -
     --  later version. This library is distributed in the hope that it will be  -
     --  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of -
     --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                    -
     --                                                                          -
     --  As a special exception under Section 7 of GPL version 3, you are        -
     --  granted additional permissions described in the GCC Runtime Library     -
     --  Exception, version 3.1, as published by the Free Software Foundation.   -
     --                                                                          -
     --  You should have received a copy of the GNU General Public License and   -
     --  a copy of the GCC Runtime Library Exception along with this program;    -
     --  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see   -
     --  <http://www.gnu.org/licenses/>.                                         -
     --                                                                          -
     --  As a special exception, if other files instantiate generics from this   -
     --  unit, or you link this unit with other files to produce an executable,  -
     --  this  unit  does not  by itself cause  the resulting executable to be   -
     --  covered by the GNU General Public License. This exception does not      -
     --  however invalidate any other reasons why the executable file  might be  -
     --  covered by the  GNU Public License.                                     -
     ------------------------------------------------------------------------------

     --  This implements the WebSocket protocol as defined in RFC-6455

     with Ada.Strings.Unbounded;
     with AWS.Status;

     private with Interfaces;

     package AWS.Net.WebSocket is

        use Ada.Strings.Unbounded;

        type Object is new Net.Socket_Type with private;
        type Object_Class is access all Object'Class;

        No_Object : constant Object'Class;

        type Kind_Type
          is (Unknown, Connection_Open, Text, Binary, Ping, Pong, Connection_Close);
        --  Data Frame Kind

        type Error_Type is
          (Normal_Closure,
           Going_Away,
           Protocol_Error,
           Unsupported_Data,
           No_Status_Received,
           Abnormal_Closure,
           Invalid_Frame_Payload_Data,
           Policy_Violation,
           Message_Too_Big,
           Mandatory_Extension,
           Internal_Server_Error,
           TLS_Handshake,
           Cannot_Resolve_Error);

        --
        --  The following three methods are the one to override or redefine. In fact
        --  the default Send implementation should be ok for most usages.
        --

        function Create
          (Socket  : Socket_Access;
           Request : AWS.Status.Data) return Object'Class;
        --  Create a new instance of the WebSocket, this is used by AWS internal
        --  server to create a default WebSocket if no other constructor are
        --  provided. It is also needed when deriving from WebSocket.

        procedure On_Message (Socket : in out Object; Message : String) is null;
        --  Default implementation does nothing, it needs to be overriden by the
        --  end-user. This is the callback that will get activated for every server
        --  incoming data. It is also important to keep in mind that the thread
        --  handling this WebSocket won't be released until the procedure returns.
        --  So the code inside this routine should be small and most importantly not
        --  wait for an event to occur otherwise other requests won't be served.

        procedure On_Message (Socket : in out Object; Message : Unbounded_String);
        --  Same a above but takes an Unbounded_String. This is supposed to be
        --  overriden when handling large messages otherwise a stack-overflow could
        --  be raised. The default implementation of this procedure to to call the
        --  On_Message above with a string.
        --
        --  So either this version is overriden to handle the incoming messages or
        --  the one above if the messages are known to be small.

        procedure On_Open (Socket : in out Object; Message : String) is null;
        --  As above but activated when a WebSocket is opened

        procedure On_Close (Socket : in out Object; Message : String) is null;
        --  As above but activated when a WebSocket is closed

        procedure On_Error (Socket : in out Object; Message : String) is null;
        --  As above but activated when a WebSocket error is detected

        procedure Send
          (Socket    : in out Object;
           Message   : String;
           Is_Binary : Boolean := False);
        --  This default implementation just send a message to the client. The
        --  message is sent in a single chunk (not fragmented).

        procedure Send
          (Socket    : in out Object;
           Message   : Unbounded_String;
           Is_Binary : Boolean := False);
        --  Same as above but can be used for large messages. The message is
        --  possibly sent fragmented.

        procedure Send
          (Socket    : in out Object;
           Message   : Stream_Element_Array;
           Is_Binary : Boolean := True);
        --  As above but default is a binary message

        --
        --  Simple accessors to WebSocket state
        --

        function Kind (Socket : Object) return Kind_Type;
        --  Returns the message kind of the current read data

        function Protocol_Version (Socket : Object) return Natural;
        --  Returns the version of the protocol for this WebSocket

        function URI (Socket : Object) return String;
        --  Returns the URI for the WebSocket

        function Origin (Socket : Object) return String;
        --  Returns the Origin of the WebSocket. That is the value of the Origin
        --  header of the client which has opened the socket.

        function Error (Socket : Object) return Error_Type;
        --  Returns the current error type

        function End_Of_Message (Socket : Object) return Boolean;
        --  Returns True if we have read a whole message

        --
        --  Socket's methods that must be overriden
        --

        overriding procedure Shutdown
          (Socket : Object;
           How    : Shutmode_Type := Shut_Read_Write);
        --  Shutdown the socket

        overriding function Get_FD (Socket : Object) return FD_Type;
        --  Returns the file descriptor associated with the socket

        overriding function Peer_Addr (Socket : Object) return String;
        --  Returns the peer name/address

        overriding function Peer_Port (Socket : Object) return Positive;
        --  Returns the port of the peer socket

        overriding function Get_Addr (Socket : Object) return String;
        --  Returns the name/address of the socket

        overriding function Get_Port (Socket : Object) return Positive;
        --  Returns the port of the socket

        overriding function Errno (Socket : Object) return Integer;
        --  Returns and clears error state in socket

        overriding function Get_Send_Buffer_Size (Socket : Object) return Natural;
        --  Returns the internal socket send buffer size.
        --  Do not confuse with buffers for the AWS.Net.Buffered operations.

        overriding function Get_Receive_Buffer_Size
          (Socket : Object) return Natural;
        --  Returns the internal socket receive buffer size.
        --  Do not confuse with buffers for the AWS.Net.Buffered operations.

     private
        --  implementation removed
     end AWS.Net.WebSocket;


File: aws.info,  Node: AWS.Net.WebSocket.Registry,  Next: AWS.Net.WebSocket.Registry.Control,  Prev: AWS.Net.WebSocket,  Up: AWS API Reference

B.31 AWS.Net.WebSocket.Registry
===============================


     ------------------------------------------------------------------------------
     --                              Ada Web Server                              -
     --                                                                          -
     --                     Copyright (C) 2012-2013, AdaCore                     -
     --                                                                          -
     --  This library is free software;  you can redistribute it and/or modify   -
     --  it under terms of the  GNU General Public License  as published by the  -
     --  Free Software  Foundation;  either version 3,  or (at your  option) any -
     --  later version. This library is distributed in the hope that it will be  -
     --  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of -
     --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                    -
     --                                                                          -
     --  As a special exception under Section 7 of GPL version 3, you are        -
     --  granted additional permissions described in the GCC Runtime Library     -
     --  Exception, version 3.1, as published by the Free Software Foundation.   -
     --                                                                          -
     --  You should have received a copy of the GNU General Public License and   -
     --  a copy of the GCC Runtime Library Exception along with this program;    -
     --  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see   -
     --  <http://www.gnu.org/licenses/>.                                         -
     --                                                                          -
     --  As a special exception, if other files instantiate generics from this   -
     --  unit, or you link this unit with other files to produce an executable,  -
     --  this  unit  does not  by itself cause  the resulting executable to be   -
     --  covered by the GNU General Public License. This exception does not      -
     --  however invalidate any other reasons why the executable file  might be  -
     --  covered by the  GNU Public License.                                     -
     ------------------------------------------------------------------------------

     --  This package is used to build and register the active WebSockets. Some
     --  services to send or broadcast messages are also provided.

     with AWS.Status;

     private with GNAT.Regexp;

     package AWS.Net.WebSocket.Registry is

        type Factory is access function
          (Socket  : Socket_Access;
           Request : AWS.Status.Data) return Object'Class;

        --  Creating and Registering WebSockets

        function Constructor (URI : String) return Registry.Factory;
        --  Get the WebObject's constructor for a specific URI

        procedure Register (URI : String; Factory : Registry.Factory);
        --  Register a WebObject's constructor for a specific URI

        --  Sending messages

        type Recipient is private;

        function Create (URI : String; Origin : String := "") return Recipient;
        --  A recipient with only an URI is called a broadcast as it designate all
        --  registered WebSocket for this specific URI. If Origin is specified then
        --  it designates a single client.
        --
        --  Note that both URI and Origin can be regular expressions.

        procedure Send
          (To          : Recipient;
           Message     : String;
           Except_Peer : String := "");
        --  Send a message to the WebSocket designated by Origin and URI. Do not
        --  send this message to the peer whose address is given by Except_Peer.
        --  Except_Peer must be the address as reported by AWS.Net.Peer_Addr. It is
        --  often needed to send a message to all registered sockets except the one
        --  which has sent the message triggering a response.

        procedure Send
          (To      : Recipient;
           Message : String;
           Request : AWS.Status.Data);
        --  As above but filter out the client having set the given request

        procedure Close
           (To         : Recipient;
           Message     : String;
           Except_Peer : String := "");
        --  Close connections

     private
        --  implementation removed
     end AWS.Net.WebSocket.Registry;


File: aws.info,  Node: AWS.Net.WebSocket.Registry.Control,  Next: AWS.Parameters,  Prev: AWS.Net.WebSocket.Registry,  Up: AWS API Reference

B.32 AWS.Net.WebSocket.Registry.Control
=======================================


     ------------------------------------------------------------------------------
     --                              Ada Web Server                              -
     --                                                                          -
     --                       Copyright (C) 2012, AdaCore                        -
     --                                                                          -
     --  This library is free software;  you can redistribute it and/or modify   -
     --  it under terms of the  GNU General Public License  as published by the  -
     --  Free Software  Foundation;  either version 3,  or (at your  option) any -
     --  later version. This library is distributed in the hope that it will be  -
     --  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of -
     --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                    -
     --                                                                          -
     --  As a special exception under Section 7 of GPL version 3, you are        -
     --  granted additional permissions described in the GCC Runtime Library     -
     --  Exception, version 3.1, as published by the Free Software Foundation.   -
     --                                                                          -
     --  You should have received a copy of the GNU General Public License and   -
     --  a copy of the GCC Runtime Library Exception along with this program;    -
     --  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see   -
     --  <http://www.gnu.org/licenses/>.                                         -
     --                                                                          -
     --  As a special exception, if other files instantiate generics from this   -
     --  unit, or you link this unit with other files to produce an executable,  -
     --  this  unit  does not  by itself cause  the resulting executable to be   -
     --  covered by the GNU General Public License. This exception does not      -
     --  however invalidate any other reasons why the executable file  might be  -
     --  covered by the  GNU Public License.                                     -
     ------------------------------------------------------------------------------

     --  This package is used to start/stop the WebSockets services

     package AWS.Net.WebSocket.Registry.Control is

        procedure Start;
        --  Start the WebSockets servers

        procedure Shutdown;
        --  Shutdown the WebSockets servers

     end AWS.Net.WebSocket.Registry.Control;


File: aws.info,  Node: AWS.Parameters,  Next: AWS.POP,  Prev: AWS.Net.WebSocket.Registry.Control,  Up: AWS API Reference

B.33 AWS.Parameters
===================


     ------------------------------------------------------------------------------
     --                              Ada Web Server                              -
     --                                                                          -
     --                     Copyright (C) 2000-2012, AdaCore                     -
     --                                                                          -
     --  This library is free software;  you can redistribute it and/or modify   -
     --  it under terms of the  GNU General Public License  as published by the  -
     --  Free Software  Foundation;  either version 3,  or (at your  option) any -
     --  later version. This library is distributed in the hope that it will be  -
     --  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of -
     --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                    -
     --                                                                          -
     --  As a special exception under Section 7 of GPL version 3, you are        -
     --  granted additional permissions described in the GCC Runtime Library     -
     --  Exception, version 3.1, as published by the Free Software Foundation.   -
     --                                                                          -
     --  You should have received a copy of the GNU General Public License and   -
     --  a copy of the GCC Runtime Library Exception along with this program;    -
     --  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see   -
     --  <http://www.gnu.org/licenses/>.                                         -
     --                                                                          -
     --  As a special exception, if other files instantiate generics from this   -
     --  unit, or you link this unit with other files to produce an executable,  -
     --  this  unit  does not  by itself cause  the resulting executable to be   -
     --  covered by the GNU General Public License. This exception does not      -
     --  however invalidate any other reasons why the executable file  might be  -
     --  covered by the  GNU Public License.                                     -
     ------------------------------------------------------------------------------

     with Ada.Strings.Unbounded;

     with AWS.Containers.Tables;

     package AWS.Parameters is

        type List is new AWS.Containers.Tables.Table_Type with private;

        subtype VString_Array is AWS.Containers.Tables.VString_Array;

        function URI_Format (Parameter_List : List) return String;
        --  Returns the list of parameters in the URI format. This can be added
        --  after the resource to form the complete URI. The format is:
        --  "?name1=value1&name2=value2..."
        --  If there is no parameter in the list, the empty string is returned.

        --  See AWS.Containers.Tables for inherited routines

     private
        --  implementation removed
     end AWS.Parameters;


File: aws.info,  Node: AWS.POP,  Next: AWS.Resources,  Prev: AWS.Parameters,  Up: AWS API Reference

B.34 AWS.POP
============


     ------------------------------------------------------------------------------
     --                              Ada Web Server                              -
     --                                                                          -
     --                     Copyright (C) 2003-2012, AdaCore                     -
     --                                                                          -
     --  This library is free software;  you can redistribute it and/or modify   -
     --  it under terms of the  GNU General Public License  as published by the  -
     --  Free Software  Foundation;  either version 3,  or (at your  option) any -
     --  later version. This library is distributed in the hope that it will be  -
     --  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of -
     --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                    -
     --                                                                          -
     --  As a special exception under Section 7 of GPL version 3, you are        -
     --  granted additional permissions described in the GCC Runtime Library     -
     --  Exception, version 3.1, as published by the Free Software Foundation.   -
     --                                                                          -
     --  You should have received a copy of the GNU General Public License and   -
     --  a copy of the GCC Runtime Library Exception along with this program;    -
     --  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see   -
     --  <http://www.gnu.org/licenses/>.                                         -
     --                                                                          -
     --  As a special exception, if other files instantiate generics from this   -
     --  unit, or you link this unit with other files to produce an executable,  -
     --  this  unit  does not  by itself cause  the resulting executable to be   -
     --  covered by the GNU General Public License. This exception does not      -
     --  however invalidate any other reasons why the executable file  might be  -
     --  covered by the  GNU Public License.                                     -
     ------------------------------------------------------------------------------

     with Ada.Finalization;
     with Ada.Strings.Unbounded;

     with AWS.Headers;
     with AWS.Net.Std;
     with AWS.Resources.Streams;
     with AWS.Utils;

     package AWS.POP is

        use Ada.Strings.Unbounded;

        POP_Error : exception;
        --  Raised by all routines when an error has been detected

        -------------
        -- Mailbox -
        -------------

        Default_POP_Port : constant := 110;

        type Mailbox is private;

        type Authenticate_Mode is (Clear_Text, APOP);

        function Initialize
          (Server_Name  : String;
           User         : String;
           Password     : String;
           Authenticate : Authenticate_Mode := Clear_Text;
           Port         : Positive          := Default_POP_Port) return Mailbox;
        --  Connect on the given Port to Server_Name and open User's Mailbox. This
        --  mailbox object will be used to retrieve messages.

        procedure Close (Mailbox : POP.Mailbox);
        --  Close mailbox

        function User_Name (Mailbox : POP.Mailbox) return String;
        --  Returns User's name for this mailbox

        function Message_Count (Mailbox : POP.Mailbox) return Natural;
        --  Returns the number of messages in the user's mailbox

        function Size (Mailbox : POP.Mailbox) return Natural;
        --  Returns the total size in bytes of the user's mailbox

        -------------
        -- Message -
        -------------

        type Message is tagged private;

        function Get
          (Mailbox : POP.Mailbox;
           N       : Positive;
           Remove  : Boolean     := False) return Message;
        --  Retrieve Nth message from the mailbox, let the message on the mailbox
        --  if Remove is False.

        procedure Delete
          (Mailbox : POP.Mailbox;
           N       : Positive);
        --  Detele message number N from the mailbox

        function Get_Header
          (Mailbox : POP.Mailbox;
           N       : Positive) return Message;
        --  Retrieve headers for the Nth message from the mailbox, let the message
        --  on the mailbox. This is useful to build a quick summary of the mailbox.

        generic
           with procedure Action
             (Message : POP.Message;
              Index   : Positive;
              Quit    : in out Boolean);
        procedure For_Every_Message
          (Mailbox : POP.Mailbox;
           Remove  : Boolean := False);
        --  Calls Action for each message read on the mailbox, delete the message
        --  from the mailbox if Remove is True. Set Quit to True to stop the
        --  iterator. Index is the mailbox's message index.

        generic
           with procedure Action
             (Message : POP.Message;
              Index   : Positive;
              Quit    : in out Boolean);
        procedure For_Every_Message_Header (Mailbox : POP.Mailbox);
        --  Calls Action for each message read on the mailbox. Only the headers are
        --  read from the mailbox. Set Quit to True to stop the iterator. Index is
        --  the mailbox's message index.

        function Size (Message : POP.Message) return Natural;
        --  Returns the message size in bytes

        function Content (Message : POP.Message) return Unbounded_String;
        --  Returns message's content as an Unbounded_String. Each line are
        --  separated by CR+LF characters.

        function From (Message : POP.Message) return String;
        --  Returns From header value

        function To (Message : POP.Message; N : Natural := 0) return String;
        --  Returns the To header value. If N = 0 returns all recipients separated
        --  by a coma otherwise it returns the Nth To recipient.

        function To_Count (Message : POP.Message) return Natural;
        --  Returns the number of To recipient for Message. returns 0 if there is
        --  no To for this message.

        function CC (Message : POP.Message; N : Natural := 0) return String;
        --  Retruns the CC header value. If N = 0 returns all recipients separated
        --  by a coma otherwise it returns the Nth CC recipient.

        function CC_Count (Message : POP.Message) return Natural;
        --  Returns the number of CC recipient for Message. Returns 0 if there is
        --  no CC for this message.

        function Subject (Message : POP.Message) return String;
        --  Returns Subject header value

        function Date (Message : POP.Message) return String;
        --  Returns Date header value

        function Header
          (Message : POP.Message;
           Header  : String) return String;
        --  Returns header value for header named Header, returns the empty string
        --  if such header does not exist.

        ----------------
        -- Attachment -
        ----------------

        type Attachment is private;

        function Attachment_Count (Message : POP.Message) return Natural;
        --  Returns the number of Attachments into Message

        function Get
          (Message : POP.Message'Class;
           Index   : Positive) return Attachment;
        --  Returns the Nth Attachment for Message, Raises Constraint_Error if
        --  there is not such attachment.

        generic
           with procedure Action
             (Attachment : POP.Attachment;
              Index      : Positive;
              Quit       : in out Boolean);
        procedure For_Every_Attachment (Message : POP.Message);
        --  Calls action for every Attachment in Message. Stop iterator if Quit is
        --  set to True, Quit is set to False by default.

        function Content
          (Attachment : POP.Attachment)
           return AWS.Resources.Streams.Stream_Access;
        --  Returns Attachment's content as a memory stream. Note that the stream
        --  has already been decoded. Most attachments are MIME Base64 encoded.

        function Content (Attachment : POP.Attachment) return Unbounded_String;
        --  Returns Attachment's content as an Unbounded_String. This routine must
        --  only be used for non file attachments. Raises Constraint_Error if
        --  called for a file attachment.

        function Filename (Attachment : POP.Attachment) return String;
        --  Returns the Attachment filename or the empty string if it is not a file
        --  but an embedded message.

        function Is_File (Attachment : POP.Attachment) return Boolean;
        --  Returns True if Attachment is a file

        procedure Write (Attachment : POP.Attachment; Directory : String);
        --  Writes Attachment's file content into Directory. This must only be used
        --  for a file attachment.

     private
        --  implementation removed
     end AWS.POP;


File: aws.info,  Node: AWS.Resources,  Next: AWS.Resources.Embedded,  Prev: AWS.POP,  Up: AWS API Reference

B.35 AWS.Resources
==================


     ------------------------------------------------------------------------------
     --                              Ada Web Server                              -
     --                                                                          -
     --                     Copyright (C) 2002-2012, AdaCore                     -
     --                                                                          -
     --  This library is free software;  you can redistribute it and/or modify   -
     --  it under terms of the  GNU General Public License  as published by the  -
     --  Free Software  Foundation;  either version 3,  or (at your  option) any -
     --  later version. This library is distributed in the hope that it will be  -
     --  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of -
     --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                    -
     --                                                                          -
     --  As a special exception under Section 7 of GPL version 3, you are        -
     --  granted additional permissions described in the GCC Runtime Library     -
     --  Exception, version 3.1, as published by the Free Software Foundation.   -
     --                                                                          -
     --  You should have received a copy of the GNU General Public License and   -
     --  a copy of the GCC Runtime Library Exception along with this program;    -
     --  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see   -
     --  <http://www.gnu.org/licenses/>.                                         -
     --                                                                          -
     --  As a special exception, if other files instantiate generics from this   -
     --  unit, or you link this unit with other files to produce an executable,  -
     --  this  unit  does not  by itself cause  the resulting executable to be   -
     --  covered by the GNU General Public License. This exception does not      -
     --  however invalidate any other reasons why the executable file  might be  -
     --  covered by the GNU Public License.                                      -
     ------------------------------------------------------------------------------

     with Ada.Calendar;
     with Ada.Streams;
     with Ada.Unchecked_Deallocation;
     with AWS.Utils;

     package AWS.Resources is

        use Ada.Streams;

        Resource_Error : exception;

        type File_Type is limited private;

        type File_Instance is (None, Plain, GZip, Both);
        --  None  : No instance of this file present.
        --  Plain : A non-compressed version of this file exists.
        --  GZip  : A gzip encoded version of this file exists.
        --  Both  : Both versions of this file exists.

        function "or" (I1, I2 : File_Instance) return File_Instance;
        --  Returns the union of I1 and I2

        subtype Content_Length_Type is Stream_Element_Offset;

        Undefined_Length : constant Content_Length_Type;
        --  Undefined length could be used when we do not know the message stream
        --  length at the start of transfer. The end of message could be determined
        --  by the chunked transfer-encoding in the HTTP/1.1, or by the closing
        --  connection in the HTTP/1.0.

        procedure Open
          (File : out File_Type;
           Name : String;
           Form : String    := "");
        --  Open file in mode In_File. Only reading from the file is supported.
        --  This procedure open the in-memory (embedded) file if present, otherwise
        --  the file on disk is opened. Note that if Name file is not found, it
        --  checks for Name & ".gz" and unzipped the file content in this case.

        procedure Open
          (File : out File_Type;
           Name : String;
           Form : String    := "";
           GZip : in out Boolean);
        --  Open file in mode In_File. Only reading from the file is supported.
        --  This procedure open the in-memory (embedded) file if present, otherwise
        --  the file on disk is opened. If GZip parameter is False this call is
        --  equivalent to the Open routine above. If GZip is True this routine will
        --  first check for the compressed version of the resource (Name & ".gz"),
        --  if found GZip output value will remain True. If GZip value is True and
        --  the compressed version of the resource does not exist it looks for
        --  non-compressed version and set GZip value to False.

        procedure Reset (Resource : in out File_Type);
        --  Reset the file, reading will restart at the beginning

        procedure Set_Index
          (Resource : in out File_Type;
           To       : Stream_Element_Offset);
        --  Set the position in the stream, next Read will start at the position
        --  whose index is To. If To is outside the content the index is set to
        --  Last + 1 to ensure that next End_Of_File will return True.

        procedure Close (Resource : in out File_Type);
        --  Close the file

        procedure Read
          (Resource : in out File_Type;
           Buffer   : out Stream_Element_Array;
           Last     : out Stream_Element_Offset);
        --  Returns a set of bytes from the file

        procedure Get_Line
          (Resource  : in out File_Type;
           Buffer    : out String;
           Last      : out Natural);
        --  Returns a line from the file. A line is a set of character terminated
        --  by ASCII.LF (UNIX style EOF) or ASCII.CR+ASCII.LF (DOS style EOF).

        function End_Of_File (Resource : File_Type) return Boolean;
        --  Returns true if there is no more data to read

        function LF_Terminated (Resource : File_Type) return Boolean;
        --  Returns True if last line returned by Get_Line was terminated with a LF
        --  or CR+LF on DOS based systems.

        function Size (Resource : File_Type) return Content_Length_Type;
        --  Returns the size (in bytes) of the resource. If the size of the
        --  resource is not defined, the routine Size returns Undefined_Length
        --  value.

        function Exist (Name : String) return File_Instance;
        --  Return GZip if only file Name & ".gz" exists.
        --  Return Plain if only file Name exists.
        --  Return Both if both file Name and Name & ".gz" exists.
        --  Return None if files neither Name nor Name & ".gz" exist.

        function Is_Regular_File (Name : String) return Boolean;
        --  Returns True if Filename is a regular file and is readable. Checks
        --  first for in memory file then for disk file.

        function File_Size (Name : String) return Utils.File_Size_Type;
        --  Returns Filename's size in bytes. Checks first for in memory file
        --  then for disk file.

        function File_Timestamp (Name : String) return Ada.Calendar.Time;
        --  Get the time for last modification to a file in UTC/GMT. Checks first
        --  for in memory file then for disk file.

     private
        --  implementation removed
     end AWS.Resources;


File: aws.info,  Node: AWS.Resources.Embedded,  Next: AWS.Resources.Files,  Prev: AWS.Resources,  Up: AWS API Reference

B.36 AWS.Resources.Embedded
===========================


     ------------------------------------------------------------------------------
     --                              Ada Web Server                              -
     --                                                                          -
     --                     Copyright (C) 2002-2012, AdaCore                     -
     --                                                                          -
     --  This library is free software;  you can redistribute it and/or modify   -
     --  it under terms of the  GNU General Public License  as published by the  -
     --  Free Software  Foundation;  either version 3,  or (at your  option) any -
     --  later version. This library is distributed in the hope that it will be  -
     --  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of -
     --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                    -
     --                                                                          -
     --  As a special exception under Section 7 of GPL version 3, you are        -
     --  granted additional permissions described in the GCC Runtime Library     -
     --  Exception, version 3.1, as published by the Free Software Foundation.   -
     --                                                                          -
     --  You should have received a copy of the GNU General Public License and   -
     --  a copy of the GCC Runtime Library Exception along with this program;    -
     --  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see   -
     --  <http://www.gnu.org/licenses/>.                                         -
     --                                                                          -
     --  As a special exception, if other files instantiate generics from this   -
     --  unit, or you link this unit with other files to produce an executable,  -
     --  this  unit  does not  by itself cause  the resulting executable to be   -
     --  covered by the GNU General Public License. This exception does not      -
     --  however invalidate any other reasons why the executable file  might be  -
     --  covered by the  GNU Public License.                                     -
     ------------------------------------------------------------------------------

     with AWS.Resources.Streams.Memory;

     package AWS.Resources.Embedded is

        use Ada;

        Resource_Error : exception renames Resources.Resource_Error;

        subtype Buffer_Access is Streams.Memory.Buffer_Access;

        procedure Open
          (File : out File_Type;
           Name : String;
           Form : String    := "";
           GZip : in out Boolean);
        --  Open resource from registered data

        procedure Create
          (File   : out File_Type;
           Buffer : Buffer_Access);
        --  Create the resource directly from memory data

        function Exist (Name : String) return File_Instance;
        --  Return GZip if only file Name & ".gz" exists.
        --  Return Plain if only file Name exists.
        --  Return Both if both file Name and Name & ".gz" exists.
        --  Return None if files neither Name nor Name & ".gz" exist.

        function Is_Regular_File (Name : String) return Boolean;
        pragma Inline (Is_Regular_File);
        --  Returns True if file named Name has been registered (i.e. it is an
        --  in-memory file).

        function File_Size (Name : String) return Utils.File_Size_Type;

        function File_Timestamp (Name : String) return Ada.Calendar.Time;

        procedure Register
          (Name      : String;
           Content   : Buffer_Access;
           File_Time : Calendar.Time);
        --  Register a new file named Name into the embedded resources. The file
        --  content is pointed to by Content, the File_Time must be the last
        --  modification time stamp for the file. If Name ends with ".gz" the
        --  embedded resource registered as compressed. If a file is already
        --  registered for this name, Content replace the previous one.

     end AWS.Resources.Embedded;


File: aws.info,  Node: AWS.Resources.Files,  Next: AWS.Resources.Streams,  Prev: AWS.Resources.Embedded,  Up: AWS API Reference

B.37 AWS.Resources.Files
========================


     ------------------------------------------------------------------------------
     --                              Ada Web Server                              -
     --                                                                          -
     --                     Copyright (C) 2002-2012, AdaCore                     -
     --                                                                          -
     --  This library is free software;  you can redistribute it and/or modify   -
     --  it under terms of the  GNU General Public License  as published by the  -
     --  Free Software  Foundation;  either version 3,  or (at your  option) any -
     --  later version. This library is distributed in the hope that it will be  -
     --  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of -
     --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                    -
     --                                                                          -
     --  As a special exception under Section 7 of GPL version 3, you are        -
     --  granted additional permissions described in the GCC Runtime Library     -
     --  Exception, version 3.1, as published by the Free Software Foundation.   -
     --                                                                          -
     --  You should have received a copy of the GNU General Public License and   -
     --  a copy of the GCC Runtime Library Exception along with this program;    -
     --  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see   -
     --  <http://www.gnu.org/licenses/>.                                         -
     --                                                                          -
     --  As a special exception, if other files instantiate generics from this   -
     --  unit, or you link this unit with other files to produce an executable,  -
     --  this  unit  does not  by itself cause  the resulting executable to be   -
     --  covered by the GNU General Public License. This exception does not      -
     --  however invalidate any other reasons why the executable file  might be  -
     --  covered by the  GNU Public License.                                     -
     ------------------------------------------------------------------------------

     with AWS.Utils;

     package AWS.Resources.Files is

        Resource_Error : exception renames Resources.Resource_Error;

        procedure Open
          (File : out File_Type;
           Name : String;
           Form : String    := "";
           GZip : in out Boolean);

        procedure Open
          (File : out File_Type;
           Name : String;
           Form : String    := "");

        function Exist (Name : String) return File_Instance;
        --  Return GZip if only file Name & ".gz" exists.
        --  Return Plain if only file Name exists.
        --  Return Both if both file Name and Name & ".gz" exists.
        --  Return None if files neither Name nor Name & ".gz" exist.

        function Is_Regular_File (Name : String) return Boolean;

        function File_Size (Name : String) return Utils.File_Size_Type;

        function File_Timestamp (Name : String) return Ada.Calendar.Time;

     end AWS.Resources.Files;


File: aws.info,  Node: AWS.Resources.Streams,  Next: AWS.Resources.Streams.Disk,  Prev: AWS.Resources.Files,  Up: AWS API Reference

B.38 AWS.Resources.Streams
==========================


     ------------------------------------------------------------------------------
     --                              Ada Web Server                              -
     --                                                                          -
     --                     Copyright (C) 2002-2012, AdaCore                     -
     --                                                                          -
     --  This library is free software;  you can redistribute it and/or modify   -
     --  it under terms of the  GNU General Public License  as published by the  -
     --  Free Software  Foundation;  either version 3,  or (at your  option) any -
     --  later version. This library is distributed in the hope that it will be  -
     --  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of -
     --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                    -
     --                                                                          -
     --  As a special exception under Section 7 of GPL version 3, you are        -
     --  granted additional permissions described in the GCC Runtime Library     -
     --  Exception, version 3.1, as published by the Free Software Foundation.   -
     --                                                                          -
     --  You should have received a copy of the GNU General Public License and   -
     --  a copy of the GCC Runtime Library Exception along with this program;    -
     --  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see   -
     --  <http://www.gnu.org/licenses/>.                                         -
     --                                                                          -
     --  As a special exception, if other files instantiate generics from this   -
     --  unit, or you link this unit with other files to produce an executable,  -
     --  this  unit  does not  by itself cause  the resulting executable to be   -
     --  covered by the GNU General Public License. This exception does not      -
     --  however invalidate any other reasons why the executable file  might be  -
     --  covered by the  GNU Public License.                                     -
     ------------------------------------------------------------------------------

     package AWS.Resources.Streams is

        use Ada;

        type Stream_Type is abstract tagged limited private;

        type Stream_Access is access all Stream_Type'Class;

        function End_Of_File (Resource : Stream_Type) return Boolean is abstract;

        procedure Read
          (Resource : in out Stream_Type;
           Buffer   : out Stream_Element_Array;
           Last     : out Stream_Element_Offset) is abstract;

        procedure Reset (Resource : in out Stream_Type) is abstract;

        procedure Set_Index
          (Resource : in out Stream_Type;
           To       : Stream_Element_Offset) is abstract;
        --  Set the position in the stream, next Read will start at the position
        --  whose index is To. If To is outside the content the index is set to
        --  Last + 1 to ensure that next End_Of_File will return True.

        procedure Close (Resource : in out Stream_Type) is abstract;

        function Size (Resource : Stream_Type) return Stream_Element_Offset;
        --  This default implementation returns Undefined_Length. If the derived
        --  stream implementation knows about the size (in bytes) of the stream
        --  this routine should be redefined.

        function Name (Resource : Stream_Type) return String;
        --  This default implementation returns the empty string. It is must be
        --  overwritten by file based stream to provide the proper filename
        --  associated with the stream.

        procedure Create
          (Resource : out File_Type;
           Stream   : Stream_Access);
        pragma Inline (Create);
        --  Create a resource file from user defined stream

     private
        --  implementation removed
     end AWS.Resources.Streams;


File: aws.info,  Node: AWS.Resources.Streams.Disk,  Next: AWS.Resources.Streams.Disk.Once,  Prev: AWS.Resources.Streams,  Up: AWS API Reference

B.39 AWS.Resources.Streams.Disk
===============================


     ------------------------------------------------------------------------------
     --                              Ada Web Server                              -
     --                                                                          -
     --                     Copyright (C) 2003-2012, AdaCore                     -
     --                                                                          -
     --  This library is free software;  you can redistribute it and/or modify   -
     --  it under terms of the  GNU General Public License  as published by the  -
     --  Free Software  Foundation;  either version 3,  or (at your  option) any -
     --  later version. This library is distributed in the hope that it will be  -
     --  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of -
     --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                    -
     --                                                                          -
     --  As a special exception under Section 7 of GPL version 3, you are        -
     --  granted additional permissions described in the GCC Runtime Library     -
     --  Exception, version 3.1, as published by the Free Software Foundation.   -
     --                                                                          -
     --  You should have received a copy of the GNU General Public License and   -
     --  a copy of the GCC Runtime Library Exception along with this program;    -
     --  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see   -
     --  <http://www.gnu.org/licenses/>.                                         -
     --                                                                          -
     --  As a special exception, if other files instantiate generics from this   -
     --  unit, or you link this unit with other files to produce an executable,  -
     --  this  unit  does not  by itself cause  the resulting executable to be   -
     --  covered by the GNU General Public License. This exception does not      -
     --  however invalidate any other reasons why the executable file  might be  -
     --  covered by the  GNU Public License.                                     -
     ------------------------------------------------------------------------------

     --  An ready-to-use implementation of the stream API where the stream content
     --  is read from an on-disk file.

     with Ada.Streams.Stream_IO;

     private with Ada.Strings.Unbounded;

     package AWS.Resources.Streams.Disk is

        type Stream_Type is new Streams.Stream_Type with private;

        procedure Open
          (File : out Stream_Type;
           Name : String;
           Form : String    := "shared=no");

        overriding function End_Of_File (Resource : Stream_Type) return Boolean;

        overriding procedure Read
          (Resource : in out Stream_Type;
           Buffer   : out Stream_Element_Array;
           Last     : out Stream_Element_Offset);

        overriding function Size
          (Resource : Stream_Type) return Stream_Element_Offset;

        overriding function Name (Resource : Stream_Type) return String;

        overriding procedure Reset (Resource : in out Stream_Type);

        overriding procedure Set_Index
          (Resource : in out Stream_Type;
           To       : Stream_Element_Offset);

        overriding procedure Close (Resource : in out Stream_Type);

     private
        --  implementation removed
     end AWS.Resources.Streams.Disk;


File: aws.info,  Node: AWS.Resources.Streams.Disk.Once,  Next: AWS.Resources.Streams.Memory,  Prev: AWS.Resources.Streams.Disk,  Up: AWS API Reference

B.40 AWS.Resources.Streams.Disk.Once
====================================


     ------------------------------------------------------------------------------
     --                              Ada Web Server                              -
     --                                                                          -
     --                     Copyright (C) 2003-2012, AdaCore                     -
     --                                                                          -
     --  This library is free software;  you can redistribute it and/or modify   -
     --  it under terms of the  GNU General Public License  as published by the  -
     --  Free Software  Foundation;  either version 3,  or (at your  option) any -
     --  later version. This library is distributed in the hope that it will be  -
     --  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of -
     --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                    -
     --                                                                          -
     --  As a special exception under Section 7 of GPL version 3, you are        -
     --  granted additional permissions described in the GCC Runtime Library     -
     --  Exception, version 3.1, as published by the Free Software Foundation.   -
     --                                                                          -
     --  You should have received a copy of the GNU General Public License and   -
     --  a copy of the GCC Runtime Library Exception along with this program;    -
     --  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see   -
     --  <http://www.gnu.org/licenses/>.                                         -
     --                                                                          -
     --  As a special exception, if other files instantiate generics from this   -
     --  unit, or you link this unit with other files to produce an executable,  -
     --  this  unit  does not  by itself cause  the resulting executable to be   -
     --  covered by the GNU General Public License. This exception does not      -
     --  however invalidate any other reasons why the executable file  might be  -
     --  covered by the  GNU Public License.                                     -
     ------------------------------------------------------------------------------

     --  An ready-to-use implementation of the stream API where the stream content
     --  is read from an on-disk file. The file is removed from the file system
     --  when the transfer is completed.

     package AWS.Resources.Streams.Disk.Once is

        type Stream_Type is new Disk.Stream_Type with null record;

        overriding procedure Close (Resource : in out Stream_Type);
        --  Only redefine Close that will not only close the stream but also delete
        --  the file.

     end AWS.Resources.Streams.Disk.Once;


File: aws.info,  Node: AWS.Resources.Streams.Memory,  Next: AWS.Resources.Streams.Memory.ZLib,  Prev: AWS.Resources.Streams.Disk.Once,  Up: AWS API Reference

B.41 AWS.Resources.Streams.Memory
=================================


     ------------------------------------------------------------------------------
     --                              Ada Web Server                              -
     --                                                                          -
     --                     Copyright (C) 2003-2012, AdaCore                     -
     --                                                                          -
     --  This library is free software;  you can redistribute it and/or modify   -
     --  it under terms of the  GNU General Public License  as published by the  -
     --  Free Software  Foundation;  either version 3,  or (at your  option) any -
     --  later version. This library is distributed in the hope that it will be  -
     --  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of -
     --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                    -
     --                                                                          -
     --  As a special exception under Section 7 of GPL version 3, you are        -
     --  granted additional permissions described in the GCC Runtime Library     -
     --  Exception, version 3.1, as published by the Free Software Foundation.   -
     --                                                                          -
     --  You should have received a copy of the GNU General Public License and   -
     --  a copy of the GCC Runtime Library Exception along with this program;    -
     --  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see   -
     --  <http://www.gnu.org/licenses/>.                                         -
     --                                                                          -
     --  As a special exception, if other files instantiate generics from this   -
     --  unit, or you link this unit with other files to produce an executable,  -
     --  this  unit  does not  by itself cause  the resulting executable to be   -
     --  covered by the GNU General Public License. This exception does not      -
     --  however invalidate any other reasons why the executable file  might be  -
     --  covered by the  GNU Public License.                                     -
     ------------------------------------------------------------------------------

     --  API to handle a memory stream. A memory stream is first created
     --  empty. User can add chunk of data using the Append routines. The stream
     --  is then read using the Read procedure.

     with AWS.Containers.Memory_Streams;
     with AWS.Utils;

     package AWS.Resources.Streams.Memory is

        type Stream_Type is new Streams.Stream_Type with private;

        subtype Stream_Element_Access is Utils.Stream_Element_Array_Access;
        subtype Buffer_Access is  Utils.Stream_Element_Array_Constant_Access;

        procedure Append
          (Resource : in out Stream_Type;
           Buffer   : Stream_Element_Array;
           Trim     : Boolean := False);
        --  Append Buffer into the memory stream

        procedure Append
          (Resource : in out Stream_Type;
           Buffer   : Stream_Element_Access);
        --  Append static data pointed to Buffer into the memory stream as is.
        --  The stream will free the memory on close.

        procedure Append
          (Resource : in out Stream_Type;
           Buffer   : Buffer_Access);
        --  Append static data pointed to Buffer into the memory stream as is.
        --  The stream would not try to free the memory on close.

        overriding procedure Read
          (Resource : in out Stream_Type;
           Buffer   : out Stream_Element_Array;
           Last     : out Stream_Element_Offset);
        --  Returns a chunck of data in Buffer, Last point to the last element
        --  returned in Buffer.

        overriding function End_Of_File (Resource : Stream_Type) return Boolean;
        --  Returns True if the end of the memory stream has been reached

        procedure Clear (Resource : in out Stream_Type);
        pragma Inline (Clear);
        --  Delete all data from memory stream

        overriding procedure Reset (Resource : in out Stream_Type);
        --  Reset the streaming data to the first position

        overriding procedure Set_Index
          (Resource : in out Stream_Type;
           To       : Stream_Element_Offset);
        --  Set the position in the stream, next Read will start at the position
        --  whose index is To.

        overriding function Size
          (Resource : Stream_Type) return Stream_Element_Offset;
        --  Returns the number of bytes in the memory stream

        overriding procedure Close (Resource : in out Stream_Type);
        --  Close the memory stream. Release all memory associated with the stream

     private
        --  implementation removed
     end AWS.Resources.Streams.Memory;


File: aws.info,  Node: AWS.Resources.Streams.Memory.ZLib,  Next: AWS.Resources.Streams.Pipe,  Prev: AWS.Resources.Streams.Memory,  Up: AWS API Reference

B.42 AWS.Resources.Streams.Memory.ZLib
======================================


     ------------------------------------------------------------------------------
     --                              Ada Web Server                              -
     --                                                                          -
     --                     Copyright (C) 2003-2012, AdaCore                     -
     --                                                                          -
     --  This library is free software;  you can redistribute it and/or modify   -
     --  it under terms of the  GNU General Public License  as published by the  -
     --  Free Software  Foundation;  either version 3,  or (at your  option) any -
     --  later version. This library is distributed in the hope that it will be  -
     --  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of -
     --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                    -
     --                                                                          -
     --  As a special exception under Section 7 of GPL version 3, you are        -
     --  granted additional permissions described in the GCC Runtime Library     -
     --  Exception, version 3.1, as published by the Free Software Foundation.   -
     --                                                                          -
     --  You should have received a copy of the GNU General Public License and   -
     --  a copy of the GCC Runtime Library Exception along with this program;    -
     --  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see   -
     --  <http://www.gnu.org/licenses/>.                                         -
     --                                                                          -
     --  As a special exception, if other files instantiate generics from this   -
     --  unit, or you link this unit with other files to produce an executable,  -
     --  this  unit  does not  by itself cause  the resulting executable to be   -
     --  covered by the GNU General Public License. This exception does not      -
     --  however invalidate any other reasons why the executable file  might be  -
     --  covered by the GNU Public License.                                      -
     ------------------------------------------------------------------------------

     --  This API is used as for standard memory stream (see parent package), the
     --  only difference is that the stream is compressing/decompressing on append.

     with ZLib;

     package AWS.Resources.Streams.Memory.ZLib is

        package ZL renames Standard.ZLib;

        type Stream_Type is new Memory.Stream_Type with private;

        subtype Window_Bits_Type   is ZL.Window_Bits_Type;
        subtype Header_Type        is ZL.Header_Type;
        subtype Compression_Level  is ZL.Compression_Level;
        subtype Strategy_Type      is ZL.Strategy_Type;
        subtype Compression_Method is ZL.Compression_Method;
        subtype Memory_Level_Type  is ZL.Memory_Level_Type;

        Default_Compression : constant Compression_Level := ZL.Default_Compression;
        Default_Header      : constant Header_Type       := ZL.Default;

        procedure Deflate_Initialize
          (Resource     : in out Stream_Type;
           Level        : Compression_Level  := ZL.Default_Compression;
           Strategy     : Strategy_Type      := ZL.Default_Strategy;
           Method       : Compression_Method := ZL.Deflated;
           Window_Bits  : Window_Bits_Type   := ZL.Default_Window_Bits;
           Memory_Level : Memory_Level_Type  := ZL.Default_Memory_Level;
           Header       : Header_Type        := ZL.Default);
        pragma Inline (Deflate_Initialize);
        --  Initialize the compression

        procedure Inflate_Initialize
          (Resource    : in out Stream_Type;
           Window_Bits : Window_Bits_Type := ZL.Default_Window_Bits;
           Header      : Header_Type      := ZL.Default);
        pragma Inline (Inflate_Initialize);
        --  Initialize the decompression

        overriding procedure Append
          (Resource : in out Stream_Type;
           Buffer   : Stream_Element_Array;
           Trim     : Boolean := False);
        --  Compress/decompress and Append Buffer into the memory stream

        overriding procedure Read
          (Resource : in out Stream_Type;
           Buffer   : out Stream_Element_Array;
           Last     : out Stream_Element_Offset);
        --  Returns a chunck of data in Buffer, Last point to the last element
        --  returned in Buffer.

        overriding function Size
          (Resource : Stream_Type) return Stream_Element_Offset;
        --  Returns the number of bytes in the memory stream

        overriding procedure Close (Resource : in out Stream_Type);
        --  Close the ZLib stream, release all memory associated with the Resource
        --  object.

     private
        --  implementation removed
     end AWS.Resources.Streams.Memory.ZLib;


File: aws.info,  Node: AWS.Resources.Streams.Pipe,  Next: AWS.Response,  Prev: AWS.Resources.Streams.Memory.ZLib,  Up: AWS API Reference

B.43 AWS.Resources.Streams.Pipe
===============================


     ------------------------------------------------------------------------------
     --                              Ada Web Server                              -
     --                                                                          -
     --                     Copyright (C) 2007-2012, AdaCore                     -
     --                                                                          -
     --  This library is free software;  you can redistribute it and/or modify   -
     --  it under terms of the  GNU General Public License  as published by the  -
     --  Free Software  Foundation;  either version 3,  or (at your  option) any -
     --  later version. This library is distributed in the hope that it will be  -
     --  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of -
     --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                    -
     --                                                                          -
     --  As a special exception under Section 7 of GPL version 3, you are        -
     --  granted additional permissions described in the GCC Runtime Library     -
     --  Exception, version 3.1, as published by the Free Software Foundation.   -
     --                                                                          -
     --  You should have received a copy of the GNU General Public License and   -
     --  a copy of the GCC Runtime Library Exception along with this program;    -
     --  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see   -
     --  <http://www.gnu.org/licenses/>.                                         -
     --                                                                          -
     --  As a special exception, if other files instantiate generics from this   -
     --  unit, or you link this unit with other files to produce an executable,  -
     --  this  unit  does not  by itself cause  the resulting executable to be   -
     --  covered by the GNU General Public License. This exception does not      -
     --  however invalidate any other reasons why the executable file  might be  -
     --  covered by the  GNU Public License.                                     -
     ------------------------------------------------------------------------------

     --  An ready-to-use implementation of the stream API where the stream content
     --  is read from a pipe.

     with Ada.Strings.Unbounded;

     with GNAT.Expect;
     with GNAT.OS_Lib;

     package AWS.Resources.Streams.Pipe is

        use GNAT;

        type Stream_Type is new Streams.Stream_Type with private;

        procedure Open
          (Pipe    : out Stream_Type;
           Command : String;
           Args    : OS_Lib.Argument_List;
           Timeout : Integer := 10_000);
        --  Open the pipe and connect it to the given command's output. Args are
        --  passed to the command. Timeout is given in milliseconds and corresponds
        --  to the time waiting for output data before timeout. This timeout must be
        --  adjusted to be compatible to the output activity of the Command process.

        overriding function End_Of_File (Resource : Stream_Type) return Boolean;

        overriding procedure Read
          (Resource : in out Stream_Type;
           Buffer   : out Stream_Element_Array;
           Last     : out Stream_Element_Offset);

        overriding procedure Close (Resource : in out Stream_Type);

        overriding procedure Reset (Resource : in out Stream_Type) is null;
        --  Does nothing as not supported on pipe streams

        overriding procedure Set_Index
          (Resource : in out Stream_Type;
           To       : Stream_Element_Offset) is null;
        --  Does nothing as not supported on pipe streams

     private
        --  implementation removed
     end AWS.Resources.Streams.Pipe;


File: aws.info,  Node: AWS.Response,  Next: AWS.Server,  Prev: AWS.Resources.Streams.Pipe,  Up: AWS API Reference

B.44 AWS.Response
=================


     ------------------------------------------------------------------------------
     --                              Ada Web Server                              -
     --                                                                          -
     --                    Copyright (C) 2000-2012, AdaCore                      -
     --                                                                          -
     --  This library is free software;  you can redistribute it and/or modify   -
     --  it under terms of the  GNU General Public License  as published by the  -
     --  Free Software  Foundation;  either version 3,  or (at your  option) any -
     --  later version. This library is distributed in the hope that it will be  -
     --  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of -
     --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                    -
     --                                                                          -
     --  As a special exception under Section 7 of GPL version 3, you are        -
     --  granted additional permissions described in the GCC Runtime Library     -
     --  Exception, version 3.1, as published by the Free Software Foundation.   -
     --                                                                          -
     --  You should have received a copy of the GNU General Public License and   -
     --  a copy of the GCC Runtime Library Exception along with this program;    -
     --  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see   -
     --  <http://www.gnu.org/licenses/>.                                         -
     --                                                                          -
     --  As a special exception, if other files instantiate generics from this   -
     --  unit, or you link this unit with other files to produce an executable,  -
     --  this  unit  does not  by itself cause  the resulting executable to be   -
     --  covered by the GNU General Public License. This exception does not      -
     --  however invalidate any other reasons why the executable file  might be  -
     --  covered by the  GNU Public License.                                     -
     ------------------------------------------------------------------------------

     --  This package is to be used to build answer to be sent to the client
     --  browser. It is also used as the object returned from the client API. So
     --  it is either a response built on the server side or the response received
     --  on the client side.

     with Ada.Calendar;
     with Ada.Strings.Unbounded;
     with Ada.Streams;
     with Ada.Finalization;
     with Ada.Unchecked_Deallocation;

     with AWS.Headers;
     with AWS.Messages;
     with AWS.MIME;
     with AWS.Net;
     with AWS.Resources.Streams;
     with AWS.Status;

     package AWS.Response is

        use Ada;
        use Ada.Streams;

        type Data is private;
        --  Note that this type use a reference counter which is not thread safe

        type Callback is access function (Request : Status.Data) return Data;
        --  This is the Web Server Callback procedure. A client must declare and
        --  pass such procedure to the HTTP server.

        type Data_Mode is
          (Header,         -- Send only the HTTP header
           Message,        -- Send a standard HTTP message
           File,           -- Send a file
           File_Once,      -- Send a file once, delete it after sending
           Stream,         -- Send a stream
           Socket_Taken,   -- Socket has been taken from the server
           WebSocket,      -- Protocol switched to WebSocket
           No_Data);       -- No data, this is not a response

        type Authentication_Mode is (Any, Basic, Digest);
        --  The authentication mode.
        --  "Basic" and "Digest" mean that server must accept the requested
        --  authentication mode. "Any" mean that server could accept any
        --  authentication from client.
        --  Note the order here should not be changed as it is used in AWS.Client.

        subtype Content_Length_Type
          is Stream_Element_Offset range -1 .. Stream_Element_Offset'Last;

        Undefined_Length : constant Content_Length_Type;
        --  Undefined length could be used when we do not know the message length
        --  at the start of transfer. The end of message could be determined by the
        --  chunked transfer-encoding in the HTTP/1.1, or by the closing connection
        --  in the HTTP/1.0.

        Default_Moved_Message : constant String;
        --  This is a template message, _@_ will be replaced by the Location (see
        --  function Build with Location below).

        Default_Authenticate_Message : constant String;
        --  This is the message that will be displayed on the Web Browser if the
        --  authentication process fails or is cancelled.

        -----------------------
        -- Data Constructors -
        -----------------------

        function Build
          (Content_Type  : String;
           Message_Body  : String;
           Status_Code   : Messages.Status_Code      := Messages.S200;
           Cache_Control : Messages.Cache_Option     := Messages.Unspecified;
           Encoding      : Messages.Content_Encoding := Messages.Identity)
           return Data;

        function Build
          (Content_Type    : String;
           UString_Message : Strings.Unbounded.Unbounded_String;
           Status_Code     : Messages.Status_Code      := Messages.S200;
           Cache_Control   : Messages.Cache_Option     := Messages.Unspecified;
           Encoding        : Messages.Content_Encoding := Messages.Identity)
           return Data;
        --  Return a message whose body is passed into Message_Body. The
        --  Content_Type parameter is the MIME type for the message
        --  body. Status_Code is the response status (see Messages.Status_Code
        --  definition).

        function Build
          (Content_Type  : String;
           Message_Body  : Streams.Stream_Element_Array;
           Status_Code   : Messages.Status_Code         := Messages.S200;
           Cache_Control : Messages.Cache_Option        := Messages.Unspecified;
           Encoding      : Messages.Content_Encoding    := Messages.Identity)
           return Data;
        --  Idem above, but the message body is a stream element array

        type Disposition_Mode is (Attachment, Inline, None);
        --  Describes the way a file/stream is sent to the browser.
        --
        --     Attachment  : The file is sent as an attachment, the browser
        --                   wont display the content even if the MIME type
        --                   is supported (.txt or .doc on IE for example).
        --
        --     Inline      : The file can be displayed inside the browser if
        --                   MIME type is supported. If not the browser will
        --                   propose to save this file.
        --
        --     None        : No specific setting is sent to the browser. The
        --                   browser default setting will be used. Note that in
        --                   this case the browser determine the filename using
        --                   the URI. This is the default setting.

        function File
          (Content_Type  : String;
           Filename      : String;
           Status_Code   : Messages.Status_Code      := Messages.S200;
           Cache_Control : Messages.Cache_Option     := Messages.Unspecified;
           Encoding      : Messages.Content_Encoding := Messages.Identity;
           Once          : Boolean                   := False;
           Disposition   : Disposition_Mode          := None;
           User_Filename : String                    := "")
           return Data;
        --  Returns a message whose message body is the content of the file. The
        --  Content_Type must indicate the MIME type for the file. User_Filename
        --  can be used to force the filename on the client side. This can be
        --  different from the server side Filename. If Once is set to True the
        --  file will be deleted after the download (this includes the case where
        --  the download is suspended).

        function Stream
          (Content_Type  : String;
           Handle        : not null access Resources.Streams.Stream_Type'Class;
           Status_Code   : Messages.Status_Code      := Messages.S200;
           Cache_Control : Messages.Cache_Option     := Messages.No_Cache;
           Encoding      : Messages.Content_Encoding := Messages.Identity;
           Server_Close  : Boolean                   := True;
           Disposition   : Disposition_Mode          := None;
           User_Filename : String                    := "")
           return Data;
        --  Returns a message whose message body is the content of the user defined
        --  stream. The Content_Type must indicate the MIME type for the data
        --  stream, Status_Code is the the header status code which should be send
        --  back to client's browser. If Server_Close is set to False the server
        --  will not close the stream after sending it, it is then user's
        --  responsability to close the stream. User_Filename can be used to force
        --  the filename on the client side. This can be different from the server
        --  side filename (for file based stream) or can be used to name a non disk
        --  based stream.

        ------------------------------
        -- Redirection Constructors -
        ------------------------------

        function URL
          (Location      : String;
           Cache_Control : Messages.Cache_Option := Messages.Unspecified)
           return Data;
        --  This ask the server for a redirection to the specified URL. This is
        --  a temporary redirection, and the client browser should query the
        --  same original URL next time.

        function Moved
          (Location      : String;
           Message       : String                := Default_Moved_Message;
           Cache_Control : Messages.Cache_Option := Messages.Unspecified)
           return Data;
        --  This send back a moved message (Messages.S301) with the specified
        --  message body.
        --  This is a permanent redirection, and the client browser is encouraged
        --  to update links so that the next query for the URL goes directly to
        --  the new location.

        ------------------------
        -- Other Constructors -
        ------------------------

        function Acknowledge
          (Status_Code  : Messages.Status_Code;
           Message_Body : String := "";
           Content_Type : String := MIME.Text_HTML) return Data;
        --  Returns a message to the Web browser. This routine must be used to
        --  send back an error message to the Web browser. For example if a
        --  requested resource cannot be served a message with status code S404
        --  must be sent.

        function Authenticate
          (Realm   : String;
           Mode    : Authentication_Mode := Basic;
           Stale   : Boolean             := False;
           Message : String              := Default_Authenticate_Message)
           return Data;
        --  Returns an authentication message (Messages.S401), the Web browser
        --  will then ask for an authentication. Realm string will be displayed
        --  by the Web Browser in the authentication dialog box.

        function Socket_Taken return Data;
        --  Must be used to say that the connection socket has been taken by user
        --  inside of user callback. No operations should be performed on this
        --  socket, and associated slot should be released for further operations.

        function Empty return Data;
        --  Returns an empty message (Data_Mode = No_Data and Status_Code is 204).
        --  It is used to say that user's handlers were not able to do something
        --  with the request. This is used by the callback's chain in the
        --  dispatchers and should not be used by users.

        --
        --  API to retrieve response data
        --

        ------------
        -- Header -
        ------------

        function Header (D : Data; Name : String; N : Positive) return String;
        pragma Inline (Header);
        --  Return the N-th value for header Name

        function Header (D : Data; Name : String) return String;
        pragma Inline (Header);
        --  Return all values as a comma-separated string for header Name.
        --  See [RFC 2616 - 4.2] last paragraph.

        function Header (D : Data) return AWS.Headers.List;

        procedure Send_Header (Socket : Net.Socket_Type'Class; D : Data);
        pragma Inline (Send_Header);
        --  Send all header lines to the socket

        function Status_Code (D : Data) return Messages.Status_Code;
        pragma Inline (Status_Code);
        --  Returns the status code

        function Content_Length (D : Data) return Content_Length_Type;
        pragma Inline (Content_Length);
        --  Returns the content length (i.e. the message body length). A value of 0
        --  indicate that there is no message body.

        function Content_Type (D : Data) return String;
        pragma Inline (Content_Type);
        --  Returns the MIME type for the message body

        function Cache_Control (D : Data) return Messages.Cache_Option;
        pragma Inline (Cache_Control);
        --  Returns the cache control specified for the response

        function Cache_Control (D : Data) return Messages.Cache_Data;
        --  As above but returns a structured record of type "Cache_Data (Request)"
        --  representing the cache options.

        function Expires (D : Data) return Calendar.Time;
        pragma Inline (Expires);
        --  Returns the Expires date as a time value

        function Location (D : Data) return String;
        pragma Inline (Location);
        --  Returns the location for the new page in the case of a moved
        --  message. See Moved constructor above.

        ----------
        -- Data -
        ----------

        function Mode (D : Data) return Data_Mode;
        pragma Inline (Mode);
        --  Returns the data mode, either Header, Message or File

        function Is_Empty (D : Data) return Boolean;
        pragma Inline (Is_Empty);
        --  Returns True if D.Mode is No_Data

        function Message_Body (D : Data) return String;
        pragma Inline (Message_Body);
        --  Returns the message body content as a string.
        --  Message_Body routines could not be used with user defined streams
        --  (see. Stream routine in this package). Constraint_Error would be raised
        --  on try to get data by the Message_Body from the user defined streams.
        --  For get data from user defined streams routine Create_Resource should
        --  be used.

        function Message_Body (D : Data) return Strings.Unbounded.Unbounded_String;
        --  Returns message body content as an unbounded_string

        function Message_Body (D : Data) return Streams.Stream_Element_Array;
        --  Returns message body as a binary content

        procedure Message_Body
          (D    : Data;
           File : out AWS.Resources.File_Type);
        --  Returns the message body as a stream

        function Filename (D : Data) return String;
        pragma Inline (Filename);
        --  Returns the filename which should be sent back

        --------------------
        -- Authentication -
        --------------------

        function Realm (D : Data) return String;
        pragma Inline (Realm);
        --  Returns the Realm for the current authentication request

        function Authentication (D : Data) return Authentication_Mode;
        pragma Inline (Authentication);
        --  Returns the authentication mode requested by server

        function Authentication_Stale (D : Data) return Boolean;
        pragma Inline (Authentication_Stale);
        --  Returns the stale parameter for authentication

        ---------------
        -- Resources -
        ---------------

        procedure Create_Resource
          (D    : in out Data;
           File : out AWS.Resources.File_Type;
           GZip : Boolean);
        pragma Inline (Create_Resource);
        --  Creates the resource object (either a file or in-memory object) for
        --  the data to be sent to the client. The resource should be closed after
        --  use.
        --  GZip is true when the http client support GZip decoding,
        --  if file or embedded resource is in the GZip format this routine would
        --  define Content-Encoding header field value.

        function Close_Resource (D : Data) return Boolean;
        --  Returns True if the resource stream must be close

        ----------------
        -- WebSockets -
        ----------------

        function WebSocket return Data;
        --  WebSocket handshake from initial WebSocket connection

     private
        --  implementation removed
     end AWS.Response;


File: aws.info,  Node: AWS.Server,  Next: AWS.Server.Hotplug,  Prev: AWS.Response,  Up: AWS API Reference

B.45 AWS.Server
===============


     ------------------------------------------------------------------------------
     --                              Ada Web Server                              -
     --                                                                          -
     --                     Copyright (C) 2000-2013, AdaCore                     -
     --                                                                          -
     --  This library is free software;  you can redistribute it and/or modify   -
     --  it under terms of the  GNU General Public License  as published by the  -
     --  Free Software  Foundation;  either version 3,  or (at your  option) any -
     --  later version. This library is distributed in the hope that it will be  -
     --  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of -
     --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                    -
     --                                                                          -
     --  As a special exception under Section 7 of GPL version 3, you are        -
     --  granted additional permissions described in the GCC Runtime Library     -
     --  Exception, version 3.1, as published by the Free Software Foundation.   -
     --                                                                          -
     --  You should have received a copy of the GNU General Public License and   -
     --  a copy of the GCC Runtime Library Exception along with this program;    -
     --  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see   -
     --  <http://www.gnu.org/licenses/>.                                         -
     --                                                                          -
     --  As a special exception, if other files instantiate generics from this   -
     --  unit, or you link this unit with other files to produce an executable,  -
     --  this  unit  does not  by itself cause  the resulting executable to be   -
     --  covered by the GNU General Public License. This exception does not      -
     --  however invalidate any other reasons why the executable file  might be  -
     --  covered by the  GNU Public License.                                     -
     ------------------------------------------------------------------------------

     with Ada.Calendar;
     with Ada.Exceptions;
     with Ada.Finalization;
     with Ada.Real_Time;
     with Ada.Task_Attributes;
     with System;

     with AWS.Config;
     with AWS.Default;
     with AWS.Dispatchers;
     with AWS.Exceptions;
     with AWS.Hotplug;
     with AWS.Log;
     with AWS.Net.Acceptors;
     with AWS.Net.SSL;
     with AWS.Response;
     with AWS.Status;
     with AWS.Utils;

     package AWS.Server is

        type HTTP is limited private;
        --  A Web server

        ---------------------------
        -- Server initialization -
        ---------------------------

        --  Note that starting a sercure server if AWS has not been configured to
        --  support HTTPS will raise Program_Error.

        procedure Start
          (Web_Server : in out HTTP;
           Callback   : Response.Callback;
           Config     : AWS.Config.Object);
        --  Start server using a full configuration object. With this routine it is
        --  possible to control all features of the server. A simplified version of
        --  Start is also provided below with the most common options.

        procedure Start
          (Web_Server : in out HTTP;
           Dispatcher : Dispatchers.Handler'Class;
           Config     : AWS.Config.Object);
        --  Idem, but using the dispatcher tagged type instead of callback. See
        --  AWS.Services.Dispatchers and AWS.Dispatchers hierarchies for built-in
        --  services and interface to build your own dispatcher models.
        --  Note that a copy of the Dispatcher is keept into Web_Server. Any
        --  changes done to the Dispatcher object will not be part of the Web
        --  server dispatcher.

        procedure Get_Message_Body;
        --  If size of message body is bigger than Upload_Size_Limit configuration
        --  parameter, server do not receive message body before calling user's
        --  callback routine. If user decide to get the message body he should call
        --  this routine.

        procedure Start
          (Web_Server                : in out HTTP;
           Name                      : String;
           Callback                  : Response.Callback;
           Max_Connection            : Positive  := Default.Max_Connection;
           Admin_URI                 : String    := Default.Admin_URI;
           Port                      : Natural   := Default.Server_Port;
           Security                  : Boolean   := False;
           Session                   : Boolean   := False;
           Case_Sensitive_Parameters : Boolean   := True;
           Upload_Directory          : String    := Default.Upload_Directory;
           Line_Stack_Size           : Positive  := Default.Line_Stack_Size);
        --  Start the Web server. Max_Connection is the number of simultaneous
        --  connections the server's will handle (the number of slots in AWS).
        --  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
        --  parameters name will be handled without case sensitivity. Upload
        --  directory point to a directory where uploaded files will be stored.

        ------------------------
        -- Server termination -
        ------------------------

        procedure Shutdown (Web_Server : in out HTTP);
        --  Stop the server and release all associated memory. This routine can
        --  take some time to terminate because it waits for all tasks to terminate
        --  properly before releasing the memory. The log facilities will be
        --  automatically stopped by calling Stop_Log below.

        type Termination is (No_Server, Q_Key_Pressed, Forever);

        procedure Wait (Mode : Termination := No_Server);
        --  The purpose of this procedure is to control the main procedure
        --  termination. This procedure will return only when no server are running
        --  (No_Server mode) or the 'q' key has been pressed. If mode is set to
        --  Forever, Wait will never return and the process will have to be killed.

        --------------------------
        -- Server configuration -
        --------------------------

        function Config (Web_Server : HTTP) return AWS.Config.Object;
        --  Returns configuration object for Web_Server

        procedure Set_Unexpected_Exception_Handler
          (Web_Server : in out HTTP;
           Handler    : Exceptions.Unexpected_Exception_Handler);
        --  Set the unexpected exception handler. It is called whenever an
        --  unrecoverable error has been detected. The default handler just display
        --  (on standard output) an error message with the location of the
        --  error. By changing this handler it is possible to log or display full
        --  symbolic stack backtrace if needed.

        procedure Set
          (Web_Server : in out HTTP;
           Dispatcher : Dispatchers.Handler'Class);
        --  Dynamically associate a new dispatcher object to the server. With the
        --  feature it is possible to change server behavior at runtime. The
        --  complete set of callback procedures will be changed when calling this
        --  routine. Note that any change in a dispatcher associated with a server
        --  using Register or Unregister must be reset into the server using this
        --  routine.

        procedure Set_Security
          (Web_Server           : in out HTTP;
           Certificate_Filename : String;
           Security_Mode        : Net.SSL.Method := Net.SSL.SSLv23_Server;
           Key_Filename         : String         := "");
        --  Set security option for AWS. Certificate_Filename is the name of a file
        --  containing a certificate. Key_Filename is the name of the file
        --  containing the key, if the empty string the key will be taken from the
        --  certificate filename. This must be called before starting the secure
        --  server otherwise the default security options or options set in the
        --  config files will be used. After that the call will have no effect.

        procedure Set_SSL_Config
          (Web_Server : in out HTTP; SSL_Config : Net.SSL.Config);
        --  Set the SSL configuration for this server

        procedure Set_Socket_Constructor
          (Web_Server         : in out HTTP;
           Socket_Constructor : Net.Socket_Constructor);
        --  Set the socket constructor routine to use when creating new sockets on
        --  the server. By calling this routine it is possible to replace the
        --  default AWS communication layer used. The default constructor is
        --  AWS.Net.Socket. Note that this routine must be called before starting
        --  the server. It is also important to note that sockets returned by the
        --  constructor must have the cache properly initialized. See AWS.Net.Cache
        --  for more information.

        type HTTP_Access is access all HTTP;

        function Get_Current return HTTP_Access;
        --  Get current server. This can be used in a callback procedure to
        --  retrieve the running HTTP server. It is needed when a callback
        --  procedure is shared by multiple servers.

        function Get_Status return Status.Data;
        --  Returns the current status data. This is useful to get the full status
        --  in a templates engine callback procedure for example.

        function Session_Name return String;
        --  Returns the current session cookie name

        ---------------
        -- Other API -
        ---------------

        procedure Give_Back_Socket
          (Web_Server : in out HTTP; Socket : Net.Socket_Type'Class);
        --  Give the socket back to the server. Socket must have been taken from
        --  the server using the Response.Socket_Taken routine in a callback.

        procedure Give_Back_Socket
          (Web_Server : in out HTTP; Socket : Net.Socket_Access);
        --  Idem.
        --  Use Socket_Access to avoid memory reallocation for already allocated
        --  sockets.

        procedure Set_Field (Id, Value : String);
        --  Set the extended log field value for the server the controlling the
        --  current task.

        procedure Skip_Log_Record;
        --  Disable logging only for the current processing request

        procedure Add_Listening
          (Web_Server    : in out HTTP;
           Host          : String;
           Port          : Natural;
           Family        : Net.Family_Type := Net.Family_Unspec;
           Reuse_Address : Boolean         := False);
        --  Add the binded/listening socket on host, port and protocol family. To be
        --  able to connect web enabled application with others in the internal
        --  network, and then give access for external clients by listening on
        --  externally available address. Also it could be used to bind one server
        --  to IPv4 and IPv6 protocols simultaneously.

     private
        --  implementation removed
     end AWS.Server;


File: aws.info,  Node: AWS.Server.Hotplug,  Next: AWS.Server.Log,  Prev: AWS.Server,  Up: AWS API Reference

B.46 AWS.Server.Hotplug
=======================


     ------------------------------------------------------------------------------
     --                              Ada Web Server                              -
     --                                                                          -
     --                      Copyright (C) 2000-2012, AdaCore                    -
     --                                                                          -
     --  This library is free software;  you can redistribute it and/or modify   -
     --  it under terms of the  GNU General Public License  as published by the  -
     --  Free Software  Foundation;  either version 3,  or (at your  option) any -
     --  later version. This library is distributed in the hope that it will be  -
     --  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of -
     --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                    -
     --                                                                          -
     --  As a special exception under Section 7 of GPL version 3, you are        -
     --  granted additional permissions described in the GCC Runtime Library     -
     --  Exception, version 3.1, as published by the Free Software Foundation.   -
     --                                                                          -
     --  You should have received a copy of the GNU General Public License and   -
     --  a copy of the GCC Runtime Library Exception along with this program;    -
     --  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see   -
     --  <http://www.gnu.org/licenses/>.                                         -
     --                                                                          -
     --  As a special exception, if other files instantiate generics from this   -
     --  unit, or you link this unit with other files to produce an executable,  -
     --  this  unit  does not  by itself cause  the resulting executable to be   -
     --  covered by the GNU General Public License. This exception does not      -
     --  however invalidate any other reasons why the executable file  might be  -
     --  covered by the  GNU Public License.                                     -
     ------------------------------------------------------------------------------

     with AWS.Hotplug;

     package AWS.Server.Hotplug is

        --  Messages used to register/unregister hotplug modules

        Register_Message      : constant String := "REGISTER";
        Unregister_Message    : constant String := "UNREGISTER";
        Request_Nonce_Message : constant String := "REQUEST_NONCE";

        --  The Authorization_File below is a file that contains authorizations
        --  for the hotplug modules. Only modules that have an entry into this
        --  file will be able to register to server. Each line on this file must
        --  have the following format:
        --
        --  <module_name>:<md5_password>:<host>:<port>
        --
        --  module_name  : The name of the module that will register
        --  md5_password : The corresponding password, use aws_password
        --                 tool to generate such password
        --  host         : The host name where requests will be redirected
        --  port         : and the corresponding port

        procedure Activate
          (Web_Server         : HTTP_Access;
           Port               : Positive;
           Authorization_File : String;
           Register_Mode      : AWS.Hotplug.Register_Mode := AWS.Hotplug.Add;
           Host               : String                    := "");
        --  Start hotplug server listening at the specified Port for the Web_Server.
        --  Only client modules listed in the authorization file will be able to
        --  connect to this server. For better securite the host of redictection
        --  must also be specified.

        procedure Shutdown;
        --  Shutdown hotplug server

     end AWS.Server.Hotplug;


File: aws.info,  Node: AWS.Server.Log,  Next: AWS.Server.Push,  Prev: AWS.Server.Hotplug,  Up: AWS API Reference

B.47 AWS.Server.Log
===================


     ------------------------------------------------------------------------------
     --                              Ada Web Server                              -
     --                                                                          -
     --                     Copyright (C) 2003-2012, AdaCore                     -
     --                                                                          -
     --  This library is free software;  you can redistribute it and/or modify   -
     --  it under terms of the  GNU General Public License  as published by the  -
     --  Free Software  Foundation;  either version 3,  or (at your  option) any -
     --  later version. This library is distributed in the hope that it will be  -
     --  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of -
     --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                    -
     --                                                                          -
     --  As a special exception under Section 7 of GPL version 3, you are        -
     --  granted additional permissions described in the GCC Runtime Library     -
     --  Exception, version 3.1, as published by the Free Software Foundation.   -
     --                                                                          -
     --  You should have received a copy of the GNU General Public License and   -
     --  a copy of the GCC Runtime Library Exception along with this program;    -
     --  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see   -
     --  <http://www.gnu.org/licenses/>.                                         -
     --                                                                          -
     --  As a special exception, if other files instantiate generics from this   -
     --  unit, or you link this unit with other files to produce an executable,  -
     --  this  unit  does not  by itself cause  the resulting executable to be   -
     --  covered by the GNU General Public License. This exception does not      -
     --  however invalidate any other reasons why the executable file  might be  -
     --  covered by the  GNU Public License.                                     -
     ------------------------------------------------------------------------------

     with AWS.Log;

     package AWS.Server.Log is

        ------------------
        -- Standard Log -
        ------------------

        procedure Start
          (Web_Server      : in out HTTP;
           Split_Mode      : AWS.Log.Split_Mode := AWS.Log.None;
           Filename_Prefix : String             := "";
           Auto_Flush      : Boolean            := False);
        --  Activate server's logging activity. See AWS.Log. If Auto_Flush is True
        --  the file will be flushed after all written data.

        procedure Start
          (Web_Server : in out HTTP;
           Callback   : AWS.Log.Callback;
           Name       : String);
        --  Activate the Web_Server access log and direct all data to the Callback.
        --  The Name String is returned when the Name function is called. It is a
        --  simple identifier, that serves no other purpose than to give the
        --  Callback a label.

        function Name (Web_Server : HTTP) return String;
        --  Return the name of the Log or an empty string if one is not active. If
        --  an external writer is used to handle the access log, then the name of
        --  that writer is returned. See the Start procedure for starting the access
        --  log with a Callback.

        procedure Stop (Web_Server : in out HTTP);
        --  Stop server's logging activity. See AWS.Log

        function Is_Active (Web_Server : HTTP) return Boolean;
        --  Returns True if the Web Server log has been activated

        procedure Flush (Web_Server : in out HTTP);
        --  Flush the server log.
        --  Note that error log does not need to be flushed because it is always
        --  flushed by default. If a Callback procedure is used to handle the log
        --  data, then calling Flush does nothing.

        ---------------
        -- Error Log -
        ---------------

        procedure Start_Error
          (Web_Server      : in out HTTP;
           Split_Mode      : AWS.Log.Split_Mode := AWS.Log.None;
           Filename_Prefix : String             := "");
        --  Activate server's logging activity. See AWS.Log

        procedure Start_Error
          (Web_Server : in out HTTP;
           Callback   : AWS.Log.Callback;
           Name       : String);
        --  Activate the Web_Server error log and direct all data to the Callback.
        --  The Name String is returned when the Error_Name function is called. It
        --  is a simple identifier, that serves no other purpose than to give the
        --  Callback a label.

        function Error_Name (Web_Server : HTTP) return String;
        --  Return the name of the Error Log or an empty string if one is not
        --  active. If a Callback is used to handle the error log, then the name of
        --  the Callback is returned. See the Start_Error procedure for starting the
        --  error log with a Callback.

        procedure Stop_Error (Web_Server : in out HTTP);
        --  Stop server's logging activity. See AWS.Log

        function Is_Error_Active (Web_Server : HTTP) return Boolean;
        --  Returns True if the Web Server error log has been activated

     end AWS.Server.Log;


File: aws.info,  Node: AWS.Server.Push,  Next: AWS.Server.Status,  Prev: AWS.Server.Log,  Up: AWS API Reference

B.48 AWS.Server.Push
====================


     ------------------------------------------------------------------------------
     --                              Ada Web Server                              -
     --                                                                          -
     --                     Copyright (C) 2000-2012, AdaCore                     -
     --                                                                          -
     --  This library is free software;  you can redistribute it and/or modify   -
     --  it under terms of the  GNU General Public License  as published by the  -
     --  Free Software  Foundation;  either version 3,  or (at your  option) any -
     --  later version. This library is distributed in the hope that it will be  -
     --  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of -
     --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                    -
     --                                                                          -
     --  As a special exception under Section 7 of GPL version 3, you are        -
     --  granted additional permissions described in the GCC Runtime Library     -
     --  Exception, version 3.1, as published by the Free Software Foundation.   -
     --                                                                          -
     --  You should have received a copy of the GNU General Public License and   -
     --  a copy of the GCC Runtime Library Exception along with this program;    -
     --  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see   -
     --  <http://www.gnu.org/licenses/>.                                         -
     --                                                                          -
     --  As a special exception, if other files instantiate generics from this   -
     --  unit, or you link this unit with other files to produce an executable,  -
     --  this  unit  does not  by itself cause  the resulting executable to be   -
     --  covered by the GNU General Public License. This exception does not      -
     --  however invalidate any other reasons why the executable file  might be  -
     --  covered by the  GNU Public License.                                     -
     ------------------------------------------------------------------------------

     --  Package to support Server Push feature. This is only supported by Netscape
     --  browsers. It will not work with Microsoft Internet Explorer.
     --  For Microsoft Internet Explorer complementary active components
     --  should be used like java applets or ActiveX controls.

     with Ada.Containers.Indefinite_Hashed_Sets;
     with Ada.Containers.Indefinite_Hashed_Maps;
     with Ada.Containers.Indefinite_Doubly_Linked_Lists;
     with Ada.Strings.Hash;
     with Ada.Streams;
     with Ada.Strings.Unbounded;

     with AWS.Containers.Tables;
     with AWS.Default;
     with AWS.Net;

     with System;

     generic

        type Client_Output_Type (<>) is private;
        --  Data type client want to send through server push

        type Client_Environment is private;
        --  Data type to keep client context. This context will be passed to the
        --  conversion routine below.

        with function To_Stream_Array
          (Output : Client_Output_Type;
           Client : Client_Environment) return Ada.Streams.Stream_Element_Array;
        --  Function used for convert Client_Output_Type to Stream_Output_Type.
        --  This is used by the server to prepare the data to be sent to the
        --  clients.

     package AWS.Server.Push is

        use Ada.Strings.Unbounded;

        Client_Gone : exception;
        --  Raised when a client is not responding

        Closed : exception;
        --  Raised when trying to register to a closed push server

        Duplicate_Client_Id : exception;
        --  Raised in trying to register an already registered client

        type Object is limited private;
        --  This is the push server object. A push server has two modes, either it
        --  is Open or Closed. When open it will send data to registered
        --  clients. No data will be sent to registered client if the server is
        --  Closed.

        type Mode is (Plain, Multipart, Chunked);
        --  Describeed the mode to communicate with the client.
        --  Plain     : no transformation is done, the data are sent as-is
        --  Multipart : data are MIME encoded.
        --  Chuncked  : data are chunked, a piece of data is sent in small pieces.

        subtype Client_Key is String;
        --  The Client Id key representation. In a server each client must have a
        --  uniq ID. This Id is used for registration and for sending data to
        --  specific client.

        type Wait_Counter_Type is mod System.Max_Binary_Modulus;

        subtype Group_Set is Containers.Tables.VString_Array;

        Empty_Group : constant Group_Set := (1 .. 0 => Null_Unbounded_String);

        procedure Register
          (Server            : in out Object;
           Client_Id         : Client_Key;
           Socket            : Net.Socket_Access;
           Environment       : Client_Environment;
           Init_Data         : Client_Output_Type;
           Init_Content_Type : String             := "";
           Kind              : Mode               := Plain;
           Duplicated_Age    : Duration           := Duration'Last;
           Groups            : Group_Set          := Empty_Group;
           Timeout           : Duration           := Default.Send_Timeout);
        --  Add client identified by Client_Id to the server subscription
        --  list and send the Init_Data (as a Init_Content_Type mime content) to
        --  him. After registering this client will be able to receive pushed data
        --  from the server in brodcasting mode.
        --  If Duplicated_Age less than age of the already registered same Client_Id
        --  then old one will be unregistered first (no exception will be raised).
        --  The Timeout is not for socket send timeout, but for internal waiting for
        --  write availability timeout.

        procedure Register
          (Server            : in out Object;
           Client_Id         : Client_Key;
           Socket            : Net.Socket_Type'Class;
           Environment       : Client_Environment;
           Init_Data         : Client_Output_Type;
           Init_Content_Type : String             := "";
           Kind              : Mode               := Plain;
           Duplicated_Age    : Duration           := Duration'Last;
           Groups            : Group_Set          := Empty_Group;
           Timeout           : Duration           := Default.Send_Timeout);
        --  Same as above but with Socket_Type'Class parameter.
        --  Is not recommended, use above one with Socket_Access parameter.

        procedure Register
          (Server         : in out Object;
           Client_Id      : Client_Key;
           Socket         : Net.Socket_Type'Class;
           Environment    : Client_Environment;
           Content_Type   : String             := "";
           Kind           : Mode               := Plain;
           Duplicated_Age : Duration           := Duration'Last;
           Groups         : Group_Set          := Empty_Group;
           Timeout        : Duration           := Default.Send_Timeout);
        --  Same as above but without sending initial data.
        --  Content_Type applicable only when Kind parameter is Plain or Chunked,
        --  in Multipart server push mode each server push message would have own
        --  Content_Type defined.
        --  Is not recommended, use above one with Socket_Access parameter.

        procedure Unregister
          (Server       : in out Object;
           Client_Id    : Client_Key;
           Close_Socket : Boolean    := True);
        --  Removes client Client_Id from server subscription list. The associated
        --  client's socket will be closed if Close_Socket is True. No exception is
        --  raised if Client_Id was not registered.

        procedure Unregister_Clients
          (Server : in out Object; Close_Sockets : Boolean := True);
        --  Remove all registered clients from the server. Closes if Close_Sockets
        --  is set to True (default) otherwise the sockets remain open. After this
        --  call the sever will still in running mode. Does nothing if there is no
        --  client registered.

        procedure Subscribe
          (Server : in out Object; Client_Id : Client_Key; Group_Id : String);
        --  Subscribe client to the group

        procedure Subscribe_Copy
          (Server : in out Object; Source : String; Target : String);
        --  Subscribe everybody in the group Source to the group Target.
        --  If Source is empty then subscribe all clients to the group Target.

        procedure Unsubscribe
          (Server : in out Object; Client_Id : Client_Key; Group_Id : String);
        --  Remove group from client's group list

        procedure Unsubscribe_Copy
          (Server : in out Object; Source : String; Target : String);
        --  Unsubscribe everybody in the group Source from the group Target.
        --  If Source is empty then unsubscribe all clients from the group Target.

        procedure Send_To
          (Server       : in out Object;
           Client_Id    : Client_Key;
           Data         : Client_Output_Type;
           Content_Type : String             := "";
           Thin_Id      : String             := "");
        --  Push data to a specified client identified by Client_Id
        --  Thin_Id is to be able to replace messages in the send client queue
        --  with the newer one with the same Thin_Id.

        procedure Send
          (Server       : in out Object;
           Data         : Client_Output_Type;
           Group_Id     : String             := "";
           Content_Type : String             := "";
           Thin_Id      : String             := "";
           Client_Gone  : access procedure (Client_Id : String) := null);
        --  Push data to group of clients (broadcast) subscribed to the server.
        --  If Group_Id is empty, data transferred to each client.
        --  Call Client_Gone for each client with broken socket.
        --  Thin_Id is to be able to replace messages in the send client queue
        --  with the newer one with the same Thin_Id.

        generic
           with procedure Client_Gone (Client_Id : String);
        procedure Send_G
          (Server       : in out Object;
           Data         : Client_Output_Type;
           Group_Id     : String             := "";
           Content_Type : String             := "";
           Thin_Id      : String             := "");
        --  Same like before, but generic for back compartibility

        function Count (Server : Object) return Natural;
        --  Returns the number of registered clients in the server

        procedure Info
          (Server  : in out Object;
           Clients : out Natural;
           Groups  : out Natural;
           Process : access procedure
                       (Client_Id   : Client_Key;
                        Address     : String;
                        State       : String;
                        Environment : Client_Environment;
                        Kind        : Mode;
                        Groups      : Group_Set) := null);
        --  Returns the number of registered clients and groups in the server.
        --  Call Process routine for each client if defined.
        --  Test internal integrity.

        function Is_Open (Server : Object) return Boolean;
        --  Return True if the server is open, meaning server is still running,
        --  ready to accept client's registration and still sending data to
        --  clients.

        --  Shutdown routines put the server in a Closed mode. The routines below
        --  provides a way to eventually close the socket, to send some
        --  finalisation data.

        procedure Shutdown
          (Server : in out Object; Close_Sockets : Boolean := True);
        --  Unregisted all clients and close all associated connections (socket) if
        --  Close_Socket is True. The server will be in Closed mode. After this
        --  call any client trying to register will get the Closed exception. It is
        --  possible to reactivate the server with Restart.

        procedure Shutdown
          (Server             : in out Object;
           Final_Data         : Client_Output_Type;
           Final_Content_Type : String             := "");
        --  Idem as above but it send Final_Data (as a Data_Content_Type mime
        --  content) before closing connections.

        procedure Shutdown_If_Empty (Server : in out Object; Open : out Boolean);
        --  Server will be shutdown (close mode) if there is no more active clients
        --  (Count = 0). Returns new server status in Open (Open will be True if
        --  server is in Open mode and False otherwise). After this call any client
        --  trying to register will get the Closed exception. It is possible to
        --  reactivate the server with Restart.

        procedure Restart (Server : in out Object);
        --  Set server to Open mode. Server will again send data to registered
        --  clients. It does nothing if server was already open.

        procedure Info
          (Size        : out Natural;
           Max_Size    : out Natural;
           Max_Size_DT : out Ada.Calendar.Time;
           Counter     : out Wait_Counter_Type);
        --  Size would return number of currently waiting sockets.
        --  Counter would return total number of waited sockets from start.

        function Wait_Send_Completion (Timeout : Duration) return Boolean;
        --  Wait for all data sending in all server_push objects of the current
        --  package instance.
        --  Return True if wait successfull. False in timeout.

        type Error_Handler is access procedure (Message : String);

        procedure Set_Internal_Error_Handler (Handler : Error_Handler);
        --  Set the handler of the internal fatal errors

     private
        --  implementation removed
     end AWS.Server.Push;


File: aws.info,  Node: AWS.Server.Status,  Next: AWS.Services.Callbacks,  Prev: AWS.Server.Push,  Up: AWS API Reference

B.49 AWS.Server.Status
======================


     ------------------------------------------------------------------------------
     --                              Ada Web Server                              -
     --                                                                          -
     --                     Copyright (C) 2003-2012, AdaCore                     -
     --                                                                          -
     --  This library is free software;  you can redistribute it and/or modify   -
     --  it under terms of the  GNU General Public License  as published by the  -
     --  Free Software  Foundation;  either version 3,  or (at your  option) any -
     --  later version. This library is distributed in the hope that it will be  -
     --  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of -
     --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                    -
     --                                                                          -
     --  As a special exception under Section 7 of GPL version 3, you are        -
     --  granted additional permissions described in the GCC Runtime Library     -
     --  Exception, version 3.1, as published by the Free Software Foundation.   -
     --                                                                          -
     --  You should have received a copy of the GNU General Public License and   -
     --  a copy of the GCC Runtime Library Exception along with this program;    -
     --  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see   -
     --  <http://www.gnu.org/licenses/>.                                         -
     --                                                                          -
     --  As a special exception, if other files instantiate generics from this   -
     --  unit, or you link this unit with other files to produce an executable,  -
     --  this  unit  does not  by itself cause  the resulting executable to be   -
     --  covered by the GNU General Public License. This exception does not      -
     --  however invalidate any other reasons why the executable file  might be  -
     --  covered by the  GNU Public License.                                     -
     ------------------------------------------------------------------------------

     --  This package provides routine to retrieve server's internal status

     with Ada.Calendar;

     with AWS.Templates;

     package AWS.Server.Status is

        function Translations (Server : HTTP) return Templates.Translate_Set;
        --  Returns a translate table to be used with a template file. This table
        --  contains all internal server's data. This table is used by the server
        --  internal status page for example.

        function Translations (Server : HTTP) return Templates.Translate_Table;
        pragma Obsolescent ("Use Translate_Set return value instead");
        --  The same as above but obsolete and keept for backward compartibility

        function Start_Time (Server : HTTP) return Ada.Calendar.Time;
        --  Returns the server's start time

        function Resources_Served (Server : HTTP) return Natural;
        --  Returns the total number of resources (static file, templates,
        --  in-memory string) served by the server.

        function Socket (Server : HTTP) return Net.Socket_Type'Class;
        --  Returns the main server's socket

        function Sockets (Server : HTTP) return Net.Acceptors.Socket_List;
        --  Returns all server's sockets

        function Port (Server : HTTP) return Positive;
        --  Returns the server's socket port

        function Host (Server : HTTP) return String;
        --  Returns the server's socket host

        function Is_Any_Address (Server : HTTP) return Boolean;
        --  Returns True if the server accepts connections on any of the host's
        --  network addresses.

        function Is_IPv6 (Server : HTTP) return Boolean;
        --  Returns True if Server is using IPv6

        function Local_URL (Server : HTTP) return String;
        --  Local URL of the server

        function Current_Connections (Server : HTTP) return Natural;
        --  Returns the current number of connections

        function Is_Session_Activated (Server : HTTP) return Boolean;
        --  Returns True if the session feature has been activated

        function Is_Security_Activated (Server : HTTP) return Boolean;
        --  Returns True if the HTTPS protocol is used

        function Is_Shutdown (Server : HTTP) return Boolean;
        --  Returns True if server has been stopped (the server could still be in
        --  the shutdown phase).

     end AWS.Server.Status;


File: aws.info,  Node: AWS.Services.Callbacks,  Next: AWS.Services.Directory,  Prev: AWS.Server.Status,  Up: AWS API Reference

B.50 AWS.Services.Callbacks
===========================


     ------------------------------------------------------------------------------
     --                              Ada Web Server                              -
     --                                                                          -
     --                     Copyright (C) 2004-2012, AdaCore                     -
     --                                                                          -
     --  This library is free software;  you can redistribute it and/or modify   -
     --  it under terms of the  GNU General Public License  as published by the  -
     --  Free Software  Foundation;  either version 3,  or (at your  option) any -
     --  later version. This library is distributed in the hope that it will be  -
     --  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of -
     --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                    -
     --                                                                          -
     --  As a special exception under Section 7 of GPL version 3, you are        -
     --  granted additional permissions described in the GCC Runtime Library     -
     --  Exception, version 3.1, as published by the Free Software Foundation.   -
     --                                                                          -
     --  You should have received a copy of the GNU General Public License and   -
     --  a copy of the GCC Runtime Library Exception along with this program;    -
     --  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see   -
     --  <http://www.gnu.org/licenses/>.                                         -
     --                                                                          -
     --  As a special exception, if other files instantiate generics from this   -
     --  unit, or you link this unit with other files to produce an executable,  -
     --  this  unit  does not  by itself cause  the resulting executable to be   -
     --  covered by the GNU General Public License. This exception does not      -
     --  however invalidate any other reasons why the executable file  might be  -
     --  covered by the  GNU Public License.                                     -
     ------------------------------------------------------------------------------

     --  Services to be used to declare aliases based on URI. This is mostly
     --  designed to be used with AWS.services.Dispatchers.URI.

     with AWS.Response;
     with AWS.Status;

     package AWS.Services.Callbacks is

        use AWS;

        generic
           Prefix    : String; -- the prefix found in the URI
           Directory : String; -- the directory where the file is
        function File (Request : Status.Data) return Response.Data;
        --  This is a callback function where URL:
        --     http://<host>/<prefix>toto
        --  references the file:
        --     <directory>/toto
        --
        --  If the URL does not start with Prefix it returns a 404 error page.
        --  This is designed to be use with AWS.Services.Dispatchers.URI.

     end AWS.Services.Callbacks;

