acp_out.c File : acp_out.c
Description : Defines the ACPOUT structure
Category : ACP Scripting
Author : Charles Yates
The ACPOUT (ACP Output) structure is used to communicate the results of
an ACP execution back to the ACP Container. It can carry binary or text data.
It is defined to allow the complete output of any HTTP request and can
contain all information such as the headers and error information.
The following shows an example of it's use:
// Create a new ACP output
ACPOUT out = ACPOUT_Init();
// Set the http error code
ACPOUT_SetError( out, 200, "OK" );
// Set the content type
ACPOUT_SetHeader( out, "Content-Type", "text/html" );
// Output something
ACPOUT_Println( out, "<HTML><BODY>Hello World.</BODY></HTML>" );
After the execution of the above, the output structure is ready for
transmission.
In the scripting environment, the ACP structure is used to obtain an ACPOUT
that is connected to the ACP Container, and this is obtained automatically for you
use as acpout. Hence, the following are equivalent:
<% ACPOUT_Println( acpout, "<HTML><BODY>Hello World.</BODY></HTML>" ); %>
<%=s::"<HTML><BODY>Hello World.</BODY></HTML>"%>
<HTML><BODY>Hello World.</BODY></HTML>
Note, it is not necessary to specify the ACPOUT_SetError and Content-Type unless
the script wishes to return something other than 200/OK and text/html content.
ACPOUT_Init ACPOUT DLLEXP ACPOUT_Init()
Function : ACPOUT_Init
Description : Creates a new acp output structure.
Input : void
Output : void
Returns : An initialised acp output structure
ACPOUT_SetUrlEncode void DLLEXP ACPOUT_SetUrlEncode( ACPOUT out, int flag ) {
Function : ACPOUT_SetUrlEncode
Description : Turns on/off URL encoding
Input : ACPOUT out - output structure to use
int flag - 0 for off, 1 for on
Output : Flag is set accordingly
Returns : void
Comments : All output written to the structure will be url encoded
when this flag is on.
For conviences in scripts, this flag is toggled by the
ACP meta tag of [%] and [/%].
ACPOUT_Write int DLLEXP ACPOUT_Write( ACPOUT out, char *buffer, int length )
Function : ACPOUT_Write
Description : Writes the data in the buffer to the acp output structure
Input : ACPOUT out - output structure to use
char *buffer - data to write to out
int length - length of data
Output : buffer is written to
Returns : int - 0 successful
ACPOUT_WriteString int DLLEXP ACPOUT_WriteString( ACPOUT out, char *buffer )
Function : ACPOUT_WriteString
Description : Convenience function to simplify string output
Input : ACPOUT out - output structure to write to
char *buffer - data to write out
Output : buffer is written to output structure
Returns : int - 0 is successful
ACPOUT_Println int DLLEXP ACPOUT_Println( ACPOUT out, char *fmt, ... )
Function : ACPOUT_Println
Description : Convenience function for sprintf type output with new line
Input : ACPOUT out - output structure to use
char *fmt - sprintf style format string
... - variable arguments
Output : output has sprintf output appended
Returns : int - number of chracters written
ACPOUT_Print int DLLEXP ACPOUT_Print( ACPOUT out, char *fmt, ... )
Function : ACPOUT_Print
Description : Convenience function for sprintf type output
Input : ACPOUT out - output structure to use
char *fmt - sprintf style format string
... - variable arguments
Output : output has sprintf output appended
Returns : int - number of chracters written
ACPOUT_Count int DLLEXP ACPOUT_Count( ACPOUT out )
Function : ACPOUT_Count
Description : Returns the number of gettable records from the output
Input : ACPOUT out - output structure to use
Output : void
Returns : int - number of output records
ACPOUT_GetLength int DLLEXP ACPOUT_GetLength( ACPOUT out, int index )
Function : ACPOUT_GetLength
Description : Returns the length of the record at the index given
Input : ACPOUT out - output structure to use
int index - index to query
Output : void
Returns : int - number of bytes in record
ACPOUT_Get char * DLLEXP ACPOUT_Get( ACPOUT out, int index )
Function : ACPOUT_Get
Description : Returns the the record at the index given
Input : ACPOUT out - output structure to use
int index - index to query
Output : void
Returns : char * - address of record
ACPOUT_SetError void DLLEXP ACPOUT_SetError( ACPOUT out, int error, char *description )
Function : ACPOUT_SetError
Description : Sets an error condition on the output structure
Input : ACPOUT out - Output structure to use
int error - error to set
char *description - associated description
Output : out is updated accordingly
Returns : void
ACPOUT_GetError int DLLEXP ACPOUT_GetError( ACPOUT out )
Function : ACPOUT_GetError
Description : Returns error code
Input : ACPOUT out - output structure to use
Output : void
Returns : int - error code set in previous SetError call
ACPOUT_GetDescription char * DLLEXP ACPOUT_GetDescription( ACPOUT out )
Function : ACPOUT_GetDescription
Description : Returns the desciption assoicated with the error code.
Input : ACPOUT out - output structure to use
Output : void
Returns : char * - description
ACPOUT_Error int DLLEXP ACPOUT_Error( ACPOUT out )
Function : ACPOUT_Error
Description : Convenience - determines if the current http error
indicates an error or not
Input : ACPOUT out - output structure to use
Output : void
Returns : int - 1 if error is < 100 or >= 400.
ACPOUT_SetStreaming void DLLEXP ACPOUT_SetStreaming( ACPOUT out )
Function : ACPOUT_SetStreaming
Description : Optional - Used by asynchronous output calls to track the
first call.
Input : ACPOUT out - output structure to use
Output : out is updated to indicate its access for streaming
Returns : void
Comments : When this is set on, the acp container will not output
the http headers (hence it is chiefly the responsibility of
the acp container to use this function). If you wish to use
acp in a non-http environment, then this call should be made
to avoid the container responding in an HTTP manner.
ACPOUT_GetStreaming int DLLEXP ACPOUT_GetStreaming( ACPOUT out )
Function : ACPOUT_GetStreaming
Description : Optional - indicates if SetStreaming has been called
Input : ACPOUT out - output structure to use
Output : void
Returns : int - 0 or 1
ACPOUT_SetHeader void DLLEXP ACPOUT_SetHeader( ACPOUT out, char *name, char *value )
Function : ACPOUT_SetHeader
Description : Convenience - sets a given HTTP header reponse value
Input : ACPOUT out - output structure to use
char *name - header name
char *value - value of name
Output : out is updated accordingly
Returns : void
Comments : Note that when the ACP_GetStreaming returns non-zero, specifying
a header will have no effect.
If the name is 'Set-Cookie', this is automatically applied to the
cookies collection.
ACPOUT_PrintHeader void DLLEXP ACPOUT_PrintHeader( ACPOUT out, char *name, char *fmt, ... )
Function : ACPOUT_PrintHeader
Description : Convenience - sets a given HTTP header reponse value
Input : ACPOUT out - output structure to use
char *name - name
char *fmt - print format
... - args
Output : out is updated accordingly
Returns : void
Comments : Note that when the ACP_GetStreaming returns non-zero, specifying
a header will have no effect.
ACPOUT_GetHeaders ACPENV DLLEXP ACPOUT_GetHeaders( ACPOUT out )
Function : ACPOUT_GetHeaders
Description : Obtains the header environment (see ACPENV)
Input : ACPOUT out - output structure to use
Output : void
Returns : ACPENV - header environment
Comments : Note that when the ACP_GetStreaming returns non-zero, specifying
a header will have no effect.
ACPOUT_GetCookies ACPENV DLLEXP ACPOUT_GetCookies( ACPOUT out )
Function : ACPOUT_GetCookies
Description : Obtains the cookie environment (see ACPENV)
Input : ACPOUT out - output structure to use
Output : void
Returns : ACPENV - header environment
Comments : Note that when the ACP_GetStreaming returns non-zero, specifying
a header will have no effect.
ACPOUT_GetContentLength int DLLEXP ACPOUT_GetContentLength( ACPOUT out )
Function : ACPOUT_GetContentLength
Description : Returns the current size of the output structure
Input : ACPOUT out - output structure to use
Output : void
Returns : int - size of output structure
Comments : Note that this function returns the current size of the data in
the acpout structure.
ACPOUT_GetTotalLength int DLLEXP ACPOUT_GetTotalLength( ACPOUT out )
Function : ACPOUT_GetTotalLength
Description : Returns the current size of the output structure
Input : ACPOUT out - output structure to use
Output : void
Returns : int - size of output structure
Comments : This function returns the total bytes sent on this acpout
structure. It is really only of use in logging since it's
not possible to determine the physical number of bytes that will
be sent (if piping is in use).
ACPOUT_SetMaxSize void DLLEXP ACPOUT_SetMaxSize( ACPOUT out, int max )
Function : ACPOUT_SetMaxSize
Description : Sets the maximum size of the output before flushing
Input : ACPOUT out - output structure to use
int max - maximum size
Output : output structure is updated to indicate the maximum size
Returns : void
ACPOUT_Transmit int ACPOUT_Transmit( ACPOUT out, FILE *in )
Function : ACPOUT_Transmit
Description : Convenience - tansfer contents of file
Input : ACPOUT out - output structure to use
FILE *in - input file stream
Output : contents of in are written to acp out
Returns : int - 0 is successful
ACPOUT_Inject int ACPOUT_Inject( ACPOUT out, ACPOUT in )
Function : ACPOUT_Inject
Description : Convenience - tansfer contents of file
Input : ACPOUT out - output structure to use
ACPOUT in - input file stream
Output : contents of in are written to acp out
Returns : int - 0 is successful
ACPOUT_Clear void DLLEXP ACPOUT_Clear( ACPOUT out )
Function : ACPOUT_Clear
Description : Clears all records in the output structure
Input : ACPOUT out - output structure to clear
Output : records in out are removed
Returns : int - 0 is successful
ACPOUT_Close void DLLEXP ACPOUT_Close( ACPOUT out )
Function : ACPOUT_Close
Description : Closes the output structure
Input : ACPOUT out - output structure to clear
Output : out and all data associated is freed
Returns : void
| 
