CBSync Class

Properties   Methods   Events   Config Settings   Errors  

The CBSync class enables seamless synchronization between local files and Cloud Storage or other remote repositories.

Syntax

CBSync

Remarks

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

Selecting a Synchronization Root

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

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

Installation and Uninstallation

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

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

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

Handling Events

While the class is active, handle the class's events to provide information as well as receive notifications about local updates. Note that events are fired on arbitrary threads and not the main thread where the class 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 class is active:

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

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

Some of these 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 pre-allocated 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, resulting in 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 UpdateItem or UpdateFolder events will fire on a per-item basis and provide an opportunity to synchronize changes to the remote storage.

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

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

Synchronizing Remote Changes

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

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

• 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 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 the file or folder is only available 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 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 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 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 icons above.

Handling Errors

The class 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.

Event handler functions should return a non-zero value only to indicate that an unexpected or catastrophic error prevented the event handler from executing properly. Doing this will likely disrupt further operations of the class. In the case of the "possible" errors (e.g. file not found, access denied), the actual return value of the event handler function must be 0 and only ResultCode should be set to the error code.

Property List

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

Method List

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

Event List

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

Config Settings

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

Active Property (CBSync Class)

This property reflects whether the class is active.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetActive();

Unicode (Windows)
BOOL GetActive();

int cbfssync_cbsync_getactive(void* lpObj);

bool GetActive();

Default Value

FALSE

Remarks

This property reflects whether the class is currently active and handling OS requests. After Activate is called this property returns true.

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

Data Type

Boolean

SyncRootIcon Property (CBSync Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetSyncRootIcon();
int SetSyncRootIcon(const char* lpszSyncRootIcon);

Unicode (Windows)
LPWSTR GetSyncRootIcon();
INT SetSyncRootIcon(LPCWSTR lpszSyncRootIcon);

char* cbfssync_cbsync_getsyncrooticon(void* lpObj);
int cbfssync_cbsync_setsyncrooticon(void* lpObj, const char* lpszSyncRootIcon);

QString GetSyncRootIcon();
int SetSyncRootIcon(QString qsSyncRootIcon);

Default Value

""

Remarks

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

If set, Windows will use the specified icon for the virtual folder visible in 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 only applicable on Windows. This property has no effect on other platforms.

Data Type

String

SyncRootLabel Property (CBSync Class)

This property specifies a label for the folder.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetSyncRootLabel();
int SetSyncRootLabel(const char* lpszSyncRootLabel);

Unicode (Windows)
LPWSTR GetSyncRootLabel();
INT SetSyncRootLabel(LPCWSTR lpszSyncRootLabel);

char* cbfssync_cbsync_getsyncrootlabel(void* lpObj);
int cbfssync_cbsync_setsyncrootlabel(void* lpObj, const char* lpszSyncRootLabel);

QString GetSyncRootLabel();
int SetSyncRootLabel(QString qsSyncRootLabel);

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 Explorer.

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

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

Data Type

String

SyncRootPath Property (CBSync Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetSyncRootPath();
int SetSyncRootPath(const char* lpszSyncRootPath);

Unicode (Windows)
LPWSTR GetSyncRootPath();
INT SetSyncRootPath(LPCWSTR lpszSyncRootPath);

char* cbfssync_cbsync_getsyncrootpath(void* lpObj);
int cbfssync_cbsync_setsyncrootpath(void* lpObj, const char* lpszSyncRootPath);

QString GetSyncRootPath();
int SetSyncRootPath(QString qsSyncRootPath);

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.

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

Data Type

String

Activate Method (CBSync Class)

This method prepares and starts the necessary mechanisms for synchronization.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Activate();

Unicode (Windows)
INT Activate();

int cbfssync_cbsync_activate(void* lpObj);

int Activate();

Remarks

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

Before calling this method, invoke the Install method to perform system-specific registration procedures if the synchronization root has not previously been registered. If files or folders exist locally in SyncRootPath that were not synchronized before, they are treated as newly created files when this method is called and are discovered, meaning events will fire as needed to provide an opportunity for the remote storage to properly reflect the synchronization root.

Note that 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.

After this method returns, the synchronized location is exposed to the system and events will begin firing as operations are performed, including when:

• The local system requests data from the remote storage location, such as when listing the directory or opening a file.
• Local changes have been made that should be synchronized to the remote storage location, such as when a new file is created or an existing file is modified.
• Remote changes have been made that should be synchronized to the local file system via the CreateFile, CreateFolder, DeleteFile, DeleteFolder, UpdateFile and UpdateFolder methods.

Note: This method cannot be called within events.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Config Method (CBSync Class)

Sets or retrieves a configuration setting.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* Config(const char* lpszConfigurationString);

Unicode (Windows)
LPWSTR Config(LPCWSTR lpszConfigurationString);

char* cbfssync_cbsync_config(void* lpObj, const char* lpszConfigurationString);

QString Config(const QString& qsConfigurationString);

Remarks

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

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, 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.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

CreateFile Method (CBSync Class)

This method creates a local file within a synchronization root.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int CreateFile(const char* lpszPath, int iAttributes, int64 lSize, int64 lCreationTime, int64 lLastAccessTime, int64 lLastModifiedTime);

Unicode (Windows)
INT CreateFile(LPCWSTR lpszPath, INT iAttributes, LONG64 lSize, LONG64 lCreationTime, LONG64 lLastAccessTime, LONG64 lLastModifiedTime);

int cbfssync_cbsync_createfile(void* lpObj, const char* lpszPath, int iAttributes, int64 lSize, int64 lCreationTime, int64 lLastAccessTime, int64 lLastModifiedTime);

int CreateFile(const QString& qsPath, int iAttributes, qint64 lSize, QDateTime qdtCreationTime, QDateTime qdtLastAccessTime, QDateTime qdtLastModifiedTime);

Remarks

This method creates a local file in a synchronization root and optionally initiates retrieval of its data from a 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 as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC, i.e., as FILETIME. 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 1st, 1970.

// Create a new file placeholder. // "/folder1/folder2/new_file.txt" is the path to the file. // 0 represents the attributes since 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 since 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);

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

CreateFolder Method (CBSync Class)

This method creates a local folder within a synchronization root.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int CreateFolder(const char* lpszPath, int iAttributes, int64 lCreationTime, int64 lLastAccessTime, int64 lLastModifiedTime);

Unicode (Windows)
INT CreateFolder(LPCWSTR lpszPath, INT iAttributes, LONG64 lCreationTime, LONG64 lLastAccessTime, LONG64 lLastModifiedTime);

int cbfssync_cbsync_createfolder(void* lpObj, const char* lpszPath, int iAttributes, int64 lCreationTime, int64 lLastAccessTime, int64 lLastModifiedTime);

int CreateFolder(const QString& qsPath, int iAttributes, QDateTime qdtCreationTime, QDateTime qdtLastAccessTime, QDateTime qdtLastModifiedTime);

Remarks

This method creates a local folder in a synchronization root. If the CBFSSYNC_ATTR_PINNED attribute is set, the class 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 as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC, i.e., as FILETIME. 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 1st, 1970.

// Create a new folder in the synchronization root. // "/folder1/folder2/new_folder" is the path to the folder. // 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.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 since 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);

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Deactivate Method (CBSync Class)

This method stops the synchronization operation.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Deactivate();

Unicode (Windows)
INT Deactivate();

int cbfssync_cbsync_deactivate(void* lpObj);

int 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 that 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 have previously 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 class uses a dedicated thread. If there exist open handles to items in a synchronization root directory, FUSE doesn't finish its operations, while the class waits for FUSE to finish. The class can forcefully stop FUSE operations, but only in the application that uses the class didn't set a handler for the SIGINT signal. If such a handler is set, the class 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 class 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.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

DeleteFile Method (CBSync Class)

This method deletes a local file from a synchronization root.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int DeleteFile(const char* lpszPath);

Unicode (Windows)
INT DeleteFile(LPCWSTR lpszPath);

int cbfssync_cbsync_deletefile(void* lpObj, const char* lpszPath);

int DeleteFile(const QString& qsPath);

Remarks

This method deletes a local file from a synchronization root but does not delete the file from the remote storage. The DeleteItem event fires for the newly deleted file after this method successfully returns.

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");

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

DeleteFolder Method (CBSync Class)

This method deletes a local folder from a synchronization root.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int DeleteFolder(const char* lpszPath, int bDeleteChildren);

Unicode (Windows)
INT DeleteFolder(LPCWSTR lpszPath, BOOL bDeleteChildren);

int cbfssync_cbsync_deletefolder(void* lpObj, const char* lpszPath, int bDeleteChildren);

int DeleteFolder(const QString& qsPath, bool bDeleteChildren);

Remarks

This method deletes a local folder from a synchronization root but does not delete it from the remote storage. The DeleteFolder event fires for the newly deleted folder after this method successfully returns.

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);

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

GetFileAttributes Method (CBSync Class)

This method returns the attributes of a local file.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetFileAttributes(const char* lpszPath);

Unicode (Windows)
INT GetFileAttributes(LPCWSTR lpszPath);

int cbfssync_cbsync_getfileattributes(void* lpObj, const char* lpszPath);

int GetFileAttributes(const QString& qsPath);

Remarks

This method returns the attributes of a local file within a 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:

Error Handling (C++)

This method returns an Integer value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetFilePath Method (CBSync Class)

This method returns the absolute path to the local file that should be sent to the remote storage.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetFilePath(int64 lTaskId);

Unicode (Windows)
LPWSTR GetFilePath(LONG64 lTaskId);

char* cbfssync_cbsync_getfilepath(void* lpObj, int64 lTaskId);

QString GetFilePath(qint64 lTaskId);

Remarks

This method may be used from within the CreateItem and UpdateItem events to obtain an absolute path to the local file containing data which was changed and should be sent to the remote storage. This method can be used to return the location of the local file so that it may be read and data can be sent to the remote storage location.

This method returns different values depending on the OS in use:

• In Windows, this returns the equivalent of combining SyncRootPath and the Path parameter of the CreateItem or UpdateItem event.
• In Linux, this returns the equivalent of combining LinuxIntermediateFolder and the Path parameter of the event.
• In macOS, this returns a URL corresponding to the local file data location.

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

// Call this method from within the CreateItem or UpdateItem event handlers. // 123456789 corresponds to the TaskId parameter of the event. // If the SyncRootPath property is set to "C:\temp" and the "myfile.txt" file was accessed, // then GetFilePath will return "C:\temp\myfile.txt" in Windows. string myLocalPath = cbsync.GetFilePath(123456789); // Use the path returned by this method when determining which local file is to be read and upload to the remote storage.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetFileStatus Method (CBSync Class)

This method returns the download status of a local file.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetFileStatus(const char* lpszPath);

Unicode (Windows)
INT GetFileStatus(LPCWSTR lpszPath);

int cbfssync_cbsync_getfilestatus(void* lpObj, const char* lpszPath);

int GetFileStatus(const QString& qsPath);

Remarks

This method returns the download status of a local file within a 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. Refer to the following table for more information.

Icon	Description
	The blue cloud icon indicates the file or folder is only available 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 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 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 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 icons above.

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:

Error Handling (C++)

This method returns an Integer value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetFolderAttributes Method (CBSync Class)

This method returns the attributes of a local folder.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetFolderAttributes(const char* lpszPath);

Unicode (Windows)
INT GetFolderAttributes(LPCWSTR lpszPath);

int cbfssync_cbsync_getfolderattributes(void* lpObj, const char* lpszPath);

int GetFolderAttributes(const QString& qsPath);

Remarks

This method returns the attributes of a local folder within a 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:

Error Handling (C++)

This method returns an Integer value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetFolderStatus Method (CBSync Class)

This method returns the download status of a local folder.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetFolderStatus(const char* lpszPath);

Unicode (Windows)
INT GetFolderStatus(LPCWSTR lpszPath);

int cbfssync_cbsync_getfolderstatus(void* lpObj, const char* lpszPath);

int GetFolderStatus(const QString& qsPath);

Remarks

This method returns the download status of a local folder within a 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. Refer to the following table for more information.

Icon	Description
	The blue cloud icon indicates the file or folder is only available 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 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 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 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 icons above.

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:

Error Handling (C++)

This method returns an Integer value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

Install Method (CBSync Class)

This method registers the synchronization root with the system.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Install();

Unicode (Windows)
INT Install();

int cbfssync_cbsync_install(void* lpObj);

int 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.

In 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.

This method must be called once for each synchronization root, but it does not need to be called again unless the Uninstall method is invoked to remove the registration. Note that the registration performed by this method is persistent and will remain even if the application exits or the class is deactivated as a result of calling the Deactivate method.

In Linux, this method checks that FUSE is installed.

Note: This method cannot be called within events.

In Windows, this method requires administrative rights to execute successfully. If the user account of the process that calls this method doesn't have such rights, the call will fail with the CBFSSYNC_ERR_INITIALIZATION_FAILED error and E_ACCESSDENIED HRESULT code reported in the WindowsLastError configuration setting.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

ListItem Method (CBSync Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ListItem(int64 lTaskId, const char* lpszItemName, int bIsDir, int iAttributes, int64 lSize, int64 lCreationTime, int64 lLastAccessTime, int64 lLastModifiedTime);

Unicode (Windows)
INT ListItem(LONG64 lTaskId, LPCWSTR lpszItemName, BOOL bIsDir, INT iAttributes, LONG64 lSize, LONG64 lCreationTime, LONG64 lLastAccessTime, LONG64 lLastModifiedTime);

int cbfssync_cbsync_listitem(void* lpObj, int64 lTaskId, const char* lpszItemName, int bIsDir, int iAttributes, int64 lSize, int64 lCreationTime, int64 lLastAccessTime, int64 lLastModifiedTime);

int ListItem(qint64 lTaskId, const QString& qsItemName, bool bIsDir, int iAttributes, qint64 lSize, QDateTime qdtCreationTime, QDateTime qdtLastAccessTime, QDateTime qdtLastModifiedTime);

Remarks

This method may be called from within the ListItems event to provide detailed information about an item contained in the directory or after ListItems returns to supply it asynchronously.

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

The ItemName parameter should contain the name of the file or folder without separators.

The IsDir parameter is used to indicate when the item is a folder.

The Attributes parameter is used to specify the attributes of the item. Available attributes are:

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 as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC, i.e., as FILETIME.

Note: This method can be called only within events, and it must be called in the same thread that the event was originally fired on.

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

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

PinFile Method (CBSync Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int PinFile(const char* lpszPath);

Unicode (Windows)
INT PinFile(LPCWSTR lpszPath);

int cbfssync_cbsync_pinfile(void* lpObj, const char* lpszPath);

int PinFile(const QString& qsPath);

Remarks

This method pins the file specified by Path. When the file is pinned, a download is initiated if the file data has not previously been downloaded. Once the file data has been downloaded, the file is marked as pinned, meaning the file is always available on the system even when no Internet connection is available. Refer to the following table for more information.

Icon	Description
	The blue cloud icon indicates the file or folder is only available 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 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 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 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 icons above.

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.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

PinFolder Method (CBSync Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int PinFolder(const char* lpszPath);

Unicode (Windows)
INT PinFolder(LPCWSTR lpszPath);

int cbfssync_cbsync_pinfolder(void* lpObj, const char* lpszPath);

int PinFolder(const QString& qsPath);

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. Refer to the following table for more information.

Icon	Description
	The blue cloud icon indicates the file or folder is only available 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 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 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 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 icons above.

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.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

PutItemData Method (CBSync Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int PutItemData(int64 lTaskId, const char* lpBuffer, int lenBuffer, int iIndex, int iCount);

Unicode (Windows)
INT PutItemData(LONG64 lTaskId, LPCSTR lpBuffer, INT lenBuffer, INT iIndex, INT iCount);

int cbfssync_cbsync_putitemdata(void* lpObj, int64 lTaskId, const char* lpBuffer, int lenBuffer, int iIndex, int iCount);

int PutItemData(qint64 lTaskId, QByteArray qbaBuffer, int iIndex, int iCount);

Remarks

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

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

When the OS must retrieve file data, the GetItemData 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 via the Buffer, where Count bytes of data will be read starting at the given Index. These data may either be supplied all at once or in chunks over multiple calls to this method.

Once all file data has been provided and the transfer is complete, inform the class by calling the TaskComplete method.

For example, if GetItemData 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.PutItemData(e.TaskId, buffer, 0, 1024); cbsync.TaskComplete(e.TaskId, 0); // Pass data in three separate chunks totaling 1024 bytes. cbsync.PutItemData(e.TaskId, buffer, 0, 512); cbsync.PutItemData(e.TaskId, buffer, 512, 100); cbsync.PutItemData(e.TaskId, buffer, 612, 412); cbsync.TaskComplete(e.TaskId, 0);

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

ResetFile Method (CBSync Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ResetFile(const char* lpszPath);

Unicode (Windows)
INT ResetFile(LPCWSTR lpszPath);

int cbfssync_cbsync_resetfile(void* lpObj, const char* lpszPath);

int ResetFile(const QString& qsPath);

Remarks

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

When files are downloaded, their data is 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");

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

ResetFolder Method (CBSync Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ResetFolder(const char* lpszPath);

Unicode (Windows)
INT ResetFolder(LPCWSTR lpszPath);

int cbfssync_cbsync_resetfolder(void* lpObj, const char* lpszPath);

int ResetFolder(const QString& qsPath);

Remarks

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

When files are downloaded, their data is 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");

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

SetFileAttributes Method (CBSync Class)

This method sets the attributes of a local file.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int SetFileAttributes(const char* lpszPath, int iAttributes);

Unicode (Windows)
INT SetFileAttributes(LPCWSTR lpszPath, INT iAttributes);

int cbfssync_cbsync_setfileattributes(void* lpObj, const char* lpszPath, int iAttributes);

int SetFileAttributes(const QString& qsPath, int iAttributes);

Remarks

This method sets the attributes of a local file within a 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);

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

SetFolderAttributes Method (CBSync Class)

This method sets the attributes of a local folder.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int SetFolderAttributes(const char* lpszPath, int iAttributes);

Unicode (Windows)
INT SetFolderAttributes(LPCWSTR lpszPath, INT iAttributes);

int cbfssync_cbsync_setfolderattributes(void* lpObj, const char* lpszPath, int iAttributes);

int SetFolderAttributes(const QString& qsPath, int iAttributes);

Remarks

This method sets the attributes of a local folder within a 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);

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

SyncFile Method (CBSync Class)

This method initiates synchronization of the specified file.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int SyncFile(const char* lpszPath);

Unicode (Windows)
INT SyncFile(LPCWSTR lpszPath);

int cbfssync_cbsync_syncfile(void* lpObj, const char* lpszPath);

int SyncFile(const QString& qsPath);

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 GetItemData 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");

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

TaskComplete Method (CBSync Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int TaskComplete(int64 lTaskId, int iErrorCode);

Unicode (Windows)
INT TaskComplete(LONG64 lTaskId, INT iErrorCode);

int cbfssync_cbsync_taskcomplete(void* lpObj, int64 lTaskId, int iErrorCode);

int TaskComplete(qint64 lTaskId, int iErrorCode);

Remarks

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

• ListItems
• GetItemData
• CreateItem / CreateFolder
• DeleteItem / DeleteFolder
• RenameItem / RenameFolder
• UpdateItem / UpdateFolder

When any of these events fire and data transfer is required, this transfer can take place without blocking the event by setting its ResultCode parameter to CBFSSYNC_PENDING (0x21000001). The event will then return, after which operations to the remote storage location can be performed to synchronize the changes. Once the synchronization operations are complete, this method must be called to indicate that the transfer is complete.

The TaskId parameter should be set to the value originally provided by the event whose operations will be complete asynchronously; thus, it is important to record 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.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Uninstall Method (CBSync Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Uninstall();

Unicode (Windows)
INT Uninstall();

int cbfssync_cbsync_uninstall(void* lpObj);

int Uninstall();

Remarks

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

When this method is called, the class is unregistered and any online-only files and folders present in SyncRootPath are removed; thus, only files which contain data locally remain. For instance, if a file was previously opened in Windows and shows a green check mark 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.

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)

Note: This method cannot be called within events.

In Windows, this method requires administrative rights to execute successfully. If the user account of the process that calls this method doesn't have such rights, the call will fail with the CBFSSYNC_ERR_INITIALIZATION_FAILED error and E_ACCESSDENIED HRESULT code reported in the WindowsLastError configuration setting.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

UnpinFile Method (CBSync Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int UnpinFile(const char* lpszPath);

Unicode (Windows)
INT UnpinFile(LPCWSTR lpszPath);

int cbfssync_cbsync_unpinfile(void* lpObj, const char* lpszPath);

int UnpinFile(const QString& qsPath);

Remarks

This method unpins the file specified by Path which has previously been 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 that 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 is 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.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

UnpinFolder Method (CBSync Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int UnpinFolder(const char* lpszPath);

Unicode (Windows)
INT UnpinFolder(LPCWSTR lpszPath);

int cbfssync_cbsync_unpinfolder(void* lpObj, const char* lpszPath);

int UnpinFolder(const QString& qsPath);

Remarks

This method unpins the folder specified by Path which has previously been 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 that 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 is 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.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

UpdateFile Method (CBSync Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int UpdateFile(const char* lpszPath, int iAttributes, int64 lSize, int64 lCreationTime, int64 lLastAccessTime, int64 lModificationTime);

Unicode (Windows)
INT UpdateFile(LPCWSTR lpszPath, INT iAttributes, LONG64 lSize, LONG64 lCreationTime, LONG64 lLastAccessTime, LONG64 lModificationTime);

int cbfssync_cbsync_updatefile(void* lpObj, const char* lpszPath, int iAttributes, int64 lSize, int64 lCreationTime, int64 lLastAccessTime, int64 lModificationTime);

int UpdateFile(const QString& qsPath, int iAttributes, qint64 lSize, QDateTime qdtCreationTime, QDateTime qdtLastAccessTime, QDateTime qdtModificationTime);

Remarks

This method allows for the updating of a local file within a 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 as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC, i.e., as FILETIME. 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 1st, 1970.

// 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);

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

UpdateFolder Method (CBSync Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int UpdateFolder(const char* lpszPath, int iAttributes, int64 lCreationTime, int64 lLastAccessTime, int64 lModificationTime);

Unicode (Windows)
INT UpdateFolder(LPCWSTR lpszPath, INT iAttributes, LONG64 lCreationTime, LONG64 lLastAccessTime, LONG64 lModificationTime);

int cbfssync_cbsync_updatefolder(void* lpObj, const char* lpszPath, int iAttributes, int64 lCreationTime, int64 lLastAccessTime, int64 lModificationTime);

int UpdateFolder(const QString& qsPath, int iAttributes, QDateTime qdtCreationTime, QDateTime qdtLastAccessTime, QDateTime qdtModificationTime);

Remarks

This method allows for the updating of a local folder within a 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 as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC, i.e., as FILETIME. 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 1st, 1970.

// 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);

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

CancelTask Event (CBSync Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireCancelTask(CBSyncCancelTaskEventParams *e);

typedef struct {
  int64 TaskId;
  const char *Path;
  int ResultCode;
  int reserved;
} CBSyncCancelTaskEventParams;


Unicode (Windows)
virtual INT FireCancelTask(CBSyncCancelTaskEventParams *e);

typedef struct {
  LONG64 TaskId;
  LPCWSTR Path;
  INT ResultCode;
  INT reserved;
} CBSyncCancelTaskEventParams;

#define EID_CBSYNC_CANCELTASK 1

virtual INT CBFSSYNC_CALL FireCancelTask(LONG64 &lTaskId, LPWSTR &lpszPath, INT &iResultCode);

class CBSyncCancelTaskEventParams {
public:
  qint64 TaskId();

  const QString &Path();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void CancelTask(CBSyncCancelTaskEventParams *e);

// Or, subclass CBSync and override this emitter function.
virtual int FireCancelTask(CBSyncCancelTaskEventParams *e) {...}

Remarks

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

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 the event is fired, the ResultCode parameter will always be 0. However, if the event cannot be handled successfully due to 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. In case an unhandled exception occurs within the event handler, the class will catch it and report an internal error.

CreateFolder Event (CBSync Class)

This event fires when a folder is created locally, enabling the creation to be reflected in the corresponding remote folder.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireCreateFolder(CBSyncCreateFolderEventParams *e);

typedef struct {
  int64 TaskId;
  const char *Path;
  int Attributes;
  int64 CreationTime;
  int64 LastAccessTime;
  int64 LastModifiedTime;
  int ResultCode;
  int reserved;
} CBSyncCreateFolderEventParams;


Unicode (Windows)
virtual INT FireCreateFolder(CBSyncCreateFolderEventParams *e);

typedef struct {
  LONG64 TaskId;
  LPCWSTR Path;
  INT Attributes;
  LONG64 CreationTime;
  LONG64 LastAccessTime;
  LONG64 LastModifiedTime;
  INT ResultCode;
  INT reserved;
} CBSyncCreateFolderEventParams;

#define EID_CBSYNC_CREATEFOLDER 2

virtual INT CBFSSYNC_CALL FireCreateFolder(LONG64 &lTaskId, LPWSTR &lpszPath, INT &iAttributes, LONG64 &lCreationTime, LONG64 &lLastAccessTime, LONG64 &lLastModifiedTime, INT &iResultCode);

class CBSyncCreateFolderEventParams {
public:
  qint64 TaskId();

  const QString &Path();

  int Attributes();

  const QDateTime &CreationTime();

  const QDateTime &LastAccessTime();

  const QDateTime &LastModifiedTime();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void CreateFolder(CBSyncCreateFolderEventParams *e);

// Or, subclass CBSync and override this emitter function.
virtual int FireCreateFolder(CBSyncCreateFolderEventParams *e) {...}

Remarks

This event fires when the class 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 location.

When this event fires and communication with the remote storage location is required, there are two supported methods 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 TaskComplete 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 location may then be completed outside of this event. After the request has been completed call TaskComplete to inform the class about the completion. When TaskComplete is called, the value of the TaskId parameter of this event must be passed to TaskComplete to identify the completed operation.

The TaskId parameter identifies the current operation and is required when calling the TaskComplete 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 as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC, i.e., as FILETIME.

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

When the event is fired, the ResultCode parameter will always be 0. However, if the event cannot be handled successfully due to 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. In case an unhandled exception occurs within the event handler, the class will catch it and report an internal error.

CreateItem Event (CBSync Class)

This event fires when a file is created locally, enabling the creation to be reflected in the corresponding remote item.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireCreateItem(CBSyncCreateItemEventParams *e);

typedef struct {
  int64 TaskId;
  const char *Path;
  int Attributes;
  int64 Size;
  int64 CreationTime;
  int64 LastAccessTime;
  int64 LastModifiedTime;
  int ResultCode;
  int reserved;
} CBSyncCreateItemEventParams;


Unicode (Windows)
virtual INT FireCreateItem(CBSyncCreateItemEventParams *e);

typedef struct {
  LONG64 TaskId;
  LPCWSTR Path;
  INT Attributes;
  LONG64 Size;
  LONG64 CreationTime;
  LONG64 LastAccessTime;
  LONG64 LastModifiedTime;
  INT ResultCode;
  INT reserved;
} CBSyncCreateItemEventParams;

#define EID_CBSYNC_CREATEITEM 3

virtual INT CBFSSYNC_CALL FireCreateItem(LONG64 &lTaskId, LPWSTR &lpszPath, INT &iAttributes, LONG64 &lSize, LONG64 &lCreationTime, LONG64 &lLastAccessTime, LONG64 &lLastModifiedTime, INT &iResultCode);

class CBSyncCreateItemEventParams {
public:
  qint64 TaskId();

  const QString &Path();

  int Attributes();

  qint64 Size();

  const QDateTime &CreationTime();

  const QDateTime &LastAccessTime();

  const QDateTime &LastModifiedTime();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void CreateItem(CBSyncCreateItemEventParams *e);

// Or, subclass CBSync and override this emitter function.
virtual int FireCreateItem(CBSyncCreateItemEventParams *e) {...}

Remarks

This event fires when the class 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 location.

When this event fires and communication with the remote storage location is required, there are two supported methods 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 TaskComplete 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 location may then be completed outside of this event. After the request has been completed call TaskComplete to inform the class about the completion. When TaskComplete is called, the value of the TaskId parameter of this event must be passed to TaskComplete to identify the completed operation.

The TaskId parameter identifies the current operation and is required when calling the TaskComplete 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 as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC, i.e., as FILETIME.

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

Use the GetFilePath method to obtain the location of the data that should be sent to a remote storage.

When the event is fired, the ResultCode parameter will always be 0. However, if the event cannot be handled successfully due to 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. In case an unhandled exception occurs within the event handler, the class will catch it and report an internal error.

DeleteFolder Event (CBSync Class)

This event fires when a local folder is deleted, enabling the deletion to be reflected in the corresponding remote folder.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireDeleteFolder(CBSyncDeleteFolderEventParams *e);

typedef struct {
  int64 TaskId;
  const char *Path;
  int DeleteFlags;
  int ResultCode;
  int reserved;
} CBSyncDeleteFolderEventParams;


Unicode (Windows)
virtual INT FireDeleteFolder(CBSyncDeleteFolderEventParams *e);

typedef struct {
  LONG64 TaskId;
  LPCWSTR Path;
  INT DeleteFlags;
  INT ResultCode;
  INT reserved;
} CBSyncDeleteFolderEventParams;

#define EID_CBSYNC_DELETEFOLDER 4

virtual INT CBFSSYNC_CALL FireDeleteFolder(LONG64 &lTaskId, LPWSTR &lpszPath, INT &iDeleteFlags, INT &iResultCode);

class CBSyncDeleteFolderEventParams {
public:
  qint64 TaskId();

  const QString &Path();

  int DeleteFlags();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void DeleteFolder(CBSyncDeleteFolderEventParams *e);

// Or, subclass CBSync and override this emitter function.
virtual int FireDeleteFolder(CBSyncDeleteFolderEventParams *e) {...}

Remarks

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

When this event fires and communication with the remote storage location is required, there are two supported methods 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 TaskComplete 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 location may then be completed outside of this event. After the request has been completed call TaskComplete to inform the class about the completion. When TaskComplete is called, the value of the TaskId parameter of this event must be passed to TaskComplete to identify the completed operation.

The TaskId parameter identifies the current operation and is required when calling the TaskComplete 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 the event is fired, the ResultCode parameter will always be 0. However, if the event cannot be handled successfully due to 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. In case an unhandled exception occurs within the event handler, the class will catch it and report an internal error.

DeleteItem Event (CBSync Class)

This event fires when a local file is deleted, enabling the deletion to be reflected in the corresponding remote item.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireDeleteItem(CBSyncDeleteItemEventParams *e);

typedef struct {
  int64 TaskId;
  const char *Path;
  int DeleteFlags;
  int ResultCode;
  int reserved;
} CBSyncDeleteItemEventParams;


Unicode (Windows)
virtual INT FireDeleteItem(CBSyncDeleteItemEventParams *e);

typedef struct {
  LONG64 TaskId;
  LPCWSTR Path;
  INT DeleteFlags;
  INT ResultCode;
  INT reserved;
} CBSyncDeleteItemEventParams;

#define EID_CBSYNC_DELETEITEM 5

virtual INT CBFSSYNC_CALL FireDeleteItem(LONG64 &lTaskId, LPWSTR &lpszPath, INT &iDeleteFlags, INT &iResultCode);

class CBSyncDeleteItemEventParams {
public:
  qint64 TaskId();

  const QString &Path();

  int DeleteFlags();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void DeleteItem(CBSyncDeleteItemEventParams *e);

// Or, subclass CBSync and override this emitter function.
virtual int FireDeleteItem(CBSyncDeleteItemEventParams *e) {...}

Remarks

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

When this event fires and communication with the remote storage location is required, there are two supported methods 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 TaskComplete 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 location may then be completed outside of this event. After the request has been completed call TaskComplete to inform the class about the completion. When TaskComplete is called, the value of the TaskId parameter of this event must be passed to TaskComplete to identify the completed operation.

The TaskId parameter identifies the current operation and is required when calling the TaskComplete 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 the event is fired, the ResultCode parameter will always be 0. However, if the event cannot be handled successfully due to 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. In case an unhandled exception occurs within the event handler, the class will catch it and report an internal error.

Error Event (CBSync Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireError(CBSyncErrorEventParams *e);

typedef struct {
  int ErrorCode;
  const char *Description;
  int reserved;
} CBSyncErrorEventParams;


Unicode (Windows)
virtual INT FireError(CBSyncErrorEventParams *e);

typedef struct {
  INT ErrorCode;
  LPCWSTR Description;
  INT reserved;
} CBSyncErrorEventParams;

#define EID_CBSYNC_ERROR 6

virtual INT CBFSSYNC_CALL FireError(INT &iErrorCode, LPSTR &lpszDescription);

class CBSyncErrorEventParams {
public:
  int ErrorCode();

  const QString &Description();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void Error(CBSyncErrorEventParams *e);

// Or, subclass CBSync and override this emitter function.
virtual int FireError(CBSyncErrorEventParams *e) {...}

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.

FileReset Event (CBSync Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireFileReset(CBSyncFileResetEventParams *e);

typedef struct {
  int64 TaskId;
  const char *Path;
  int reserved;
} CBSyncFileResetEventParams;


Unicode (Windows)
virtual INT FireFileReset(CBSyncFileResetEventParams *e);

typedef struct {
  LONG64 TaskId;
  LPCWSTR Path;
  INT reserved;
} CBSyncFileResetEventParams;

#define EID_CBSYNC_FILERESET 7

virtual INT CBFSSYNC_CALL FireFileReset(LONG64 &lTaskId, LPWSTR &lpszPath);

class CBSyncFileResetEventParams {
public:
  qint64 TaskId();

  const QString &Path();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void FileReset(CBSyncFileResetEventParams *e);

// Or, subclass CBSync and override this emitter function.
virtual int FireFileReset(CBSyncFileResetEventParams *e) {...}

Remarks

This event is fired when the local copy of a file's data has been discarded. When files are downloaded, their data is 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 either 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.

GetItemData Event (CBSync Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireGetItemData(CBSyncGetItemDataEventParams *e);

typedef struct {
  int64 TaskId;
  const char *Path;
  int64 Offset;
  int64 Length;
  int ResultCode;
  int reserved;
} CBSyncGetItemDataEventParams;


Unicode (Windows)
virtual INT FireGetItemData(CBSyncGetItemDataEventParams *e);

typedef struct {
  LONG64 TaskId;
  LPCWSTR Path;
  LONG64 Offset;
  LONG64 Length;
  INT ResultCode;
  INT reserved;
} CBSyncGetItemDataEventParams;

#define EID_CBSYNC_GETITEMDATA 8

virtual INT CBFSSYNC_CALL FireGetItemData(LONG64 &lTaskId, LPWSTR &lpszPath, LONG64 &lOffset, LONG64 &lLength, INT &iResultCode);

class CBSyncGetItemDataEventParams {
public:
  qint64 TaskId();

  const QString &Path();

  qint64 Offset();

  qint64 Length();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void GetItemData(CBSyncGetItemDataEventParams *e);

// Or, subclass CBSync and override this emitter function.
virtual int FireGetItemData(CBSyncGetItemDataEventParams *e) {...}

Remarks

This event fires when the class 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 class by calling the PutItemData 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 TaskComplete 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 TaskComplete method should not be called.

The TaskId parameter identifies the current operation and is required when calling both the PutItemData method and the TaskComplete 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 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 the event is fired, the ResultCode parameter will always be 0. However, if the event cannot be handled successfully due to 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. In case an unhandled exception occurs within the event handler, the class will catch it and report an internal error.

ListItems Event (CBSync Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireListItems(CBSyncListItemsEventParams *e);

typedef struct {
  int64 TaskId;
  const char *Path;
  const char *Mask;
  int ResultCode;
  int reserved;
} CBSyncListItemsEventParams;


Unicode (Windows)
virtual INT FireListItems(CBSyncListItemsEventParams *e);

typedef struct {
  LONG64 TaskId;
  LPCWSTR Path;
  LPCWSTR Mask;
  INT ResultCode;
  INT reserved;
} CBSyncListItemsEventParams;

#define EID_CBSYNC_LISTITEMS 9

virtual INT CBFSSYNC_CALL FireListItems(LONG64 &lTaskId, LPWSTR &lpszPath, LPWSTR &lpszMask, INT &iResultCode);

class CBSyncListItemsEventParams {
public:
  qint64 TaskId();

  const QString &Path();

  const QString &Mask();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void ListItems(CBSyncListItemsEventParams *e);

// Or, subclass CBSync and override this emitter function.
virtual int FireListItems(CBSyncListItemsEventParams *e) {...}

Remarks

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

It is important to note that the event is triggered at the discretion of the operating system. This means that the directory listings in the Path will not be automatically refreshed upon user action. Instead, updates should be manually reported by calling methods such as CreateFile, CreateFolder, UpdateFile, UpdateFolder, DeleteFile, and DeleteFolder.

To handle the event properly, items within the directory must be reported by calling the ListItem method for each item being reported. 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. When the operation with the remote storage location is performed in this manner, the TaskComplete method must be called to inform the class that the operation has been completed.

The TaskId parameter identifies the current operation and is required when calling both the ListItem method and the TaskComplete 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 Mask parameter allows you to specify a filename mask for filtering the results. It can contain any combination of valid filename characters and wildcards such as * and ?. Alternatively, it can be an exact filename without any wildcards if you need to query file information by specifying an exact filename in the enumeration.

When the event is fired, the ResultCode parameter will always be 0. However, if the event cannot be handled successfully due to 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. In case an unhandled exception occurs within the event handler, the class will catch it and report an internal error.

Log Event (CBSync Class)

This log reports events that occur in the class.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireLog(CBSyncLogEventParams *e);

typedef struct {
  int Level;
  const char *Message;
  int reserved;
} CBSyncLogEventParams;


Unicode (Windows)
virtual INT FireLog(CBSyncLogEventParams *e);

typedef struct {
  INT Level;
  LPCWSTR Message;
  INT reserved;
} CBSyncLogEventParams;

#define EID_CBSYNC_LOG 10

virtual INT CBFSSYNC_CALL FireLog(INT &iLevel, LPWSTR &lpszMessage);

class CBSyncLogEventParams {
public:
  int Level();

  const QString &Message();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void Log(CBSyncLogEventParams *e);

// Or, subclass CBSync and override this emitter function.
virtual int FireLog(CBSyncLogEventParams *e) {...}

Remarks

This event fires when the class 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.

RenameFolder Event (CBSync Class)

This event fires when a local folder is about to be renamed or moved, enabling the change to be reflected in the corresponding remote folder.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireRenameFolder(CBSyncRenameFolderEventParams *e);

typedef struct {
  int64 TaskId;
  const char *OldPath;
  const char *NewPath;
  int ResultCode;
  int reserved;
} CBSyncRenameFolderEventParams;


Unicode (Windows)
virtual INT FireRenameFolder(CBSyncRenameFolderEventParams *e);

typedef struct {
  LONG64 TaskId;
  LPCWSTR OldPath;
  LPCWSTR NewPath;
  INT ResultCode;
  INT reserved;
} CBSyncRenameFolderEventParams;

#define EID_CBSYNC_RENAMEFOLDER 11

virtual INT CBFSSYNC_CALL FireRenameFolder(LONG64 &lTaskId, LPWSTR &lpszOldPath, LPWSTR &lpszNewPath, INT &iResultCode);

class CBSyncRenameFolderEventParams {
public:
  qint64 TaskId();

  const QString &OldPath();

  const QString &NewPath();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void RenameFolder(CBSyncRenameFolderEventParams *e);

// Or, subclass CBSync and override this emitter function.
virtual int FireRenameFolder(CBSyncRenameFolderEventParams *e) {...}

Remarks

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

When this event fires and communication with the remote storage location is required, there are two supported methods 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 TaskComplete 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 location may then be completed outside of this event. After the request has been completed call TaskComplete to inform the class about the completion. When TaskComplete is called, the value of the TaskId parameter of this event must be passed to TaskComplete to identify the completed operation.

The TaskId parameter identifies the current operation and is required when calling the TaskComplete 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 the event is fired, the ResultCode parameter will always be 0. However, if the event cannot be handled successfully due to 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. In case an unhandled exception occurs within the event handler, the class will catch it and report an internal error.

RenameItem Event (CBSync Class)

This event fires when a local file is about to be renamed or moved, enabling the change to be reflected in the corresponding remote item.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireRenameItem(CBSyncRenameItemEventParams *e);

typedef struct {
  int64 TaskId;
  const char *OldPath;
  const char *NewPath;
  int ResultCode;
  int reserved;
} CBSyncRenameItemEventParams;


Unicode (Windows)
virtual INT FireRenameItem(CBSyncRenameItemEventParams *e);

typedef struct {
  LONG64 TaskId;
  LPCWSTR OldPath;
  LPCWSTR NewPath;
  INT ResultCode;
  INT reserved;
} CBSyncRenameItemEventParams;

#define EID_CBSYNC_RENAMEITEM 12

virtual INT CBFSSYNC_CALL FireRenameItem(LONG64 &lTaskId, LPWSTR &lpszOldPath, LPWSTR &lpszNewPath, INT &iResultCode);

class CBSyncRenameItemEventParams {
public:
  qint64 TaskId();

  const QString &OldPath();

  const QString &NewPath();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void RenameItem(CBSyncRenameItemEventParams *e);

// Or, subclass CBSync and override this emitter function.
virtual int FireRenameItem(CBSyncRenameItemEventParams *e) {...}

Remarks

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

When this event fires and communication with the remote storage location is required, there are two supported methods 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 TaskComplete 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 location may then be completed outside of this event. After the request has been completed call TaskComplete to inform the class about the completion. When TaskComplete is called, the value of the TaskId parameter of this event must be passed to TaskComplete to identify the completed operation.

The TaskId parameter identifies the current operation and is required when calling the TaskComplete 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 the event is fired, the ResultCode parameter will always be 0. However, if the event cannot be handled successfully due to 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. In case an unhandled exception occurs within the event handler, the class will catch it and report an internal error.

UpdateFolder Event (CBSync Class)

This event fires when a folder is updated locally, enabling the update to be reflected in the corresponding remote folder.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireUpdateFolder(CBSyncUpdateFolderEventParams *e);

typedef struct {
  int64 TaskId;
  const char *Path;
  int UpdateFlags;
  int Attributes;
  int64 CreationTime;
  int64 LastAccessTime;
  int64 LastModifiedTime;
  int ResultCode;
  int reserved;
} CBSyncUpdateFolderEventParams;


Unicode (Windows)
virtual INT FireUpdateFolder(CBSyncUpdateFolderEventParams *e);

typedef struct {
  LONG64 TaskId;
  LPCWSTR Path;
  INT UpdateFlags;
  INT Attributes;
  LONG64 CreationTime;
  LONG64 LastAccessTime;
  LONG64 LastModifiedTime;
  INT ResultCode;
  INT reserved;
} CBSyncUpdateFolderEventParams;

#define EID_CBSYNC_UPDATEFOLDER 13

virtual INT CBFSSYNC_CALL FireUpdateFolder(LONG64 &lTaskId, LPWSTR &lpszPath, INT &iUpdateFlags, INT &iAttributes, LONG64 &lCreationTime, LONG64 &lLastAccessTime, LONG64 &lLastModifiedTime, INT &iResultCode);

class CBSyncUpdateFolderEventParams {
public:
  qint64 TaskId();

  const QString &Path();

  int UpdateFlags();

  int Attributes();

  const QDateTime &CreationTime();

  const QDateTime &LastAccessTime();

  const QDateTime &LastModifiedTime();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void UpdateFolder(CBSyncUpdateFolderEventParams *e);

// Or, subclass CBSync and override this emitter function.
virtual int FireUpdateFolder(CBSyncUpdateFolderEventParams *e) {...}

Remarks

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

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

When this event fires and communication with the remote storage location is required, there are two supported methods 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 TaskComplete 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 location may then be completed outside of this event. After the request has been completed call TaskComplete to inform the class about the completion. When TaskComplete is called, the value of the TaskId parameter of this event must be passed to TaskComplete to identify the completed operation.

The TaskId parameter identifies the current operation and is required when calling the TaskComplete 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 as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC, i.e., as FILETIME.

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

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

When the event is fired, the ResultCode parameter will always be 0. However, if the event cannot be handled successfully due to 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. In case an unhandled exception occurs within the event handler, the class will catch it and report an internal error.

UpdateItem Event (CBSync Class)

This event fires when a file is updated locally, enabling the update to be reflected in the corresponding remote item.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireUpdateItem(CBSyncUpdateItemEventParams *e);

typedef struct {
  int64 TaskId;
  const char *Path;
  int UpdateFlags;
  int Attributes;
  int64 Size;
  int64 CreationTime;
  int64 LastAccessTime;
  int64 LastModifiedTime;
  int ResultCode;
  int reserved;
} CBSyncUpdateItemEventParams;


Unicode (Windows)
virtual INT FireUpdateItem(CBSyncUpdateItemEventParams *e);

typedef struct {
  LONG64 TaskId;
  LPCWSTR Path;
  INT UpdateFlags;
  INT Attributes;
  LONG64 Size;
  LONG64 CreationTime;
  LONG64 LastAccessTime;
  LONG64 LastModifiedTime;
  INT ResultCode;
  INT reserved;
} CBSyncUpdateItemEventParams;

#define EID_CBSYNC_UPDATEITEM 14

virtual INT CBFSSYNC_CALL FireUpdateItem(LONG64 &lTaskId, LPWSTR &lpszPath, INT &iUpdateFlags, INT &iAttributes, LONG64 &lSize, LONG64 &lCreationTime, LONG64 &lLastAccessTime, LONG64 &lLastModifiedTime, INT &iResultCode);

class CBSyncUpdateItemEventParams {
public:
  qint64 TaskId();

  const QString &Path();

  int UpdateFlags();

  int Attributes();

  qint64 Size();

  const QDateTime &CreationTime();

  const QDateTime &LastAccessTime();

  const QDateTime &LastModifiedTime();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void UpdateItem(CBSyncUpdateItemEventParams *e);

// Or, subclass CBSync and override this emitter function.
virtual int FireUpdateItem(CBSyncUpdateItemEventParams *e) {...}

Remarks

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

• 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 storage locations.
• Modification of file attributes: When changes are made to a file's attributes, such as permissions, ownership, timestamps, or other metadata, the event enables the corresponding attributes in the remote storage to be updated to match the local changes.

When this event fires and communication with the remote storage location is required, there are two supported methods 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 TaskComplete 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 location may then be completed outside of this event. After the request has been completed call TaskComplete to inform the class about the completion. When TaskComplete is called, the value of the TaskId parameter of this event must be passed to TaskComplete to identify the completed operation.

The TaskId parameter identifies the current operation and is required when calling the TaskComplete 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 as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC, i.e., as FILETIME.

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

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

When file contents are updated, use the GetFilePath method to obtain the location of the data that should be sent to a remote storage.

When the event is fired, the ResultCode parameter will always be 0. However, if the event cannot be handled successfully due to 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. In case an unhandled exception occurs within the event handler, the class will catch it and report an internal error.

Config Settings (CBSync Class)

CBSync Config Settings

Base Config Settings

Trappable Errors (CBSync Class)

Error Handling (C++)

Call the GetLastErrorCode() method to obtain the last called method's result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. Known error codes are listed below. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

Events that include a ResultCode or ErrorCode parameter expect the value to be one of the codes listed below.

CBSync Errors

Special Use Errors