web_common.c

   File         : web_common.c
   Description  : Provides the Common structure
   Category     : Web Internal
   Author       : Charles Yates
  
   This API is designed to encapsulate the HTTPD external structure and 
   provide general utility functions and structures for the web server.

   WEB_COMMON COMMON_Init( HTTPD httpd )
 
   Function     : COMMON_Init
   Description  : Creates a common structure which is used to communicate the
                  server state through the various threads of the server
   Input        : void
   Output       : void
   Returns      : WEB_COMMON - an initialised common structure

   int COMMON_GetPort( WEB_COMMON common )
 
   Function     : COMMON_GetPort
   Description  : Get the port
   Input        : WEB_COMMON common - common structure to use
   Output       : void
   Returns      : int - port number of http server

   char *COMMON_GetRoot( WEB_COMMON common )
 
   Function     : COMMON_GetRoot
   Description  : Get the root directory of the http server
   Input        : WEB_COMMON common - common structure to use
   Output       : void
   Returns      : char * - root directory of web server

   int COMMON_GetInitialThreads( WEB_COMMON common )
 
   Function     : COMMON_GetInitialThreads
   Description  : Get the initial number of threads
   Input        : WEB_COMMON common - common structure to use
   Output       : void
   Returns      : 

   int COMMON_GetMaximumThreads( WEB_COMMON common )
 
   Function     : COMMON_GetMaximumThreads
   Description  : Get the maximum number of threads
   Input        : WEB_COMMON common - common structure to use
   Output       : void
   Returns      : 

   int COMMON_SetData( WEB_COMMON common, char *name, void *value )
 
   Function     : COMMON_SetData
   Description  : Associate a name with a user defined data structure
   Input        : WEB_COMMON common - common structure to use
                  char *name - name to register the data with
                  void *data - data to use
   Output       : void
   Returns      : 

   void *COMMON_GetData( WEB_COMMON common, char *name )
 
   Function     : COMMON_GetData
   Description  : 
   Input        : WEB_COMMON common - common structure to use
   Output       : void
   Returns      : 

   ACPENV COMMON_GetGlobalEnvironment( WEB_COMMON common )
 
   Function     : COMMON_GetGlobalEnvironment
   Description  : 
   Input        : WEB_COMMON common - common structure to use
   Output       : void
   Returns      : 

   int COMMON_GetSocketBacklog( WEB_COMMON common )
 
   Function     : COMMON_GetSocketBackLog
   Description  : Retreive socket backlog setting
   Input        : WEB_COMMON common - common structure to use
   Output       : void
   Returns      : int indicating socket backlog setting

   int COMMON_GetKeepaliveTimeout( WEB_COMMON common )
 
   Function     : COMMON_GetKeepaliveTimeout
   Description  : Retreive keep alive timeout setting
   Input        : WEB_COMMON common - common structure to use
   Output       : void
   Returns      : int indicating keep alive timeout setting

   int COMMON_GetKeepaliveMaximum( WEB_COMMON common )
 
   Function     : COMMON_GetKeepaliveMaximum
   Description  : Retreive keep alive maximum
   Input        : WEB_COMMON common - common structure to use
   Output       : void
   Returns      : int indicating maximum keep alive setting

   PLIST COMMON_GetThreadList( WEB_COMMON common )
 
   Function     : COMMON_GetThreadList
   Description  : Get the thread list
   Input        : WEB_COMMON common - common structure to use
   Output       : void
   Returns      : PLIST containing all the threads created

   int COMMON_GetThreadCount( WEB_COMMON common )
 
   Function     : COMMON_GetThreadCount
   Description  : Get the thread count
   Input        : WEB_COMMON common - common structure to use
   Output       : void
   Returns      : int - number of threads used by the server

   int COMMON_CreateWorkers( WEB_COMMON common, void *worker( void * ) )
 
   Function     : COMMON_CreateWorkers
   Description  : Create the initial pool of worker threads
   Input        : WEB_COMMON common - common structure to use
                  void *worker( void * ) - worker function
   Output       : the initial threads are created
   Returns      : 0 for OK

   int COMMON_EmployWorker( WEB_COMMON common, int fd )
 
   Function     : COMMON_EmployWorker
   Description  : Employ a worker with the given file descriptor
   Input        : WEB_COMMON common - common structure to use
                  int fd - file descriptor the worker will get
   Output       : worker is busy
   Returns      : 0 for OK

   void COMMON_CloseWorkers( WEB_COMMON common )
 
   Function     : COMMON_CloseWorkers
   Description  : Make all workers redundant
   Input        : WEB_COMMON common - common structure to use
   Output       : all workers are deactivated
   Returns      : void

   void COMMON_Stop( WEB_COMMON common )
 
   Function     : COMMON_Stop
   Description  : Communicates a stop to the server
   Input        : WEB_COMMON common - common structure to use
   Output       : Server is requested to be stopped
   Returns      : void

   int COMMON_GetStatus( WEB_COMMON common )
 
   Function     : COMMON_GetStatus
   Description  : Returns the status of the server
   Input        : WEB_COMMON common - common structure to use
   Output       : void
   Returns      : int - COMMON_CONTINUE, COMMON_STOPPED or COMMON_BLOCKED

   char *COMMON_GetMimeType( WEB_COMMON common, char *file )
 
   Function     : COMMON_GetMimeType
   Description  : Retreive the mime type associated to the given files extension
   Input        : WEB_COMMON common - common structure to use
                  char *file - file to query
   Output       : void
   Returns      : returns the mime type

   ACPDB COMMON_AcpDatabase( WEB_COMMON common )
 
   Function     : COMMON_AcpDatabase
   Description  : Retreive ACP database of loaded modules
   Input        : WEB_COMMON common - common structure to use
   Output       : void
   Returns      : returns the acp db structure

   int COMMON_LocateStat( WEB_COMMON common, char *action )
 
   Function     : COMMON_LocateStat
   Description  : Locate the action in the stats array
   Input        : WEB_COMMON common - common structure to use
                  char *action - action to locate
   Output       : void
   Returns      : int - index of action

   void COMMON_Stat( WEB_COMMON common, char *action )
 
   Function     : COMMON_Stat
   Description  : Retains a count of the number of requests for each unique action
   Input        : WEB_COMMON common - common structure to use
                  char *action - action to incrment counter of
   Output       : The stats are updated accordingly (hmm.. this needs more explaination I think...)
   Returns      : void

   time_t COMMON_GetStartTime( WEB_COMMON common )
 
   Function     : COMMON_GetStartTime
   Description  : Returns the time at which the server is started
   Input        : WEB_COMMON common - common structure to use
   Output       : void
   Returns      : time_t - the time of the server start up

   int COMMON_GetStat( WEB_COMMON common, int index, char *action )
 
   Function     : COMMON_GetStat
   Description  : Returns the static info at the given index
   Input        : WEB_COMMON common - common structure to use
                  int index - index to inquire on
                  char *action - returns the name of the action at index
   Output       : actions contains the name of the action at index
   Returns      : int - the number of requests of action at index 
                    (0 if passed end of list)

   void COMMON_Close( WEB_COMMON common )
 
   Function     : COMMON_Close
   Description  : Closes the common structure (dangerous!)
   Input        : WEB_COMMON common - common structure to use
   Output       : Common is cleared
   Returns      : void