ziparchive.h

ZIP压缩代码：基于开源ZipArchive和zlib

		a zero-based index of the file to get from the \e zip archive
	\param iReplaceIndex the same as CZipAddNewFileInfo::m_iReplaceIndex
	\param bKeepSystComp
		if \c false, which is default, then the file from \e zip archive
		system compatibility is converted to the current archive system
		compatibility (if they differ)	
	\return \c false if the operation could not be performed (either of archives is closed, 
	a file inside either of archives is opened, \e zip archive is multi-disk or the current
	archive is an existing multi-disk archive)
	\note Throws exceptions <BR>
	(when an exception is thrown, you may need to call #CloseNewFile with \e bAfterException set to \c true, to make the archive reusable).	
	\note it is safe to abort the action (by returning false from the callback call) in non-disk spanning archive and when no replacing is taking place
	(the file not entirely added is removed from the archive)
	\see SetCallback
	\see GetFromArchive(CZipArchive& , CZipWordArray &, bool)
	\see GetFromArchive(CZipArchive& , CZipStringArray &, bool)
	\see FindMatches
	\see SetAdvanced 
*/
	bool GetFromArchive(CZipArchive& zip, WORD uIndex, int iReplaceIndex = -1, bool bKeepSystComp = false)
	{
				
		m_info.Init();
		bool bRet;
		try
		{
			bRet = GetFromArchive(zip, uIndex, iReplaceIndex, bKeepSystComp, GetCallback(cbGetFromArchive));
		}
		catch(...)
		{
			m_info.ReleaseBuf();
			throw;
		}
		m_info.ReleaseBuf();
		if (bRet && m_bAutoFlush)
			Flush();

		return bRet;
	}

	/**
	Acquire files with the given indexes from another archive. 
	
	\param	aIndexes
		an array of zero-based indexes of the files inside the \e zip archive	

	\see GetFromArchive(CZipArchive& , WORD, int, bool)

	\note 
	- To get files which filenames match a specified pattern, use #FindMatches function
	*/
	bool GetFromArchive(CZipArchive& zip, CZipWordArray &aIndexes, bool bKeepSystComp = false);
	
	/**
	Acquire files with the given indexes from another archive. 
	\param	aNames
		an array of filenames inside the \e zip archive; 	

	\see GetFromArchive(CZipArchive& , WORD, int, bool)
	\see EnableFindFast

	\note 
	- Set the case-sensitivity with #SetCaseSensitivity
	- Enables FindFast if not enabled
	
	*/
	
	bool GetFromArchive(CZipArchive& zip, CZipStringArray &aNames, bool bKeepSystComp = false)
	{
		CZipWordArray indexes;
		zip.GetIndexes(aNames, indexes);
		return GetFromArchive(zip, indexes, bKeepSystComp);
		
	}

	/**
		Get indexes of the files stored int \e aNames array and put them into \e aIndexes
		\param	aNames
			an array of filenames inside the archive; 
		\param aIndexes
			an array of indexes to be build
		\note 
		- Set the case-sensitivity with #SetCaseSensitivity
		- Enables FindFast if not enabled
			
	*/
	void GetIndexes(const CZipStringArray &aNames, CZipWordArray& aIndexes);

/**
	Extract the file from the archive. You can set the callback functor with #SetCallback.
	The argument \e lpszNewName may point to the full path and is influenced by \e bFullPath 
	argument (if \e lpszNewName contains drive specification then it is removed)
	\param	uIndex
		the index of the file to extract
	\param	lpszPath
	\verbatim
		The PATH only to extract the file to. May not be NULL. If you wish to 
		use UNC path you need to replace \\\\ at the beginning of UNC path with \\\\?\UNC\ .
	\endverbatim
	\param	bFullPath <BR>
		- if \c true, then extract with the full path - in this case the resulting
		file path is \e lpszPath plus the path stored in the archive or plus \e lpszNewName 
		if \e lpszNewName is not NULL. <BR>
		- if \c false, the destination file path is \e lpszPath + \e the filename only
		extracted from the path stored in the archive or from \e lpszNewName if
		\e lpszNewName is specified; <BR>
		if #m_szRootPath is set previously with #SetRootPath then to \e lpszPath
		is added the path stored in the archive (or \e lpszNewName if
		\e lpszNewName is specified) that has removed the beginning that equals 
		#m_szRootPath (if there is no common beginning then is behaves like 
		#m_szRootPath was empty)
	\param	lpszNewName 
			The new name of the file after extraction. 
			If NULL the original filename stored in the archive is used.
			May point to the full path but, if \e bFullPath is \c false, only the filename is extracted from this argument,			
	\param	nBufSize 
		the size of the buffer used while file operations
	\return	\c true if successful
	\note 
	- To extract files which filenames match a specified pattern, use #FindMatches function
	- Throws exceptions.
	\see SetCallback
	\see <CODE> ExtractFile(WORD, CZipMemFile&, DWORD) </CODE> 
	\see FindMatches
*/
	bool ExtractFile(WORD uIndex, LPCTSTR lpszPath, bool bFullPath = true,
		LPCTSTR lpszNewName = NULL, DWORD nBufSize = 65536);

	
	/**
		The same as <CODE> #ExtractFile(WORD , LPCTSTR , bool , LPCTSTR , DWORD ) </CODE>
		but instead to a physical file, this function decompress the data into CZipMemFile object
		\note 
		- if you pass CZipMemFile object already with data, its contents are NOT overwirtten, but the decompressed data is appended at the end
		- if you try to extract a directory, the function will return \c false
	*/
	bool ExtractFile(WORD uIndex, CZipMemFile& mf, DWORD nBufSize = 65536);

/**
	Open the file with the given index in the archive for extracting.
	Not successful opening the file doesn't lock the whole archive, so 
	you can try to open another one (after catching an exception if it was 
	thrown). Throw exception CZipException::badPassword if the password
	was not set for the encrypted file.
	\param	uIndex
		the index of the file
	\return	\c true if successful
	\note Throws exceptions.
*/
	bool OpenFile(WORD uIndex);

/**
	Decompress currently opened file to the buffer.
	\param	pBuf
		buffer to receive data
	\param	iSize
		the size of the buffer
	\return	the number of bytes read
	\see OpenFile
	\note Throws exceptions.
*/
	DWORD ReadFile(void *pBuf, DWORD iSize);


/**
	Test the file with the given index for the integrity. You can set the callback functor with #SetCallback.
 	The method throws exceptions but performs all the necessary cleanup
	before, so that the next file can be tested after catching the exception.
	\param	uIndex
		index of the file to test
	\param	uBufSize
		the size of the buffer used during extraction
	\return \c false if the incorrect action has been taken by 
	the user or the programmer (it is when #OpenFile or #GetFileInfo returned \c false or \e uBufSize is 0).
	If the file didn't passed the test or there was a disk I/O error, an exception is thrown.
	\note Throws exceptions.
	\see SetCallback
	
*/
	bool TestFile(WORD uIndex, DWORD uBufSize = 65536);

/**
	Perform the necessary cleanup after an exception was thrown
	while testing the archive so that next files in the archive can be tested.
	Called by #TestFile. Does not remove the file headers
	information from the central directory.
	\see TestFile
	\see CZipCentralDir::Clear
*/
	void CloseFileAfterTestFailed();

/**
	Get the local extra filed of the currently opened 
	for extraction file in the archive.
	\param	pBuf
		the buffer to receive the data
	\param	iSize
		the size of the buffer
	\return	If \e pBuf is NULL or iSize is 0, returns the size of the local extra field.
	Returns -1 if there is no file opened for the extraction.
*/
	int GetLocalExtraField(char* pBuf, int iSize)const ;

/**
	The same as CZipArchive::CloseFile(LPCTSTR), but additionally
	closes \e file.
	\param	file
		OPENED CZipFile structure of the extracted file
	\return	
	\note Throws exceptions.
	\see CZipArchive::CloseFile(LPCTSTR)
*/
	int CloseFile(CZipFile &file);


/**
	Close the file opened for extraction in the archive and copy its date and 
	attributes to the file pointed by \e lpszFilePath
	\param	lpszFilePath 
		Points to the path of the file to have the date and attributes information updated.
	\param bAfterException
		Set to \c true to close the file inside archive after an exception has been 
		thrown, to allow futher operations on the archive.
	\warning Close the file pointed by \e lpszFilePath before using this method, 
		because the system may not be able to retrieve information from it.
	\return	<BR>
	-  "1" = ok
	-  "-1" = some bytes left to uncompress - probably due to a bad password
	-  "-2" = setting extracted file date and attributes was not successful	
	\note Throws exceptions.
*/
	int CloseFile(LPCTSTR lpszFilePath = NULL, bool bAfterException = false);

/**
	Delete the file from the archive with the given index. 
	You can set the callback functor with #SetCallback.
	If you plan to delete more than one file, use one of <EM>DeleteFiles </EM>functions rather than calling DeleteFile
	successively, because these functions are optimized for deleting multiple files
	\param	uIndex
		a zero-based index
	\note Throws exceptions.
	\see SetCallback
	\see DeleteFiles(CZipWordArray&)
	\see DeleteFiles(const CZipStringArray&)
	\see FindMatches
*/
	void DeleteFile(WORD uIndex);

/**
	Delete files from the archive.
	You can set the callback functor with #SetCallback.
	Sorts \e aIndexes array in an ascending order.
	\param	aIndexes
		an array of zero-based indexes of the files inside the archive	
	\note 
	- To remove files which filenames match a specified pattern, use #FindMatches function
	- Throws exceptions.
	\see SetCallback
	\see DeleteFile
	\see DeleteFiles(const CZipStringArray& )
	\see FindMatches
*/
	void DeleteFiles(CZipWordArray &aIndexes);


/**
	Delete files from the archive.
	You can set the callback functor with #SetCallback.
	\param	aNames
		an array of filenames inside the archive; 	
	\note 
	- Set the case-sensitivity with #SetCaseSensitivity
	- Enables FindFast if not enabled
	- Throws exceptions.
	\see SetCallback
	\see DeleteFile
	\see DeleteFiles(CZipWordArray&)
	\see EnableFindFast
*/
	void DeleteFiles(const CZipStringArray &aNames);


/**
	Set the global comment in the archive.
	\param	lpszComment
		the file comment		
	\return \c false if the archive is closed or if it is an existing disk spanning archive
	\note Throws exceptions.
*/
	bool SetGlobalComment(LPCTSTR lpszComment);


/**
	\return the global comment or an empty string if the archive is closed	
*/
	CZipString GetGlobalComment()const ;


/**
	Set the comment of the file with the given index inside the archive.
	\param	uIndex
		zero-based index of the file in the archive
	\param	lpszComment
		a comment to add
	\return	\c false if the comment change is impossible
	\note Throws exceptions.
*/
	bool SetFileComment(WORD uIndex, LPCTSTR lpszComment);

/**
	\return the path of the currently opened archive volume	
*/
	CZipString GetArchivePath()const;

/**
	\return	<BR>
	- a one-based number of the current disk
	- 0 if there is no current disk (the archive is closed)
	\note Useful mostly while working with the disk-spanning archive in creation to find out
	how many disks were already created. To find out how many disks are in an existing disk-spanning archive,
	use the function #GetCentralDirInfo
*/
	int GetCurrentDisk()const ;

/**
	Return the disk spanning mode of the current archive.

	\return	<BR>
	- -2 - existing TD mode compatible disk spanning archive
	- -1 - existing PKZIP compatible 
	- 0 - no disk spanning
	- 1 - PKZIP compatible in creation
	- 2 - TD compatible in creation

  \see \ref PKSpan, \ref TDSpan

*/
	int GetSpanMode()const 
	{
		return m_storage.m_iSpanMode * m_storage.IsSpanMode();
	}

	/**
		case-sensitivity values used as argument \e iCaseSensitive in #FindFile
	*/
	enum FFCaseSens
	{
		ffDefault,  ///< use the default case-sensitivity as set with #SetCaseSensitivity function;
					 ///< if CZipCentralDir::m_findarray was build before with a different case-sensitivity,
					 ///< it is rebuild again, if it hasn't been build so far, it is build now with the
					 ///< default case-sensitivity