ziparchive.h

ZIP压缩、解压缩算法库

	as the argument to the #OpenNewFile
	\param	pBuf
		the bufer with the data to be copied
	\param	iSize
		the size of the extra field in the buffer
	\see OpenNewFile
*/
	void SetExtraField(const char *pBuf, WORD iSize);

/**
	Close the new file in the archive.
	\return \c false if there is no new file opened 
	\param bAfterException 
		it will close the new file without writing anything (call it also
		with this parameter set to \c true after an exception other than CZipException::abortedSafely was
		thrown from one of #AddNewFile functions)
	\note Throws exceptions.
	\see OpenNewFile
*/
	bool CloseNewFile(bool bAfterException = false);

/**
	Acquire a file with the given index from another archive. 
	The compressed data of the file from another archive are copied 
	without decompressing to the current archive.
	You can set the callback functor with #SetCallback.	
	\param zip 
		an opened archive to get the file from (must not be multi-disk)
	\param	uIndex
		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
		\param	uIndex
			the index of the file to extract
		\param mf
			the memory file to receive decompressed data
		\param bRewind
			if \c true, the current memory file pointer is positioned at the beginning of the compressed data after compression
			(even if it was aborted, but not if other exception than CZipException::abortedAction or CZipException::abortedSafely was thrown in the meantime)
		\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, bool bRewind = true, 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 or the password supplied was incorrect, 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 or extracting the archive so that next files in the archive can be tested or extracted.
	Called by #TestFile. Does not remove the file headers
	information from the central directory. You can use this method after you have extracted only part of the file (not entire file) and you wish to close it.
	\see TestFile
	\see CZipCentralDir::Clear
*/
	void CloseFileWithNoUpdate();

/**
	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 or corrupted archive
	-  "-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);