CBSync Component

Properties   Methods   Events   Config Settings   Errors  

The CBSync component enables seamless synchronization between local files and cloud storages or other remote repositories.

Syntax

callback.CBFSSync.CBSync

Remarks

CBSync provides an intuitive way to synchronize local files and folders with a remote storage. When remote changes are made, use the included methods to notify the local system. The following topics provide information about configuring and operating the component.

Selecting the Synchronization Root

Each instance of the component is capable of synchronizing a local directory with a remote storage. To begin, first set the SyncRootPath property to the location on a local disk where files will be visible (this step is not used on macOS). 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 are stored. When Activate is called, the system FUSE library (version 2.9) is used to project a virtual file system in SyncRootPath. The file data actually reside within LinuxIntermediateFolder because all files within SyncRootPath are virtual.

On macOS, the MacDomainId and MacDomainLabel configuration settings must be set before calling the Install and Activate methods. These settings identify the synchronization root on macOS and make it visible to a user.

Installation and Uninstallation

Before the component can be activated, it must be registered with the system 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.

Starting and Stopping 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 ListDirectory event, which is used to populate the synchronization root with files and folders. The Activate method needs to be called only once, and events will continue to fire as needed.

Note: Files and subfolders that already exist locally but are not reported by a ListDirectory event handler are considered newly created items, and either UpdateFile or UpdateFolder will fire for each.

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

Handling Events

While the component is active, handle the component's events to provide information as well as receive notifications about local updates.

Note: Events are fired on arbitrary threads and not the main thread, in which the component was created. Multiple events can fire simultaneously, in different threads, and it is the responsibility of the user to implement any necessary synchronization.

The following events may fire while the component is active:

When these events fire and communication with the remote storage is required, an application may use either of the two strategies 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 is performed in this manner, the FinalizeTask method must be called to inform the component that the operation has been completed.

Some of the events include one or more parameters intended for use as binary data buffers, which either contain or expect data to be provided to complete the operation. Buffer parameters point to preallocated blocks of unmanaged memory, in which the size is specified by the parameter immediately following; as such, be sure to write data directly to the pointed-to memory rather than change the value of the buffer parameter itself.

Finally, use caution when accessing files from within events. Performing an action on a file that is within the synchronization root may cause the event to fire again before the first event has returned. This can lead to an infinite recursion scenario, which may cause a deadlock or undefined behavior.

Synchronizing Local Changes

If changes to a local file or folder in the synchronization root are made, the UpdateFile 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 UpdateFile 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.

Synchronizing Remote Changes

If changes in the remote storage 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 item within the synchronization root.
• The Size of the item (not applicable to folders).
• The CreationTime, LastAccessTime, and LastModifiedTime of the item, 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.

File Status Icons

On Windows, the status of files is represented by icons visible in Windows File Explorer. These icons are defined by the operating system and are the same icons used by OneDrive.

Icon	Description
	The blue cloud icon indicates that the file or folder is available only online. Online-only files do not take up space on the local system but are not accessible without an internet connection.
	The green check icon indicates that the file or folder has been downloaded to the local system and is available anytime, even without internet access. Users may invoke the "Free up space" command in Windows File Explorer to change the file back to an online-only file.
	The solid green circle icon indicates the file or folder has been pinned and will always be available on the local system. Pinning a file or folder ensures that it is not automatically changed back to an online-only file by the operating system at any time.
	Files that are currently being synchronized are represented by this icon. When the operation completes, the icon will be updated to one of the listed icons.

Handling Errors

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

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.

Use of CBSync in Windows projects

CBSync can be used in both console and GUI projects. UWP applications, however, cannot use CBSync because of the limitations of the CfAPI, the set of functions and methods used by CBSync.

Use of CBSync in macOS projects

To host a synchronization solution on macOS, the project must be a GUI application rather than a console project. The project must include certain keys in its entitlements (more on this below), and it must also link the replicated file provider extension in the form of an application extension during building. The extension should be included to the bundle of the application. CBFS Sync does not include a pre-built extension because some modifications in its source files are required. Instead, CBFS Sync includes the source code of this application extension and a precompiled extension framework with the core extension logic.

Building the extension from the source code requires a macOS system due to the need to sign the product of the build process. To build the extension, the development tools (XCode, the SDK for macOS, and the command-line tools) must be installed on the macOS system.

Due to the architecture of extensions, the extension that is linked includes certain identifiers that must be identical to the ones used in the main application. Before the extension is built, some modifications must be made in several source files.

The files to modify are located in the extension/cbsync and demos/Local Sync for macOS (MAUI) directories (the sample is used as a reference, and you need to use your project's files instead). The required modifications for each file are detailed below.

Additionally, the following keys must be added or updated in the entitlements list of your project. These keys are already included in the sample. The component must have access to the "/Library/CloudStorage/" directory because macOS stores local copies of synchronized files under this directory and serves the files from there; the component picks information about the state of the local copies of synchronized files from this directory. <key>com.apple.security.app-sandbox</key> <true/> <key>com.apple.security.temporary-exception.files.home-relative-path.read-only</key> <array> <string>/Library/CloudStorage/</string> </array>

The extension is compiled using a Before Build step in the .NET project and then copied into the application bundle using the After Build step in the .NET project. The Local Sync for macOS (MAUI) sample includes the corresponding steps in the form of .sh files. The .NET project must be updated with the corresponding steps and either call the corresponding scripts or simply use their contentx as shown:

Before Build step: pushd {CBFS Sync installation folder}/extension/cbsync xcodebuild -target Extension popd

After Build step: mkdir -p "$(ProjectDir)$(AppBundleDir)/Contents/PlugIns" cp -a {CBFS Sync installation folder}/extension/cbsync/build/Release/Extension.appex "$(ProjectDir)$(AppBundleDir)/Contents/PlugIns" codesign --force --sign "{identity}" --entitlements entitlements.plist --timestamp --generate-entitlement-der "$(ProjectDir)$(AppBundleDir)" The "{identity}" (together with curly brackets) must be replaced with the actual identity value, which has a form of "Development: John Doe (DEVELOPERID)".

Property List

The following is the full list of the properties of the component with short descriptions. Click on the links for further details.

Method List

The following is the full list of the methods of the component with short descriptions. Click on the links for further details.

Event List

The following is the full list of the events fired by the component with short descriptions. Click on the links for further details.

Config Settings

The following is a list of config settings for the component with short descriptions. Click on the links for further details.

Active Property (CBSync Component)

This property reflects whether the component is active.

Syntax

• C#
• VB.NET

public CBSyncActives Active { get; }

enum CBSyncActives {
  asInactive,
  asActivating,
  asActive
}

Public ReadOnly Property Active As CbsyncActives

Enum CBSyncActives
  asInactive
  asActivating
  asActive
End Enum

Default Value

0

Remarks

This property reflects whether the component is currently inactive, being activated, or active and handling OS requests. The value of the property depends on whether the Activate method was called and how it progressed.

This property is read-only and not available at design time.

SyncRootIcon Property (CBSync Component)

This property specifies a path to an icon for the folder.

Syntax

• C#
• VB.NET

public string SyncRootIcon { get; set; }

Public Property SyncRootIcon As String

Default Value

""

Remarks

This property specifies a path to an icon that will be displayed in Windows File Explorer.

If set, Windows will use the specified icon for the virtual folder visible in Windows File Explorer. The value may contain either a resource path (e.g., SyncProvider.dll,-100) or a full path to an .ico file. For instance:

// Specify the same icon that .txt files use in Windows Explorer. cbsync.SyncRootIcon = @"%SystemRoot%\system32\imageres.dll,-102"; // Specify an .ico file. cbsync.SyncRootIcon = @"C:\somewhere\MyIcon.ico";

Note: This property cannot be changed when Active is true, and it cannot be changed within events.

Note: This property is applicable only on Windows. This property has no effect on other platforms.

SyncRootLabel Property (CBSync Component)

This property specifies a label for the folder.

Syntax

• C#
• VB.NET

public string SyncRootLabel { get; set; }

Public Property SyncRootLabel As String

Default Value

""

Remarks

This property specifies a label for the synchronization root. This property must be set before calling Activate.

On Windows, this value is used as the folder name visible in Windows File Explorer.

On Linux, this value is used as part of the LinuxIntermediateFolder.

On macOS, this property is not used; instead, an application must set the MacDomainId and MacDomainLabel configuration settings.

Note: This property cannot be changed when Active is true, and it cannot be changed within events.

SyncRootPath Property (CBSync Component)

This property specifies the root directory for synchronized files and folders.

Syntax

• C#
• VB.NET

public string SyncRootPath { get; set; }

Public Property SyncRootPath As String

Default Value

""

Remarks

This property is used to specify the location on the local disk where files and folders are synchronized. This property must be set before calling Install or Activate.

On Windows, this must be set to an existing directory.

On Linux, this must be set to an existing empty directory. After Activate is called, files will be visible at this location. Although this property specifies where files are visible, file data and metadata are stored at the location specified by the LinuxIntermediateFolder configuration setting.

On macOS, the operating system manages the location of the synchronization root (it is located under a user's home directory). An application should use the MacDomainId and MacDomainLabel configuration settings to make it possible for the OS to create and display a synchronization root.

Note: This property cannot be changed when Active is true, and it cannot be changed within events.

Activate Method (CBSync Component)

This method prepares and starts the necessary mechanisms for synchronization.

Syntax

• C#
• VB.NET

public void Activate(bool wait);

Public Sub Activate(ByVal Wait As Boolean)

Remarks

This method prepares and starts the necessary mechanisms for synchronization of the directory specified by the SyncRootPath property.

On macOS, set the MacDomainId configuration setting to uniquely identify this synchronization root instance before calling this method.

Before calling this method, invoke the Install method to perform system-specific registration procedures if the synchronization root has not previously been registered. When this method executes, the component discovers files or folders which exist locally in SyncRootPath and which were not synchronized before. Such files and directories are reported as newly created ones via the corresponding events. This is needed to provide an opportunity for the remote storage to properly reflect the synchronization root.

When the Wait parameter is true, this method will not return until these events have completed. Thus, as a result, it may be desirable to complete them asynchronously by setting the ResultCode parameter of the events to CBFSSYNC_PENDING (0x21000001), allowing this method to return in a timely manner.

When the Wait parameter is false, the method returns immediately and a separate Activated event is fired when the component completes the activation phase (either successfully or with an error).

After this method returns or the Activated event fires (depending on whether Wait is true or false), the synchronized location is exposed to the system and events will begin firing as operations are performed, including when the following occur:

• The local system requests data from the remote storage, such as when listing the directory or opening a file.
• Local changes have been made that should be synchronized to the remote storage, such as when a new file is created or an existing file is modified.

Note: This method cannot be called within events.

Config Method (CBSync Component)

Sets or retrieves a configuration setting.

Syntax

• C#
• VB.NET

public string Config(string configurationString);

Public Function Config(ByVal ConfigurationString As String) As String

Remarks

Config is a generic method available in every component. It is used to set and retrieve configuration settings for the component.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

CreateFile Method (CBSync Component)

This method creates a local file within the synchronization root.

Syntax

• C#
• VB.NET

public void CreateFile(string path, int attributes, long size, DateTime creationTime, DateTime lastAccessTime, DateTime lastModifiedTime);

Public Sub CreateFile(ByVal Path As String, ByVal Attributes As Integer, ByVal Size As Long, ByVal CreationTime As DateTime, ByVal LastAccessTime As DateTime, ByVal LastModifiedTime As DateTime)

Remarks

This method creates a local file in the synchronization root and optionally initiates retrieval of its data from remote storage. To create a local file and initiate the retrieval of the data, set the CBFSSYNC_ATTR_PINNED attribute.

The Path parameter should be a path that begins with the directory separator and identifies the location of the file or folder within the synchronization root.

The Attributes parameter is used to specify the attributes of the file or folder. The specified attributes replace existing attributes of the file or folder. The special value 0 indicates no modification will be made to the existing attributes. To clear all attributes of a file or folder, set the CBFSSYNC_ATTR_NORMAL attribute. To obtain the current attributes, use the GetFileAttributes or GetFolderAttributes method. The value passed in this parameter should be a binary OR of the following values:

The Size parameter must be set to the size of the file in bytes.

The CreationTime, LastAccessTime, and LastModifiedTime parameters contain the corresponding time values specified in UTC. To indicate no change in the time when calling UpdateFile or UpdateFolder, use a DateTime value that is less than or equal to the Unix epoch of January 1, 1970 (e.g., DateTime.MinValue).

// Create a new file placeholder. // "/folder1/folder2/new_file.txt" is the path to the file. // 0 represents the attributes because this is a file with no special attributes. // 0 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.CreateFile("/folder1/folder2/new_file.txt", 0, 0, FileCreationTime, FileLastAccessTime, FileLastWriteTime); // Create a new file and request the data to be downloaded. // "/folder1/folder2/new_file.txt" is the path to the file. // CBFSSYNC_ATTR_PINNED represents the attributes because this is a file that will be pinned. // 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.CreateFile("/folder1/folder2/get_data_file.txt", Constants.CBFSSYNC_ATTR_PINNED, 100, FileCreationTime, FileLastAccessTime, FileLastWriteTime);

CreateFolder Method (CBSync Component)

This method creates a local folder within the synchronization root.

Syntax

• C#
• VB.NET

public void CreateFolder(string path, int attributes, DateTime creationTime, DateTime lastAccessTime, DateTime lastModifiedTime);

Public Sub CreateFolder(ByVal Path As String, ByVal Attributes As Integer, ByVal CreationTime As DateTime, ByVal LastAccessTime As DateTime, ByVal LastModifiedTime As DateTime)

Remarks

This method creates a local folder in the synchronization root. If the CBFSSYNC_ATTR_PINNED attribute is set, the component will initiate the retrieval of the items of the directory from the remote storage. If any files or folders are found, they are also pinned.

The Path parameter should be a path that begins with the directory separator and identifies the location of the file or folder within the synchronization root.

The Attributes parameter is used to specify the attributes of the file or folder. The specified attributes replace existing attributes of the file or folder. The special value 0 indicates no modification will be made to the existing attributes. To clear all attributes of a file or folder, set the CBFSSYNC_ATTR_NORMAL attribute. To obtain the current attributes, use the GetFileAttributes or GetFolderAttributes method. The value passed in this parameter should be a binary OR of the following values:

The CreationTime, LastAccessTime, and LastModifiedTime parameters contain the corresponding time values specified in UTC. To indicate no change in the time when calling UpdateFile or UpdateFolder, use a DateTime value that is less than or equal to the Unix epoch of January 1, 1970 (e.g., DateTime.MinValue).

// Create a new folder in the synchronization root. // "/folder1/folder2/new_folder" is the path to the folder. // 0 represents the attributes because this is a folder with no special attributes. // FolderCreationTime is a DateTime (in UTC). // FolderLastAccessTime is a DateTime (in UTC). // FolderLastWriteTime is a DateTime (in UTC). cbsync.CreateFolder("/folder1/folder2/new_folder", 0, FolderCreationTime, FolderLastAccessTime, FolderLastWriteTime); // Create a new folder and request the contents are pinned. // "/folder1/folder2/" is the path to the folder. // CBFSSYNC_ATTR_PINNED represents the attributes because this is a folder that will be pinned. // FolderCreationTime is a DateTime (in UTC). // FolderLastAccessTime is a DateTime (in UTC). // FolderLastWriteTime is a DateTime (in UTC). cbsync.CreateFolder("/folder1/folder2/", Constants.CBFSSYNC_ATTR_PINNED, FolderCreationTime, FolderLastAccessTime, FolderLastWriteTime);

Deactivate Method (CBSync Component)

This method stops the synchronization operation.

Syntax

• C#
• VB.NET

public void Deactivate();

Public Sub Deactivate()

Remarks

This method stops the synchronization operation previously started by the Activate method. After calling this method, events will no longer fire as operations are performed on files within SyncRootPath.

Note: The synchronization root will still be registered and accessible after this method is called. Users will continue to be able to perform offline operations, including creating new files or modifying files that previously have been synchronized.

To unregister and remove access to the synchronization root, call the Uninstall method instead.

Linux:

To handle requests of the sytem FUSE library, the component uses a dedicated thread. If there exist open handles to items in a synchronization root directory, FUSE doesn't finish its operations, while the component waits for FUSE to finish. The component can forcefully stop FUSE operations, but only if the application that uses the component didn't set a handler for the SIGINT signal. If such a handler is set, the component cannot forcefully stop the operations and has to wait for the handles to be closed and for FUSE to stop.

If a process that uses the component is killed or crashes, there's a hanging FUSE mounting point left visible in the system. To remove it, call one of these commands:

• if a process was run under the same user account that performs the removal operation, call "fusermount -u <mounting_point>", where "mounting_point" is a synchronization root directory as set in the SyncRootPath property.
• if a process was run under a different user account, call "sudo umount <mounting_point>" instead. Note that this operation requires that a user either is root or is included in the "sodoers" group.

Note: This method cannot be called within events.

DeleteFile Method (CBSync Component)

This method deletes a local file from the synchronization root.

Syntax

• C#
• VB.NET

public void DeleteFile(string path);

Public Sub DeleteFile(ByVal Path As String)

Remarks

This method deletes a local file from the synchronization root. Use it when the folder has been file from the remote storage, and the application needs to update the local synchronization root.

The Path parameter should be a path that begins with the directory separator and identifies the location of the file or folder within the synchronization root.

// Delete a specific file from the synchronization root. cbsync.DeleteFile("/folder1/folder2/file.txt");

DeleteFolder Method (CBSync Component)

This method deletes a local folder from the synchronization root.

Syntax

• C#
• VB.NET

public void DeleteFolder(string path, bool deleteChildren);

Public Sub DeleteFolder(ByVal Path As String, ByVal DeleteChildren As Boolean)

Remarks

This method deletes a local folder from the synchronization root. Use it when the folder has been deleted from the remote storage, and the application needs to update the local synchronization root.

The Path parameter should be a path that begins with the directory separator and identifies the location of the file or folder within the synchronization root.

When a folder is deleted, a caller may use DeleteChildren to specify that if the folder contains files or subfolders, those should also be removed. If this parameter is not set and the folder contains children, the call will fail.

// Delete the specified folder and all its contents. // DeleteChildren parameter set to true indicates all contained files and subfolders will be deleted. cbsync.DeleteFolder("/folder1/folder2/target_folder", true);

FinalizeTask Method (CBSync Component)

This method notifies the component that the asynchronous data transfer operation has been completed.

Syntax

• C#
• VB.NET

public void FinalizeTask(long taskId, int errorCode);

Public Sub FinalizeTask(ByVal TaskId As Long, ByVal ErrorCode As Integer)

Remarks

This method must be called to inform the component that the asynchronous transfer of data, initiated in response to any of the following events, has been completed (either successfully or with an error):

• ListDirectory
• GetFileData
• CreateFile
• CreateFolder
• DeleteFile
• DeleteFolder
• RenameFile
• RenameFolder
• UpdateFile
• UpdateFolder

When any of these events fire and data transfer is required, this transfer can take place asynchronously, without blocking the event. For this, the event handler should set the ResultCode parameter of the event to CBFSSYNC_PENDING (0x21000001), schedule the asynchronous operation, and let the event return. Once the synchronization operations are complete, this FinalizeTask method must be called to indicate that the operation is complete.

The application should set the TaskId parameter to the value it received in the handler of the event whose operations are completed asynchronously; thus, it is important that the application stores this value before returning from the event handler.

If the operation completed successfully, the ErrorCode parameter should be set to 0; otherwise, it should be set to an appropriate value to report an error. Please refer to the Error Codes section for the set of possible values.

Note: This method cannot be called within events.

GetFileAttributes Method (CBSync Component)

This method returns the attributes of a local file.

Syntax

• C#
• VB.NET

public int GetFileAttributes(string path);

Public Function GetFileAttributes(ByVal Path As String) As Integer

Remarks

This method returns the attributes of a local file within the synchronization root. It may be used at any time, including from within events, to obtain the attributes of a local file.

The Path parameter should be a path that begins with the directory separator and identifies the location of the file or folder within the synchronization root.

The return value is a binary OR of the following values:

GetFileData Method (CBSync Component)

This method reads data from the local file associated with a creation or update of a local file.

Syntax

• C#
• VB.NET

public int GetFileData(long taskId, long position, byte[] buffer, int index, int count);

Public Function GetFileData(ByVal TaskId As Long, ByVal Position As Long, ByVal Buffer As Byte(), ByVal Index As Integer, ByVal Count As Integer) As Integer

Remarks

This method may be used from within the CreateFile and UpdateFile events to obtain the data of the local file that was created or changed and that should be sent to the remote storage.

The TaskId parameter must be set to the same TaskId value provided by the corresponding CreateFile or UpdateFile event.

Count bytes of data will be read from the file, starting from the specified Position, into the given Buffer. The data are written to Buffer starting at the given Index.

The method returns the number of bytes read.

GetFileStatus Method (CBSync Component)

This method returns the download status of a local file.

Syntax

• C#
• VB.NET

public int GetFileStatus(string path);

Public Function GetFileStatus(ByVal Path As String) As Integer

Remarks

This method returns the download status of a local file within the synchronization root. A downloaded file is one that is available on the local system but may be automatically changed to an online-only file by the operating system.

The Path parameter should be a path that begins with the directory separator and identifies the location of the file or folder within the synchronization root.

The return value is a binary OR of the following values:

macOS: This method does nothing.

GetFolderAttributes Method (CBSync Component)

This method returns the attributes of a local folder.

Syntax

• C#
• VB.NET

public int GetFolderAttributes(string path);

Public Function GetFolderAttributes(ByVal Path As String) As Integer

Remarks

This method returns the attributes of a local folder within the synchronization root. It may be used at any time, including from within events, to obtain the attributes of a local folder.

The Path parameter should be a path that begins with the directory separator and identifies the location of the file or folder within the synchronization root.

The return value is a binary OR of the following values:

GetFolderStatus Method (CBSync Component)

This method returns the download status of a local folder.

Syntax

• C#
• VB.NET

public int GetFolderStatus(string path);

Public Function GetFolderStatus(ByVal Path As String) As Integer

Remarks

This method returns the download status of a local folder within the synchronization root. A downloaded folder is one for which all the files within it are available on the local system, but it may be automatically changed to an online-only folder by the operating system.

The Path parameter should be a path that begins with the directory separator and identifies the location of the file or folder within the synchronization root.

The return value is a binary OR of the following values:

macOS: This method does nothing.

Install Method (CBSync Component)

This method registers the synchronization root with the system.

Syntax

• C#
• VB.NET

public void Install();

Public Sub Install()

Remarks

This method registers the synchronization root specified by SyncRootPath with the system. After calling this method, invoke the Activate method to begin synchronization operations.

On Windows, set the WindowsStorageProviderAccount and WindowsStorageProviderId configuration settings to uniquely identify this synchronization root instance before calling this method, which is important when working with multiple synchronized locations on one system. Note: this method won't work in a UWP or MAUI application due to security restrictions imposed on the environment, in which these types of applications are run by the OS.

On macOS, set the MacDomainId and MacDomainLabel configuration settings to uniquely identify this synchronization root instance before calling this method.

This method must be called once for each synchronization root, but it does not need to be called again for an altready registered root unless the Uninstall method is invoked to remove the registration.

Note: The registration performed by this method is persistent and will remain even if the application exits or the component is deactivated as a result of calling the Deactivate method.

On Linux, this method checks that FUSE is installed.

Note: This method cannot be called within events.

On Windows, this method requires administrative rights to execute successfully. If the user account of the process that calls this method does not have such rights, the call will fail with an error, and the E_ACCESSDENIED HRESULT code will be reported in the OSLastError configuration setting.

ListFile Method (CBSync Component)

This method is used to provide information about a file item during directory enumeration.

Syntax

• C#
• VB.NET

public void ListFile(long taskId, string fileName, int attributes, long size, DateTime creationTime, DateTime lastAccessTime, DateTime lastModifiedTime);

Public Sub ListFile(ByVal TaskId As Long, ByVal FileName As String, ByVal Attributes As Integer, ByVal Size As Long, ByVal CreationTime As DateTime, ByVal LastAccessTime As DateTime, ByVal LastModifiedTime As DateTime)

Remarks

This method may be called to provide detailed information about a file item contained in the directory; call it either from within the ListDirectory event or after ListDirectory returns to supply the information asynchronously.

The TaskId parameter must be set to the same value provided in the ListDirectory event.

The FileName parameter should contain the name of the file without a path or path separator.

The Attributes parameter is used to specify the attributes of the file. Available attributes are as follows:

The Size parameter must be set to the size of the file in bytes. This parameter is not applicable to folders.

The CreationTime, LastAccessTime, and LastModifiedTime parameters contain the corresponding time values specified in UTC.

Note: This method can be called only within events, and, unless the event has been completed with the CBFSSYNC_PENDING result earlier, the method must be called in the same thread that the event was fired on.

// Return information about a file. // 123456789 is the e.TaskId value from the ListDirectory event. // "myfile.txt" is the name of the file (without separators). // 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.ListFile(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.ListFile(123456789, "myfile.txt", Constants.CBFSSYNC_ATTR_READONLY | Constants.CBFSSYNC_ATTR_HIDDEN, 100, FileCreationTime, FileLastAccessTime, FileLastWriteTime);

ListFolder Method (CBSync Component)

This method is used to provide information about a directory item during directory enumeration.

Syntax

• C#
• VB.NET

public void ListFolder(long taskId, string folderName, int attributes, DateTime creationTime, DateTime lastAccessTime, DateTime lastModifiedTime);

Public Sub ListFolder(ByVal TaskId As Long, ByVal FolderName As String, ByVal Attributes As Integer, ByVal CreationTime As DateTime, ByVal LastAccessTime As DateTime, ByVal LastModifiedTime As DateTime)

Remarks

This method may be called to provide detailed information about a directory item contained in the directory; call it either from within the ListDirectory event or after ListDirectory returns to supply the information asynchronously.

The TaskId parameter must be set to the same value provided in the ListDirectory event.

The FolderName parameter should contain the name of the folder without separators.

The Attributes parameter is used to specify the attributes of the folder. Available attributes are as follows:

The CreationTime, LastAccessTime, and LastModifiedTime parameters contain the corresponding time values specified in UTC.

Note: This method can be called only within events, and, unless the event has been completed with the CBFSSYNC_PENDING result earlier, the method must be called in the same thread that the event was fired on.

// Return information about a folder. // 123456789 is the e.TaskId value from the ListDirectory event. // "myfolder" is the name of the folder (without separators). // 0 represents the attributes since this is a directory with no special attributes. // FileCreationTime is a DateTime (in UTC). // FileLastAccessTime is a DateTime (in UTC). // FileLastWriteTime is a DateTime (in UTC). // Return information about a folder. cbsync.ListFolder(123456789, "myfolder", 0, FileCreationTime, FileLastAccessTime, FileLastWriteTime);

PinFile Method (CBSync Component)

This method marks the file as pinned so it is always available on the system.

Syntax

• C#
• VB.NET

public void PinFile(string path);

Public Sub PinFile(ByVal Path As String)

Remarks

This method pins the file specified by Path. When the file is pinned, a download is initiated if the file data have not previously been downloaded. Once the file data have been downloaded, the file is marked as pinned, meaning the file is always available on the system even when no Internet connection is available.

The Path parameter should be a path that begins with the directory separator and identifies the location of the file or folder within the synchronization root.

Calling this method is equivalent to calling SetFileAttributes and passing only the CBFSSYNC_ATTR_PINNED attribute. To unpin a file so that the local file data may be freed, call UnpinFile.

macOS: This method sets a transient flag that does not survive restart of the extension, Finder, or the system. If necessary, an application should pin files and folders on startup.

PinFolder Method (CBSync Component)

This method marks the folder as pinned so it is always available on the system.

Syntax

• C#
• VB.NET

public void PinFolder(string path);

Public Sub PinFolder(ByVal Path As String)

Remarks

This method pins the folder specified by Path. When the folder is pinned, a download is initiated if files within the folder have not been downloaded. Once the files within the folder have been downloaded, the folder is marked as pinned, meaning the files within the folder are always available on the system even when no Internet connection is available.

The Path parameter should be a path that begins with the directory separator and identifies the location of the file or folder within the synchronization root.

Calling this method is equivalent to calling SetFolderAttributes and passing only the CBFSSYNC_ATTR_PINNED attribute. To unpin a folder so that the local files may be freed, call UnpinFolder.

macOS: This method sets a transient flag that does not survive restart of the extension, Finder, or the system. If necessary, an application should pin files and folders on startup.

PutFileData Method (CBSync Component)

This method is used to provide the file data that were requested during item retrieval.

Syntax

• C#
• VB.NET

public void PutFileData(long taskId, byte[] buffer, int index, int count);

Public Sub PutFileData(ByVal TaskId As Long, ByVal Buffer As Byte(), ByVal Index As Integer, ByVal Count As Integer)

Remarks

This method may be called from within the GetFileData event to immediately provide the requested file data or after GetFileData returns to supply them asynchronously.

The TaskId parameter must be set to the same value provided in the GetFileData event.

When the OS must retrieve file data, the GetFileData event is fired, which specifies the range of remote file data that must be read and passed back by this method. If the data are to be provided asynchronously, the event's ResultCode parameter should be set to CBFSSYNC_PENDING (0x21000001) before returning from the event handler; otherwise, this method should be called from within the handler.

Requested file data can be supplied through the Buffer, where Count bytes of data will be read by the component starting at the given Index. The data requested by the event may be supplied either all at once or in chunks over multiple calls to this method.

Once all file data have been provided and the transfer is complete, inform the component by calling the FinalizeTask method.

For example, if GetFileData fires and requests 1024 bytes of file data, the user can opt to pass these data in one or multiple chunks:

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

RenameFile Method (CBSync Component)

This method renames a local file in a synchronization root.

Syntax

• C#
• VB.NET

public void RenameFile(string path, string newPath, bool overwrite);

Public Sub RenameFile(ByVal Path As String, ByVal NewPath As String, ByVal Overwrite As Boolean)

Remarks

This method renames or moves a local file in a synchronization root. Use it when the file has been renamed in the remote storage, and the application needs to update the local synchronization root.

The Path parameter should be a path that begins with the directory separator and identifies the location of the file or folder within the synchronization root.

The NewPath parameter should be a new path that begins with the directory separator and includes a file name; it identifies the new name and location of the file within the synchronization root.

Overwrite, when set to true, tells the component to overwrite another file that is located at NewPath at the moment of a call to this method. If a file exists and Overwrite is false, the method fails with an error.

Note: If a directory exists at NewPath, the method will fail regardless of the value of the Overwrite parameter.

RenameFolder Method (CBSync Component)

This method renames a local folder in a synchronization root.

Syntax

• C#
• VB.NET

public void RenameFolder(string path, string newPath);

Public Sub RenameFolder(ByVal Path As String, ByVal NewPath As String)

Remarks

This method renames or moves a local folder in a synchronization root. Use it when the folder has been renamed in the remote storage, and the application needs to update the local synchronization root.

The Path parameter should be a path that begins with the directory separator and identifies the location of the file or folder within the synchronization root.

The NewPath parameter should be a new path that begins with the directory separator and includes a folder name; it identifies the new name and location of the folder within the synchronization root.

The method will fail if a file or folder already exists at NewPath.

ResetFile Method (CBSync Component)

This method removes the local copy of the data for the specified file.

Syntax

• C#
• VB.NET

public void ResetFile(string path);

Public Sub ResetFile(ByVal Path As String)

Remarks

This method removes the local copy of data for the specified file identified by Path, leaving behind an empty placeholder locally. The ResetPinnedFiles setting controls whether pinned files are reset or skipped (default).

When files are downloaded, their data are stored both locally and remotely. This method should be used to remove the local copy of data and keep only the empty placeholder files.

The Path parameter should be a path that begins with the directory separator and identifies the location of the file or folder within the synchronization root.

// Reset a specific file. cbsync.ResetFile("/MyFolder/MyFile.txt");

ResetFolder Method (CBSync Component)

This method removes the local copy of the data for the specified folder.

Syntax

• C#
• VB.NET

public void ResetFolder(string path);

Public Sub ResetFolder(ByVal Path As String)

Remarks

This method removes the local copy of the data for the specified folder identified by Path, leaving behind an empty placeholder locally. The component will recursively reset all files within that folder. The ResetPinnedFiles setting controls whether pinned files are reset or skipped (default).

When files are downloaded, their data are stored both locally and remotely. This method should be used to remove the local copy of data and keep only the empty placeholder files.

The Path parameter should be a path that begins with the directory separator and identifies the location of the file or folder within the synchronization root.

// Reset all files within "MyFolder" and its subfolders. cbsync.ResetFolder("/MyFolder");

SetFileAttributes Method (CBSync Component)

This method sets the attributes of a local file.

Syntax

• C#
• VB.NET

public void SetFileAttributes(string path, int attributes);

Public Sub SetFileAttributes(ByVal Path As String, ByVal Attributes As Integer)

Remarks

This method sets the attributes of a local file within the synchronization root. It may be used at any time, including from within events, to modify the attributes of a local file.

The Path parameter should be a path that begins with the directory separator and identifies the location of the file or folder within the synchronization root.

The Attributes parameter is used to specify the attributes of the file or folder. The specified attributes replace existing attributes of the file or folder. The special value 0 indicates no modification will be made to the existing attributes. To clear all attributes of a file or folder, set the CBFSSYNC_ATTR_NORMAL attribute. To obtain the current attributes, use the GetFileAttributes or GetFolderAttributes method. The value passed in this parameter should be a binary OR of the following values:

// Set a specific file's attributes to be read-only and hidden. // "myfile.txt" is the name of the file (without separators). cbsync.SetFileAttributes("/myfile.txt", Constants.CBFSSYNC_ATTR_READONLY | Constants.CBFSSYNC_ATTR_HIDDEN);

SetFolderAttributes Method (CBSync Component)

This method sets the attributes of a local folder.

Syntax

• C#
• VB.NET

public void SetFolderAttributes(string path, int attributes);

Public Sub SetFolderAttributes(ByVal Path As String, ByVal Attributes As Integer)

Remarks

This method sets the attributes of a local folder within the synchronization root. It may be used at any time, including from within events, to modify the attributes of a local folder.

The Path parameter should be a path that begins with the directory separator and identifies the location of the file or folder within the synchronization root.

The Attributes parameter is used to specify the attributes of the file or folder. The specified attributes replace existing attributes of the file or folder. The special value 0 indicates no modification will be made to the existing attributes. To clear all attributes of a file or folder, set the CBFSSYNC_ATTR_NORMAL attribute. To obtain the current attributes, use the GetFileAttributes or GetFolderAttributes method. The value passed in this parameter should be a binary OR of the following values:

// Set a specific folder's attributes to be read-only and hidden. // "myfolder" is the name of the folder (without separators). cbsync.SetFolderAttributes("/myfolder", Constants.CBFSSYNC_ATTR_READONLY | Constants.CBFSSYNC_ATTR_HIDDEN);

SyncFile Method (CBSync Component)

This method initiates synchronization of the specified file.

Syntax

• C#
• VB.NET

public void SyncFile(string path);

Public Sub SyncFile(ByVal Path As String)

Remarks

This method initiates retrieval of the specified file. When this method is called, the file data will be downloaded, even if the file has been previously downloaded. After calling this method, the GetFileData event will fire. This method may be used to download a local copy of a file at any time, even if the user has not yet opened the file.

The Path parameter should be a path that begins with the directory separator and identifies the location of the file or folder within the synchronization root.

// Synchronize a specific file. cbsync.SyncFile("/folder1/folder2/file.txt");

Uninstall Method (CBSync Component)

This method unregisters the synchronization root from the system and performs cleanup operations.

Syntax

• C#
• VB.NET

public void Uninstall();

Public Sub Uninstall()

Remarks

This method is used to unregister the synchronization root specified by SyncRootPath. In most cases, this method should be called only when the application using the component will be removed from the system. To simply stop the synchronization but leave the component registered, call the Deactivate method instead.

When this method is called, the component is unregistered and any online-only files and folders present in SyncRootPath are removed; thus, only files that contain data locally remain. For instance, if a file was previously opened in Windows and shows a green checkmark in Explorer, that file will remain after calling this method, whereas a file showing a blue cloud icon would not. The folder structure for remaining files is preserved when this method is called, but empty folders are deleted.

On Windows, this method won't work in a UWP or MAUI application due to security restrictions imposed on the environment, in which these types of applications are run by the OS.

When calling this method, the following values must match the values used when Install was called:

• SyncRootPath
• SyncRootLabel
• WindowsStorageProviderAccount (Windows only)
• WindowsStorageProviderId (Windows only)
• LinuxIntermediateFolder (Linux only)
• MacDomainId (macOS only)
• MacDomainLabel (macOS only)

Note: This method cannot be called within events.

On Windows, this method requires administrative rights to execute successfully. If the user account of the process that calls this method does not have such rights, the call will fail with an error, and the E_ACCESSDENIED HRESULT code will be reported in the OSLastError configuration setting.

UnpinFile Method (CBSync Component)

This method marks the file as unpinned so the local copy of the file data may be freed.

Syntax

• C#
• VB.NET

public void UnpinFile(string path);

Public Sub UnpinFile(ByVal Path As String)

Remarks

This method unpins the file specified by Path that previously was pinned. When the file is unpinned, the local file data may be freed. To explicitly free previously downloaded file data, call ResetFile after calling this method. If ResetFile is not called, a local copy of the data may still be kept locally until the file system initiates the freeing of file data.

Note: This method only removes CBFSSYNC_ATTR_PINNED from the file's attributes. To set the CBFSSYNC_ATTR_UNPINNED attribute so that the file is converted to an online-only file and local file data are freed, use the SetFileAttributes method.

The Path parameter should be a path that begins with the directory separator and identifies the location of the file or folder within the synchronization root.

UnpinFolder Method (CBSync Component)

This method marks the folder as unpinned so the local copy of the files within the folder may be freed.

Syntax

• C#
• VB.NET

public void UnpinFolder(string path);

Public Sub UnpinFolder(ByVal Path As String)

Remarks

This method unpins the folder specified by Path that previously was pinned. When the folder is unpinned, the local data for files within the folder may be freed. To explicitly free previously downloaded files, call ResetFolder after calling this method. If ResetFolder is not called, a local copy of the file data may still be kept locally until the file system initiates the freeing of file data.

Note: This method only removes CBFSSYNC_ATTR_PINNED from the folder's attributes. To set the CBFSSYNC_ATTR_UNPINNED attribute so that the folder is converted to an online-only folder and local file data are freed, use the SetFolderAttributes method.

The Path parameter should be a path that begins with the directory separator and identifies the location of the file or folder within the synchronization root.

UpdateFile Method (CBSync Component)

This method is used to update a local file within the synchronization root.

Syntax

• C#
• VB.NET

public void UpdateFile(string path, int attributes, long size, DateTime creationTime, DateTime lastAccessTime, DateTime modificationTime);

Public Sub UpdateFile(ByVal Path As String, ByVal Attributes As Integer, ByVal Size As Long, ByVal CreationTime As DateTime, ByVal LastAccessTime As DateTime, ByVal ModificationTime As DateTime)

Remarks

This method allows for the updating of a local file within the synchronization root. The method may be used to update the attributes as well as the creation time, last access time, and modified time of a file. If updating the file's attributes is the only desired operation, the SetFileAttributes method may be used instead.

The Path parameter should be a path that begins with the directory separator and identifies the location of the file or folder within the synchronization root.

The Attributes parameter is used to specify the attributes of the file or folder. The specified attributes replace existing attributes of the file or folder. The special value 0 indicates no modification will be made to the existing attributes. To clear all attributes of a file or folder, set the CBFSSYNC_ATTR_NORMAL attribute. To obtain the current attributes, use the GetFileAttributes or GetFolderAttributes method. The value passed in this parameter should be a binary OR of the following values:

The Size parameter must be set to the size of the file in bytes.

The CreationTime, LastAccessTime, and LastModifiedTime parameters contain the corresponding time values specified in UTC. To indicate no change in the time when calling UpdateFile or UpdateFolder, use a DateTime value that is less than or equal to the Unix epoch of January 1, 1970 (e.g., DateTime.MinValue).

// Update a file. // "myfile.txt" is the name of the file (without separators). // 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.UpdateFile("/myfile.txt", 0, 100, FileCreationTime, FileLastAccessTime, FileLastWriteTime); // Update a read-only hidden file. cbsync.UpdateFile("/myfile.txt", Constants.CBFSSYNC_ATTR_READONLY | Constants.CBFSSYNC_ATTR_HIDDEN, 100, FileCreationTime, FileLastAccessTime, FileLastWriteTime);

UpdateFolder Method (CBSync Component)

This method is used to update a local folder within the synchronization root.

Syntax

• C#
• VB.NET

public void UpdateFolder(string path, int attributes, DateTime creationTime, DateTime lastAccessTime, DateTime modificationTime);

Public Sub UpdateFolder(ByVal Path As String, ByVal Attributes As Integer, ByVal CreationTime As DateTime, ByVal LastAccessTime As DateTime, ByVal ModificationTime As DateTime)

Remarks

This method allows for the updating of a local folder within the synchronization root. The method may be used to update the attributes as well as the creation time, last access time, and modified time of a folder. If updating the folder's attributes is the only desired operation, the SetFolderAttributes method may be used instead.

The Path parameter should be a path that begins with the directory separator and identifies the location of the file or folder within the synchronization root.

The Attributes parameter is used to specify the attributes of the file or folder. The specified attributes replace existing attributes of the file or folder. The special value 0 indicates no modification will be made to the existing attributes. To clear all attributes of a file or folder, set the CBFSSYNC_ATTR_NORMAL attribute. To obtain the current attributes, use the GetFileAttributes or GetFolderAttributes method. The value passed in this parameter should be a binary OR of the following values:

The CreationTime, LastAccessTime, and LastModifiedTime parameters contain the corresponding time values specified in UTC. To indicate no change in the time when calling UpdateFile or UpdateFolder, use a DateTime value that is less than or equal to the Unix epoch of January 1, 1970 (e.g., DateTime.MinValue).

// Update a folder. // "myfolder" is the name of the folder (without separators). // 0 represents the attributes since this is a folder with no special attributes. // FolderCreationTime is a DateTime (in UTC). // FolderLastAccessTime is a DateTime (in UTC). // FolderLastWriteTime is a DateTime (in UTC). cbsync.UpdateFolder("/myfolder", 0, FolderCreationTime, FolderLastAccessTime, FolderLastWriteTime);

Activated Event (CBSync Component)

This event fires when the activation of the component has been completed.

Syntax

• C#
• VB.NET

public event OnActivatedHandler OnActivated;

public delegate void OnActivatedHandler(object sender, CBSyncActivatedEventArgs e);

public class CBSyncActivatedEventArgs : EventArgs {
  public int Result { get; }
}

Public Event OnActivated As OnActivatedHandler

Public Delegate Sub OnActivatedHandler(sender As Object, e As CBSyncActivatedEventArgs)

Public Class CBSyncActivatedEventArgs Inherits EventArgs
  Public ReadOnly Property Result As Integer
End Class

Remarks

This event fires when an application calls the Activate method with its Wait parameter set to false after the activation process is completed (either successfully or with an error). The Result parameter specifies whether activation was successful, and the Active property reflects new status.

CancelTask Event (CBSync Component)

This event fires when an ongoing transfer of item data will not be completed and must be canceled.

Syntax

• C#
• VB.NET

public event OnCancelTaskHandler OnCancelTask;

public delegate void OnCancelTaskHandler(object sender, CBSyncCancelTaskEventArgs e);

public class CBSyncCancelTaskEventArgs : EventArgs {
  public long TaskId { get; }
  public string Path { get; }
  public int ResultCode { get; set; }
}

Public Event OnCancelTask As OnCancelTaskHandler

Public Delegate Sub OnCancelTaskHandler(sender As Object, e As CBSyncCancelTaskEventArgs)

Public Class CBSyncCancelTaskEventArgs Inherits EventArgs
  Public ReadOnly Property TaskId As Long
  Public ReadOnly Property Path As String
  Public Property ResultCode As Integer
End Class

Remarks

This event fires when the component has been notified that the ongoing transfer must be canceled. It can be fired in the same thread in which the transfer is handled or in another thread.

When an operation is canceled, the event handler that is busy with the corresponding task handler should finish its work as soon as possible, set ResultCode to either 0 or CBFSSYNC_ERR_OPERATION_CANCELED, and return. After that, this CancelTask event handler may set ResultCode to either 0 or CBFSSYNC_ERR_OPERATION_CANCELED and return.

The TaskId parameter identifies the transfer operation to which this event applies. The TaskId value from this event will match the value provided by the event where the operation began.

The Path parameter represents the path of the file relative to the synchronization root; for example, "/MyFolder/MyFile.txt".

When this event is fired, the ResultCode parameter will always be 0. If, however, the event cannot be handled successfully because of reasons such as unavailable resources or failed security checks, you can set it to an appropriate value to report an error. Please refer to the Error Codes section for the set of possible values. If an unhandled exception occurs within the event handler, the component will catch it and report an internal error.

CreateFile Event (CBSync Component)

This event fires when a local file is created.

Syntax

• C#
• VB.NET

public event OnCreateFileHandler OnCreateFile;

public delegate void OnCreateFileHandler(object sender, CBSyncCreateFileEventArgs e);

public class CBSyncCreateFileEventArgs : EventArgs {
  public long TaskId { get; }
  public string Path { get; }
  public int Attributes { get; }
  public long Size { get; }
  public DateTime CreationTime { get; }
  public DateTime LastAccessTime { get; }
  public DateTime LastModifiedTime { get; }
  public int ResultCode { get; set; }
}

Public Event OnCreateFile As OnCreateFileHandler

Public Delegate Sub OnCreateFileHandler(sender As Object, e As CBSyncCreateFileEventArgs)

Public Class CBSyncCreateFileEventArgs Inherits EventArgs
  Public ReadOnly Property TaskId As Long
  Public ReadOnly Property Path As String
  Public ReadOnly Property Attributes As Integer
  Public ReadOnly Property Size As Long
  Public ReadOnly Property CreationTime As DateTime
  Public ReadOnly Property LastAccessTime As DateTime
  Public ReadOnly Property LastModifiedTime As DateTime
  Public Property ResultCode As Integer
End Class

Remarks

This event fires when the component detects that a new file has been created at the location specified by Path.

When a new file is created within the synchronization root, this event allows for the addition of the file to be acknowledged and replicated in the remote storage.

Use the GetFileData method to obtain the the data that should be sent to the remote storage.

When this event fires and communication with the remote storage is required, an application may use either of the two strategies for reporting the completion of the operation:

• If the request can be completed quickly, set the ResultCode parameter to 0 and return from this event. Do not call FinalizeTask in this case.
• If the request cannot be completed quickly, set the ResultCode parameter to CBFSSYNC_PENDING (0x21000001) and return from this event. The communication with the remote storage then may be completed outside of this event. After the request has been completed, call FinalizeTask to inform the component about the completion. When calling FinalizeTask , pass the value of the TaskId parameter of this event to FinalizeTask to identify the completed operation.

The TaskId parameter identifies the current operation and is required when calling the FinalizeTask method; thus, it is important to record this value when an operation will be completed after the event handler has returned.

The Path parameter represents the path of the file relative to the synchronization root; for example, "/MyFolder/MyFile.txt".

The Size parameter specifies the new size of the file.

The CreationTime, LastAccessTime, and LastModifiedTime parameters contain the corresponding time value, specified in UTC.

The Attributes parameter is a bitmask defining the attributes of the file. The possible attributes include the following:

When this event is fired, the ResultCode parameter will always be 0. If, however, the event cannot be handled successfully because of reasons such as unavailable resources or failed security checks, you can set it to an appropriate value to report an error. Please refer to the Error Codes section for the set of possible values. If an unhandled exception occurs within the event handler, the component will catch it and report an internal error.

Note that when this event is fired, a change in the local synchronization root has already occurred. This change cannot be reversed by returning an error code from the event handler.

CreateFolder Event (CBSync Component)

This event fires when a local folder is created.

Syntax

• C#
• VB.NET

public event OnCreateFolderHandler OnCreateFolder;

public delegate void OnCreateFolderHandler(object sender, CBSyncCreateFolderEventArgs e);

public class CBSyncCreateFolderEventArgs : EventArgs {
  public long TaskId { get; }
  public string Path { get; }
  public int Attributes { get; }
  public DateTime CreationTime { get; }
  public DateTime LastAccessTime { get; }
  public DateTime LastModifiedTime { get; }
  public int ResultCode { get; set; }
}

Public Event OnCreateFolder As OnCreateFolderHandler

Public Delegate Sub OnCreateFolderHandler(sender As Object, e As CBSyncCreateFolderEventArgs)

Public Class CBSyncCreateFolderEventArgs Inherits EventArgs
  Public ReadOnly Property TaskId As Long
  Public ReadOnly Property Path As String
  Public ReadOnly Property Attributes As Integer
  Public ReadOnly Property CreationTime As DateTime
  Public ReadOnly Property LastAccessTime As DateTime
  Public ReadOnly Property LastModifiedTime As DateTime
  Public Property ResultCode As Integer
End Class

Remarks

This event fires when the component detects that a new folder has been created at the location specified by Path.

When a new folder is created within the synchronization root, this event allows for the addition of the folder to be acknowledged and replicated in the remote storage.

When this event fires and communication with the remote storage is required, an application may use either of the two strategies for reporting the completion of the operation:

• If the request can be completed quickly, set the ResultCode parameter to 0 and return from this event. Do not call FinalizeTask in this case.
• If the request cannot be completed quickly, set the ResultCode parameter to CBFSSYNC_PENDING (0x21000001) and return from this event. The communication with the remote storage then may be completed outside of this event. After the request has been completed, call FinalizeTask to inform the component about the completion. When calling FinalizeTask , pass the value of the TaskId parameter of this event to FinalizeTask to identify the completed operation.

The TaskId parameter identifies the current operation and is required when calling the FinalizeTask method; thus, it is important to record this value when an operation will be completed after the event handler has returned.

The Path parameter represents the path of the folder relative to the synchronization root; for example, "/MyFolder/MyOtherFolder".

The CreationTime, LastAccessTime, and LastModifiedTime parameters contain the corresponding time value, specified in UTC.

The Attributes parameter is a bitmask defining the attributes of the folder. The possible attributes include the following:

When this event is fired, the ResultCode parameter will always be 0. If, however, the event cannot be handled successfully because of reasons such as unavailable resources or failed security checks, you can set it to an appropriate value to report an error. Please refer to the Error Codes section for the set of possible values. If an unhandled exception occurs within the event handler, the component will catch it and report an internal error.

Note that when this event is fired, a change in the local synchronization root has already occurred. This change cannot be reversed by returning an error code from the event handler.

DeleteFile Event (CBSync Component)

This event fires when a local file is deleted.

Syntax

• C#
• VB.NET

public event OnDeleteFileHandler OnDeleteFile;

public delegate void OnDeleteFileHandler(object sender, CBSyncDeleteFileEventArgs e);

public class CBSyncDeleteFileEventArgs : EventArgs {
  public long TaskId { get; }
  public string Path { get; }
  public int DeleteFlags { get; }
  public int ResultCode { get; set; }
}

Public Event OnDeleteFile As OnDeleteFileHandler

Public Delegate Sub OnDeleteFileHandler(sender As Object, e As CBSyncDeleteFileEventArgs)

Public Class CBSyncDeleteFileEventArgs Inherits EventArgs
  Public ReadOnly Property TaskId As Long
  Public ReadOnly Property Path As String
  Public ReadOnly Property DeleteFlags As Integer
  Public Property ResultCode As Integer
End Class

Remarks

This event fires when the local file identified by Path is deleted.

When this event fires and communication with the remote storage is required, an application may use either of the two strategies for reporting the completion of the operation:

• If the request can be completed quickly, set the ResultCode parameter to 0 and return from this event. Do not call FinalizeTask in this case.
• If the request cannot be completed quickly, set the ResultCode parameter to CBFSSYNC_PENDING (0x21000001) and return from this event. The communication with the remote storage then may be completed outside of this event. After the request has been completed, call FinalizeTask to inform the component about the completion. When calling FinalizeTask , pass the value of the TaskId parameter of this event to FinalizeTask to identify the completed operation.

The TaskId parameter identifies the current operation and is required when calling the FinalizeTask method; thus, it is important to record this value when an operation will be completed after the event handler has returned.

The Path parameter represents the path of the file relative to the synchronization root; for example, "/MyFolder/MyFile.txt".

The DeleteFlags parameter specifies optional parameters of the operation and contains a combination of the following flags:

When this event is fired, the ResultCode parameter will always be 0. If, however, the event cannot be handled successfully because of reasons such as unavailable resources or failed security checks, you can set it to an appropriate value to report an error. Please refer to the Error Codes section for the set of possible values. If an unhandled exception occurs within the event handler, the component will catch it and report an internal error.

Note that when this event is fired, a change in the local synchronization root has already occurred. This change cannot be reversed by returning an error code from the event handler.

DeleteFolder Event (CBSync Component)

This event fires when a local folder is deleted.

Syntax

• C#
• VB.NET

public event OnDeleteFolderHandler OnDeleteFolder;

public delegate void OnDeleteFolderHandler(object sender, CBSyncDeleteFolderEventArgs e);

public class CBSyncDeleteFolderEventArgs : EventArgs {
  public long TaskId { get; }
  public string Path { get; }
  public int DeleteFlags { get; }
  public int ResultCode { get; set; }
}

Public Event OnDeleteFolder As OnDeleteFolderHandler

Public Delegate Sub OnDeleteFolderHandler(sender As Object, e As CBSyncDeleteFolderEventArgs)

Public Class CBSyncDeleteFolderEventArgs Inherits EventArgs
  Public ReadOnly Property TaskId As Long
  Public ReadOnly Property Path As String
  Public ReadOnly Property DeleteFlags As Integer
  Public Property ResultCode As Integer
End Class

Remarks

This event fires when the local folder identified by Path is deleted.

When this event fires and communication with the remote storage is required, an application may use either of the two strategies for reporting the completion of the operation:

• If the request can be completed quickly, set the ResultCode parameter to 0 and return from this event. Do not call FinalizeTask in this case.
• If the request cannot be completed quickly, set the ResultCode parameter to CBFSSYNC_PENDING (0x21000001) and return from this event. The communication with the remote storage then may be completed outside of this event. After the request has been completed, call FinalizeTask to inform the component about the completion. When calling FinalizeTask , pass the value of the TaskId parameter of this event to FinalizeTask to identify the completed operation.

The TaskId parameter identifies the current operation and is required when calling the FinalizeTask method; thus, it is important to record this value when an operation will be completed after the event handler has returned.

The Path parameter represents the path of the folder relative to the synchronization root; for example, "/MyFolder/MyOtherFolder".

The DeleteFlags parameter specifies optional parameters of the operation and contains a combination of the following flags:

When this event is fired, the ResultCode parameter will always be 0. If, however, the event cannot be handled successfully because of reasons such as unavailable resources or failed security checks, you can set it to an appropriate value to report an error. Please refer to the Error Codes section for the set of possible values. If an unhandled exception occurs within the event handler, the component will catch it and report an internal error.

Note that when this event is fired, a change in the local synchronization root has already occurred. This change cannot be reversed by returning an error code from the event handler.

Error Event (CBSync Component)

This event fires if an unhandled error occurs during an event.

Syntax

• C#
• VB.NET

public event OnErrorHandler OnError;

public delegate void OnErrorHandler(object sender, CBSyncErrorEventArgs e);

public class CBSyncErrorEventArgs : EventArgs {
  public int ErrorCode { get; }
  public string Description { get; }
}

Public Event OnError As OnErrorHandler

Public Delegate Sub OnErrorHandler(sender As Object, e As CBSyncErrorEventArgs)

Public Class CBSyncErrorEventArgs Inherits EventArgs
  Public ReadOnly Property ErrorCode As Integer
  Public ReadOnly Property Description As String
End Class

Remarks

This event fires if an unhandled error occurs during another event. Developers can use this information to track down unhandled errors in an application's event handlers.

GetFileData Event (CBSync Component)

This event fires when file data are needed from the remote storage.

Syntax

• C#
• VB.NET

public event OnGetFileDataHandler OnGetFileData;

public delegate void OnGetFileDataHandler(object sender, CBSyncGetFileDataEventArgs e);

public class CBSyncGetFileDataEventArgs : EventArgs {
  public long TaskId { get; }
  public string Path { get; }
  public long Offset { get; }
  public long Length { get; }
  public int ResultCode { get; set; }
}

Public Event OnGetFileData As OnGetFileDataHandler

Public Delegate Sub OnGetFileDataHandler(sender As Object, e As CBSyncGetFileDataEventArgs)

Public Class CBSyncGetFileDataEventArgs Inherits EventArgs
  Public ReadOnly Property TaskId As Long
  Public ReadOnly Property Path As String
  Public ReadOnly Property Offset As Long
  Public ReadOnly Property Length As Long
  Public Property ResultCode As Integer
End Class

Remarks

This event fires when the component needs to retrieve file data from the remote storage and put them into the local file identified by Path.

To handle the event properly, the data must be passed to the component by calling the PutFileData method one or more times. This can be accomplished in two ways:

• The transfer may be completed within this event. This prevents the event from returning and is suitable for data transfer 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.

After the data transfer is finished, the FinalizeTask method must be called to notify the component that the operation has been completed, as long as the event handler will be returned with success (i.e., ResultCode set to 0) or was previously returned with pending status (i.e., ResultCode set to CBFSSYNC_PENDING). In the case of any other error, the FinalizeTask method should not be called.

The TaskId parameter identifies the current operation and is required when calling both the PutFileData method and the FinalizeTask method; thus, it is important to record this value when an operation will be completed after the event handler has returned.

The Path parameter represents the path of the file relative to the synchronization root; for example, "/MyFolder/MyFile.txt".

The Offset and Length parameters specify the starting position of the data in the file to be retrieved and the expected size of the retrieved data, respectively.

It is possible that the retrieval will be canceled, in which case, the CancelTask event will fire.

When this event is fired, the ResultCode parameter will always be 0. If, however, the event cannot be handled successfully because of reasons such as unavailable resources or failed security checks, you can set it to an appropriate value to report an error. Please refer to the Error Codes section for the set of possible values. If an unhandled exception occurs within the event handler, the component will catch it and report an internal error.

ListDirectory Event (CBSync Component)

This event is fired when the contents of a remote directory need to be listed locally.

Syntax

• C#
• VB.NET

public event OnListDirectoryHandler OnListDirectory;

public delegate void OnListDirectoryHandler(object sender, CBSyncListDirectoryEventArgs e);

public class CBSyncListDirectoryEventArgs : EventArgs {
  public long TaskId { get; }
  public string Path { get; }
  public string Mask { get; }
  public int ResultCode { get; set; }
}

Public Event OnListDirectory As OnListDirectoryHandler

Public Delegate Sub OnListDirectoryHandler(sender As Object, e As CBSyncListDirectoryEventArgs)

Public Class CBSyncListDirectoryEventArgs Inherits EventArgs
  Public ReadOnly Property TaskId As Long
  Public ReadOnly Property Path As String
  Public ReadOnly Property Mask As String
  Public Property ResultCode As Integer
End Class

Remarks

This event is fired by the component when it needs to list the contents of the remote directory specified by Path.

Note: The event is triggered at the discretion of the operating system, and their number is minimized to increase performance. This means that the directory listings in the Path will not be automatically refreshed upon user action; e.g., when the user navigates into the folder in File Explorer in Windows, there is no directory listing performed, and the event is not fired.

To deal with remote changes and update the local information accordingly, an application should track these remote changes in an application-specific manner and then notify about any changes in the contents of a remote directory by calling the methods of the component, such as CreateFile, CreateFolder, UpdateFile, UpdateFolder, DeleteFile, and DeleteFolder.

To handle the event properly, items within the directory must be reported by calling the ListFile and ListFolder methods for each file or folder being reported. This can be accomplished in two ways:

• The listing may be completed within this event.
• Alternatively, the ResultCode parameter may be set to CBFSSYNC_PENDING (0x21000001) to allow the event handler to return without delay, and the work can be completed separately. When the operation with the remote storage is performed in this manner, the FinalizeTask method must be called to inform the component that the operation has been completed.

The TaskId parameter identifies the current operation and is required when calling both the ListFile method and the FinalizeTask method; thus, it is important to record this value for later, when an operation is completed later than the event handler has returned.

The Path parameter represents the path of the file relative to the synchronization root; for example, "/MyFolder/MyFile.txt".

The Mask parameter specifies the filename mask that should be used by an event handler to filter the reported items. This value can contain any combination of valid filename characters and wildcards (the * and ? characters). Alternatively, the mask can be an exact filename (i.e., a value without any wildcards), because some applications query file information by specifying an exact filename in an enumeration.

When this event is fired, the ResultCode parameter will always be 0. If, however, the event cannot be handled successfully because of reasons such as unavailable resources or failed security checks, you can set it to an appropriate value to report an error. Please refer to the Error Codes section for the set of possible values. If an unhandled exception occurs within the event handler, the component will catch it and report an internal error.

Log Event (CBSync Component)

This log reports events that occur in the component.

Syntax

• C#
• VB.NET

public event OnLogHandler OnLog;

public delegate void OnLogHandler(object sender, CBSyncLogEventArgs e);

public class CBSyncLogEventArgs : EventArgs {
  public int Level { get; }
  public string Message { get; }
}

Public Event OnLog As OnLogHandler

Public Delegate Sub OnLogHandler(sender As Object, e As CBSyncLogEventArgs)

Public Class CBSyncLogEventArgs Inherits EventArgs
  Public ReadOnly Property Level As Integer
  Public ReadOnly Property Message As String
End Class

Remarks

This event fires when the component needs to notify an application or developers about something that happened internally. The verbosity is controlled by the LogLevel setting.

LogLevel indicates the level of the message. Possible values are as follows:

Message is the log entry.

Note: This event will fire in the context of a dedicated worker thread. Keep handling of this event as quick as possible.

RenameFile Event (CBSync Component)

This event fires when a local file is about to be renamed or moved.

Syntax

• C#
• VB.NET

public event OnRenameFileHandler OnRenameFile;

public delegate void OnRenameFileHandler(object sender, CBSyncRenameFileEventArgs e);

public class CBSyncRenameFileEventArgs : EventArgs {
  public long TaskId { get; }
  public string OldPath { get; }
  public string NewPath { get; }
  public int ResultCode { get; set; }
}

Public Event OnRenameFile As OnRenameFileHandler

Public Delegate Sub OnRenameFileHandler(sender As Object, e As CBSyncRenameFileEventArgs)

Public Class CBSyncRenameFileEventArgs Inherits EventArgs
  Public ReadOnly Property TaskId As Long
  Public ReadOnly Property OldPath As String
  Public ReadOnly Property NewPath As String
  Public Property ResultCode As Integer
End Class

Remarks

This event fires when the system needs to notify the component that the local file located at OldPath is about to be renamed or moved.

When this event fires and communication with the remote storage is required, an application may use either of the two strategies for reporting the completion of the operation:

• If the request can be completed quickly, set the ResultCode parameter to 0 and return from this event. Do not call FinalizeTask in this case.
• If the request cannot be completed quickly, set the ResultCode parameter to CBFSSYNC_PENDING (0x21000001) and return from this event. The communication with the remote storage then may be completed outside of this event. After the request has been completed, call FinalizeTask to inform the component about the completion. When calling FinalizeTask , pass the value of the TaskId parameter of this event to FinalizeTask to identify the completed operation.

The TaskId parameter identifies the current operation and is required when calling the FinalizeTask method; thus, it is important to record this value when an operation will be completed after the event handler has returned.

The OldPath parameter specifies the current path of the file.

The NewPath parameter specifies the new path of the file.

When this event is fired, the ResultCode parameter will always be 0. If, however, the event cannot be handled successfully because of reasons such as unavailable resources or failed security checks, you can set it to an appropriate value to report an error. Please refer to the Error Codes section for the set of possible values. If an unhandled exception occurs within the event handler, the component will catch it and report an internal error.

Note that when this event is fired, a change in the local synchronization root has already occurred. This change cannot be reversed by returning an error code from the event handler.

RenameFolder Event (CBSync Component)

This event fires when a local folder is about to be renamed or moved.

Syntax

• C#
• VB.NET

public event OnRenameFolderHandler OnRenameFolder;

public delegate void OnRenameFolderHandler(object sender, CBSyncRenameFolderEventArgs e);

public class CBSyncRenameFolderEventArgs : EventArgs {
  public long TaskId { get; }
  public string OldPath { get; }
  public string NewPath { get; }
  public int ResultCode { get; set; }
}

Public Event OnRenameFolder As OnRenameFolderHandler

Public Delegate Sub OnRenameFolderHandler(sender As Object, e As CBSyncRenameFolderEventArgs)

Public Class CBSyncRenameFolderEventArgs Inherits EventArgs
  Public ReadOnly Property TaskId As Long
  Public ReadOnly Property OldPath As String
  Public ReadOnly Property NewPath As String
  Public Property ResultCode As Integer
End Class

Remarks

This event fires when the system needs to notify the component that the local folder located at OldPath is about to be renamed or moved.

When this event fires and communication with the remote storage is required, an application may use either of the two strategies for reporting the completion of the operation:

• If the request can be completed quickly, set the ResultCode parameter to 0 and return from this event. Do not call FinalizeTask in this case.
• If the request cannot be completed quickly, set the ResultCode parameter to CBFSSYNC_PENDING (0x21000001) and return from this event. The communication with the remote storage then may be completed outside of this event. After the request has been completed, call FinalizeTask to inform the component about the completion. When calling FinalizeTask , pass the value of the TaskId parameter of this event to FinalizeTask to identify the completed operation.

The TaskId parameter identifies the current operation and is required when calling the FinalizeTask method; thus, it is important to record this value when an operation will be completed after the event handler has returned.

The OldPath parameter specifies the current path of the folder.

The NewPath parameter specifies the new path of the folder.

When this event is fired, the ResultCode parameter will always be 0. If, however, the event cannot be handled successfully because of reasons such as unavailable resources or failed security checks, you can set it to an appropriate value to report an error. Please refer to the Error Codes section for the set of possible values. If an unhandled exception occurs within the event handler, the component will catch it and report an internal error.

Note that when this event is fired, a change in the local synchronization root has already occurred. This change cannot be reversed by returning an error code from the event handler.

ResetFile Event (CBSync Component)

This event is fired after the local copy of a file's data has been discarded.

Syntax

• C#
• VB.NET

public event OnResetFileHandler OnResetFile;

public delegate void OnResetFileHandler(object sender, CBSyncResetFileEventArgs e);

public class CBSyncResetFileEventArgs : EventArgs {
  public long TaskId { get; }
  public string Path { get; }
}

Public Event OnResetFile As OnResetFileHandler

Public Delegate Sub OnResetFileHandler(sender As Object, e As CBSyncResetFileEventArgs)

Public Class CBSyncResetFileEventArgs Inherits EventArgs
  Public ReadOnly Property TaskId As Long
  Public ReadOnly Property Path As String
End Class

Remarks

This event is fired when the local copy of a file's data has been discarded. When files are downloaded, their data are stored both locally and remotely. At times, the local copy of the data may be purged while the file placeholder remains.

The local file data can be manually removed by calling the ResetFile method, or it may be initiated by the system. In the latter case, after the local copy of the file data has been purged, this event is fired to notify the user.

Following the firing of this event, the file placeholder will still be present, but no file data will be stored locally.

The Path parameter represents the path of the file relative to the synchronization root; for example, "/MyFolder/MyFile.txt".

The TaskId parameter is reserved for future use.

This event is provided for informational purposes only and does not require any immediate action.

UpdateFile Event (CBSync Component)

This event fires when a local file is updated.

Syntax

• C#
• VB.NET

public event OnUpdateFileHandler OnUpdateFile;

public delegate void OnUpdateFileHandler(object sender, CBSyncUpdateFileEventArgs e);

public class CBSyncUpdateFileEventArgs : EventArgs {
  public long TaskId { get; }
  public string Path { get; }
  public int UpdateFlags { get; }
  public int Attributes { get; }
  public long Size { get; }
  public DateTime CreationTime { get; }
  public DateTime LastAccessTime { get; }
  public DateTime LastModifiedTime { get; }
  public int ResultCode { get; set; }
}

Public Event OnUpdateFile As OnUpdateFileHandler

Public Delegate Sub OnUpdateFileHandler(sender As Object, e As CBSyncUpdateFileEventArgs)

Public Class CBSyncUpdateFileEventArgs Inherits EventArgs
  Public ReadOnly Property TaskId As Long
  Public ReadOnly Property Path As String
  Public ReadOnly Property UpdateFlags As Integer
  Public ReadOnly Property Attributes As Integer
  Public ReadOnly Property Size As Long
  Public ReadOnly Property CreationTime As DateTime
  Public ReadOnly Property LastAccessTime As DateTime
  Public ReadOnly Property LastModifiedTime As DateTime
  Public Property ResultCode As Integer
End Class

Remarks

This event fires when the component detects a change in the metadata or data of the local file identified by Path. Scenarios in which this event is fired include the following:

• Modification of file content: The event captures changes to the content of a file, such as appending or removing data within a file. This ensures that the modified content can be synchronized between the local and remote storages.
• Modification of file metadata: When changes are made to a file's metadata, such as timestamps and attributes, the event enables the corresponding metadata in the remote storage to be updated to match the local changes.

When file contents are updated, use the GetFileData method to obtain the data that should be sent to the remote storage.

When this event fires and communication with the remote storage is required, an application may use either of the two strategies for reporting the completion of the operation:

• If the request can be completed quickly, set the ResultCode parameter to 0 and return from this event. Do not call FinalizeTask in this case.
• If the request cannot be completed quickly, set the ResultCode parameter to CBFSSYNC_PENDING (0x21000001) and return from this event. The communication with the remote storage then may be completed outside of this event. After the request has been completed, call FinalizeTask to inform the component about the completion. When calling FinalizeTask , pass the value of the TaskId parameter of this event to FinalizeTask to identify the completed operation.

The TaskId parameter identifies the current operation and is required when calling the FinalizeTask method; thus, it is important to record this value when an operation will be completed after the event handler has returned.

The Path parameter represents the path of the file relative to the synchronization root; for example, "/MyFolder/MyFile.txt".

The Size parameter specifies the new size of the file.

The CreationTime, LastAccessTime, and LastModifiedTime parameters contain the corresponding time value, specified in UTC.

The Attributes parameter is a bitmask defining the attributes of the file. The possible attributes include the following:

The UpdateFlags parameter indicates which information has been updated. This value is a combination of the following flags:

When this event is fired, the ResultCode parameter will always be 0. If, however, the event cannot be handled successfully because of reasons such as unavailable resources or failed security checks, you can set it to an appropriate value to report an error. Please refer to the Error Codes section for the set of possible values. If an unhandled exception occurs within the event handler, the component will catch it and report an internal error.

UpdateFolder Event (CBSync Component)

This event fires when a local folder is updated.

Syntax

• C#
• VB.NET

public event OnUpdateFolderHandler OnUpdateFolder;

public delegate void OnUpdateFolderHandler(object sender, CBSyncUpdateFolderEventArgs e);

public class CBSyncUpdateFolderEventArgs : EventArgs {
  public long TaskId { get; }
  public string Path { get; }
  public int UpdateFlags { get; }
  public int Attributes { get; }
  public DateTime CreationTime { get; }
  public DateTime LastAccessTime { get; }
  public DateTime LastModifiedTime { get; }
  public int ResultCode { get; set; }
}

Public Event OnUpdateFolder As OnUpdateFolderHandler

Public Delegate Sub OnUpdateFolderHandler(sender As Object, e As CBSyncUpdateFolderEventArgs)

Public Class CBSyncUpdateFolderEventArgs Inherits EventArgs
  Public ReadOnly Property TaskId As Long
  Public ReadOnly Property Path As String
  Public ReadOnly Property UpdateFlags As Integer
  Public ReadOnly Property Attributes As Integer
  Public ReadOnly Property CreationTime As DateTime
  Public ReadOnly Property LastAccessTime As DateTime
  Public ReadOnly Property LastModifiedTime As DateTime
  Public Property ResultCode As Integer
End Class

Remarks

This event fires when the component detects a change in the metadata of the local folder identified by Path.

When changes are made to a folder's metadata, such as timestamps and attributes, the event enables the corresponding metadata in the remote storage to be updated to match the local changes.

When this event fires and communication with the remote storage is required, an application may use either of the two strategies for reporting the completion of the operation:

• If the request can be completed quickly, set the ResultCode parameter to 0 and return from this event. Do not call FinalizeTask in this case.
• If the request cannot be completed quickly, set the ResultCode parameter to CBFSSYNC_PENDING (0x21000001) and return from this event. The communication with the remote storage then may be completed outside of this event. After the request has been completed, call FinalizeTask to inform the component about the completion. When calling FinalizeTask , pass the value of the TaskId parameter of this event to FinalizeTask to identify the completed operation.

The TaskId parameter identifies the current operation and is required when calling the FinalizeTask method; thus, it is important to record this value when an operation will be completed after the event handler has returned.

The Path parameter represents the path of the folder relative to the synchronization root; for example, "/MyFolder/MyOtherFolder".

The CreationTime, LastAccessTime, and LastModifiedTime parameters contain the corresponding time value, specified in UTC.

The Attributes parameter is a bitmask defining the attributes of the folder. The possible attributes include the following:

The UpdateFlags parameter indicates which information has been updated. This value is a combination of the following flags:

When this event is fired, the ResultCode parameter will always be 0. If, however, the event cannot be handled successfully because of reasons such as unavailable resources or failed security checks, you can set it to an appropriate value to report an error. Please refer to the Error Codes section for the set of possible values. If an unhandled exception occurs within the event handler, the component will catch it and report an internal error.

Config Settings (CBSync Component)

CBSync Config Settings

Base Config Settings

Trappable Errors (CBSync Component)

Events that include a ResultCode parameter expect the value to be one of the following codes:

CBSync Errors

Special Use Errors