httputil.h

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

	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
\*____________________________________________________________________________*/
PUBLIC_PIAPI int HTTPUtil_regexMatch( const char *pRegex, int iRegex,
		const char *pString, int iStringLen );

/*____________________________________________________________________________*\
 *
 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
\*____________________________________________________________________________*/
PUBLIC_PIAPI int HTTPUtil_regexMatchPi3String( const Pi3String *pRegexPattern,
		const Pi3String *pString ); 

/*____________________________________________________________________________*\
 *
 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
\*____________________________________________________________________________*/
PUBLIC_PIAPI void HTTPUtil_urlEncode( const Pi3String *pToEncode,
		Pi3String *pResult );

/*____________________________________________________________________________*\
 *
 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
\*____________________________________________________________________________*/
PUBLIC_PIAPI void HTTPUtil_urlDecode( const Pi3String *pToDecode,
		Pi3String *pResult );

/*____________________________________________________________________________*\
 *
 Name:
	HTTPUtil_doHTTPError

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

 Description:
	This function raises an HTTP error by
	<UL>
		<LI>set the error status code in pPIHTTP to iError
		<LI>clear any content-type, content-length, objectmap,
		authentication realm, authentication type in the databases
		<LI>reset the method to 'GET' in the request database
		<LI>disable keep alive
		<LI>cause an internal redirect
	</UL>
 Notes:
 Return Values:
	return INT_REDIRECT to cause a redirect

 Errors:
 See Also:
\*____________________________________________________________________________*/
PUBLIC_PIAPI int HTTPUtil_doHTTPError( PIHTTP *pPIHTTP, int iError );

/*____________________________________________________________________________*\
 *
 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
\*____________________________________________________________________________*/
PUBLIC_PIAPI int HTTPUtil_sendFile( PIIOBuffer *pBuffer, PIFInfo *pFInfo,
		int iBufferingFlags, int iSendFlags );

/*____________________________________________________________________________*\
 *
 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
\*____________________________________________________________________________*/
PUBLIC_PIAPI int HTTPUtil_sendFileRange( PIIOBuffer *pBuffer, PIFInfo *pFInfo,
		int iBufferingFlags, unsigned int uiFrom, unsigned int uiTo );

/*____________________________________________________________________________*\
 *
 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
\*____________________________________________________________________________*/
PUBLIC_PIAPI int HTTPUtil_recvFile( PIHTTP *pPIHTTP, PIIOBuffer *pBuffer, PIFInfo *pFInfo );

/*____________________________________________________________________________*\
 *
 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:
	<UL>
		<LI>Gather items for the HTTP request and validate them
		<LI>Send the HTTP request line and standard headers 
		<LI>Send the other included RFC822 headers
	</UL>

 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:

\*____________________________________________________________________________*/
PUBLIC_PIAPI int HTTPUtil_doHTTPRequest( PIIOBuffer *pBuffer,
    PIDB *pQ );

// callback prototype to handle multipart messages
typedef int ( *PFN_MUTLIPARTCB )( int iKind, char *szName, char *szData, long lData,
										    PIHTTP *pPIHTTP, void *pUser );
// callback types
#define MP_PART_NONE  0
#define MP_PART_FIRST 1
#define MP_PART_NEXT  2
#define MP_PART_LAST  4

/*____________________________________________________________________________*\
 *
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
	<PRE> 
	typedef int (__stdcall * PFN_MUTLIPARTCB )( int iKind,
                                                  char *szName,
                                                  char *szData,
                                                  long lData,
                                                  PIHTTP *pPIHTTP,
                                                  void *pUser );
	</PRE>

	The callback parameter 'kind' will be one ore more of the following constants

	<TABLE BORDER=1>
	<TR>
	<TH>Constant
	<TH>Description
	<TR>
	<TD>MP_PART_NONE
	<TD>Not used in callbacks.
	<TR>
	<TD>MP_PART_FIRST
	<TD>'szData' points to the first block of the message part with 'szName'.
	<TR>
	<TD>MP_PART_NEXT
	<TD>'szData' points to any block of the message part with 'szName'.
	<TR>
	<TD>MP_PART_LAST
	<TD>'szData' points to the last block of the message part with 'szName'.
	</TABLE>
	<P>
	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
	<UL>
	<LI>Content-Length header of the HTTP request is empty or 0
	<LI>The function couldn't allocate receive buffer
	<LI>The content isn't a multipart HTTP message (no header 'Content-Disposition' found)
	<LI>An error during read the data from the request occurs
	<LI>The user callback function returns PIAPI_ERROR
	</UL>

 See Also:
	HTTPUtil_recvFile
\*____________________________________________________________________________*/
PUBLIC_PIAPI int HTTPUtil_recvMultipartMsg( PIHTTP *pPIHTTP, PIIOBuffer *pBuffer, PFN_MUTLIPARTCB cb, void *pUser );

#endif /* HTTPUTIL_H_ */