Getting Started Synchronizing Files
Sync Framework includes a file synchronization provider that extends the UnmanagedSyncProviderWrapper object (for managed code) or IKnowledgeSyncProvider interface (for unmanaged code) to simplify creation of an application that synchronizes files and folders among file systems.
Creating and Initializing the Provider
Managed code An application creates a FileSyncProvider object. Paths and configuration options are specified in the constructor.
Unmanaged code An application creates an IFileSyncProvider object by passing CLSID_FileSyncProvider and IID_IFileSyncProvider to CoCreateInstance. Paths and configuration options are specified by calling the Initialize method.
The paths that are specified when the provider is constructed or initialized define the root folder to synchronize, and the folder and file name in which the synchronization metadata is stored. Optionally, the application can also specify a folder to store temporary files and a folder to store files that are updated because of a conflict. These must be valid paths and must exist before the provider is initialized.
Note
For all methods in the file synchronization provider, paths cannot exceed MAX_PATH.
A set of configuration flags can be specified when the provider is constructed or initialized. These flags modify the behavior of the provider in various ways, such as to improve change detection by calculating a hash value for each file, or to move deleted files to the recycle bin instead of permanently deleting them. These flags are represented by FileSyncOptions (for managed code) or FILESYNC_INIT_FLAGS (for unmanaged code).
After source and destination providers have been created and initialized, they can be passed to a synchronization session and synchronization can be started.
File Attributes
Sync Framework recognizes only the following file and folder attributes:
FILE_ATTRIBUTE_DIRECTORY
FILE_ATTRIBUTE_READONLY
FILE_ATTRIBUTE_HIDDEN
FILE_ATTRIBUTE_SYSTEM
FILE_ATTRIBUTE_TEMPORARY
Other file attributes are ignored and are not propagated.
Security and Encryption
The provider does not perform any authentication on the folders that are involved in synchronization. The application must authenticate the folders that are used before it passes them to the provider.
Security information, such as the Discretionary Access Control List (DACL), is not propagated. It is up to the application or user to correctly secure the destination folders to help prevent unauthorized access.
Files in an encrypted folder are decrypted before they are sent and will not be encrypted in the destination folder. Be aware that this means that even if the source folder is encrypted, the files will still not be encrypted when they are sent. To help prevent unauthorized access or tampering, the communication channel between the provider and the folder must be trusted.
Synchronization metadata and temporary files are stored in folders specified when the provider is initialized. These folders must be appropriately secured and the temporary folder cleaned up to avoid unwanted information disclosure, because these files might contain user data.
Consistency Guarantee
Sync Framework guarantees that, when the file synchronization provider applies a change, if all contents of a file stream cannot be applied then no content will be. This is done in part by opening the files in exclusive share mode. This means that the file cannot be opened or deleted by any other application until its handle is closed. For more information, see the CreateFile function in the Microsoft Win32 documentation.
If the file cannot be opened in exclusive share mode it will be skipped. The skip will be recorded in the metadata so that it can be processed appropriately in future sessions.
Metadata Storage
The file synchronization provider uses the metadata storage service to store all synchronization metadata in a custom data store. The metadata store is one file. This file can be stored with the files and folders that are to be synchronized or in another location that is specified when the provider is initialized. For more information about metadata storage service components, see Sync Framework Metadata Storage Service.
Backing up and Restoring a File System Replica
When a file system replica is restored from a backup, problems can occur with synchronization. For example, local changes made after the restore might not propagate to other replicas. This can occur because the tick count used to assign versions to changes on the source replica may cause changes to be detected as obsolete by other replicas.
To ensure that this situation does not occur, when a file system replica is restored from a backup, discard the synchronization metadata and treat the replica as a new replica, assigning it a new replica ID. The file synchronization provider can then create synchronization metadata for the replica and synchronize it correctly with other replicas in the community.