Cloud Files API Frequently Asked Questions
What is On-Demand Loading?
On-demand loading allows the partial download of the remote storage file system, that was requested by the applications(s) on the client machine. While your entire remote storage may contain a lot of data and large folders hierarchy, only a small part of it is downloaded on the client and synced with remote storage. This functionality is provided by the underlying Windows Cloud Files API driver, file attributes set by the driver and IT Hit User File System Engine API.
What is Selective Offline Availability?
A user can select which files or folders are required to stay on a local drive and be available regardless of the connection to the server. A user can select "Always keep on this device" and "Free up space" in the Windows File Manager context menu to manage the offline availability.
What does "In-Sync" Mean?
In terms of Microsoft Cloud API, "In-Sync" means that the file or folder is NOT modified on the client machine. The file on the server still can be different from the file on the client. If the file is not in-sync, this means the file content must be sent from the client to the remote storage. The In-sync items are marked with a cloud icon
if the file or folder is offline (has Offline(O) attribute) or with a checkmark on a white background
if the file content was loaded on disk. Not In-sync files and folders are marked with the Sync pending ("arrows") icon
and "Sync pending" text in the Status column in Windows File Manager.
Note that if you modify the file inside the folder, the folder in which this file is located (and all folders up to the sync root) will be marked with "arrows" / "Sync pending" in Windows File Manager. However, the state of such folders will be "In-sync". You can NOT discover if any files are modified inside the folder using the "In-sync" state of the folder.
How Does the "Always keep on this device" Menu Works?
This is a standard menu provided by Windows OS, which appears under the sync root folder on all files and folders, you do not have to program anything for the menu itself to appear. When a user selects "Always keep on this device" the file or folder is marked with Pinned (P) attribute.
If the file or folder is offline, it receives the "Sync pending" icon. The file content itself does NOT start loading on the local disk automatically. Instead, you have to monitor the Pinned attribute and Offline attribute combination and load file content using the PlaceholderFile.Hydrate() method. Note that not the In-Sync icon may be confusing for the developer because the file/folder itself is "In-Sync" state in terms of the Cloud Files API (no content is modified on the client).
If the file or folder is loaded on disk and NOT modified (has In-Sync state), the file is marked with a Pinned icon
.
When this menu is called for a folder, all files and folders will automatically receive the Pinned attribute. In this case, the Engine will call IFolder.GetChildrenAsync() method requesting the creation of all placeholders representing files and folders under the folder that was pinned.
How Does the "Free up space" Menu Works?
This is a standard menu provided by Windows OS, which appears under the sync root folder on all files and folders, you do not have to program anything for the menu itself to appear. When a user selects the "Free up space" menu the file is marked with Unpinned(U) attribute. The file content itself is NOT removed automatically from the local disk. Instead, you have to monitor the Unpinned attribute change and remove the file content calling the PlaceholderFile.Dehydrate() method.
When this menu is called for a folder, all files and folders will automatically receive the Unpinned attribute. Note that folder placeholders are not being deleted automatically under the unpinned folder. As soon as empty placeholders consume minimum space on disk, typically you can leave the unpinned folders and their content in the user file system.
That is a "Placeholder"?
Files and folders under the sync root are called "placeholders". You will manipulate placeholders using the PlaceholderFile and PlaceholderFolder classes.
The major placeholder states are In-sync and not In-sync. It can be in several more states, such as the partially loaded state. All states are represented by the PlaceholderState flags enum and can be queried via PlaceholderItem.GetState() method call.
Note that under your sync root you can find not only placeholders but also regular files and folders. To determine if the file or folder is a placeholder use the PlaceholderItem.GetState() method and check the PlaceholderState.NoStates flag.
When a file or folder is created under sync root, they are being created as a regular file or folder. You can convert such files and folders into placeholders using PlaceholderItem.ConvertToPlaceholder() static method.
What is an Offline(O) attribute?
The Offline attribute means that the file content is located in the remote storage and is not on the local disk. When the application tries to open a document, by default all files and folders in your user file system will be automatically marked with this attribute by default and receive a cloud icon. This attribute is set and removed by the OS only, you should NOT set this attribute from your code. You still can read this attribute in your code, for example, to understand if the content of the folder is loaded to disk.
What Happens When a Folder Content is Being Listed?
When an application is listing folder content, the operating system creates files and folders placeholders for this particular folder. Note that this process is done only during first folder access.
When the folder content is being listed the first time, the Engine calls Engine.GetFileSystemItemAsync() method, requesting a folder object with your IFolder interface implementation. Then the Engine calls IFolder.GetChildrenAsync() method. You will create a list with information about files and folders in the requested folder and return it to the Engine.
Why Folder Listing is Called only One Time?
Applications as well as the operating system may make a lot of folder listing, search, and indexing operations. Such calls, transmitted into your remote storage (even with some caching) will cause slow performance of the file system and can make your file system unusable. The solution is to list folder content only one time, during firs access, which will implement on-demand loading. All further folder content updates must be made by other means, using a pull or push approach. For example, you can use web sockets to receive notifications from the remote storage, use full synchronization, Sync-ID synchronization algorithm, or any other approach.
What Happens When an Application is Reading the File Content of the Offline File?
When an application is accessing the file, opening it for reading or writing, the operating system initiates the process called Hydration. The file content is transferred from remote storage to your local drive.
What is File Hydration?
This is a process of transferring data from your remote storage into local disk. It is initiated by the application accessing the file for reading or writing. Hydration is triggered only when the application opens a document for reading or writing. File attributes reading and writing, file creation and modification date/time reading and writing as well as folder content listing dates not initiate the hydration.
When hydration starts, the operating system redirects the call to the IT Hit User File System Engine and the Engine calls Engine.GetFileSystemItemAsync() method, requesting a file object with your IFile interface implementation. Then the Engine calls IFile.ReadAsync() method. You will transfer file content in this method and return it to the Engine.
Depending on the user file system settings, specified during the file system root registration, the file content becomes available to the application either when the entire file is transferred or when a segment of data, requested by the application becomes available.
The file can also be hydrated programmatically from your code. For example, you will hydrate the file when the file is pinned. To manually initiate the hydration call the PlaceholderFile.Hydrate() method.
Why Not Map All File Read / Write Operations Directly Into Remote Storage?
Such an approach would not work as expected. Applications accessing file system expect fast response and make a lot of reads and writes. Any delays will make the file system very slow and unusable. Saving even a small MS Office document will become very slow, not saying about AutoCAD or Photoshop files. To make it work you will need to build a caching and synchronization mechanism, which will defeat the idea of the direct operations mapping.
You still can map some operations, such as delate and move/rename directly into remote storage. The Engine provides IFileSystemItem.DeleteAsync() and IFileSystemItem.MoveToAsync() methods where you can call your remote storage as well as confirm or reject the operation.