acp.c

   File         : acp.c
   Description  : Structure for passing all ACP related structures to the
                  ACP Scripting System
   Category     : ACP Scripting
   Author       : Charles Yates
  
   These are the APIs that can be used in ACP Scripts.

   void *DLLEXP ACP_GetData( ACP acp, char *name )
 
   Function     : ACP_GetData
   Description  : Gets a global data entity
   Input        : ACP acp - ACP structure to use
                  char *name - name of entity
   Output       : void
   Returns      : void * - address of named entity

   int DLLEXP ACP_SetData( ACP acp, char *name, void *value )
 
   Function     : ACP_SetData
   Description  : Sets a global data entity
   Input        : ACP acp - ACP structure to use
                  char *name - name of entity 
                  void *value - value associated to entity 
   Output       : void
   Returns      : int - 0 is successful

   int DLLEXP ACP_CanContinue( ACP acp )
 
   Function     : ACP_CanContinue
   Description  : Long running acp scripts should call this periodically
   Input        : ACP acp - ACP structure to use
   Output       : void
   Returns      : int - 0 if the script should terminate
   TODO         : Should check on recompilation requests too

   ACPENV DLLEXP ACP_GetServerProperties( ACP acp )
 
   Function     : ACP_GetServerProperties
   Description  : Gets the server properties entry in the ACP structure
   Input        : ACP acp - ACP structure to query
   Output       : void
   Returns      : ACPENV - The server properties in the ACP structure

   ACPENV DLLEXP ACP_GetRequest( ACP acp )
 
   Function     : ACP_GetRequest
   Description  : Gets the Request environment entry in the ACP structure
   Input        : ACP acp - ACP structure to query
   Output       : void
   Returns      : ACPENV - The requests headers

   ACPENV DLLEXP ACP_GetCgi( ACP acp )
 
   Function     : ACP_GetCgi
   Description  : Gets the CGI env entry in the ACP structure
   Input        : ACP acp - ACP structure to query
   Output       : void
   Returns      : ACPENV - a CGI environment

   ACPOUT DLLEXP ACP_GetOut( ACP acp )
 
   Function     : ACP_GetOut
   Description  : Gets the output entry in the ACP structure
   Input        : ACP acp - ACP structure to query
   Output       : void
   Returns      : ACPOUT - the output structure to use

   ACPIN DLLEXP ACP_GetIn( ACP acp )
 
   Function     : ACP_GetIn
   Description  : Gets the In entry in the ACP structure
   Input        : ACP acp - ACP structure to query
   Output       : void
   Returns      : ACPIN - the input structure to use

   void * DLLEXP ACP_GetUser( ACP acp )
 
   Function     : ACP_GetUser
   Description  : Gets the container specified structure from the ACP structure.
   Input        : ACP acp - ACP structure to use
   Output       : void
   Returns      : void * - address of user defined structure
   Comments     : Portable scripts should not rely on a specific structure
                  to be returned here.

   char * DLLEXP ACP_GetRequestLine( ACP acp )
 
   Function     : ACP_GetRequestLine
   Description  : Returns the http request line.
   Input        : ACP acp - ACP structure to use
   Output       : void
   Returns      : char * - http request line requested
   Comments     : char * - Full request line being processed.

   char * DLLEXP ACP_GetMethod( ACP acp )
 
   Function     : ACP_GetMethod
   Description  : Returns the http method.
   Input        : ACP acp - ACP structure to use
   Output       : void
   Returns      : char * - http method requested

   char * DLLEXP ACP_GetRequestURI( ACP acp )
 
   Function     : ACP_GetRequestURI
   Description  : Returns the http request uri.
   Input        : ACP acp - ACP structure to use
   Output       : void
   Returns      : char * - http request uri requested
   Comments     : URL encoded request including query

   char * DLLEXP ACP_GetAbsoluteURI( ACP acp )
 
   Function     : ACP_GetAbsoluteURI
   Description  : Returns the http absolute uri.
   Input        : ACP acp - ACP structure to use
   Output       : void
   Returns      : char * - http request uri requested
   Comments     : URL decoded request excluding query

   char * DLLEXP ACP_GetQuery( ACP acp )
 
   Function     : ACP_GetQuery
   Description  : Returns the http query.
   Input        : ACP acp - ACP structure to use
   Output       : void
   Returns      : char * - http query requested
   Comment      : URL encoded query string

   char * DLLEXP ACP_GetProtocol( ACP acp )
 
   Function     : ACP_GetProtocol
   Description  : Returns the protocol associated to this acp
   Input        : ACP acp - ACP structure to use
   Output       : void
   Returns      : char * - protocol associated to acp

   void DLLEXP ACP_SetRoot( ACP acp, char *root )
 
   Function     : ACP_SetRoot
   Description  : Specifies the root directory of the server
   Input        : ACP acp - ACP structure to use
                  char *root - root directory
   Output       : acp is updated appropriately
   Returns      : void
   Comment      : This function allows an acp script to arbitrarily 
                  specify a location other than the specified DOC*ROOT
                  for URI to file translation.

   char * DLLEXP ACP_GetRoot( ACP acp )
 
   Function     : ACP_GetRoot
   Description  : Obtains the root directory of the server
   Input        : ACP acp - ACP structure to use
   Output       : void
   Returns      : the root of the server in the current context

   char *ACP_GetRequestedFile( ACP acp )
 
   Function     : ACP_GetRequestedFile
   Description  : Obtains the requested file relative to the current root.
   Input        : ACP acp - ACP structure to use
   Output       : void
   Returns      : the full file spec to the requested file

   char *ACP_GetDirOfRequestedFile( ACP acp )
 
   Function     : ACP_GetDirOfRequestedFile
   Description  : Obtains the directory of the requested file relative to 
                  the current root.
   Input        : ACP acp - ACP structure to use
   Output       : void
   Returns      : the full directory of the requested file

   char * DLLEXP ACP_GetScript( ACP acp )
 
   Function     : ACP_GetScript
   Description  : Returns the script which this acp is executing
   Input        : ACP acp - ACP structure to use
   Output       : acp is updated with script information
   Returns      : char * - returns the script
   Comment      : Full path to the executing acp script

   int DLLEXP ACP_SetRequestURI( ACP acp, char *uri )
 
   Function     : ACP_SetRequestURI
   Description  : Sets the request uri
   Input        : ACP acp - ACP structure to use
                  char *uri - uri to direct to
   Output       : acp is updated 
   Returns      : int - 0 is successful
   Comment      : Dual functionality is annoying here - serves as both the 
                  initial request handler and server side redirect

   int DLLEXP ACP_SetRequestLine( ACP acp, char *line )
 
   Function     : ACP_SetRequestLine
   Description  : Sets the request Line
   Input        : ACP acp - ACP structure to use
                  char *line - uri to direct to
   Output       : acp is updated 
   Returns      : int - 0 is successful
   Comment      : Dual functionality is annoying here - serves as both the 
                  initial request handler and server side redirect/transform

   int ACP_Run( ACP acp )
 
   Function     : ACP_Run
   Description  : Executes the ACP.
   Input        : ACP acp - ACP structure to use
   Output       : Whatever is carried out by the ACP
   Returns      : 0 on success
   Comment      : This function is allows a script to carry out Server Side Include
                  type functionality and should not be called without a call to
                  ACP_SetRequestLine or SetRequestURI before hand. Take care to avoid
                  infinite loops.

   int ACP_RunNext( ACP acp )
 
   Function     : ACP_RunNext
   Description  : Executes the ACP in the next content handler.
   Input        : ACP acp - ACP structure to use
   Output       : Whatever is carried out by the ACP
   Returns      : 0 on success
   Comment      : This function is allows a script to carry out Server Side Include
                  type functionality and should not be called without a call to
                  ACP_SetRequestLine or SetRequestURI before hand. 
  
                  The difference between ACP_Run and ACP_RunNext is that this
                  function passes control down the chain of registered content handlers.
                  As such, it avoids the infinite recursion which could occur if
                  a script wishes to include something which it's claimed responsibility
                  for.

   int ACP_RunGlobalScript( ACP acp, char *script )
 
   Function     : ACP_RunGlobalScript
   Description  : Passes the current request to a global script/module.
   Input        : ACP acp - ACP structure to use
                  char *script - script to execute
   Output       : Whatever is carried out by the ACP
   Returns      : 0 on success
   Comment      : This function allows a script to carry out Server Side Include
                  type functionality. The premise here is that the current request
                  is passed to the script for processing and can be used to override
                  the default content negotiation of the site.