httpcore.h

mini http server,可以集成嵌入到程序中,实现简单的web功能

 Errors:
 See Also:
	HTTPCore_initServer
\*____________________________________________________________________________*/
PUBLIC_PIAPI const char *HTTPCore_getServerStamp();

/*____________________________________________________________________________*\
 *
 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
\*____________________________________________________________________________*/
PUBLIC_PIAPI void HTTPCore_releaseCachedFile( PIFInfo *pInfo );

/*____________________________________________________________________________*\
 *
 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:

	<PRE>	
	MIME-Type SP Ext1 SP Ext2 SP ... ExtN LF

	e.g.

	#
	# File media types
	#
	application/msexcel		xls xlt
	application/msword		doc
	</PRE>

 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
\*____________________________________________________________________________*/
PUBLIC_PIAPI int HTTPCore_loadMIMEFile( PIObject *pObject, PIDB *pMimeDB,
	const char *pMimeFile );

/*____________________________________________________________________________*\
 *
 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
\*____________________________________________________________________________*/
PUBLIC_PIAPI const char *HTTPCore_getMIMETypeFromExtension(
		const char *pExtension );

/*____________________________________________________________________________*\
 *
 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:
\*____________________________________________________________________________*/
PUBLIC_PIAPI int HTTPCore_relativeToAbsolutePath( PIDB *pDB,
        const char *pRelative, Pi3String *pResult );

/*____________________________________________________________________________*\
 *
 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 <CODE>sprintf</CODE>.

 Notes:
	A timestamp with format <PRE>DOW MON dd hh:mm:ss yyyy TZN</PRE> will be
	prefixed to the message.

 Return Values:
	PIAPI_COMPLETED

 Errors:
 See Also:
	HTTPCore_logDebug
\*____________________________________________________________________________*/
PUBLIC_PIAPI int HTTPCore_logError( PIHTTP *pPIHTTP, const char *pFormat, ... );

/*____________________________________________________________________________*\
 *
 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
	<CODE>sprintf</CODE>. The debug level in iLevel is specified by
	<TABLE>
		<TR><TD>DBG_LOW<TD>Low priority
		<TR><TD>DBG_MED<TD>Medium priority
		<TR><TD>DBG_HIGH<TD>High priority
	</TABLE>
	but will be ignored by current implementation.
 Notes: Debugging can simply switched on/off by configuration of a debug log file.

 Return Values:
	PIAPI_COMPLETED

 Errors:
 See Also:
	HTTPCore_debugEnabled
	HTTPCore_logError
\*____________________________________________________________________________*/
PUBLIC_PIAPI int HTTPCore_logDebug( int iLevel, const char *pFormat, ... );

/*____________________________________________________________________________*\
 *
 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:
	<TABLE>
		<TR><TD>PIAPI_CONTINUE<TD>No processing of the whole phase, often a configuration error
		<TR><TD>PIAPI_COMPLETED<TD>The phase was completed successful
		<TR><TD>PIAPI_ERROR<TD>The phase was completed with an error returned by one handler
		<TR><TD>PIAPI_ABORT<TD>The processing of the phase was aborted by a handler
		<TR><TD>INT_REDIRECT<TD>Internal redirect, i.e. the HTTP request will be processed again
	</TABLE>
 Errors:
	PIAPI_EINVAL if handler name is wrong<BR>
	PIAPI_ERROR and PIAPI_ABORT may be returned by handler objects

 See Also:
	HTTPCore_dispatch
\*____________________________________________________________________________*/
PUBLIC_PIAPI int HTTPCore_executePhase( PIHTTP *pPIHTTP,
		PIObject *(* nextHandler)(void *), void *pArg);

/*____________________________________________________________________________*\
 *
 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.

	<TABLE>
		<TR><TH>Phase No.<TH>Description
		<TR><TD>PH_INVALID<TD>Not a valid phase at all
		<TR><TD>PH_INIT<TD>Initialization of a new request process
		<TR><TD>PH_HEADERS<TD>Parsing of request headers
		<TR><TD>PH_HOSTMAP<TD>Mapping of the request to a virtual host accordingly
		<TR><TD>PH_MAPPING<TD>Mapping of URI to a physical path, often a cetrtain file
		<TR><TD>PH_CHECKPATH<TD>Check, if the resource exists
		<TR><TD>PH_CHECKAUTH<TD>Check, if the client is authenticated, if required
		<TR><TD>PH_CHECKACCESS<TD>Check if there're sufficient permissions to access the requested recource,
		e.g. file permissions (to Read/Write/Execute a certain file)
		<TR><TD>PH_CHECKTYPE<TD>Set the MIME type for the requested resource accordingly
		<TR><TD>PH_HANDLE<TD>The real request process
		<TR><TD>PH_LOG<TD>Logging of results of process
		<TR><TD>PH_DESTROY<TD>Destruction of objects dynamically created during processing
	</TABLE>
 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
\*____________________________________________________________________________*/
PUBLIC_PIAPI int HTTPCore_dispatch( PIHTTP *pPIHTTP, int iStartPhase,
		int iEndPhase );

/*____________________________________________________________________________*\
 *
 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
\*____________________________________________________________________________*/
PUBLIC_PIAPI int HTTPCore_debugEnabled();

#endif /* HTTPCORE_H_ */