Getting Started with the CBSync Component

Introduction

The CBSync component enables seamless, bidirectional synchronization between local files and remote repositories by building on industry-standard technologies, including the Cloud Filter API on Windows, FUSE on Linux, and File Provider on macOS. The event-driven design of the CBSync component provides an intuitive way to handle operations performed on local files and folders. When remote changes are made, the included methods can be used to notify the local system.

The choice of the remote storage location is entirely up to you. Whether your data is stored on a popular cloud storage service, a custom file server, or anywhere else, the CBSync component handles the integration with the OS. Your code is responsible for responding to events and transferring data between the local and remote systems to facilitate the desired synchronization.

The following topics cover how to set up and interact with the CBSync component to smoothly incorporate it into your application.

Contents

Select a Synchronization Root

Each instance of the CBSync component is capable of synchronizing a local directory with a remote storage location. To begin, first set the SyncRootPath property to the location on a local disk where files will be visible. This location is also referred to as the "synchronization root". After calling the Install and Activate methods, the remote files will be visible at this location.

On Linux, the LinuxIntermediateFolder configuration setting specifies the location on disk where file data is stored. When Activate is called, FUSE is used to project a virtual file system in SyncRootPath. The file data actually resides within LinuxIntermediateFolder since all files within SyncRootPath are virtual.

Install and Uninstall

Before the CBSync component can be activated, it must be registered with the system (on Windows and macOS) by calling the Install method.

During normal operation, files are accessed in the synchronization root (and a temporary directory on Linux). To clean up local placeholder files and unregister from the system, use the Uninstall method. After uninstalling, the remote files will no longer be visible at the location specified by SyncRootPath. Uninstalling is typically performed only when an application will be removed from the system.

Start and Stop Synchronization

Call the Activate method to start operations. After this method returns, events will fire as requests for remote files are made. One of the first events to fire is the ListItems event, which is used to populate the synchronization root with files and folders. The Activate method only needs to be called once, and events will continue to fire as needed.

Note that files and subfolders that already exist locally, but are not reported by a ListItems event handler, are considered newly created items and either the UpdateItem or UpdateFolder event will fire for each item.

To stop synchronization but keep the synchronization root registered, call the Deactivate method, which will allow users to continue to work with offline files.

Handle the Events

While the CBSync component is active, handle the following events to provide information as well as receive notifications about local updates. Note that events are fired on arbitrary threads and not the main thread where the component was created. Multiple events can fire simultaneously, in different threads, and it is your responsibility to implement any necessary synchronization.

These events are similar in design and share several key parameters:

  • The TaskId parameter identifies the current operation.
  • The Path parameter represents the path of the item relative to the synchronization root; for example, /MyFolder/MyFile.txt.
  • The ResultCode parameter is used to report the status of an event. If the event cannot be handled successfully due to reasons such as unavailable resources or failed security checks, set this to an appropriate value to report an error. Please refer to the Error Codes section of the CBSync component documentation for more details.

Additionally, when any of these events fire and communication with the remote storage location is required, there are two supported methods for reporting the completion of the operation:

  • The request may be completed within the event. This prevents the event from returning and is suitable for operations that can be completed quickly.
  • Alternatively, the ResultCode parameter can be set to CBFSSYNC_PENDING (0x21000001) to allow the event to return without delay, and the work can be completed separately. When the operation with the remote storage location is performed in this manner, the TaskComplete method must be called to inform the component that the operation has been completed. It is important to record the TaskId parameter value in this case, as this is a required parameter when calling TaskComplete.

List Items

The ListItems event is fired by the CBSync component when it needs to list the contents of the directory specified by Path.

It is important to note that the event is triggered at the discretion of the operating system. This means that the directory listings in the Path will not be automatically refreshed upon user action. Instead, if remote changes are made, call methods such as CreateFile, CreateFolder, UpdateFile, UpdateFolder, DeleteFile, and DeleteFolder to inform the local system of the changes.

To handle the event properly, items within the directory must be reported by calling the ListItem method for each item being reported.

// Return information about a file. // 123456789 is the e.TaskId value from the ListItems event. // "myfile.txt" is the name of the file (without separators). // IsDir parameter set to false indicates the item is a file. // 0 represents the attributes since this is a file with no special attributes. // 100 is the size of the file in bytes. // FileCreationTime is a DateTime (in UTC). // FileLastAccessTime is a DateTime (in UTC). // FileLastWriteTime is a DateTime (in UTC). cbsync.ListItem(123456789, "myfile.txt", false, 0, 100, FileCreationTime, FileLastAccessTime, FileLastWriteTime); // Return information about a read-only hidden file. // Constants.CBFSSYNC_ATTR_READONLY | Constants.CBFSSYNC_ATTR_HIDDEN represents the attributes since this is a read-only hidden file. cbsync.ListItem(123456789, "myfile.txt", false, Constants.CBFSSYNC_ATTR_READONLY | Constants.CBFSSYNC_ATTR_HIDDEN, 100, FileCreationTime, FileLastAccessTime, FileLastWriteTime); // Return information about a directory. // IsDir parameter set to true indicates the item is a directory. // 0 represents the file size because size is not applicable to directories. cbsync.ListItem(123456789, "myfolder", true, 0, 0, FileCreationTime, FileLastAccessTime, FileLastWriteTime);

Get Item Data

The GetItemData event fires when the CBSync component needs to retrieve file data from the remote storage.

To handle the event properly, the data must be passed to the component by calling the PutItemData method one or more times. After the data transfer is finished, the TaskComplete method must also be called to notify the component that the operation has been completed.

// Pass all 1024 bytes of data at once. cbsync.PutItemData(e.TaskId, buffer, 0, 1024); cbsync.TaskComplete(e.TaskId, 0); // Pass data in three separate chunks totaling 1024 bytes. cbsync.PutItemData(e.TaskId, buffer, 0, 512); cbsync.PutItemData(e.TaskId, buffer, 512, 100); cbsync.PutItemData(e.TaskId, buffer, 612, 412); cbsync.TaskComplete(e.TaskId, 0);

Create Items

The CreateItem and CreateFolder events fire when the CBSync component detects that a new file or folder has been created locally at the location specified by Path.

When a new file or folder is created within the synchronization root, these events allow for the addition of the file or folder to be acknowledged and replicated in the remote storage location.

To handle the events properly, inspect the new item details provided by the event that you would like to replicate remotely; this includes, but is not limited to, creation, last access, and last modified times, attributes (read-only, hidden, etc.), and content (when the item is a file).

Delete Items

The DeleteItem and DeleteFolder events fire when the CBSync component detects that the local file or folder identified by Path is deleted.

The DeleteFlags parameter is a bitmask that defines how the deletion should be handled. If the flag is set, the event handler should move the file to a location that acts as a Recyle Bin / Trash; otherwise, the file is gone, and the event handler should delete the file on the remote side.

Rename Items

The RenameItem and RenameFolder events fire when the system needs to notify the CBSync component that the local file or folder located at OldPath is about to be renamed or moved.

The NewPath parameter represents where the event handler should move the item.

Update Items

The UpdateItem and UpdateFolder events fire when the CBSync component detects a change in the metadata or data of the local file or folder identified by Path.

When changes are made to an item's attributes, such as permissions, ownership, timestamps, or other metadata, and in the case of files, when the contents change, such as appending or removing data within a file, these events allow for the changes to the file or folder to be acknowledged and replicated in the remote storage location.

To handle the events properly, identify the item changes supplied by the event that you would like the to replicate remotely; this includes, but it not limited to, creation, last access, and last modified times, attributes (read-only, hidden, etc.), and content (when the item is a file).

Synchronize Local Changes

If changes to a local file or folder in the synchronization root are made, the UpdateItem or UpdateFolder events will fire on a per-item basis and provide an opportunity to synchronize changes to the remote storage.

Information about the modified file or folder is provided through the UpdateItem and UpdateFolder events. These events provide information about the following file or folder properties:

  • The Path of the file or folder within the synchronization root.
  • The Size of the file (not applicable to folders).
  • The CreationTime, LastAccessTime, and LastModifiedTime of the file or folder, specified in UTC.
  • Attributes including Read-Only, Archived, Hidden, and Pinned statuses.

Synchronize Remote Changes

If changes in the remote storage location are made, use the CreateFile, CreateFolder, UpdateFile or UpdateFolder methods to reflect the corresponding changes in the local filesystem.

These operations require that the following information about the item be provided to the component:

  • The Path of the file or folder within the synchronization root.
  • The Size of the file (not applicable to folders).
  • The CreationTime, LastAccessTime, and LastModifiedTime of the file or folder, specified in UTC.

Optionally, additional attributes may be provided if desired.

If the remote item was deleted, use the DeleteFile or DeleteFolder methods to reflect the item deletion in the local filesystem.

Handle Errors

The CBSync component communicates errors using the error codes defined in the Error Codes section of the component documentation.

The ResultCode parameter of events can be used to report an error when the operation could not be completed successfully. The ResultCode parameter is set to 0 by default, which indicates the operation was successful.

If an unhandled exception occurs in the event handler, it will be caught by the component and an internal error will be reported.

We appreciate your feedback. If you have any questions, comments, or suggestions about this article please contact our support team at support@callback.com.