Cloud File API FAQ

Question

Cloud File API FAQ

alan henry 0

Based on the introduction from Windows official documentation at https://learn.microsoft.com/en-us/windows/win32/cfapi/build-a-cloud-file-sync-engine and the Cloud Mirror Sample, we attempted to develop a SyncEngine independently. However, we encountered numerous issues. We believe other developers may face similar challenges, so we have listed them in detail below, hoping that Windows system developers can provide thorough explanations.

The article https://learn.microsoft.com/en-us/windows/win32/cfapi/build-a-cloud-file-sync-engine suggests that the Cloud File API comprises two parts: the Cloud Filter API and the Windows.Storage.Provider namespace. What is the relationship between these two? In the sample, winrt::StorageProviderSyncRootManager::Register is used, while the Cloud Filter API provides CfRegisterSyncRoot. What is the difference between these two functions? Must both be used? Or which one is recommended?
Can a background console application (without a desktop UI) be developed using the Cloud File API?
After developing with the Cloud File API, is the article https://learn.microsoft.com/en-us/windows/win32/shell/integrate-cloud-storage still relevant as a reference?
Referring to the Cloud Mirror sample, we implemented the creation and deletion of file and directory placeholders. However, when deleting an empty directory, Explorer prompts a timeout error (error code 0x800701AA). Why does this occur? Is it due to an unimplemented callback? Or could there be an issue with the properties of the placeholder created via CfCreatePlaceholders?
What is the default timeout duration for the Cloud File API? Can this timeout be adjusted? If the timeout is short and non-adjustable, and user operations are frequent, what approach is recommended for implementing the SyncEngine?
Does the Cloud File API provide logs to assist in issue diagnosis? How can we quickly identify which specific interface timed out?
Is the status and UI display implemented via COM interfaces in the sample mandatory?
While the SyncEngine is online, how should it identify newly added files under the SyncRoot? If the SyncEngine is offline, and files are added/deleted under the SyncRoot, how should these changes be detected later?
When the SyncEngine starts, will new files created under the SyncRoot automatically have placeholders added? After the SyncEngine uploads a local file to the cloud, is it necessary to manually call a function to transition the file state to "full"?
During the Hydrate process, if file download is canceled, will the system automatically clear the partially downloaded data? Or must Dehydrate be explicitly called?
Can a chunked download approach be used for hydration? Does CfExecute support this method?
During file deletion, we received two Delete callbacks. Is this behavior expected?
As development progresses, additional questions may arise. We appreciate ongoing support for future issues.

My questions might be a bit lengthy and complicated—please bear with me.

Michael Le (WICLOUD CORPORATION) 6,020 Reputation points Microsoft External Staff Moderator

2025-11-06T07:18:18.0733333+00:00

Hi @alan henry , apologies for the delayed response. Just checking in—has this been resolved on your end? If not, we're happy to help whenever you're available.
alan henry 0 Reputation points

2025-11-06T07:47:30.8466667+00:00

Hi, @Michael Le , happy to hear from you.

The questions is not resolved yet, your help is welcome.
Michael Le (WICLOUD CORPORATION) 6,020 Reputation points Microsoft External Staff Moderator

2025-11-06T07:59:03.67+00:00

Thanks for the response. We'll look into this and update you as soon as we have more information. Appreciate your patience.

Answer recommended by moderator

1 additional answer

Your answer

Michael Le (WICLOUD CORPORATION) 6,020 Reputation points Microsoft External Staff Moderator

2025-11-06T07:18:18.0733333+00:00

Hi @alan henry , apologies for the delayed response. Just checking in—has this been resolved on your end? If not, we're happy to help whenever you're available.
alan henry 0 Reputation points

2025-11-06T07:47:30.8466667+00:00

Hi, @Michael Le , happy to hear from you.

The questions is not resolved yet, your help is welcome.
Michael Le (WICLOUD CORPORATION) 6,020 Reputation points Microsoft External Staff Moderator

2025-11-06T07:59:03.67+00:00

Thanks for the response. We'll look into this and update you as soon as we have more information. Appreciate your patience.

Answer 1

Danny Nguyen (WICLOUD CORPORATION) 5,065 Microsoft External Staff Moderator

Hi,

To answer your new questions:

“The metadata of the placeholder file is missing, so I can’t judge the meta version. It’s by design?”

Yes, the process goes like this:

Overwriting/replacing a placeholder with a normal file removes the Cloud Files (M$CF) reparse point.
Once that’s gone, CFAPI no longer has the placeholder metadata or your meta version.
CFAPI does not preserve or merge the old identity/version for you in this replace scenario.

“What can I do for this?”

Detect that the placeholder was overwritten (e.g. CfGetPlaceholderState and/or directory change monitoring like ReadDirectoryChangesW / USN).
Treat the result as a new local edit: upload the content to your service and assign a new remote version.
Call CfConvertToPlaceholder on the now-normal file to attach a fresh identity (with your new version), then CfSetInSyncState when it’s in sync.
Keep your own versioning/metadata store so you can reason about versions even when the on-disk placeholder metadata (reparse point) is lost (optional but I think it would be essential if you're creating a full application).

Also note that the Cloud Files / Cloud Filter API is not a full sync engine. It only manages placeholders and hydration on the local file system. All higher-level sync behavior like version tracking, conflict resolution, and any extra metadata, you have to implement in your own sync engine (typically using your own local/remote metadata store) and then drive CFAPI with the appropriate calls.

Danny Nguyen (WICLOUD CORPORATION) 5,065 Reputation points Microsoft External Staff Moderator

2025-11-21T10:28:19.5733333+00:00
2、I can proactively cancel a HyDration by clicking the cancel button of the progress bar, but how can I cancel the HyDration with background mode?

The shell’s “Cancel” button just cancels the underlying CFAPI hydration operation. For background hydration, you do the same thing yourself:

Keep track of the CFAPI operation for each hydration request (the OperationId from the callback).

When your background logic decides to cancel (timeout, user action in your own UI, policy), mark that operation as cancelled in your engine and complete it with a cancel/abort status via the CFAPI completion call you’re using.

Your background worker should periodically check a “cancel” flag and stop streaming data when it’s set.

There’s no separate “background hydration cancel” API: you cancel by finishing the CFAPI fetch operation with an abort result rather than success, exactly as the shell does when the user clicks the cancel button.

Minimal pattern:

CF_OPERATION_INFO opInfo = {}; opInfo.StructSize = sizeof(opInfo); opInfo.Type = CF_OPERATION_TYPE_ACK_DATA; opInfo.ConnectionKey = fetchParams->ConnectionKey; opInfo.TransferKey = fetchParams->TransferKey; CF_OPERATION_PARAMETERS opParams = {}; opParams.StructSize = sizeof(opParams); opParams.AckData.Flags = CF_OPERATION_ACK_DATA_FLAG_CANCELED; // Optionally set opParams.AckData.CompletionStatus = HRESULT_FROM_WIN32(ERROR_OPERATION_ABORTED); HRESULT hr = CfExecute(&opInfo, &opParams);

3、I noticed a weird scene that I created a normal symlink(not a dir symlink), the ReadDirectoryChangeExW returned two actions which the first one is FILE_ACTION_ADDED without ReparsePoint attribute value, and the second one is FILE_ACTION_MODIFIED with the correct ReparsePoint attribute and ReparsePoint tag value. It's by design? And how could I correctly monitor the files' or directories' modification?

what you're seeing is expected. ReadDirectoryChangesExW reports low-level NTFS changes, not high-level, coalesced “operations”. When you create a file symlink, it’s normal to see:

First: FILE_ACTION_ADDED with initial attributes (possibly without FILE_ATTRIBUTE_REPARSE_POINT).

Then: FILE_ACTION_MODIFIED when the reparse point and its tag are set.

The API streams the changes as they happen; it doesn’t guarantee a single notification with fully-finalized attributes for each logical user action.

To monitor modifications correctly, you would have to maintain your own state per entry (attributes, reparse flag, tag, etc.) and treat ReadDirectoryChangesExW events as a stream of deltas and compare “before vs after” to detect real semantic changes (e.g., “this entry became a symlink now”).
alan henry 0 Reputation points

2025-11-22T02:54:21.6033333+00:00

Hi, the flag CF_OPERATION_ACK_DATA_FLAG_CANCELED appears to be undefined?
Danny Nguyen (WICLOUD CORPORATION) 5,065 Reputation points Microsoft External Staff Moderator

2025-11-25T07:23:29.2333333+00:00

according to https://learn.microsoft.com/en-us/windows/win32/api/cfapi/ne-cfapi-cf_operation_ack_data_flags

the only data flag it takes is CF_OPERATION_ACK_DATA_FLAG_NONE so please change to that

Answer 2

Danny Nguyen (WICLOUD CORPORATION) 5,065 Microsoft External Staff Moderator

Hi,

Thank you for posting in Microsoft Learn Q&A forum,

I will try to address your answer in chunks to keep the response not bloat. Feel free to let me know if you need clarification anywhere.

The Cloud Files API consists of the Cloud Filter API and Windows.Storage.Provider namespace.
- Cloud Filter API: "This native Win32 API provides functionality at the boundary between the user mode and the file system. This API handles the creation and management of placeholder files and directories."
- Windows.Storage.Provider namespace: "This WinRT API enables applications to configure the cloud storage provider and register the sync root with the operating system."
Cloud Filter API manages file system interactions; Windows.Storage.Provider handles configuration and shell integration.
- CfRegisterSyncRoot: Win32 function for sync root registration using CF_SYNC_REGISTRATION structure.
- winrt::StorageProviderSyncRootManager::Register: WinRT method that "Registers a sync root with the operating system" using StorageProviderSyncRootInfo.
In short, CfRegisterSyncRoot is low-level (Win32); Register is high-level (WinRT) for easier shell integration. Use one, not both. WinRT Register is recommended for modern apps.
Yes, a background console application (no UI) can use the Cloud Files API, as sync engines can run as background processes via Win32 APIs.
Yes, aside from legacy overlay/placeholder parts superseded by CFAPI, the “Integrate cloud storage” doc is still relevant for Shell integration (context menus, property/thumbnail handlers, indexing, UX guidelines).
Error 0x800701AA means "The cloud operation was not completed before the time-out period expired." This occurs if the sync engine doesn't respond to deletion callbacks in time, likely due to an unimplemented callback like CF_CALLBACK_DELETE_FLAGS: "This callback informs the sync provider that a placeholder file or directory under one of its sync roots is about to be deleted or undeleted." Not typically an issue with CfCreatePlaceholders properties; implement deletion callbacks properly.

Danny Nguyen (WICLOUD CORPORATION) 5,065 Reputation points Microsoft External Staff Moderator

2025-11-11T07:23:33.26+00:00
CFAPI does not expose or document a configurable timeout. The Windows Cloud Filter Driver / Explorer enforces a fixed internal deadline after which the request is canceled and a CANCEL_FETCH_DATA callback may fire. Hydration policies don’t change this, and indirect factors (network latency, provider blocking, CPU load) only affect whether you exceed it. So try to mitigate by returning the first bytes quickly, streaming in chunks, avoiding long blocking operations, and handling cancellations cleanly.

CFAPI itself has no built‑in programmable logging, you must instrument every callback (FETCH_DATA, CANCEL_FETCH_DATA, ENUMERATE_CHILDREN, etc.) in your sync engine. Use your own structured logs using ETW TraceLogging/EventSource/WPP or simple text.

For system visibility rely on: Event Viewer (Microsoft > Windows > CloudFiles > Operational), ETW tracing (cldflt.sys + FS activity via Windows Performance Recorder/xperf), and ProcMon to observe IRPs and FSCTLs.

Best practice: keep callbacks fast, stream data early in chunks, and log enough performance metrics to spot stalls before they trigger the OS’s internal timeout.

It is mandatory if you want Windows to surface your provider’s sync status, errors, and actions in the built‑in Shell status flyout and related UX. Minimal Cloud Files provider can still function but you will miss out on status UI and provider specific commands.

When SyncEngine is either online or offline: Online Sync Engine

After registering the sync root (CfRegisterSyncRoot) and connecting (CfConnectSyncRoot), you receive CFAPI callbacks for deletes (CF_CALLBACK_TYPE_NOTIFY_FILE_DELETE) and renames (CF_CALLBACK_TYPE_NOTIFY_FILE_RENAME), but not for local file creations or content edits. Detect those via either

ReadDirectoryChangesW for near real‑time FILE_ACTION_ADDED / MODIFIED events (CloudMirror uses a DirectoryWatcher)

the NTFS USN Change Journal for scalable, loss‑resistant enumeration (USN_REASON_FILE_CREATE, FILE_DELETE, RENAME_OLD_NAME + RENAME_NEW_NAME, DATA_OVERWRITE/EXTEND/TRUNCATION)

When a new non‑placeholder file appears: upload to your cloud backend, then call CfSetInSyncState to mark it synchronized. Optionally later convert (CfConvertToPlaceholder + potential CfDehydratePlaceholder) if you want a space‑saving placeholder rather than a hydrated local copy.

Offline Gap Recovery

If the provider was not running, on restart read the persisted last processed USN. If the journal still contains that USN, enumerate forward (FSCTL_ENUM_USN_DATA / FSCTL_READ_USN_JOURNAL) collecting creates, deletes, renames, and data changes; reconcile with remote (upload new/changed, propagate deletes, update placeholder metadata). If the journal was truncated or the ID changed, fall back to a full directory scan comparing current tree to your metadata (detect missing entries = deletes, new entries = creates, changed hashes/sizes = modifications, attempt rename pairing via File IDs). After processing, persist the new last USN. Use the USN Journal also to recover from any ReadDirectoryChangesW buffer overflows.
Danny Nguyen (WICLOUD CORPORATION) 5,065 Reputation points Microsoft External Staff Moderator

2025-11-12T10:50:28.3166667+00:00
No, Windows does not automatically create placeholders for new locally created files under your sync root when your SyncEngine starts (or when a user saves a file). A brand‑new user file is just an ordinary NTFS file. Your engine must detect it (directory change or USN journal), upload it to your service, and then optionally convert it to a placeholder if you want it managed as an on‑demand cloud item (call CfConvertToPlaceholder, supplying identity metadata). If you leave it as a normal file, that is acceptable; it simply won’t have cloud placeholder semantics (e.g., future dehydration, placeholder state flags).

If a hydration (FETCH_DATA) is canceled after you have already written some bytes, Windows does not automatically roll back or purge those partially hydrated ranges—the data you successfully wrote stays on disk and the placeholder is now partially hydrated. Cancellation just stops further range requests. You only need to call CfDehydratePlaceholder (or later dehydrate via policy) if you explicitly want to reclaim space or revert the file to a fully dehydrated state instead of keeping partial data for a faster future resume.

If cancellation occurs before any data is written, the file remains a dehydrated placeholder. To resume later, future reads will trigger new FETCH_DATA callbacks for missing ranges. So: partial data is retained unless you deliberately dehydrate; explicit cleanup is provider-controlled, not automatic.

Yes - hydration is inherently chunked. Windows requests byte ranges in the FETCH_DATA callback; your sync engine responds by calling CfExecute with CF_OPERATION_TYPE_TRANSFER_DATA for each chunk (range) you choose to supply. If the platform asks for a large range, you may either:

Internally fetch it in smaller pieces from your cloud and then issue a single CfExecute covering the whole requested range, or

Issue multiple CfExecute calls, each with a TRANSFER_DATA operation for successive sub‑ranges (offset + length) until the requested region is fully satisfied. Unhydrated portions remain sparse; later reads trigger additional FETCH_DATA requests. You can report progress during long transfers with CfReportProviderProgress. After all needed ranges for the current version are present, mark sync status (not hydration state) with CfSetInSyncState. Optional programmatic hydrations (without immediate user I/O) can be initiated via CfHydratePlaceholder. Space reclamation later uses CfDehydratePlaceholder.

Yes, it can be normal. A “single” user delete often produces multiple platform events you might count as two delete callbacks:

Common causes:

Recycle Bin flow: Explorer rename/move to $Recycle.Bin then final delete.

Folder delete: one callback per child + one for the folder.

Replace‐on‑save (temp file swap): overwrite + old file delete.

Delete‑on‑close: initial pending delete, then final delete when last handle closes.

Multiple connected sessions (two CfConnectSyncRoot connections) doubling callbacks.

You’re logging both a CFAPI NOTIFY_FILE_DELETE and a separate filesystem watcher DELETE event as if both were CFAPI.

Log and compare CF_REQUEST_KEY, ConnectionKey, FileId/FileReferenceNumber. If they differ, treat them idempotently (tombstone once; ignore repeats). If you show a sample of the two parameter blobs I can pinpoint which pattern applies.
alan henry 0 Reputation points

2025-11-26T08:14:30.4633333+00:00

Hi, Nguyen, we found that deleting the pure placeholder file will skip the trash bin in MacOS's OneDrive. Can you give us some advice to show how to do it?

(It's the default that deleting the pure placeholder file will skip the trash bin in Windows, but not in macOS)
Danny Nguyen (WICLOUD CORPORATION) 5,065 Reputation points Microsoft External Staff Moderator

2025-11-26T08:49:12.64+00:00

Hi Alan, in your case, those items are managed by Apple's File Provider Framework. So the behavior might differ between macOS's and Windows's Explorer.
alan henry 0 Reputation points

2025-12-01T09:26:44.1433333+00:00

Hi Nguyen, I've found a peculiar case. The placeholder was automatically triggered Hydration by Windows Explorer.exe when I tried to DeHydrate some placeholder. At the end, the placeholder became status full, not unpinned. Is it expected? Or what should I do for this?

Share via

Cloud File API FAQ

1 additional answer

Your answer