After an initial scan during which it is determined that AbstractFile objects are being synchronized, if AbstractFolder objects are also found, an additional scan is made where the GettingSynchronizationFileFromFolder event is triggered for each folder in the list. The goal of this operation is to identify a file to be synchronized within each folder. When possible, the algorithm will suggest a file from the folder based on the name of the latest file that was identified or the manually selected master file.
At this point, the list will contain AbstractFiles.
A name for the synchronization is then computed. The name is based on the names of all the AbstractFiles in the list, in the order they were added. If enabled in the options, metadata is then loaded from the previous synchronization of the file set, using the synchronization name as the key.
Next, the file list is scanned to look for possible conflicts. A conflict arises when the synchronization algorithm is unable to unambiguously select which file should be the master file, that is, which file should be used as the source to overwrite the target files. This search prevents target files that could contain precious data from being overwritten without warning.
The master file is never marked for conflict. Each file's data will typically be compared for equality with the master file's data to correctly ascertain whether there is a possibility for data loss. The following SynchronizationConflictReason values can be associated with files during the scan:
If conflicts are detected, the Conflict event will be triggered and event handlers will be asked to select the master file. The event arguments supply the currently designated master file ( OriginalMasterFileIndex property) and a property where the master file must be set ( ChosenMasterFileIndex property). The event arguments also allow for files in the list to be manually excluded from the synchronization.
The AutoConflictResolution option controls whether the algorithm should suggest using the currently selected master file. When set to false, the algorithm requires that the Conflict event handlers confirm a master file and will cancel the synchronization operation if none is selected. To prevent accidental loss of data, the default value of AutoConflictResolution is false. Note that care should be taken when using the AutoConflictResolution property to avoid data loss.
A preview of the file operations that will be performed is built using values from the SynchronizationAction enumeration. The Analysis event is then triggered. The event arguments of the handler present the list of files to be synchronized and an associated list of actions that will be performed on these files. The master file typically has no action performed on it since it is the source.
The typical action for target files is CreateOrOverwriteWithMaster: the target will be overwritten, or created if it doesn't exist, using the master file's data. However, if a target file is found to have the same data as the master, OverwriteAttributesOnly is used and only the attributes will be copied to save time. If the master file doesn't exist, the target file's action will be Delete. The situation where the master file can be non-existent arises when a master file is designated manually with MasterItemParameter, but where the AbstractFile passed to its constructor does not exist.
If the AllowCreations option is set to false in a SynchronizationOptions object passed to one of the synchronization methods, the CreateOrOverwriteWithMaster action of any target file that doesn't exist will be changed to SuspendedCreateOrOverwrite. Conversely, if the AllowDeletions option is set to false, the Delete action of any target file that exists will be changed to SuspendedDelete. In order to prevent the accidental loss of data, the default value of AllowDeletions is false.
Finally, the actual synchronization operations can begin. The file list is scanned one last time and the recorded action for each file is carried out.
The synchronization methods return a SynchronizationResult value that specifies one or more results from the synchronization. The value is a set of flags. Typically, a value with the ItemsSynchronized bit set indicates success; when the bit is not set, it means that no files were synchronized, indicating some kind of failure.
In success or failure, the other bit values of the SynchronizationResult enumeration give useful information on what occurred during the synchronization.
For example, if a call to Synchronize returns a value where the ConflictsDetected bit is set and the ItemsSynchronized bit is not set. This combination obviously means that no items were synchronized and that conflicts between files were detected, perhaps because conflicts were not handled in the Conflict event or because options such as AutoConflictResolution prevented the conflicts from being silently resolved. Conversely, a call to Synchronize can return a value where the ConflictsDetected bit is set and the ItemsSynchronized bit is also set. This shows that even though conflicts were detected, the synchronization was able to proceed.
To summarize, the bit values in SynchronizationResult are not, unless otherwise noted, mutually exclusive. Each bit represents something that occurred during the synchronization and is set when appropriate. This means that you should examine the return value of the synchronization methods for the presence of bits like ItemsSynchronized, instead of performing straight comparisons and expecting all other bit values to be set a certain way.