Assume that you have 2 files, which you would like to compare and in case they are different to build a difference file (df-file).
To start th comparing process it is necessary to create the so called TDfCmp, which contains all necessary information concerning the compared files, and also includes additional fields. (See description of TDfCmp structure for details).. Comparing context is a special data structure
Creation of the comparing context can be implemented using one of the following functions:
int dfOpenCmpByNames ( _TCHAR const * szOldFileName, _TCHAR const * szNewFileName, int bExtractPEVersions, PTDfCmp * ppCmp );
int dfOpenCmpByHandles ( FD_T hOldFile, FD_T hNewFile, PTDfCmp * ppCmp );
In the first function compared files are set as names of files and in the second by files descriptors, which are probably created to the moment of comparing start.
Pointer on the successfully created comparing context is saved in the variable on which a ppCmp parameter points.
After the comparing context is successfully created we are ready to start comparing our files.
To compare files use function dfCompare:
int dfCompare ( TDfCmp * pCmp, TDfCmpOptions * pCmpOpt, TDfInteract * pInteract, TDfCmpResult * pCmpRes );
Besides the comparing context let's take other 3 parameters:
pCmpOpt – pointer on the structure TDfCmpOptions, which contains parameters of comparing.
Each from compared files can be divided into to main parts in the view of df-file building: file name, file attributes, last modification date/time and file content. Comparing of files is implemented by comparing of all 4 parts. Files are considered different from each other if at least one part differs. In case of file content difference there is an option used to set necessity of identical parts search for the following df-file building. (See structure TDfCmpOptions for detailed description of comparing options).
Process of content comparing and search for identical parts can be a long operation (especially for big files).
pInteract – parameter which can be used to provide the operation progress representation (for instance as a progress indicator)
Fields of structure TDfInteract on which pInteract points used to set addresses of necessary callback-functions (see TDfInteract structure description for details).
pCmpRes – points on TDfCmpResult structure where the result of file comparing (per each part) will be saved in case of successful dfCompare function termination.
The following function can be used for generalization of the comparing results to the simple conclusion: files are equal or not.
int dfTestCmpResult ( TDfCmpResult * pCmpRes );
By analysing fields of the structure TDfCmpResult using or own tools or by using the function dfTestCmpResult you can made a conclusion whether compared files are different or not and if they are then what particular parts among 4 available are different and finally you make a decision if it necessary to build a df-file. Note that difference file can be built even if files are identical. This feature can useful in some special applications.
If a decision to build df-file is made then the following function is called:
int dfBuildN ( _TCHAR const * szDfFile, TDfCmp * pCmp, TDfBldOptions * pBldOpt, TDfInteract * pInteract );
int dfBuildH ( FD_T hDfFile, TDfCmp * pCmp, TDfBldOptions * pBldOpt, TDfInteract * pInteract );
These functions differ from each other only in specifying the way the result df-file will be saved: in the file with specified name or using already created file descriptor.
pCmp – using this parameter you can pass the pointer on the comparing context which participated in the successful dfCompare function call (see dfBuildN, dfBuildH functions descriptions for details).
pBldOpt – pointer on the structure containing parameters of difference file building and also additional application data, which can be saved in the result df-file.
pInteract – this parameter allows an application program to get information on the progress of difference file building process.
Successful termination of function dfBuildN (or dfBuildH) says that df-file is successfully built.