Name:
ConnectionPool_delete

Synopsis:
int ConnectionPool_delete( ConnectionPool *pConnectionPool )

Description:
Deletes an instance of a ConnectionPool object.

Notes:

Return Values:
PIAPI_COMPLETED on success or PIAPI_EINVAL, if wrong pConnectionPool given.

Errors:
PIAPI_EINVAL

See Also:
ConnectionPool_new

Return to index

Name:
ConnectionPool_grapConnection

Synopsis:
PIIOBuffer *ConnectionPool_grapConnection( ConnectionPool *pConnectionPool, const char *pHost, int iPort )

Description:
This function will establish a connection to the remote server using the given parameters.

Notes:

Return Values:
Returns a pointer to the new PIIOBuffer object, or NULL if an error occurred.

Errors:

See Also:
ConnectionPool_releaseConnection

Return to index

Name:
ConnectionPool_new

Synopsis:
ConnectionPool *ConnectionPool_new( PIObject *pIOObject, int iMaxSize )

Description:
Create an instance of a ConnectionPool object from the given IOObject A ConnectionPool object could be used e.g. in a TCP or HTTP client library.

Notes:
The parameter iMaxSize is ignored in the current implementation.

Return Values:
Returns a pointer to the new ConnectionPool object, or NULL if an error occurred.

Errors:

See Also:
ConnectionPool_delete

Return to index

Name:
ConnectionPool_releaseConnection

Synopsis:
int ConnectionPool_releaseConnection( ConnectionPool *pConnectionPool, PIIOBuffer *pConnection, bool bMustClose )

Description:
This function will release a connection to the remote server using the given parameters.

Notes:
The parameter bMustClose is ignored by the current implementation.

Return Values:
PIAPI_COMPLETED on success or PIAPI_ERROR, PIAPI_EINVAL

Errors:
PIAPI_EINVAL, if wrong pConnectionPool given, PIAPI_ERROR for all other error cases.

See Also:
ConnectionPool_grapConnection

Return to index

Name:
HTTPCore_cleanupClient

Synopsis:
int HTTPCore_cleanupClient()

Description:
This function closes the core HTTP client library.

Notes:

Return Values:
PIAPI_COMPLETED

Errors:

See Also:
HTTPCore_initClient

Return to index

Name:
HTTPCore_cleanupServer

Synopsis:
int HTTPCore_cleanupServer()

Description:
This function closes the core HTTP server library.

Notes:
This function is called by the request dispatcher object internally.

Return Values:
PIAPI_COMPLETED

Errors:

See Also:
HTTPCore_initServer

Return to index

Name:
HTTPCore_debugEnabled

Synopsis:
int HTTPCore_debugEnabled()

Description:
This function returns if writing of a debug log is enabled.

Notes:

Return Values:
PIAPI_TRUE if debugging is switched on PIAPI_FALSE otherwise.

Errors:

See Also:
HTTPCore_logDebug

Return to index

Name:
HTTPCore_dispatch

Synopsis:
int HTTPCore_dispatch( PIHTTP *pPIHTTP, int iStartPhase, int iEndPhase )

Description:
This function does dispatch an accepted HTTP request by iterating through the processing phases successive and invocating the HTTPCore_executePhase to all logic handlers configured for the server.

Phase No.	Description
PH_INVALID	Not a valid phase at all
PH_INIT	Initialization of a new request process
PH_HEADERS	Parsing of request headers
PH_HOSTMAP	Mapping of the request to a virtual host accordingly
PH_MAPPING	Mapping of URI to a physical path, often a cetrtain file
PH_CHECKPATH	Check, if the resource exists
PH_CHECKAUTH	Check, if the client is authenticated, if required
PH_CHECKACCESS	Check if there're sufficient permissions to access the requested recource, e.g. file permissions (to Read/Write/Execute a certain file)
PH_CHECKTYPE	Set the MIME type for the requested resource accordingly
PH_HANDLE	The real request process
PH_LOG	Logging of results of process
PH_DESTROY	Destruction of objects dynamically created during processing

Notes:
The function does also check, if an internal redirect is allowed in the current phase and if the maximum number of internal redirects (10) isn't exceeded.

Return Values:
PIAPI_COMPLETED in case of success, PIAPI_ERROR or PIAPI_ABORT otherwise

Errors:
PIAPI_ERROR PIAPI_ABORT

See Also:
HTTPCore_executePhase

Return to index

Name:
HTTPCore_executePhase

Synopsis:
int HTTPCore_executePhase( PIHTTP *pPIHTTP, PIObject *(* nextHandler)(void *), void *pArg)

Description:
This function executes the given handler objects in pointer list nextHandler and the argument parameters by invokation of PILogic_execute for each handler object successively until a handler returns PIAPI_COMPLETED, INT_REDIRECT or an error. This has the scope of one single phase of execution as defined in pPIHTTP->iPhase, i.e. HTTPCore_executePhase will be invoked once for each phase of execution to process a single HTTP request.

Notes:
If debug log is enabled, comprehensive profiling information will be written into the debug log prior and after invocation of the handler object. This can be used to find miss-configurations or performance bottlenecks.

Return Values:
The return value is the result of the execution of the handler object:

PIAPI_CONTINUE	No processing of the whole phase, often a configuration error
PIAPI_COMPLETED	The phase was completed successful
PIAPI_ERROR	The phase was completed with an error returned by one handler
PIAPI_ABORT	The processing of the phase was aborted by a handler
INT_REDIRECT	Internal redirect, i.e. the HTTP request will be processed again

Errors:
PIAPI_EINVAL if handler name is wrong
PIAPI_ERROR and PIAPI_ABORT may be returned by handler objects

See Also:
HTTPCore_dispatch

Return to index

Name:
HTTPCore_getCachedFile

Synopsis:
PIFInfo *HTTPCore_getCachedFile( const char *pPath )

Description:
Create an instance of a PIFInfo object from the given pPath to be used for reading the associated file.

Notes:

Return Values:
A valid PIFInfo object or NULL on error.

Errors:

See Also:
HTTPUtil_sendFile HTTPCore_releaseCachedFile

Return to index

Name:
HTTPCore_getMIMETypeFromExtension

Synopsis:
const char *HTTPCore_getMIMETypeFromExtension( const char *pExtension )

Description:
This function is used to lookup the MIME type by a certain file extension in an entity handler of the server in order to create the appriopriate Content-Type entity header for the response.

Notes:
Extensions are handled case insensitive on Windows but case sensitive on POSIX platforms.

Return Values:
The corresponding MIME type string for the given pExtension or the default MIME type if no entry found in MIME database.

Errors:

See Also:
HTTPCore_initServer HTTPCore_loadMIMEFile

Return to index

Name:
HTTPCore_getServerStamp

Synopsis:
const char *HTTPCore_getServerStamp()

Description:
This function retrieves the configured server name stamp.

Notes:

Return Values:
The configured server name stamp, maybe empty string if nothing configured.

Errors:

See Also:
HTTPCore_initServer

Return to index

Name:
HTTPCore_initClient

Synopsis:
int HTTPCore_initClient()

Description:
This function initiates the core HTTP client library and performs:

• make sure fast keys are setup
• read client stamp

Notes:

Return Values:
PIAPI_COMPLETED on success or PIAPI_ERROR otherwise

Errors:
PIAPI_ERROR

See Also:
HTTPCore_cleanupClient

Return to index

Name:
HTTPCore_initServer

Synopsis:
int HTTPCore_initServer( PIObject *pObject )

Description:
This function initiates the core HTTP server library and performs:

• make sure fast keys are setup
• read the server root and make it absolute
• read server stamp
• open error log and log initial message
• open debug log and log initial message
• load the debug expressions
• create MIME database and read in MIME file
• read the DefaultMIMEType
• read MIME types from configuration
• load top level handlers

Notes:
This function is called by the request dispatcher object internally. DefaultMIMEType is set to application/octet-stream if not set in configuration.

Return Values:
PIAPI_COMPLETED on success or PIAPI_ERROR otherwise

Errors:
PIAPI_ERROR

See Also:
HTTPCore_cleanupServer

Return to index

Name:
HTTPCore_loadMIMEFile

Synopsis:
int HTTPCore_loadMIMEFile( PIObject *pObject, PIDB *pMimeDB, const char *pMimeFile )

Description:
This function reads the contents of the MIME file as in pMimeFile into the database object pMimeDB. This is one comfortable way to set the MIME types which are recognized by Pi3Web later during server initialization. Comment lines may be inserted, starting with '#'. A MIME entry has the following format:

	
	MIME-Type SP Ext1 SP Ext2 SP ... ExtN LF

	e.g.

	#
	# File media types
	#
	application/msexcel		xls xlt
	application/msword		doc
	

Notes:
This function is used by HTTPCore_initServer internally. Another way is to set each separate MIME type in the Pi3Web configuration file. The configuration is read after the MIME file, thus both MIME sources may be mixed.

Return Values:
PIAPI_COMPLETED on success or PIAPI_ERROR otherwise

Errors:
PIAPI_ERROR

See Also:
HTTPCore_initServer

Return to index

Name:
HTTPCore_logDebug

Synopsis:
int HTTPCore_logDebug( int iLevel, const char *pFormat, ... )

Description:
This function formats and prints the given debug message into the server debug log. It does accept a variable parameter list as known from sprintf. The debug level in iLevel is specified by

DBG_LOW	Low priority
DBG_MED	Medium priority
DBG_HIGH	High priority

but will be ignored by current implementation.

Notes:

Return Values:
PIAPI_COMPLETED

Errors:

See Also:
HTTPCore_debugEnabled HTTPCore_logError

Return to index

Name:
HTTPCore_logError

Synopsis:
int HTTPCore_logError( PIHTTP *pPIHTTP, const char *pFormat, ... )

Description:
This function formats and prints the given error message into the server error log and the response database used in the current connection. It does accept a variable parameter list as known from sprintf.

Notes:
A timestamp with format

DOW MON dd hh:mm:ss yyyy TZN

Return Values:
PIAPI_COMPLETED

Errors:

See Also:
HTTPCore_logDebug

Return to index

Name:
HTTPCore_readHeaders

Synopsis:
int HTTPCore_readHeaders( PIIOBuffer *pB, PIDB *pDB, int iFlags )

Description:
This function reads in the HTTP request line and the HTTP request headers. The behaviour depends on the value of parameter iFlags:

RH_CLIENTREQUEST	The server parses a new client-side request
RH_RESPONSE	A client parses the response received by the server

Consistency checks will be performed, the request or response line will be parsed and all header values will be written into the connection database given as pDB.

Notes:
This function is called by the server ReadRequestHeaders object internally.

Return Values:
Returns INT_CONTINUE on success, otherwise HTTPCore_readHeaders() returns an HTTP status code representing an error.

Errors:

ST_BADREQUEST	Non compliant or empty HTTP request line or headers
ST_REQUESTURITOOLONG	Too long request line
ST_INTERNALERROR	Unspecified internal error when reading request line

See Also:

Return to index

Name:
HTTPCore_relativeToAbsolutePath

Synopsis:
int HTTPCore_relativeToAbsolutePath( PIDB *pDB, const char *pRelative, Pi3String *pResult )

Description:
This function does convert a given relative filesystem path in pRelative into an absolute filepath in the Pi3String *pResult. The conversion will either consider the root path of the virtual host as found in the given virtual host database pDB or the server root path as the root for the result path.

Notes:
It is important for server security to deny access to upper directories e.g. by prevention of uncontrolled usage of relative paths in URL's or file access in CGI programs. Pi3Web doesn't allow relative URI's and converts URL-mappings to relative physical paths into absolute paths based in the virtual host or server root.

Return Values:
PIAPI_TRUE if the relative path has been converted PIAPI_FALSE otherwise. The converted absolute path is in pResult in case of conversion.

Errors:

See Also:

Return to index

Name:
HTTPCore_releaseCachedFile

Synopsis:
void HTTPCore_releaseCachedFile( PIFInfo *pInfo )

Description:
Destroys the given instance of a PIFInfo object.

Notes:

Return Values:

Errors:

See Also:
HTTPCore_getCachedFile HTTPUtil_sendFile

Return to index

Name:
HTTPCore_sendEntityHeaders

Synopsis:
int HTTPCore_sendEntityHeaders( PIHTTP *pPIHTTP, PIDB *pR )

Description:
This function sends all entity specific RFC822 headers to the client.

Notes:
This function doesn't do anything for subrequests.

Return Values:
PIAPI_COMPLETED on success or PIAPI_ERROR otherwise

Errors:
PIAPI_ERROR

See Also:
HTTPCore_sendGeneralHeaders

Return to index

Name:
HTTPCore_sendGeneralHeaders

Synopsis:
int HTTPCore_sendGeneralHeaders( PIHTTP *pPIHTTP )

Description:
This function sends a HTTP response line and the general HTTP headers (Server, Date, Connection, Transfer-Encoding) in accordance with the used HTTP protocol version to the client.

Notes:
This function doesn't do anything for subrequests. If the HTTP status is 0 then it's silently changed to 200 OK

Return Values:
PIAPI_COMPLETED on success or PIAPI_ERROR otherwise

Errors:
PIAPI_ERROR

See Also:
HTTPCore_sendEntityHeaders

Return to index

Name:
HTTPUtil_contractPath

Synopsis:
int HTTPUtil_contractPath( char *pPath )

Description:
Contract the directory path pPath in place by removing directories with the name '..'.

Notes:

Return Values:
Returns the number of directories above the root pPath which should be discarded. Typically a value of 0 is the desired result.

Errors:

See Also:

Return to index

Name:
HTTPUtil_doHTTPError

Synopsis:
int HTTPUtil_doHTTPError( PIHTTP *pPIHTTP, int iError )

Description:
This function raises an HTTP error by

• set the error status code in pPIHTTP to iError
• clear any content-type, content-length, objectmap, authentication realm, authentication type in the databases
• reset the method to 'GET' in the request database
• disable keep alive
• cause an internal redirect

Notes:

Return Values:
return INT_REDIRECT to cause a redirect

Errors:

See Also:

Return to index

Name:
HTTPUtil_doHTTPRequest

Synopsis:
int HTTPUtil_doHTTPRequest( PIIOBuffer *pBuffer, PIDB *pQ )

Description:
This function sends an HTTP request through pBuffer to the server, i.e. acts as an HTTP client. The request parameters are taken from the request database pQ. The function does particular:

• Gather items for the HTTP request and validate them
• Send the HTTP request line and standard headers
• Send the other included RFC822 headers

Notes:
It is expected to find the HTTP method, the protocol version, the keep-alive flag and the request URI in pQ, otherwise PIAPI_EINVAL will be returned. A query string is considered as optional and appended to the URI.

Return Values:
PIAPI_COMPLETED on success, PIAPI_EINVAL on missing request parameters, PIAPI_ERROR otherwise.

Errors:
PIAPI_EINVAL PIAPI_ERROR

See Also:

Return to index

Name:
HTTPUtil_getHostName

Synopsis:
const char *HTTPUtil_getHostName( PIHTTP *pPIHTTP )

Description:
This function returns the name of the virtual host associated with the HTTP object in pPIHTTP.

Notes:

Return Values:
The name of the virtual host or NULL.

Errors:

See Also:
HTTPUtil_getHostPort

Return to index

Name:
HTTPUtil_getHostPort

Synopsis:
const char *HTTPUtil_getHostPort( PIHTTP *pPIHTTP )

Description:
This function returns the port of the virtual host associated with the HTTP object in pPIHTTP.

Notes:

Return Values:
The port number of the virtual host as decimal string or NULL.

Errors:

See Also:
HTTPUtil_getHostName

Return to index

Name:
HTTPUtil_phaseNameToNumber

Synopsis:
int HTTPUtil_phaseNameToNumber( const char *pPhaseName )

Description:
This function returns the corresponding code to the given process phase name.

Notes:

Return Values:
Refer to the table of return values of HTTPUtil_phaseNumberToName.

Errors:
PH_INVALID

See Also:
HTTPUtil_phaseNumberToName

Return to index

Name:
HTTPUtil_phaseNumberToName

Synopsis:
const char *HTTPUtil_phaseNumberToName( int iPhaseNumber )

Description:
This function does convert a given process phase number to the corresponding string.

Notes:

Return Values:
The name corresponding to the given process phase number

Phase No.	Name string
PH_INVALID	INVALID
PH_INIT	INIT
PH_HEADERS	HEADERS
PH_HOSTMAP	HOSTMAP
PH_MAPPING	MAPPING
PH_CHECKPATH	CHECKPATH
PH_CHECKAUTH	CHECKAUTH
PH_CHECKACCESS	CHECKACCESS
PH_CHECKTYPE	CHECKTYPE
PH_HANDLE	HANDLE
PH_LOG	LOG
PH_DESTROY	DESTROY

Errors:

See Also:
HTTPUtil_phaseNameToNumber

Return to index

Name:
HTTPUtil_protocolNumberToName

Synopsis:
const char *HTTPUtil_protocolNumberToName( int iProtocol )

Description:
This function does convert a given HTTP protocol version number to the corresponding string.

Notes:

Return Values:
The name corresponding to the given process phase number

Protocol version	Name string
PR_HTTP09	HTTP/0.9
PR_HTTP10	HTTP/1.0
PR_HTTP11	HTTP/1.1

Errors:
The string "Unknown" is returned in case of unknown value in iProtocol.

See Also:

Return to index

Name:
HTTPUtil_rFC822Time

Synopsis:
int HTTPUtil_rFC822Time( struct tm *pT, Pi3String *pResult )

Description:
This function converts a given time value into a valid RFC822 time string.

Notes:

Return Values:
PIAPI_TRUE on success, PIAPI_ERROR otherwise. The converted time string is returned in pResult.

Errors:
PIAPI_ERROR

See Also:

Return to index

Name:
HTTPUtil_rcNameToNumber

Synopsis:
int HTTPUtil_rcNameToNumber( const char *pName )

Description:
This function returns the corresponding code to the name of a PiAPI return value.

Notes:

Return Values:
Refer to the table of return values of HTTPUtil_rcNumberToName.

Errors:
PIAPI_ABORT is also returned on a wrong name in pName.

See Also:
HTTPUtil_rcNumberToName

Return to index

Name:
HTTPUtil_rcNumberToName

Synopsis:
const char *HTTPUtil_rcNumberToName( int iRC )

Description:
This function does convert a given PiAPI return code to the corresponding string.

Notes:

Return Values:
The name corresponding to the given PiAPI return code

API return code	Name string
PIAPI_COMPLETED	COMPLETED
PIAPI_CONTINUE	CONTINUE
PIAPI_ERROR	ERROR
PIAPI_ABORT	ABORT
INT_REDIRECT	REDIRECT
	UNKNOWN

Errors:

See Also:
HTTPUtil_rcNameToNumber

Return to index

Name:
HTTPUtil_readTime

Synopsis:
int HTTPUtil_readTime( const char *pLine, struct tm *pT )

Description:
This function does scan pLine for a valid ANSI-C, RFC1123 or RFC850 timestamp and parse it into a time structure.

Notes:
The pLine may contain more characters than only the time string.

Return Values:
PIAPI_COMPLETED on success, PIAPI_ERROR otherwise. The time structure in pT will be filled in case of success.

Errors:
PIAPI_ERROR

See Also:

Return to index

Name:
HTTPUtil_recvFile

Synopsis:
HTTPUtil_recvFile( PIHTTP *pPIHTTP, PIIOBuffer *pBuffer, PIFInfo *pFInfo )

Description:
This function receives the file resource as described by pFInfo through the PIIOBuffer from the client. The method doesn't consider HTTP headers, i.e. request headers must be read before this method is invoked.

Notes:

Return Values:
PIAPI_COMPLETED on success, PIAPI_ERROR otherwise.

Errors:
PIAPI_ERROR

See Also:
HTTPUtil_sendFile HTTPUtil_recvMultipartMsg

Return to index

Name:
HTTPUtil_recvMultipartMsg

Synopsis:
HTTPUtil_recvMultipartMsg( PIHTTP *pPIHTTP, PIIOBuffer *pBuffer, PFN_MUTLIPARTCB cb, void *pUser )

Description:
This function is to be used to split a multipart HTTP message (RFC1867) into its parts.

Notes:
The parameter 'cb' is a pointer to a callback function of type

 
	typedef int (__stdcall * PFN_MUTLIPARTCB )( int iKind,
                                                  char *szName,
                                                  char *szData,
                                                  long lData,
                                                  PIHTTP *pPIHTTP,
                                                  void *pUser );
	

The pointer 'pUser' is passed through by the callback function. It could point to any user defined data or class. If you make the callback function a friend of your handler class and 'pUser' is a reference to the handler you can use all class members of the handler in your callback function.

Return Values:
PIAPI_COMPLETED on success or PIAPI_ERROR on any error

Errors:
PIAPI_ERROR is returned if

• Content-Length header of the HTTP request is empty or 0
• The function couldn't allocate receive buffer
• The content isn't a multipart HTTP message (no header 'Content-Disposition' found)
• An error during read the data from the request occurs
• The user callback function returns PIAPI_ERROR

See Also:
HTTPUtil_recvFile

Return to index

Name:
HTTPUtil_regexMatch

Synopsis:
int HTTPUtil_regexMatch( const char *pRegex, int iRegex, const char *pString, int iStringLen )

Description:
This function does match the regular expression in pRegex with length iRegex against iStringLen characters in pString.

Notes:
The regular expression syntax is currently very limitated, only asterisk '*' is supported, e.g. HTTPUtil_regexMatch("*admin*", 7, pPath, 25)" does scan the first 25 characters of pPath for pattern "admin" at any position.

Return Values:
PIAPI_TRUE if matched, PIAPI_FALSE otherwise

Errors:

See Also:
HTTPUtil_regexMatchPi3String

Return to index

Name:
HTTPUtil_regexMatchPi3String

Synopsis:
int HTTPUtil_regexMatchPi3String( const Pi3String *pRegexPattern, const Pi3String *pString )

Description:
This function does match the regular expression in Pi3String pRegexPattern against the Pi3String in pString.

Notes:

Return Values:
PIAPI_TRUE if matched, PIAPI_FALSE otherwise

Errors:

See Also:
HTTPUtil_regexMatch

Return to index

Name:
HTTPUtil_sendFile

Synopsis:
HTTPUtil_sendFile( PIIOBuffer *pBuffer, PIFInfo *pFInfo, int iBufferingFlags, int iSendFlags )

Description:
This function sends the file resource as described by pFInfo through the PIIOBuffer to the client. The method doesn't consider HTTP headers, i.e. response headers must be sent before this method is invoked.

Notes:
For the iBufferingFlags refer to PIIOBuffer_write. The iSendFlags aren't used currently.

Return Values:
PIAPI_COMPLETED on success, PIAPI_ERROR otherwise.

Errors:
PIAPI_ERROR

See Also:
HTTPUtil_sendFileRange HTTPUtil_recvFile PIIOBuffer_write

Return to index

Name:
HTTPUtil_sendFileRange

Synopsis:
HTTPUtil_sendFileRange( PIIOBuffer *pBuffer, PIFInfo *pFInfo, int iBufferingFlags, unsigned int uiFrom, unsigned int uiTo )

Description:
This function sends the requested range of iFrom-iTo within the file resource described by pFInfo through the PIIOBuffer to the client. The method doesn't consider HTTP headers, i.e. range headers must be evaluated (request) or created (response), status code must be set properly (206 Partial Content) and response headers must be sent before this method is invoked.

Notes:
For the iBufferingFlags refer to PIIOBuffer_write. The correct range is checked internally.

Return Values:
PIAPI_COMPLETED on success, PIAPI_ERROR otherwise.

Errors:
PIAPI_ERROR

See Also:
HTTPUtil_sendFile HTTPUtil_recvFile PIIOBuffer_write

Return to index

Name:
HTTPUtil_urlDecode

Synopsis:
void HTTPUtil_urlDecode( const Pi3String *pToDecode, Pi3String *pResult )

Description:
This function does url-decode the string pToDecode in accordance with RFC1738, but with swapped spaces.

Notes:

Return Values:
The url-decoded string is returned in Pi3String pResult.

Errors:

See Also:
HTTPUtil_urlEncode

Return to index

Name:
HTTPUtil_urlEncode

Synopsis:
void HTTPUtil_urlEncode( const Pi3String *pToEncode, Pi3String *pResult )

Description:
This function does url-encode the string pToEncode in accordance with RFC1738. Spaces are additional swapped with '+'.

Notes:

Return Values:
The url-encoded string is returned in Pi3String pResult.

Errors:

See Also:
HTTPUtil_urlDecode

Return to index

Name:
PIHTTP_allocMem

Synopsis:
void *PIHTTP_allocMem( PIHTTP *pPIHTTP, unsigned int iSize )

Description:
This function does allocate user memory in the scope of the HTTP object referred by *pPIHTTP. The memory will be freed, when the HTTP object is deleted.

Notes:

Return Values:
Pointer to the new memory block with iSize on success, otherwise NULL on error.

Errors:

See Also:
PIHTTP_delete

Return to index

Name:
PIHTTP_delete

Synopsis:
int PIHTTP_delete( PIHTTP *pPIHTTP )

Description:
This function deletes the given HTTP object.

Notes:
The function will free all memory blocks allocated with PIHTTP_allocMem.

Return Values:
PIAPI_COMPLETED on success, otherwise PIAPI_ERROR.

Errors:
PIAPI_ERROR

See Also:
PIHTTP_new PIHTTP_allocMem

Return to index

Name:
PIHTTP_isChild

Synopsis:
int PIHTTP_isChild( PIHTTP *pPIHTTP )

Description:
Checks if a HTTP request is a child request.

Notes:

Return Values:
PIAPI_TRUE if the request is a child, otherwise PIAPI_FALSE.

Errors:

See Also:

Return to index

Name:
PIHTTP_new

Synopsis:
PIHTTP *PIHTTP_new( PIObject *pIOObject, PIDB *pHostDB )

Description:
This function creates a new HTTP request object, which is internally used by the request dispatcher. The HTTP request object is forwarded to the logic handlers during process the request.

Notes:
The created PIHTTP * is accessible as the following C structure:

struct _PIHTTP
{
	// --- public constant values --- //
	int ciPhase;

	// --- public mutable values --- //
	int iStatus;
	
	PIDB *pConnectionDB;
	PIDB *pHostDB;
	PIDB *pRequestDB;
	PIDB *pResponseDB;
	PIIOBuffer *pBuffer;
	void *pUser1;           // --- user data --- //
	void *pUser2;           // --- pointers  --- //
};
typedef struct _PIHTTP PIHTTP;
	

Return Values:
A new pointer to a PIHTTP structure or NULL on error.

Errors:

See Also:
PIHTTP_delete PIHTTP_newChild HTTPCore_dispatch

Return to index

Name:
PIHTTP_newChild

Synopsis:
PIHTTP *PIHTTP_newChild( PIHTTP *pParent )

Description:
This function will create a child of the pParent HTTP object, which will inherit/share the following properties:

• connection database
• host database
• request database
• IO-buffer
• object internal database (configuration values)

Notes:
This function is often used to create a child object in order to process a request in a speculative way. This can be used to calculate certain values, which are required for further processing in the parent or to forward a request. The following example does compute the physical mapping for an arbitrary URI in pPath:

Return Values:
A new pointer to a PIHTTP structure or NULL on error.

Errors:

See Also:
PIHTTP_new

Return to index

Name:
PIIOBuffer_advanceBufferPointer

Synopsis:
int PIIOBuffer_advanceBufferPointer( PIIOBuffer *pIOBuf, int iCount )

Description:
Advances the internal buffer pointer by iCount bytes. See PIIOBuffer_getOutputBuffer() for more information.

Notes:

Return Values:
Returns a positive integer on success.

Errors:
Returns a negative or zero value on failure.

See Also:
PIIOBuffer_getOutputBuffer

Return to index

Name:
PIIOBuffer_delete

Synopsis:
int PIIOBuffer_delete( PIIOBuffer *pPIIOBuffer )

Description:
Deallocate memory associated with IO buffer object pIOBuffer after flushing output.

Notes:
Destroying the buffer object does not destroy the IO channel it encapsulates.

Return Values:
PIAPI_COMPLETED if success or PIAPI_ERROR in case of an error.

Errors:
PIAPI_ERROR

See Also:
PIIOBuffer_new

Return to index

Name:
PIIOBuffer_flush

Synopsis:
int PIIOBuffer_flush( PIIOBuffer *pIOBuf )

Description:
Flush contents of output buffer to the IO channel.

Notes:
If PIIOBUF_CHUNKED has been used to write data to the client, the last chunk will be closed accordingly to HTTP/1.1.

Return Values:
Returns an integer which is interpreted as a boolean.

Errors:
Returns non-zero on success, 0 on failure.

See Also:

Return to index

Name:
PIIOBuffer_getBufferLen

Synopsis:
int PIIOBuffer_getBufferLen( PIIOBuffer *pIOBuf )

Description:
Returns the length of data in the internal input buffer. Mainly used to determine buggy browser Content-Length.

Notes:

Return Values:
The length of data in the input buffer or 0 if there's no more input data.

Errors:
This function does not raise an error.

See Also:

Return to index

Name:
PIIOBuffer_getBytesSent

Synopsis:
int PIIOBuffer_getBytesSent( PIIOBuffer *pIOBuf )

Description:
Returns the number of byes which have been place into this buffer object since it was created or PIIOBuffer_resetBytesSent() was last invoked. This value is the sum of the data sent down the IO channel and data currently in the output buffer.

Notes:

Return Values:
Returns number of bytes sent.

Errors:
This function does not raise an error.

See Also:
PIIOBuffer_resetBytesSent

Return to index

Name:
PIIOBuffer_getLine

Synopsis:
int PIIOBuffer_getLine( PIIOBuffer *pIOBuf, char *pszBuf, int iBufLen )

Description:
Read a line from the IO buffer into buffer pszBuf. Up to iBufLen characters are written.

Notes:

Return Values:
Returns number of characters read or PIAPI_ERROR (-1) on error.

Errors:
Returns PIAPI_ERROR (-1) on error.

See Also:
PIIOBuffer_read

Return to index

Name:
PIIOBuffer_getOutputBuffer

Synopsis:
int PIIOBuffer_getOutputBuffer( PIIOBuffer *pIOBuf, char **ppBuffer )

Description:
Returns the output buffer and its length so data can be written into it directly rather than using intermediate buffering. If the buffer length is not sufficient PIIOBuffer_flush() may be invoked followed by PIIOBuffer_getOutputBuffer() to get the flushed buffer. The pointer ppBuffer will be set to point at the internal buffer. After data has been written to the buffer and before any other output buffer functions are invoked the function PIIOBuffer_advanceBufferPointer() should be called to set the internal length of the output buffer.

Notes:

Return Values:
Returns the length of the output buffer.

Errors:

See Also:
PIIOBuffer_advanceBufferPointer

Return to index

Name:
PIIOBuffer_getUserData

Synopsis:
void *PIIOBuffer_getUserData( PIIOBuffer *pIOBuf )

Description:
Used to retrieve additional user data assigned to pIOBuf.

Notes:

Return Values:
Pointer to the additional user data or NULL.

Errors:
This function does not raise an error.

See Also:
PIIOBuffer_setUserData

Return to index

Name:
PIIOBuffer_new

Synopsis:
PIIOBuffer *PIIOBuffer_new( PIObject *pIOObject )

Description:
Create a new IO buffer object which uses IO channel object pIOObject for input and output.

Notes:

Return Values:
New created PIIOBuffer or NULL on error.

Errors:

See Also:
PIIOBuffer_delete

Return to index

Name:
PIIOBuffer_pollBeforeRead

Synopsis:
int PIIOBuffer_pollBeforeRead( PIIOBuffer *pIOBuf )

Description:
Causes the current thread to sleep until data has been read from the IO channel into the internal buffer.

Notes:

Return Values:
Returns PIAPI_ERROR (-1) on error, PIAPI_FALSE (0) for channel closed and PIAPI_TRUE (>0) for success.

Errors:
Returns PIAPI_ERROR (-1) on error, PIAPI_FALSE (0) on channel closed.

See Also:
PIIOBuffer_read

Return to index

Name:
PIIOBuffer_read

Synopsis:
const char *PIIOBuffer_read( PIIOBuffer *pIOBuf, int *piRead )

Description:
Reads data from the IO channel into the internal buffer and returns a pointer to the data read. The pointer piRead should point at an integer which will be set to the number of bytes read on success.

Notes:

Return Values:
Return a non-NULL pointer on success.

Errors:
Returns NULL on channel closed or error.

See Also:
PIIOBuffer_readToBuffer

Return to index

Name:
PIIOBuffer_readToBuffer

Synopsis:
int PIIOBuffer_readToBuffer( PIIOBuffer *pIOBuf, char *pszBuf, int iMaxLen )

Description:
Reads data from the IO channel into the buffer pIOBuf. Up to iMaxLen bytes will be read. A positive return value gives the number of bytes written into the buffer.

Notes:

Return Values:
Returns PIAPI_ERROR (-1) on error, PIAPI_FALSE (0) for channel closed and >0 for success.

Errors:
Returns PIAPI_ERROR (-1) on IO error, PIAPI_FALSE (0) on channel closed.

See Also:
PIIOBuffer_read

Return to index

Name:
PIIOBuffer_resetBytesSent

Synopsis:
int PIIOBuffer_resetBytesSent( PIIOBuffer *pIOBuf )

Description:
Resets the count of bytes sent through this buffer object to 0. Refer to PIIOBuffer_getBytesSent() for more information.

Notes:

Return Values:
This function does not return a value. Returns number of bytes sent.

Errors:
This function does not raise an error.

See Also:
PIIOBuffer_getBytesSent

Return to index

Name:
PIIOBuffer_setUserData

Synopsis:
void PIIOBuffer_setUserData( PIIOBuffer *pIOBuf, void *pUserData )

Description:
Used to assign additional user data to pIOBuf.

Notes:

Return Values:

Errors:
This function does not raise an error.

See Also:
PIIOBuffer_getUserData

Return to index

Name:
PIIOBuffer_write

Synopsis:
int PIIOBuffer_write( PIIOBuffer *pIOBuf, const char *pszBuf, int iLen, int iFlags )

Description:
Write the contents of the buffer pszBuf of length iLen into the the internal output buffer optionally flushing the output buffer. The value iFlags is formed by OR'ing the following flags

PIIOBUF_NONE	No flags (0).
PIIOBUF_NOBUFFER	Don't buffer, output data with directly after flushing existing output buffer.
PIIOBUF_CHUNKED	Output data using HTTP/1.1 chunked transfer encoding.

Notes:
If iLen is -1, PIIOBuffer_write() uses strlen() to determine the length of the string pszBuf. If PIIOBUF_CHUNKED has been used, subsequent calls of PIIOBuffer_write() must also provide the flag.

Return Values:
Returns number of bytes written or 0 on error.

Errors:
Returns 0 on error.

See Also:
PIIOBuffer_writeLn

Return to index

Name:
PIIOBuffer_writeLn

Synopsis:
int PIIOBuffer_writeLn( PIIOBuffer *pIOBuf, const char *pszBuf, int iLen, int iFlags )

Description:
Write the contents of the buffer pszBuf of length iLen into the the internal output buffer followed by CRLF to terminate the line. See PIIOBuffer_write() for a description of flags.

Notes:
If iLen is -1, PIIOBuffer_write() uses strlen() to determine the length of the string pszBuf.

Return Values:
Returns number of bytes written or 0 on error.

Errors:
Returns 0 on error.

See Also:
PIIOBuffer_write

Return to index

Name:
Pi3Expression_delete

Synopsis:
int Pi3Expression_delete( Pi3Expression *pExpression );

Description:
This function deletes the regexp object in pExpression.

Notes:

Return Values:
PIAPI_COMPLETED on success, PIAPI_EINVAL on invalid pExpression

Errors:
PIAPI_EINVAL

See Also:

Return to index

Name:
Pi3Expression_new

Synopsis:
Pi3Expression *Pi3Expression_new( const char *pExpression, FnPi3Write *pParameters, Pi3String *pErrorDescription )

Description:
This function creates a new regular expression object using the expression in pExpression.

Notes:
pParameters is an optional pointer to an array of callback functions:

typedef int (* FnPi3Write)( PIHTTP *, void *, char *, int );

Return Values:
A reference to new Pi3Expression or NULL on error. If NULL is returned, an error description can be obtained from pErrorDescription.

Errors:
NULL will be returned on invalid pExpression or pErrorDescription.

See Also:

Return to index

Name:
Pi3Expression_write

Synopsis:
int Pi3Expression_write( Pi3Expression *pExpression, PIHTTP *pPIHTTP, void *pData, char *pBuffer, int iBufferLength );

Description:
This function writes the result of pExpression in the context of pPIHTTP and pData into the buffer pBuffer of iBufferLength.

Notes:
The returned length can be used to re-allocate a sufficient buffer. The optional pData points to any user defined data. This element is handed over to the write callback function later and may contain context information.

Return Values:
The number of bytes of the interpreted regexp on success, PIAPI_EINVAL on parameter error, PIAPI_ERROR on write error.

Errors:
PIAPI_EINVAL PIAPI_ERROR

See Also:
Pi3Expression_new

Return to index

Name:
Pi3String_delete

Synopsis:
int Pi3String_delete( Pi3String *pString );

Description:
This deletes the Pi3String in pString.

Notes:

Return Values:
PIAPI_COMPLETED on success or PIAPI_EINVAL on invalid pString.

Errors:
PIAPI_EINVAL

See Also:
Pi3String_new Pi3String_newEx

Return to index

Name:
Pi3String_getLength

Synopsis:
int Pi3String_getLength( Pi3String *pString );

Description:
This function returns the length of the actual string in pString.

Notes:

Return Values:
The length of the string or PIAPI_EINVAL on invalid pString.

Errors:
PIAPI_EINVAL

See Also:
Pi3String_getPtr

Return to index

Name:
Pi3String_getPtr

Synopsis:
const char *Pi3String_getPtr( Pi3String *pString );

Description:
This function returns a read-only pointer of the actual string in pString.

Notes:

Return Values:
A valid pointer to the internal string or NULL on invalid pString.

Errors:

See Also:
Pi3String_getLength

Return to index

Name:
Pi3String_new

Synopsis:
Pi3String *Pi3String_new( const char *pString );

Description:
This function creates an new Pi3String object, an encapsulation for PIString. The value is based on the pString parameter.

Notes:
The parameter pString may be NULL to indicate an empty string.

Return Values:
A new Pi3String or NULL on error.

Errors:

See Also:
Pi3String_newEx Pi3String_delete

Return to index

Name:
Pi3String_newEx

Synopsis:
Pi3String *Pi3String_newEx( const char *pString, int iLength );

Description:
This function creates an new Pi3String object, an encapsulation for PIString. The value is based on the first iLength characters of the pString parameter.

Notes:
The parameter pString may be NULL to indicate an empty string.

Return Values:
A new Pi3String or NULL on error.

Errors:

See Also:
Pi3String_new Pi3String_delete

Return to index