ziparchive.h

ZIP压缩、解压缩算法库

	void GetAdvanced(int* piWriteBuffer = NULL, int* piGeneralBuffer = NULL, int* piSearchBuffer= NULL)
	{
		if (piWriteBuffer)
			*piWriteBuffer = 	m_storage.m_iWriteBufferSize;
		if (piGeneralBuffer)
			*piGeneralBuffer = m_info.m_iBufferSize;
		if (piSearchBuffer)
			*piSearchBuffer = m_centralDir.m_iBufferSize;
	}

	/**
		Enum values used as \e iWhich parameter in #SetCallback function.
		You can assign several values to the same functor (OR them)
		\see CZipActionCallback
	*/
	enum CallbackType
	{
		cbNothing	= 0x0000,	///< you can use it for your own purposes
		cbAdd		= 0x0001,	///< called when adding a file with one of #AddNewFile functions
		cbAddTmp	= 0x0002,	///< called while adding a file (only on a disk-spanning archive) when the smartness level contains CZipArchive::zipsmCheckForEff or CZipArchive::zipsmCheckForEffInMem 
								///< and if just compressed file is being moved from a temporary place (file or memory) to the archive 
		cbAddStore	= 0x0004,	///< called while adding a file and if it's compressing has proven to be inefficient and it is now being stored (instead of compressed) in the archive;
								///< smartness level must contain CZipArchive::zipsmCheckForEff or CZipArchive::zipsmCheckForEffInMem; the archive can be disk-spanning or not

		cbExtract	= 0x0008,	///< called when extracting a file with one of #ExtractFile functions

		cbDeleteCnt	= 0x0010,	///< called before the actual deletion takes place and the map of holes and continuous areas is being created (it safe to break it by returning \c false from the callback method)
		cbDelete	= 0x0020,	///< called when moving data while deleting file(s) with function #DeleteFile or one of #DeleteFiles functions

		cbTest		= 0x0040,	///< called when testing a file with #TestFile function
		cbSave		= 0x0080,	///< called when saving the central directory with CZipCentralDir::Write (usually on close or flush); it is safe to break on non-disk spanning archive - the saved part of 
								///< the central directory will be removed from disk
		cbGetFromArchive 
					= 0x0100,	///< called when using one of #GetFromArchive methods
		cbRename	= 0x0200,	///< called when during the renaming a file there is a need to make less or more space for the new filename
		cbReplace	= 0x0400,   ///< called when moving data while replacing files to make less or more space for the new file
		cbNextValue = 0x0800,	///< for CZipActionCallback overrides and user defined callbacks
		

		cbSubActions= cbAddTmp | cbAddStore | cbDeleteCnt | cbReplace,				///< sub actions - they are part of bigger actions (#cbAddTmp | #cbAddStore | #cbDeleteCnt | #cbReplace)
		cbActions	= cbAdd | cbExtract | cbDelete | cbTest | cbSave | cbGetFromArchive | cbRename,	///< main actions (#cbAdd | #cbExtract | #cbDelete | #cbTest | #cbSave | #cbGetFromArchive | #cbRename)
		cbAll		= cbActions | cbSubActions							///< assign all callbacks to the same functor
	};


    /**
       
		Set callback functors for the following operations on the zip archive: adding, extracting, testing or deleting files.
		See \ref sectCallb information on how to use functors.
		\param pCallback
			the address of the functional object which class is derived from CZipActionCallback
			(you need to override member function CZipCallback::Callback in the derived class)
			Set it to \c NULL to clear callback for the selected actions.
		\param iWhich
			can be one or more (use logical OR) #CallbackType values.

		\see CZipActionCallback
		\see GetCallback
		
     */
	void SetCallback(CZipActionCallback* pCallback = NULL, int iWhich = cbAll);

	/**
		\return the callback \e iWhich set with #SetCallback
	*/
	CZipActionCallback* GetCallback(CallbackType iWhich)
	{
		return m_callbacks.Get(iWhich);
	}

	/**
		Set the callback functor used during operations on a 
		PKZIP compatible disk spanning archive to change disks.
		Set it before opening the archive. If you open the archive
		in the \ref PKSpan "PKZIP compatible mode" and don't set the callback functor, 
		the exception CZipException::noCallback will be thrown.

		Callback functor's method CZipSpanCallback::Callback is called when there is a need for a disk change.
		Calling CZipArchive methods from inside this method may result in an unexpected behavior.
		\param pCallback
			the address of the functional object which class is derived from CZipSpanCallback
			(you need to override member function CZipCallback::Callback in the derived class)
			Set it to \c NULL to clear the callback.

		\see CZipSpanCallback
	*/
	void SetSpanCallback(CZipSpanCallback* pCallback = NULL){m_storage.m_pChangeDiskFunc = pCallback;}


	
	/**
		Archive open modes used in <CODE> #Open(LPCTSTR , int , int ) </CODE>
		and <CODE> #Open(CZipMemFile, int ) </CODE>
	*/
	enum OpenMode
	{
		zipOpen,			///< open an existing archive
		/**
			Open an existing archive as a read only file.
			This mode is intended to use in a self extract code or opening 
			archive on storage without write access (e.g. CD-ROMS),
			If you try to modify the archive in this mode,
			an exception will be thrown.
		*/
		zipOpenReadOnly,
		zipCreate,			///< create a new archive
		zipCreateSpan		///< create a disk spanning archive
	};



/**
	Open or create a zip archive.

	The archive creation mode depends on \e iMode and \e iVolumesSize values:
	- if \e iMode == #zipCreateSpan and \e iVolumeSize <= 0 then create disk spanning 
		archive in \ref PKSpan "PKZIP compatible mode" (pkzipSpan)
	- if \e iMode == #zipCreateSpan and \e iVolumeSize > 0 then create disk spanning 
		archive in \ref TDSpan "TD compatible mode" (tdSpan)
	- if \e iMode == #zipOpen and the existing archive is a spanned archive
		then pkzipSpan mode is assumed if the archive is on a removable device
		or tdSpan otherwise;			<BR>
		if you want to open tdSpan archive on a removable device, set \e iVolumeSize
		to a value different from 0	
	- if \e iMode == #zipCreate then \e iVolumeSize doesn't matter

	\param	szPathName
		the path to the archive
	\param	iMode
		one of the #OpenMode values
	\param	iVolumeSize
	the volume size in the disk spanning archive; 
	the size of the volume may be from 1 to INT_MAX , 
	and the bigger - the faster is creation and extraction (no file changes between volumes) - but the size of the whole archive is the same. 
	If you're creating disk-spanning archive in \ref TDSpan "TD span compatible mode" 
	and plan later to convert it to \ref PKSpan "PKZIP compatible mode" (see \ref sectSpan), it is good to set this this value to 
	about the size of the diskette (a little less just in case).
	
	\note Throws exceptions.
	\see Open(CZipMemFile&, int);
	\see GetSpanMode
*/
	void Open(LPCTSTR szPathName, int iMode = zipOpen, int iVolumeSize = 0);


/**
	Open or create the archive in memory. The CZipMemFile object is not closed
	after closing the archive, so that is it possible to work with it afterwards.
	\param	mf
		CZipMemFile structure to create archive in or extract from
		\note This is important: you shouldn't destroy CZipMemFile object before
		closing the archive, because you'll get an error;
	\param	iMode
		Open mode. 
		The following modes are valid:  #zipOpen, #zipOpenReadOnly, #zipCreate
	\note	Throws exceptions.
	\see Open(LPCTSTR, int, int);
*/
	void Open(CZipMemFile& mf, int iMode = zipOpen);

/**
	Set #m_szRootPath to a specified value. Use it if you don't want to set
	\e bFullPath argument in #AddNewFile or #ExtractFile to true and you 
	don't want to strip the whole path neither, but only a specific beginning.
	Use it AFTER opening the archive and before using #AddNewFile or #ExtractFile.
	See \ref q9 "the FAQ" for the example of use.
	\param	szPath
		Set it to the string that you want to be omitted from the beginning of the path of the file
		in the archive <BR>
		if \c NULL - clears the #m_szRootPath and no path beginning will be matched against it

	\note Set the case-sensitivity with #SetCaseSensitivity

	\see AddNewFile 
	\see ExtractFile
	\see GetRootPath

*/
	void SetRootPath(LPCTSTR szPath = NULL);


    /**
       Return the current value of #m_szRootPath
       \return CZipString 
     */
	CZipString GetRootPath()const 
	{
		return m_szRootPath;
	}

	/**
		The levels of smartness of the adding files action (see #AddNewFile)
		\note If you wish to use \e zipsmCheckForEff, you should use 
		\e zipsmNotCompSmall as well, because it will save you the time
		( the small file will be surely larger after compression, so that
		we can add it not compressed straight away);the compression level 
		is always ignored for a directory and set to 0
	*/

	enum Smartness
	{
		zipsmLazy			= 0x0000,		///< do not bother (you know what you're doing after all)
		zipsmCPassDir		= 0x0001,		///< clear password for directories
		zipsmCPFile0		= 0x0002,		///< clear password for files of 0 size
		zipsmNotCompSmall	= 0x0004,		///< do not compress files smaller than 5 bytes (they are always stored larger than uncompressed)
		zipsmCheckForEff	= 0x0008,		///< check whether the compressed file is larger than uncompressed and if so, remove it and store without the compression; 
										///< in the disk spanning mode, the temporary file is used for that: if the file compression is efficient, the data is not compressed
										///< again, but moved from the temporary file to the archive; you can use #SetTempPath() to set the path where the 
										///< file will be created or you can let the library figure it out (the library tries first the system default temporary directory,
										///< if it is not present or there is not enough space there, it tries the current directory, if it fails, no temporary file is created
										///< and the compression goes the usual way

		zipsmMemoryFlag		= 0x0010,  ///< combine it with zipsmCheckForEff or use zipsmCheckForEffInMem, you can also use this when replacing files see note at CZipAddNewFileInfo::m_iReplaceIndex

		zipsmCheckForEffInMem = zipsmMemoryFlag | zipsmCheckForEff, ///< the same as #zipsmCheckForEff, but the temporary file is created created in memory instead (the temporary directory set with #SetTempPath() is ignored); has the meaning only with a disk-spanning archive,
																	///< non-disk spanning archives don't need a temporary file 
		zipsmSmartPass	= zipsmCPassDir | zipsmCPFile0,			///< smart password policy (a combination of \e zipsmCPassDir and \e zipsmCPFile0)
		zipsmSmartAdd = zipsmNotCompSmall | zipsmCheckForEff,	///< smart adding (a combination of \e zipsmNotCompSmall and \e zipsmCheckForEff)
		zipsmSafeSmart = zipsmSmartPass | zipsmNotCompSmall,    ///< safe smart (smartest without checking for efficiency)
		zipsmSmartest = zipsmSmartPass | zipsmSmartAdd,			///< smart at its best

		
		zipsmInternal01		= 0xf000   ///< for internal use only

	};

	
	/**
		Add a new file to the archive. You can set the callback functor with #SetCallback.
		\param info see CZipAddNewFileInfo
		\return	\c if it returns false then the file was not added, but the internal
		state allows you to add other files (which is not possible after throwing 
		an exception)
		
		\note 
		- If you abort while adding a file in a non-disk-spanning archive, the added data will be removed from the archive
		- Throws exceptions.
		
		\see SetCallback
		\see <CODE> AddNewFile(LPCTSTR, LPCTSTR, int, int, unsigned long) </CODE>
		\see <CODE> AddNewFile(LPCTSTR, int, bool, int, unsigned long) </CODE>
		\see <CODE> AddNewFile(CZipMemFile&, LPCTSTR, int, int, unsigned long)</CODE>
	*/
	bool AddNewFile(CZipAddNewFileInfo& info);


	/**
		\see AddNewFile(CZipAddNewFileInfo& ); the parameters are equivalent to CZipAddNewFileInfo member variables
	
	*/
	bool AddNewFile(LPCTSTR lpszFilePath, int iComprLevel = -1, bool bFullPath = true,
		int iSmartLevel = zipsmSafeSmart, unsigned long nBufSize = 65536);


	/**
		\see AddNewFile(CZipAddNewFileInfo& ); the parameters are equivalent to CZipAddNewFileInfo member variables
	*/
	bool AddNewFile(LPCTSTR lpszFilePath,
							 LPCTSTR lpszFileNameInZip,
                             int iComprLevel = -1,                             
							 int iSmartLevel = zipsmSafeSmart,
                             unsigned long nBufSize = 65536);

	/**
		\see AddNewFile(CZipAddNewFileInfo& ); the parameters are equivalent to CZipAddNewFileInfo member variables
	*/
	bool AddNewFile(CZipMemFile& mf,
							 LPCTSTR lpszFileNameInZip,
                             int iComprLevel = -1,                             
							 int iSmartLevel = zipsmSafeSmart,
                             unsigned long nBufSize = 65536);



/**
	Add a new file to the opened zip archive. The zip archive cannot be 
	an existing disk spanning archive (existing at the moment of opening archive),
	because modifying such an archive is not possible (at least not with this
	version ).

	\param	header
		The structure that provides additional information about the added file.
		The following fields are valid:
		- \e m_uMethod - file compression method; can be 0 (storing) or Z_DEFLATE (deflating)
			otherwise Z_DEFLATE is assumed
		- \e m_uModDate, \e m_uModTime - Use CZipFileHeader::SetTime to set them.
			If \e lpszFilePath is not NULL this fields are overwritten and updated automatically.
			See CZipFileHeader::SetTime
		- \e m_uExternalAttr - Attributes of the file.
			If \e lpszFilePath is not NULL this field is overwritten and updated automatically.
			Use #SetFileHeaderAttr to set them. See #SetFileHeaderAttr.
		- \e m_szFileName - A filename (may be with path) to be stored inside archive
			to represent this file. See CZipFileHeader::SetFileName
		- \e m_szComment - A file comment.	See CZipFileHeader::SetComment
		- \e m_pExtraField - LOCAL extra field, use #SetExtraField after opening 
			a new file, but before closing it to set the not local extra field 
			in the header in the central directory. See #SetExtraField	<BR>
	Other fields are ignored - they are updated automatically.
	If the function returns \c true, \link #GetSystemCompatibility 
	system compatibility \endlink for this object is
	set to the correct value (the same as #m_iArchiveSystCompatib),
		additionally if \e lpszFilePath was not NULL, the attributes and 
	the time fields are filled with information retrieved from 
	the file pointed by \e lpszFilePath.		
	\param	iLevel
		The level of compression (-1, 0 - 9).
		The are several preset values for the compression level:
		- Z_DEFAULT_COMPRESSION	: -1 (equals 6)
		- Z_NO_COMPRESSION		: 0
		- Z_BEST_SPEED			: 1
		- Z_BEST_COMPRESSION	: 9			
	\param	lpszFilePath
		The path to the file to retrieve date stamp and attributes from.
		These values are stored inside the archive.
	\param uInternal
		for internal use only

	\return	\c false in the following cases:
	- the \e lpszFilePath is not NULL and the file attributes and data was not correctly retrieved
	- a file is already opened for extraction or compression
	- archive is an existing disk span archive
	- maximum file count inside archive already reached (65536)
	\note Throws exceptions.

*/
	bool OpenNewFile(CZipFileHeader & header, int iLevel = Z_DEFAULT_COMPRESSION, LPCTSTR lpszFilePath = NULL, DWORD uInternal = 0);

/**
	Compress the contents of the buffer and write it to a new file.
	\param	pBuf
		the buffer containing the data to be compressed and written
	\param	iSize
		the number of bytes to be written from the buffer
	\return	\c false if the new file hasn't been opened yet
	\note Throws exceptions.
	\see OpenNewFile
*/
	bool WriteNewFile(const void *pBuf, DWORD iSize);


/**
	Set the extra field in the central directory of the currently opened file.
	Must be used after opening a new file in the archive, but before closing it
	To set the local extra field, set it in the CZipFileHeader structure passed