pifile.h

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

/*____________________________________________________________________________*\
 *

 Copyright (c) 1997-2003 John Roy, Holger Zimmermann. All rights reserved.

 These sources, libraries and applications are
 FREE FOR COMMERCIAL AND NON-COMMERCIAL USE
 as long as the following conditions are adhered to.

 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions
 are met:

 1. Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer. 

 2. Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in
    the documentation and/or other materials provided with the
    distribution.

 3. The name of the author may not be used to endorse or promote products
    derived from this software without specific prior written permission.

 THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
 WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
 IN NO EVENT SHALL THE AUTHORS OR ITS CONTRIBUTORS BE LIABLE FOR ANY
 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
 GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
 STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 OF THE POSSIBILITY OF SUCH DAMAGE.

 *____________________________________________________________________________*|
 *
 * $Source: /cvsroot/pi3web/Pi3Web_200/Source/PiAPI/PIFile.h,v $
 * $Date: 2003/05/13 18:42:12 $
 *
 Description:
\*____________________________________________________________________________*/
/* $HeaderTop:$ */

#ifndef PIFILE_H_
#define PIFILE_H_

#include "PiAPI.h"

/*____________________________________________________________________________*\
 *
 Name:
	PIFile_open

 Synopsis:
	PIPLATFORM_FD PIFile_open( const char *pPath, const char *pFlags )

 Description:
	Open a new platform specific file handle to the file identified
	by the path pPath.


	The value pFlags is a sequence of characters with the following
	meanings. "W" - open file in write mode overwritting any 
	previous file with the same path. "A" - open the file in write
	mode appending to any file with the same path. "R" can be
	specified for opening a file for reading. "N" indicates that the
	file should not be opened if it already exists (must not alreadu exist).
	In all cases
	With the exception of when the "N" flag is present, 
	a new file will be created if it did not exist.
	<P>
	Flags are not case sensitive.

 Notes:
	PIPLATFORM_FD, is an operating system specific handle or descriptor,
	other operations may be performed on this object by casting this 
	value to the type associated with operating system specific descriptors
	and using system calls.

	PIFile_* functions are primarily intented for creating and appended
	file optimally with synchronization amoungst write operations from
	multiple threads and processes, however they may also be used for
	simple unbuffering readonly access to existing files.

	The function PIFile_close() should be used to close a file handle when
	it is no longer needed. File handles should be considered an
	easily exhaustable resource, and omitting to match successful
	PIFile_open() calls with calls to PIFile_close() is a serious
	resource leak.

 Return Values:
	The values returned from PIFile_open should be compared with
	the PIPLATFORM_FD_INVALID to determine if an error occurred, i.e.

<CODE><PRE>
		PIPLATFORM_FD tFD;
		if ((tFD = PIFile_open( "/tmp/dummy.txt", "w" ))==PIPLATFORM_FD_INVALID)
			{
			/.* --- handle error --- *./
			int iErrorCode = PiPlatform_getLastError();

			...

			}
		else
			{
			/.* --- tFD is a valid file handle --- *./

			...

			PIFile_close( tFD );
			};
</PRE></CODE>

 Errors:
	More specific error information can be retrieved using
	PIPlatform_getLastError().
		
 See Also:
	PIFile_close().
\*____________________________________________________________________________*/
PUBLIC_PIAPI int PIFile_open( const char *pPath, const char *pFlags );

/*____________________________________________________________________________*\
 *
 Name:
	PIFile_close

 Synopsis:
	int PIFile_close( PIPLATFORM_FD tFD )

 Description:
	Closes a platform specific file descriptor opened by PIFile_open().

 Notes:

 Return Values:
	On success PIFile_close() returns zero (PIAPI_COMPLETED).

 Errors:
	On error PIFile_close() does not return PIAPI_COMPLETED. The function
	PIPlatform_getLastError() can be used to retrieve more specific
	error information.

 See Also:
	PIFile_open().
\*____________________________________________________________________________*/
PUBLIC_PIAPI int PIFile_close( PIPLATFORM_FD tFD );

/*____________________________________________________________________________*\
 *
 Name:
	PIFile_unlink

 Synopsis:
	int PIFile_unlink( const char *pPath )

 Description:
	Unlink or delete a file.

 Notes:
 Return Values:
	On success PIFile_unlink() returns zero (PIAPI_COMPLETED).

 Errors:
	On error PIFile_unlink() does not return PIAPI_COMPLETED. The function
	PIPlatform_getLastError() can be used to retrieve more specific
	error information.

 See Also:
	PIFile_open().
\*____________________________________________________________________________*/
PUBLIC_PIAPI int PIFile_unlink( const char *pPath );
/*____________________________________________________________________________*\
 *
 Name:
	PIFile_read

 Synopsis:
	int PIFile_read( PIPLATFORM_FD tFD, int iLength, void *pData )

 Description:
	Read the data block of Length bytes from the file referenced by
	the descriptor tFD.
	
 Notes:
	The function PIPlatform_PollFD() may to used yield processing to
	another thread if the read operation would block.

 Return Values:
	On success PIFile_read() returns zero (PIAPI_COMPLETED).

 Errors:
	On error, the function PIPlatform_getLastError() can be used to get 
	more specific error information.
		
 See Also:
	PIFile_write(), PIFile_writeAtomic()
\*____________________________________________________________________________*/
PUBLIC_PIAPI int PIFile_read( PIPLATFORM_FD tFD, int iLength, void *pData );

/*____________________________________________________________________________*\
 *
 Name:
	PIFile_write

 Synopsis:
	int PIFile_write( PIPLATFORM_FD tFD, int iLength, const void *pData )

 Description:
	Write the data block of Length bytes to the file referenced by
	the descriptor tFD.
	
 Notes:
	The function PIPlatform_PollFD() may to used yield processing to
	another thread if the write operation would block.

 Return Values:
	On success PIFile_write() returns zero (PIAPI_COMPLETED).

 Errors:
	On error, the function PIPlatform_getLastError() can be used to get 
	more specific error information.
		
 See Also:
	PIFile_read(), PIFile_writeAtomic()
\*____________________________________________________________________________*/
PUBLIC_PIAPI int PIFile_write( PIPLATFORM_FD tFD, int iLength, const 
	void *pData );

/*____________________________________________________________________________*\
 *
 Name:
	PIFile_writeAtomic

 Synopsis:
	int PIFile_writeAtomic( PIPLATFORM_FD tFD, int iLength, const void *pData )

 Description:
	Write the data block if Length bytes to the file referenced by
	the descriptor tFD. The write operation is atomic, meaning that 
	descriptor will be locked using a platform specific method to ensure
	the block of a data is written correctly in an environment where
	multiple processes and threads are competing to write to the file. 
	
 Notes:
	This function will only gaurentee synchronized writes amoungst
	processes on POSIX compliant platforms. On other platforms only
	thread synchronization is performed.

 Return Values:
	On success PIFile_writeAtomic() returns zero (PIAPI_COMPLETED).

 Errors:
	On error, the function PIPlatform_getLastError() can be used to get 
	more specific error information.
		
 See Also:
	PIFile_read(), PIFile_write()
\*____________________________________________________________________________*/
PUBLIC_PIAPI int PIFile_writeAtomic( PIPLATFORM_FD tFD, int iLength, const 
	void *pData );

#endif /* PIFILE_H_ */