web_server.c

   File         : web_server.c
   Description  : The External HTTPD API
   Category     : Web External
   Author       : Charles Yates
  
   This is API provides the means for plugging an ACP HTTP server into 
   an application.
  
   The simplest use of this API is as follows:
  
    #include <acp/interfaces/web_server/web_server.h>
  
    int main( void )
    {
        // Construct the http instance
        HTTPD httpd = HTTPD_Init( );
        // Start up the httpd instance using the defaults
        HTTPD_Start( httpd );
        // Wait for the server to be shutdown via an action from the user
        HTTPD_Wait( httpd );
        // Clean up
        HTTPD_Close( httpd );
        return 0;
    }
  
   Note that in this example, the use of HTTPD_Wait is required since the
   application shown would otherwise terminate immediately. For a typical
   application it is only necessary to call HTTPD_Start and then normal
   user interaction can occur.
  
   Prior to the HTTPD_Start, it is possible for you to change the defaults
   using the HTTPD_Set functions below.
   
   It is very important to note, that once you start the server, the 
   application will not allow changes to the root and port as this will
   have a knock on effect on the running instance. In other words, the
   API is provided to encapuslate and protect an HTTPD instance and as 
   an application developer, you should honour the restrictions imposed
   by the API and not access the structure directly (ever).

   HTTPD HTTPD_Init( ) 
 
   Function     : HTTPD_Init
   Description  : Initialise an HTTPD instance
   Input        : void
   Output       : void
   Returns      : An initialised HTTPD structure
   Special Logic:
   
   The default initialisation is a ready to start HTTPD with the following
   values:
  
   - Port of 8080
   - Root of the current working directory
   - Admin turned off
   - Initial threads of 1
   - Maximum threads of 10
  
   NB:  When the server is started, it will look for a site.properties file
        in the root directory. See the separate documentation on this file
        for details.

   HTTPD HTTPD_CreateChild( HTTPD httpd )
 
   Function     : HTTPD_CreateChild
   Description  : Initialise a child HTTPD instance
   Input        : HTTPD parent - parent to which the new instance belongs
   Output       : void
   Returns      : An initialised HTTPD structure

   int HTTPD_SetPort( HTTPD httpd, int port )
 
   Function     : HTTPD_SetPort
   Description  : Set the port of a non-running HTTPD instance
   Input        : HTTPD httpd - httpd instance to modify
                  int port - port to listen on
   Output       : Modifified httpd
   Returns      : HTTPD_OK when OK, HTTPD_RUNNING when unable to change

   int HTTPD_GetPort( HTTPD httpd )
 
   Function     : HTTPD_GetPort
   Description  : Get the port of an HTTPD instance
   Input        : HTTPD httpd - httpd instance to use
   Output       : void
   Returns      : the port of this httpd instance

   int HTTPD_SetAdminPort( HTTPD httpd, int port )
 
   Function     : HTTPD_SetAdminPort
   Description  : Set the admin port of a non-running HTTPD instance
   Input        : HTTPD httpd - httpd instance to modify
                  int port - port to listen on
   Output       : Modifified httpd
   Returns      : HTTPD_OK when OK, HTTPD_RUNNING when unable to change

   int HTTPD_GetAdminPort( HTTPD httpd )
 
   Function     : HTTPD_GetAdminPort
   Description  : Get the admin port of an HTTPD instance
   Input        : HTTPD httpd - httpd instance to use
   Output       : void
   Returns      : the admin port of this httpd instance (0 = disabled)

   int HTTPD_SetRoot( HTTPD httpd, char *root )
 
   Function     : HTTPD_SetRoot
   Description  : Set the root directory a non-running HTTPD instance
   Input        : HTTPD httpd - httpd instance to modify
                  char *root - root directory to use
   Output       : Modifified httpd
   Returns      : HTTPD_OK when OK, HTTPD_RUNNING when unable to change

   char *HTTPD_GetRoot( HTTPD httpd )
 
   Function     : HTTPD_GetRoot
   Description  : Get the root of an HTTPD instance
   Input        : HTTPD httpd - httpd instance to use
   Output       : void
   Returns      : the root directory of the httpd instance

   int HTTPD_SetInitialThreads( HTTPD httpd, int threads )
 
   Function     : HTTPD_SetInitialThreads
   Description  : Set the number of initial threads of a non-running HTTPD 
                  instance
   Input        : HTTPD httpd - httpd instance to modify
                  int threads - number of threads to create on start up
   Output       : Modifified httpd
   Returns      : HTTPD_OK when OK, HTTPD_RUNNING when unable to change

   int HTTPD_GetInitialThreads( HTTPD httpd )
 
   Function     : HTTPD_GetInitialThreads
   Description  : Get the number of initial threads created on an HTTPD instance
   Input        : HTTPD httpd - httpd instance to use
   Output       : void
   Returns      : the number of threads created on startup

   int HTTPD_SetMaximumThreads( HTTPD httpd, int threads )
 
   Function     : HTTPD_SetMaximumThreads
   Description  : Set the number of maximum threads of a non-running HTTPD 
                  instance
   Input        : HTTPD httpd - httpd instance to modify
                  int threads - max number of threads to create during execution
   Output       : Modifified httpd
   Returns      : HTTPD_OK when OK, HTTPD_RUNNING when unable to change

   int HTTPD_GetMaximumThreads( HTTPD httpd )
 
   Function     : HTTPD_GetMaximumThreads
   Description  : Get the maximum number of threads created in an HTTPD instance
   Input        : HTTPD httpd - httpd instance to use
   Output       : void
   Returns      : the maximum number of threads created during execution 

   int HTTPD_SetData( HTTPD httpd, char *name, void *value )
 
   Function     : HTTPD_SetData
   Description  : Pass application defined structures into the HTTPD for use 
                  in scripts
   Input        : HTTPD httpd - httpd instance to modify
                  char *name - name of data entity
                  void *value - address of data entity
   Output       : Modifified httpd
   Returns      : HTTPD_OK when OK, HTTPD_DUPLICATE_DATA when name has already been specified

   void *HTTPD_GetData( HTTPD httpd, char *name )
 
   Function     : HTTPD_GetData
   Description  : Retrieve application defined structures from the HTTPD
   Input        : HTTPD httpd - httpd instance to modify
                  char *name - name of data entity
   Output       : void
   Returns      : Address of data structure requested

   ACPENV HTTPD_GetGlobalEnvironment( HTTPD httpd )
 
   Function     : HTTPD_GetGlobalEnvironment
   Description  : Retrieve the site properties environment
   Input        : HTTPD httpd - httpd instance to modify
   Output       : void
   Returns      : Address of data structure requested

   int HTTPD_Start( HTTPD httpd )
 
   Function     : HTTPD_Start
   Description  : Start a non-running HTTPD
   Input        : HTTPD httpd - httpd instance to modify
   Output       : httpd is started
   Returns      : HTTPD_OK when successful
                  HTTPD_RUNNING when server is already running
                  HTTPD_INVALID_SITE when unable to locate the properties in 
                    the root specified
                  HTTPD_SOCKET_UNAVAILABLE when requested port is unavailable
                  HTTPD_ADMIN_FAILED when admin port is unavailable or in use 
                    (main server will still run)

   void HTTPD_Wait( HTTPD httpd )
 
   Function     : HTTPD_Wait
   Description  : Block process until server has received a shutdown request
   Input        : HTTPD httpd - httpd instance to modify
   Output       : void
   Returns      : void

   int HTTPD_IsRunning( HTTPD httpd )
 
   Function     : HTTPD_IsRunning
   Description  : Indicates if the server is currently running or not
   Input        : HTTPD httpd - httpd instance to modify
   Output       : void
   Returns      : 0 for no, != 0 for yes

   int HTTPD_Stop( HTTPD httpd )
 
   Function     : HTTPD_Stop
   Description  : Terminates a running instance
   Input        : HTTPD httpd - running instance to terminate
   Output       : httpd is stopped
   Returns      : HTTPD_OK when successful
                  HTTPD_NOT_RUNNING if the server was already stopped

   void HTTPD_Close( HTTPD httpd )
 
   Function     : HTTPD_Close
   Description  : Terminates an httpd instance
   Input        : HTTPD httpd - running instance to close
   Output       : httpd is stopped and all memory associated to it is freed
   Returns      : void