ziparchive.h

ZIP压缩、解压缩算法库

/**
	\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
		ffCaseSens,  ///< perform a case-sensitive search (if the \c CZipArchive is non-case-sensitive,
					 ///< a less effective search is perfomed); does not rebuild CZipCentralDir::m_findarray,
					 ///< but if the array hasn't been built yet, it is build now as \b non-case-sensitive
					 ///< (you can use \c SetCaseSensitivity(true) and then #ffDefault to build it as case-sensitive)
		ffNoCaseSens ///< perform a non-case-sensitive search (if the \c CZipArchive is case-sensitive,
					 ///< a less effective search is performed); does not rebuild CZipCentralDir::m_findarray,
 					 ///< but if the array hasn't been built yet, it is build now as \b case-sensitive
					 ///< (you can use \c SetCaseSensitivity(false) and then #ffDefault to build it as non-case-sensitive)

	};

/**
	Find the file in the archive.
	If the archive wasn't opened with CZipCentralDir::m_bConvertAfterOpen set to \c true, 
	this function automatically convert all the filenames with the function
	CZipCentralDir::ConvertAll and set CZipCentralDir::m_bConvertAfterOpen to \c true.
	This function requires \link CZipCentralDir::m_bFindFastEnabled FindFast \endlink
	feature enabled.
	\param	lpszFileName
		the name of the file to be found in the archive; must be with path unless
		you set \e bFileNameOnly to \c true. Use path separators the same as they are for your system 
		(\e "\" for Windows and \e "/" for Unix/Linux)
	\param iCaseSensitive can be one of #FFCaseSens values
	\param bFileNameOnly
		if \c true, the function tries to find a filename without a path (a less effective search is performed); if you wish to find
		a directory name, do not end it with the path separator, which is required if you set \e bFileName to \c false		
	\return	<BR>
	- the index of the file found 
	- -1 if there is no such a file in the archive
	\see CZipCentralDir::FindFileNameIndex
	\see EnableFindFast
	\see CZipCentralDir::ConvertAll
	\see SetConvertAfterOpen
*/
	int FindFile(LPCTSTR lpszFileName, int iCaseSensitive = ffDefault, bool bFileNameOnly = false);

/**
	Get the info of the file with the given index.
	\param	fhInfo
		the structure to receive info			
	\param	uIndex
		a zero-based index of the file inside the archive
	\return	\c true if successful
*/
	bool GetFileInfo(CZipFileHeader & fhInfo, WORD uIndex) const;


/**
	\param	bOnlyFiles
		if \c true, the directories are not inluded in a total count;
		default is \c false
	\return	the number of files in the archive
*/
	int GetCount(bool bOnlyFiles = false)const 
	{
		int iTotalCount = m_centralDir.m_headers.GetSize();
		if (bOnlyFiles)
		{
			int iCount = 0;
			for (int i = 0; i < iTotalCount; i++)
				if (!m_centralDir.m_headers[i]->IsDirectory())
					iCount++;
			return iCount;
		}
		else
			return iTotalCount;
	}

	/**
		values used in #Close function as parameter \e iAfterException
	*/
	enum CloseAfterException
	{
		afNoException,		///< normal close, no exception was thrown before by CZipArchive object
		afAfterException,	///< an exception has been thrown, don't write any data but perform necessary cleaning to reuse CZipArchive object for another archive
		afWriteDir			///< the same as above, but write the central directory end structure to the archive, so that we can save at least the files that have
							///< been added properly and maybe try to repair the archive later
	};

/**
	Close the archive.
	\param	iAfterException
		one of #CloseAfterException enum values
	\param bUpdateTimeStamp
		if \c true, set the modification date of the zip file to the date of the newest file in the archive;		
		in disk-spanning mode only the last archive file will have the time stamp updated; 
		you can use this option even without performing any additional processing on the archive, just open and close it
	\note Throws exceptions if \e iAfterException is different from \c afAfterException
*/
	void Close(int iAfterException = afNoException, bool bUpdateTimeStamp = false);


/**
	Test if the archive is closed (a whole or the current volume only)
	\param	bArchive <BR>
		- \c true: test for the whole archive
		- \c false: test for the volume file only		

	\return	\c true if closed
*/
	bool IsClosed(bool bArchive = true)const ;

	/**
		Write the central directory to the archive and flushes the internal buffers to the disk, 
		so that the archive is finalized on the disk, but you can still modify it. Use it after 
		opening (or creating) and modifying the archive if you want to prevent the loss 
		of the data you've compressed so far in case of the program crash. <BR>
		If you use it on a disk spanning archive in creation it will not be closed, but its state
		will be changed from "archive in creation" to "an existing span archive". Use it when you finish adding files to the disk-spanning archive and want to 
		begin extracting or testing it. It follows that you can call it only once in this case. However, if 
		after finalizing the disk spanning archive it turns out that it is one disk only, it is converted to 
		a normal archive and you can use it as such. If you want to know what is the state of the archive after using
		this function call #GetSpanMode.
		\note 
		- Cannot be used on existing disk spanning archives (they are not modifable anyway)
		- If you have an archive with a huge central directory, it'll influence the perfomance calling this function without a reason.
		- Throws exceptions.
		\see GetSpanMode
		\see SetAutoFlush
		\see GetAutoFlush

	*/
	void Flush();


	/**
		Set the CZipArchive object to call #Flush after each operation that modifies the archive
		(adding a new file, deleting file(s), modifying the global or a file comment).
		It is useful when we want to prevent the loss of data in case of the program crash - the zip file will be then finalized on the disk.
		Use it after opening the archive.
		\note 
		- You can set AutoFlush only for non-disk spanning archives, however you can call #Flush once for a disk-spanning archive in creation.
		- If you have an archive with a huge central directory, setting Auto-Flush will influence the performance.
		\see Flush	
		\see GetAutoFlush
	*/
	void SetAutoFlush(bool bAutoFlush = true);
	

	/**
		return the current #m_bAutoFlush value
		\see Flush	
		\see SetAutoFlush
	*/
	bool GetAutoFlush()const {return m_bAutoFlush;}

/**
	Return the system compatibility of the current archive.
	System compatibility value for the single file in the archive
	(represented by CZipFileHeader) influences file attributes conversion
	(the file attributes are defined differently across the platforms).
	When opening an existing archive CZipArchive assumes the system compatibility
	of the whole archive to be the same as of the first file in the archive
	(if present). In other cases the current system value is assumed which is
	taken from ZipPlatform::GetSystemID during creating or opening an archive
	\remark
	If the existing archive during opening is empty, ZipPlatform::GetSystemID
	is assumed to be the default system for the files that will be added to the archive.
		
	\return	
		one of the enum values defined in \link ZipCompatibility::ZipPlatforms
		ZipCompatibility.h \endlink
	\see ZipCompatibility::ZipPlatforms
	\see ZipPlatform::GetSystemID
	\see CZipFileHeader::GetSystemCompatibility
*/
	int GetSystemCompatibility() const {return m_iArchiveSystCompatib;}

/**
	Set the system compatibility of the archive. By default it is set to the 
	current system value (the one returned by ZipPlatform::GetSystemID() function).
	Use it after opening the archive, but before adding a new file or using 
	SetFileHeaderAttr() function
	\param iSystemComp
		can be one of ZipCompatibility::ZipPlatforms values
	\return
		return \c false if the value \e iSystemComp is not supported 
		(ZipCompatibility::IsPlatformSupported returns \c false for the value)
		or it is not possible to set it right now
*/
	bool SetSystemCompatibility(int iSystemComp);

/**
	Set the attributes for CZipFileHeader structure to be used
	in #OpenNewFile method as an argument.
	This special procedure is taken, because the system compatibility must
	be set for CZipFileHeader prior to the value, which must be identical to
	the return value of #GetSystemCompatibility method.
	\param	header
		the structure to have attributes set
	\param	uAttr
		attributes to set
	\note Throws exceptions if the archive system or the current system 
	is not supported by the ZipArchive library.
	\see GetSystemCompatibility
*/
	void SetFileHeaderAttr(CZipFileHeader& header, DWORD uAttr);


/**
	A helper for a various purposes (needed e.g. by the program that
	cracks the zip archives password)
	\return	the pointer to the static CRC table in the zlib library
	
*/
	static const DWORD* GetCRCTable()
	{
			return get_crc_table();
	}

/**
	Return the underlying archive storage medium.
	\warning A method for a very advanced use - you normally never need it.
	\return	the pointer to #m_storage
	\see CZipStorage
*/
	CZipStorage* GetStorage(){return &m_storage;}


/**
	Set #m_bDetectZlibMemoryLeaks value.
	\param	bDetect
	\note Use before opening a file in the archive.
	\see m_bDetectZlibMemoryLeaks
		
*/
	void SetDetectZlibMemoryLeaks(bool bDetect)
	{
		if (m_iFileOpened != nothing)
		{
			TRACE(_T("CZipArchive::SetDetectZlibMemoryLeaks: Set it before opening a file in the archive"));
			return;
		}
		m_bDetectZlibMemoryLeaks = bDetect;
		
	}

/**
	Set CZipCentralDir::m_bConvertAfterOpen value.
	The default value is \c true.
	Setting this value to \c false is generally not effective and is intended 
	only for quick and short operations on archives with lots of files inside
	(e.g. open archive, make an operation on a file which index you already know
	and close the archive - using #FindFile function already makes setting this 
	value to \c false inefficient)
	
	\param	bConvertAfterOpen
	\note Use before opening the archive.
	\see CZipCentralDir::m_bConvertAfterOpen		
*/
	void SetConvertAfterOpen (bool bConvertAfterOpen)
	{
		if (!IsClosed())
		{
			TRACE(_T("CZipArchive::SetConvertAfterOpen: Set it before opening the archive"));
			return;
		}
		m_centralDir.m_bConvertAfterOpen = bConvertAfterOpen;

	}


	/**
	Set CZipCentralDir::m_bOemConversion value. This has only effect on the archives that are created
	or read under Windows platform.
	The default value is \c true.
	It enables or disables OEM conversion of the filenames in the archive. The OEM conversion is not desired when 
	filenames contain e.g. Japanese or Korean characters. You need to disable the OEM conversion in this case
	to properly extract the filenames later. Disabling the OEM conversion and creating a new archive in this mode, 
	will make the filenames with non-US characters not properly readable under other Windows archivers
	(e.g. WinRar, WinZip).
	\param enable
	\note Use before opening the archive.
	\see CZipCentralDir::m_bOemConversion		
	\see WideConversionUseAnsi
	*/
	void EnableOemConversion(bool enable)
	{
		if (!IsClosed())
		{
			TRACE(_T("CZipArchive::EnableOemConversion: Set it before opening the archive"));
			return;
		}
		m_centralDir.m_bOemConversion = enable;
	}

/**
	Enable fast finding by the file name of the files inside the archive.
	Set CZipCentralDir::m_bFindFastEnabled to \c true, which is required by #FindFile.
	#FindFileIt is called by #FindFileif necessary. It builds CZipCentralDir::m_findarray
	with the default case-sensitivity (set with #SetCaseSensitivity)
	\note Call it only after opening the archive. 
	\param	bEnable
	\see CZipCentralDir::m_bFindFastEnabled
	\see FindFile
*/
	void EnableFindFast(bool bEnable = true);


    /**
		After you enable FindFast feature with #EnableFindFast, you can retrieve