////////////////////////////////////////////////////////////////////////////////
|
// This source file is part of the ZipArchive library source distribution and
|
// is Copyrighted 2000 - 2011 by Artpol Software - Tadeusz Dracz
|
//
|
// This program is free software; you can redistribute it and/or
|
// modify it under the terms of the GNU General Public License
|
// as published by the Free Software Foundation; either version 2
|
// of the License, or (at your option) any later version.
|
//
|
// For the licensing details refer to the License.txt file.
|
//
|
// Web Site: http://www.artpol-software.com
|
////////////////////////////////////////////////////////////////////////////////
|
|
/**
|
* \file ZipCallback.h
|
* Includes the CZipCallback and the derived classes.
|
*
|
*/
|
|
#if !defined(ZIPARCHIVE_ZIPCALLBACK_DOT_H)
|
#define ZIPARCHIVE_ZIPCALLBACK_DOT_H
|
|
#if _MSC_VER > 1000
|
#pragma once
|
#if defined ZIP_HAS_DLL
|
#pragma warning (push)
|
#pragma warning( disable : 4251 ) // needs to have dll-interface to be used by clients of class
|
#endif
|
#endif
|
|
#include "ZipString.h"
|
#include "ZipExport.h"
|
|
/*
|
When processing split archives, this value is passes as the argument to the CZipCallback::Callback method
|
to notify that the current volume is the last one.
|
*/
|
#define ZIP_SPLIT_LAST_VOLUME (ZIP_SIZE_TYPE)(-1)
|
|
/**
|
A base class for callback objects that are notified when various actions take place.
|
You need to derive your own class and overload the #Callback method to use it.
|
Do not derive from CZipCallback directly but derive from:
|
\li CZipSegmCallback, when you create a segmented archive - you will be notified
|
when a next volume is processed in a segmented archive.
|
\li CZipActionCallback, for other notifications.
|
|
\see
|
<a href="kb">0610051553|span</a>
|
\see
|
<a href="kb">0610231200</a>
|
\see
|
CZipSegmCallback
|
\see
|
CZipActionCallback
|
*/
|
struct ZIP_API CZipCallback
|
{
|
/**
|
The method called as a callback.
|
|
Return \c false from inside of this method to abort the current operation. If it is a segmented archive callback object,
|
a CZipException with CZipException::aborted code will be thrown, otherwise the code will be CZipException::abortedAction or CZipException::abortedSafely.
|
The following actions can be safely aborted (without corrupting the archive):
|
- extracting
|
- testing
|
- saving the central directory in a not segmented archive
|
- counting bytes before deleting files
|
(saved data is removed in case of break and you can save it again).
|
|
If the archive is segmented and if saving is aborted, the archive
|
will not be damaged, but saved part of the central directory will be not removed
|
and the new central directory will have to be saved after it.
|
|
\param uProgress
|
The value depends on the type of the operation.
|
|
\return
|
\c false to abort the current operation; \c true to continue it.
|
|
\note
|
Override this method in a derived class. If you define this method inside the class declaration, consider inlining
|
it to make an action progress faster.
|
|
\see
|
CZipSegmCallback
|
*/
|
virtual bool Callback(ZIP_SIZE_TYPE uProgress) = 0;
|
|
|
/**
|
The filename of an external file, if an action (adding, extracting or segmentation) uses such a file.
|
You can set its value, to change the currently used path.
|
*/
|
CZipString m_szExternalFile;
|
virtual ~CZipCallback(){}
|
};
|
|
/**
|
When you derive from CZipSegmCallback, you can use the derived class as a callback object for:
|
- the disk change notification in a spanned archive,
|
- notification about the next part being processed in a split archive.
|
|
You need to override the CZipActionCallback::Callback method.
|
The value of the \a uProgress parameter in the callback method has the following meaning:
|
- the minimum number of free bytes required on the disk when writing a spanned archive
|
- it is set to \c 0 when reading a spanned archive
|
- when writing or reading a split archive it is set to \c 0 apart for the last volume when it is set to \c ZIP_SPLIT_LAST_VOLUME
|
|
Return \c false from the callback function to abort the operation: the proper exception will be thrown.
|
|
\see
|
<a href="kb">0610051553|span</a>
|
\see
|
CZipActionCallback::Callback
|
\see
|
CZipArchive::SetSegmCallback
|
*/
|
struct ZIP_API CZipSegmCallback : public CZipCallback
|
{
|
/**
|
Values indicating the reason for calling the callback.
|
*/
|
enum SegmCodes
|
{
|
scVolumeNeededForRead, ///< The next volume is needed when reading a segmented archive. The number of the volume is stored in #m_uVolumeNeeded.
|
scVolumeNeededForWrite, ///< The next volume is needed when writing a segmented archive. The number of the volume is stored in #m_uVolumeNeeded.
|
scFileNameDuplicated, ///< The file that is used for writing a new volume already exists.
|
scCannotSetVolLabel, ///< The disk label could not be set. The disk may be write-protected. It is called only for spanned archives.
|
scFileCreationFailure, ///< The archive file could not be created. The disk may be write-protected.
|
scFileNotFound, ///< The given volume file was not found when reading a split archive. The number of the volume is stored in #m_uVolumeNeeded. It is called only for split archives.
|
};
|
|
ZIP_VOLUME_TYPE m_uVolumeNeeded; ///< The number of the volume needed when reading or writing a segmented archive. Volumes are numbered starting from 1.
|
|
int m_iCode; ///< The reason for calling the callback. It can be one of the #SegmCodes values.
|
};
|
|
/**
|
When you derive from CZipActionCallback, you can use the new class as a callback object when adding, extracting, deleting, testing files
|
or saving the central directory.
|
You need to override the CZipActionCallback::Callback method.
|
The value of the \a uProgress parameter in the callback method is the amount of data just processed.
|
|
\see
|
<a href="kb">0610231200</a>
|
\see
|
CZipActionCallback::Callback
|
\see
|
CZipArchive::SetCallback
|
*/
|
struct ZIP_API CZipActionCallback : public CZipCallback
|
{
|
friend class CZipArchive;
|
friend class CZipCentralDir;
|
|
/**
|
Values used for specifying a callback type in the CZipArchive::SetCallback method.
|
You can assign several values to the same callback object (use the logical \c OR).
|
\see
|
<a href="kb">0610231200</a>
|
\see
|
CZipArchive::SetCallback
|
\see
|
CZipActionCallback
|
*/
|
enum CallbackType
|
{
|
/**
|
Not used.
|
You can use it for your own purposes.
|
*/
|
cbNothing = 0x0000,
|
|
/**
|
Compressing a file.
|
The callback called when adding a file with one of the CZipArchive::AddNewFile methods.
|
*/
|
cbAdd = 0x0001,
|
|
/**
|
Moving a file from a temporary archive.
|
The callback called while adding a file (only on a segmented archive) when the smartness level contains
|
CZipArchive::zipsmCheckForEff or CZipArchive::zipsmCheckForEffInMem
|
and if the just compressed file is being moved from a temporary place (file or memory) to the archive.
|
*/
|
cbAddTmp = 0x0002,
|
|
/**
|
Storing a file.
|
The callback called while adding a file and if its compressing has proven to be inefficient
|
and it is now being stored (instead of compressed) in the archive. The smartness level must
|
contain CZipArchive::zipsmCheckForEff or CZipArchive::zipsmCheckForEffInMem. The archive can be
|
segmented or not.
|
*/
|
cbAddStore = 0x0004,
|
|
/**
|
Extracting a file.
|
The callback called when extracting a file with one of the CZipArchive::ExtractFile methods.
|
*/
|
cbExtract = 0x0008,
|
|
/**
|
Counting data to process before deleting.
|
The callback called before the actual deletion takes place and the map of holes and continuous
|
areas is being created. It is safe to abort the operation (by returning \c false from
|
the callback method).
|
*/
|
cbDeleteCnt = 0x0010,
|
|
/**
|
Deleting files.
|
The callback called when moving data while deleting file(s) with the CZipArchive::RemoveFile
|
method or one of the CZipArchive::RemoveFiles methods.
|
*/
|
cbDelete = 0x0020,
|
|
/**
|
Testing a file.
|
The callback called when testing a file with the CZipArchive::TestFile method.
|
*/
|
cbTest = 0x0040,
|
|
/**
|
Saving the central directory.
|
The callback called when saving the central directory with the CZipCentralDir::Write method
|
(usually on close or flush). It is safe to abort the operation on a segmented archive -
|
the saved part of the central directory will be removed from disk.
|
*/
|
cbSave = 0x0080,
|
|
/**
|
Getting a file from another archive.
|
The callback called when using one of the CZipArchive::GetFromArchive methods.
|
*/
|
cbGet = 0x0100,
|
|
/**
|
Renaming a file.
|
The callback called when committing changes with the CZipArchive::CommitChanges method, if there is a need to adjust space
|
for the new filenames.
|
*/
|
cbModify = 0x0200,
|
|
/**
|
Moving data.
|
The callback called when moving data inside the archive. It happens while replacing files to adjust space
|
for the new file or while shifting data with the CZipArchive::ShiftData() method.
|
*/
|
cbMoveData = 0x0400,
|
|
/**
|
The callback called when counting files and bytes to process when performing multiple actions.
|
When this callback is called, CZipActionCallback::m_uTotalToProcess is
|
not set (because it is unknown and that's why the counting is performed),
|
but it allows to abort the counting process.
|
*/
|
cbCalculateForMulti= 0x0800,
|
|
/**
|
The callback called when adding multiple files with one of the CZipArchive::AddNewFiles
|
methods. This callback also registers for #cbAdd.
|
|
\see
|
<a href="kb">0610231200|multi</a>
|
*/
|
cbMultiAdd = 0x1000 | cbAdd,
|
|
|
/**
|
The callback called when preparing existing files for encryption.
|
|
\see
|
<a href="kb">0610201627|existing</a>
|
*/
|
cbEncryptPrepare= 0x2000,
|
|
/**
|
The callback called in order to report the progress of adjusting space inside the archive before the actual encryption takes place.
|
|
\see
|
<a href="kb">0610201627|existing</a>
|
*/
|
cbEncryptMoveData= 0x4000,
|
|
/**
|
The callback called for every file being encrypted.
|
|
\see
|
<a href="kb">0610201627|existing</a>
|
*/
|
cbEncrypt = 0x8000,
|
|
|
/**
|
The callback called when encrypting existing files in the archive. This callback also registers for #cbEncryptMoveData and #cbEncrypt.
|
|
\see
|
<a href="kb">0610201627|existing</a>
|
\see
|
<a href="kb">0610231200|multi</a>
|
*/
|
cbMultiEncrypt = 0x10000 | cbEncryptMoveData | cbEncrypt,
|
|
/**
|
Reserved.
|
You can declare your own callback types above this value. Do not use the numeric value,
|
but the symbol name - the value may change in the future releases of the library.
|
*/
|
cbNextValue = 0x20000,
|
|
/**
|
All sub-actions.
|
Represents the sub-actions callbacks - they are called as a part of bigger actions
|
(#cbAddTmp | #cbAddStore | #cbDeleteCnt | #cbMoveData | #cbCalculateForMulti | #cbEncryptPrepare | #cbEncryptMoveData).
|
*/
|
cbSubActions = cbAddTmp | cbAddStore | cbDeleteCnt | cbMoveData | cbCalculateForMulti | cbEncryptPrepare | cbEncryptMoveData,
|
|
/**
|
Main callbacks.
|
Represents the main action callbacks (#cbAdd | #cbExtract | #cbDelete | #cbTest | #cbSave | #cbGet | #cbModify | #cbEncrypt).
|
*/
|
cbActions = cbAdd | cbExtract | cbDelete | cbTest | cbSave | cbGet | cbModify | cbEncrypt,
|
|
/**
|
Multiple action callbacks.
|
Represents the multiple action callbacks.
|
*/
|
|
cbMultiActions = cbMultiAdd | cbMultiEncrypt,
|
|
/**
|
All values.
|
Use this value to use one callback object for all callback types.
|
*/
|
cbAll = cbActions | cbSubActions | cbMultiActions
|
};
|
|
|
/**
|
A structure that provides global information in case of using multiple actions callbacks.
|
|
\see
|
<a href="kb">0610231200|multi</a>
|
\see
|
cbMultiActions
|
*/
|
struct ZIP_API CMultiActionsInfo
|
{
|
friend struct CZipActionCallback;
|
|
ZIP_SIZE_TYPE m_uTotalBytesToProcess; ///< The total number of bytes to process.
|
ZIP_SIZE_TYPE m_uTotalFilesToProcess; ///< The total number of files to process.
|
ZIP_SIZE_TYPE m_uBytesProcessed; ///< The total number of bytes processed so far.
|
ZIP_SIZE_TYPE m_uFilesProcessed; ///< The total number of files processed so far.
|
|
/**
|
Returns the number of files left to process.
|
\return
|
The number of files left to process.
|
*/
|
ZIP_SIZE_TYPE LeftFilesToProcess() const {return m_uTotalFilesToProcess - m_uFilesProcessed;}
|
|
/**
|
Returns the number of bytes left to process.
|
\return
|
The number of bytes left to process.
|
*/
|
ZIP_SIZE_TYPE LeftBytesToProcess() const {return m_uTotalBytesToProcess - m_uBytesProcessed;}
|
private:
|
void Init(ZIP_SIZE_TYPE uTotalItemsToProcess, ZIP_SIZE_TYPE uTotalBytesToProcess, int iReactType)
|
{
|
m_uTotalFilesToProcess = uTotalItemsToProcess;
|
m_uTotalBytesToProcess = uTotalBytesToProcess;
|
m_uBytesProcessed = m_uFilesProcessed = 0;
|
m_iReactType = iReactType;
|
m_bActive = false;
|
}
|
void OnCallbackInit(int iType)
|
{
|
// this assumes, that the callback type will stay unchanged
|
// between Init() and CallbackEnd()
|
m_bActive = iType == m_iReactType;
|
}
|
|
void OnCallCallback(ZIP_SIZE_TYPE uProgress)
|
{
|
if (m_bActive)
|
m_uBytesProcessed += uProgress;
|
}
|
bool OnNextFile()
|
{
|
if (m_bActive)
|
{
|
m_uFilesProcessed++;
|
return true;
|
}
|
else
|
return false;
|
}
|
bool m_bActive;
|
int m_iReactType;
|
};
|
|
CZipActionCallback()
|
{
|
m_uTotalToProcess = 0;
|
m_uProcessed = 0;
|
m_pMultiActionsInfo = NULL;
|
}
|
|
/**
|
Called when a multiple actions operation is about to begin. Initializes CMultiActionsInfo object.
|
|
\param uTotalFilesToProcess
|
The number of files to process.
|
|
\param uTotalBytesToProcess
|
The number of bytes to process.
|
|
\param iReactType
|
The type of the callback that will cause increasing of values in CMultiActionsInfo.
|
It can be one of #CallbackType values.
|
|
\see
|
<a href="kb">0610231200|multi</a>
|
\see
|
GetMultiActionsInfo
|
|
\note
|
When overriding this method, call the base method from your code.
|
*/
|
virtual void MultiActionsInit(ZIP_SIZE_TYPE uTotalFilesToProcess, ZIP_SIZE_TYPE uTotalBytesToProcess, int iReactType)
|
{
|
InitMultiActionsInfo();
|
m_pMultiActionsInfo->Init(uTotalFilesToProcess, uTotalBytesToProcess, iReactType);
|
}
|
|
/**
|
Called to initialize the callback object.
|
Sets the filenames and resets #m_uTotalToProcess and #m_uProcessed variables to \c 0.
|
#m_iType variable is already set to the proper value. Called at the beginning of the operation.
|
|
\param lpszFileInZip
|
The file that is being processed in the archive.
|
|
\param lpszExternalFile
|
The external file being processed. This is set to \c NULL, if the operation takes place in memory.
|
*/
|
virtual void Init(LPCTSTR lpszFileInZip = NULL, LPCTSTR lpszExternalFile = NULL)
|
{
|
m_szFileInZip = lpszFileInZip;
|
m_szExternalFile = lpszExternalFile;
|
m_uTotalToProcess = 0; // not yet known
|
m_uProcessed = 0; // nothing yet done
|
CacheStepSize();
|
ResetProgressStage();
|
if (m_pMultiActionsInfo)
|
// the type is known now
|
m_pMultiActionsInfo->OnCallbackInit(m_iType);
|
}
|
|
/**
|
Called after calculating the total amount of data to process.
|
|
\param uTotalToDo
|
Total amount of data to process. The method initializes #m_uTotalToProcess with this value.
|
*/
|
virtual void SetTotal(ZIP_SIZE_TYPE uTotalToDo)
|
{
|
m_uTotalToProcess = uTotalToDo;
|
// m_uProcessed = 0; // already done in CZipCallbackProvider::Get
|
}
|
|
/**
|
Called when a next action begins in multiple actions processing.
|
This method calls #Callback method with \a uProgress parameter set to \c 0.
|
|
\return
|
The value returned from the #Callback method.
|
|
\see
|
<a href="kb">0610231200|multi</a>
|
|
\note
|
When overriding this method, call the base method from your code.
|
*/
|
virtual bool MultiActionsNext()
|
{
|
if (m_pMultiActionsInfo && m_pMultiActionsInfo->OnNextFile())
|
return Callback(0);
|
else
|
return true;
|
}
|
|
/**
|
Called after the operation finishes.
|
It is not called in case of an exception, but
|
it is called before throwing CZipException::abortedAction or CZipException::abortedSafely.
|
*/
|
virtual void CallbackEnd()
|
{
|
//ASSERT(m_uProcessed == m_uTotalToProcess);
|
};
|
|
/**
|
Called at the end of the multiple actions operation.
|
Releases multiple actions information (CMultiActionsInfo).
|
Override this method, if you want this information to be persisted after
|
operation finishes. In that case, CMultiActionsInfo will be released
|
on destruction.
|
|
\see
|
<a href="kb">0610231200|multi</a>
|
*/
|
virtual void MultiActionsEnd()
|
{
|
ReleaseMultiActionsInfo();
|
}
|
|
/**
|
Returns the amount of data left to process.
|
|
\return
|
The amount of data left to process.
|
*/
|
ZIP_SIZE_TYPE LeftToProcess() const {return m_uTotalToProcess - m_uProcessed;}
|
|
/**
|
The total amount of data to process. This value is set when the #SetTotal method is called.
|
|
Depending on the action it is set then to:
|
- Adding a file : the size of the external file being added (or if the type of the callback is CZipActionCallback::cbAddTmp,
|
the size of the compressed data: CZipFileHeader::m_uComprSize).
|
- Extracting a file : the size of the uncompressed data (CZipFileHeader::m_uUncomprSize).
|
- Testing a file : the same as above.
|
- Deleting a file : the number of bytes to move - the size of all files to remain above the first
|
file to delete (calculated from offsets in CZipFileHeader::m_uOffset).
|
- Saving the central directory : the number of files in the archive.
|
*/
|
ZIP_SIZE_TYPE m_uTotalToProcess;
|
ZIP_SIZE_TYPE m_uProcessed; ///< The total amount of data processed so far.
|
CZipString m_szFileInZip; ///< The name of the file being processed in the archive.
|
|
/**
|
The type of the callback. It is set to one of the #CallbackType values when an action begins.
|
It's useful, if you have more than one callback assigned to the same callback object.
|
*/
|
int m_iType;
|
|
/**
|
Returns the current CMultiActionsInfo object in multiple actions operation or \c NULL, if
|
the current operation is not one of CZipActionCallback::cbMultiActions actions.
|
|
\return
|
The current CMultiActionsInfo object.
|
|
\see
|
<a href="kb">0610231200|multi</a>
|
*/
|
CMultiActionsInfo* GetMultiActionsInfo()
|
{
|
return m_pMultiActionsInfo;
|
}
|
|
/**
|
Sets the type of the callback, that will cause the current CMultiActionsInfo object to update its progress.
|
|
\param iType
|
The type of the callback. It can be one of the #CallbackType values.
|
*/
|
void SetReactType(int iType)
|
{
|
m_pMultiActionsInfo->m_iReactType = iType;
|
}
|
|
/**
|
Specifies how often the Callback() method is called. The Callback() method is called every \b n-th callback request,
|
where \b n is the value returned from the GetStepSize() method.
|
Override this method to adjust the frequency of calling the callback.
|
|
\return
|
The value that determines the frequency of calling the Callback() method.
|
By default, it returns \c 256 for #cbSave, #cbDeleteCnt, #cbCalculateForMulti and #cbEncryptPrepare and \c 1
|
for other callback types.
|
|
\note
|
This method is called in the Init() method and the returned value is cached for further processing.
|
This means that when you override this method, even with some time-consuming operations, it will not affect
|
the in-action performance.
|
|
\note
|
Do not use a too low value, because it may increase significantly the time needed to process a large number of files.
|
*/
|
virtual int GetStepSize()
|
{
|
return m_iType == cbSave || m_iType == cbDeleteCnt || m_iType == cbCalculateForMulti || m_iType == cbEncryptPrepare ? 256 : 1;
|
}
|
|
~CZipActionCallback()
|
{
|
ReleaseMultiActionsInfo();
|
}
|
|
/**
|
Called by processing classes when data processing progressed.
|
|
\param uProgress
|
The amount of data processed.
|
|
\return
|
The value returned from #Callback, if the method was called; \c true otherwise.
|
|
*/
|
bool RequestCallback(ZIP_SIZE_TYPE uProgress = 1)
|
{
|
if (!uProgress)
|
return true;
|
if (m_iCachedStepSize == 1)
|
return CallCallback(uProgress);
|
else
|
{
|
m_uAccumulatedProgress += uProgress;
|
if (m_iCurrentStep >= m_iCachedStepSize)
|
{
|
bool ret = CallCallback(m_uAccumulatedProgress);
|
ResetProgressStage();
|
return ret;
|
}
|
else
|
{
|
m_iCurrentStep++;
|
return true;
|
}
|
}
|
}
|
|
/**
|
Called by processing classes when data processing is finished to
|
allow calling the Callback() method for the remaining amount of processed data (for
|
which the Callback() has not been called). This usually happens,
|
when GetStepSize() does not return 1.
|
|
\param uProgress
|
The amount of data processed.
|
|
\return
|
The value returned from the #Callback method, if the method was called; \c true otherwise.
|
|
*/
|
bool RequestLastCallback(ZIP_SIZE_TYPE uProgress = 0)
|
{
|
bool ret;
|
if (m_uAccumulatedProgress == 0 && uProgress == 0)
|
ret = true;
|
else
|
ret = CallCallback(m_uAccumulatedProgress + uProgress);
|
ResetProgressStage();
|
return ret;
|
}
|
|
protected:
|
/**
|
|
Calls the Callback() method internally, increases CZipActionCallback::m_uProcessed and lets the CZipActionCallback
|
increase its values, if needed.
|
|
\param uProgress
|
The amount of data processed.
|
|
\return
|
The return value from the Callback() method.
|
*/
|
virtual bool CallCallback(ZIP_SIZE_TYPE uProgress)
|
{
|
m_uProcessed += uProgress;
|
if (m_pMultiActionsInfo)
|
m_pMultiActionsInfo->OnCallCallback(uProgress);
|
return Callback(uProgress);
|
}
|
|
/**
|
Caches the value returned from the GetStepSize() method. Called in the Init()method.
|
*/
|
void CacheStepSize()
|
{
|
m_iCachedStepSize = GetStepSize();
|
if (m_iCachedStepSize == 0)
|
m_iCachedStepSize = 1;
|
}
|
|
/**
|
Initializes the values that depend on the frequency of calling the Callback() method.
|
Called with every call to the Callback() method.
|
|
\see
|
GetStepSize
|
*/
|
void ResetProgressStage()
|
{
|
m_iCurrentStep = 1;
|
m_uAccumulatedProgress = 0;
|
}
|
private:
|
CMultiActionsInfo* m_pMultiActionsInfo;
|
void InitMultiActionsInfo()
|
{
|
ReleaseMultiActionsInfo();
|
m_pMultiActionsInfo = new CMultiActionsInfo();
|
}
|
void ReleaseMultiActionsInfo()
|
{
|
if (m_pMultiActionsInfo != NULL)
|
{
|
delete m_pMultiActionsInfo;
|
m_pMultiActionsInfo = NULL;
|
}
|
}
|
|
int m_iCachedStepSize; ///< The cached step value for the time of processing.
|
int m_iCurrentStep;
|
ZIP_SIZE_TYPE m_uAccumulatedProgress;
|
};
|
|
#if (_MSC_VER > 1000) && (defined ZIP_HAS_DLL)
|
#pragma warning (pop)
|
#endif
|
|
|
#endif
|
