Cloud File API FAQ

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