Programmatically set a file as a "Placeholder" (Cloud Icon) using Windows Cloud Files API or Nextcloud Desktop

đź’» Development
,
1

I’m using Nextcloud Desktop (Windows version) with the Virtual Files feature enabled. I’m working on a Python script to interact with Nextcloud Desktop (Windows version) and manage the state of synchronized files. Specifically, I want to programmatically set files as “Make always available locally” (Pinned Full File) or “Free up local space” (Placeholder/Cloud Icon).

I’ve successfully implemented the functionality to mark files as “Make always available locally” using the SetFileAttributesW function with the FILE_ATTRIBUTE_PINNED attribute. However, I’m struggling to set files as “Free up local space” (Placeholder/Cloud Icon). The FILE_ATTRIBUTE_RECALL_ON_DATA_ACCESS attribute doesn’t seem to work as I expected.

Here’s the Python code I’m using to manage file states:

import os
import ctypes
from ctypes import wintypes

# Windows API Constants
FILE_ATTRIBUTE_PINNED = 0x00080000
FILE_ATTRIBUTE_RECALL_ON_DATA_ACCESS = 0x00040000

# Windows API Functions
kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)

# Define argument and return types for SetFileAttributesW
SetFileAttributesW = kernel32.SetFileAttributesW
SetFileAttributesW.argtypes = [wintypes.LPCWSTR, wintypes.DWORD]
SetFileAttributesW.restype = wintypes.BOOL

def set_file_state(path, pin=True):
    """
    Set the state of a file using the Windows Cloud Files API.
    :param path: Path to the file or folder.
    :param pin: True to mark as "Always available locally", False to free up space.
    """
    try:
        # Set the file attribute
        if pin:
            print(f"Marking file '{path}' as 'Always available locally'...")
            success = SetFileAttributesW(path, FILE_ATTRIBUTE_PINNED)
        else:
            print(f"Freeing up local space for file '{path}'...")
            success = SetFileAttributesW(path, FILE_ATTRIBUTE_RECALL_ON_DATA_ACCESS)

        # Check if the operation was successful
        if not success:
            raise ctypes.WinError(ctypes.get_last_error())

        print("Operation completed successfully!")
    except Exception as e:
        print(f"Error setting file state: {e}")

# Test file path
file_path = r"C:\Users\Thiago\Desktop\encana_nextcloud\Shared\0000testagem\teste\textnext\testfile.txt"

# Test marking as "Always available locally"
# set_file_state(file_path, pin=True)

# Test freeing up local space
set_file_state(file_path, pin=False)

The FILE_ATTRIBUTE_PINNED attribute works correctly, marking the file as “Make Always available locally” (Pinned Full File, green circle with the white check mark).
image

However, the FILE_ATTRIBUTE_RECALL_ON_DATA_ACCESS attribute does not transform the file into a Placeholder (Cloud Icon). Instead, the file remains as a Full File, availe locally (Green Tick Icon), just unpinning the file.
image

I need a way to programmatically set a file as a Placeholder (Cloud Icon), using either The Windows Cloud Files API or maybe trying to interact with the Nextcloud Desktop application.

I’ve read about the Cloud Filter API, but it seems much more complex to develop for the small scope I have.

Any ideia what could I do?
Are there any alternative approaches to achieve this functionality?

Any help or guidance would be greatly appreciated! Thank you in advance