Unpin method of the Win32_OfflineFilesCache class

Article
05/31/2018

Unpins files, directories, and network shared folders from the Offline Files cache. Pinning is called "Always Available Offline" in the Windows user interface.

When a file is unpinned, it is no longer guaranteed to be available offline. If the unpin operation removes all instances of pin information in that it is not pinned by Folder Redirection, Group Policy, or by the user and that item has no unsynchronized offline changes, it may be automatically removed from the cache at any time.

Syntax

uint32 Unpin(
  [in] string  Paths[],
  [in] uint32  Flags,
  [in] boolean Deep
);

Parameters

Paths [in]: Array of strings, each of which contains the qualified UNC path of a file or directory to be unpinned.
Flags [in]: Controls behavior of the unpin operation. May be one or more of the following flags.
OfflineFilesPinControlFlagForUser (0x00000020): Unpins the items for the calling user. This is the flag typically set for a caller of this function. It is important to note that Offline Files does not support a true per-user notion of pinning. When an item is unpinned for a user, it is pinned for all users of that machine. An item that is pinned with this flag can be unpinned by any user who has access to that file. The ability to access that pinned file depends on the user's access rights to that file computed while online.
OfflineFilesPinControlFlagForUser_Policy (0x00000040): Unpins the items for per-user policy. This differs from the OfflineFilesPinControlFlagForUser flag in that this flag cannot be modified by the user through the Offline Files user interface. Internally, Offline Files sets this flag when items are unpinned by its Group Policy extension.
OfflineFilesPinControlFlagForAll (0x00000080): Unpins the items for all users of the local machine.
OfflineFilesPinControlFlagLowPriority (0x00000200): Reserved for future use.
OfflineFilesPinControlFlagAsyncProgress (0x00000400): Progress is reported to the progress interface asynchronously with respect to the actual operations. If this flag is not set, progress is reported synchronously with each operation.
OfflineFilesPinControlFlagInteractive (0x00000800): Set this flag if the operation is allowed to display user interface elements as necessary. An example is the system's credential-request dialog.
OfflineFilesPinControlFlagConsole (0x00001000): This flag is ignored if the OfflineFilesPinControlFlagInteractive flag is not set. If the OfflineFilesPinControlFlagInteractive flag is set, this flag indicates that any UI produced should be directed to the console window associated with the process invoking the operation.
OfflineFilesPinControlFlagBackground (0x00010000): Set this flag if you want the unpin operation to avoid sharing violations in the event that an application wishes to open a file that is currently open for the unpin operation. When that scenario occurs and this flag is set, the unpin operation will "back off" and not finish for that particular file at that time. This flag is primarily used by the Offline Files service for internal operations.

Deep [in]

If one or more of the paths provided refers to a directory or shared folder, this argument indicates whether all subdirectories are to be unpinned as well. If this parameter is TRUE, all subdirectories are unpinned recursively. If this parameter is FALSE, only files that are immediate children of the directory are unpinned.

Return value

This method returns either a WMI return code or a system error code.

Remarks

To monitor progress, implement a WMI event sink to receive SWbem.OnProgress event notifications. The strMessage parameter contains a text string that is encoded with the following colon-delimited format:

Reason:Result:ResultText:[Path]

Reason

Specifies the type of progress notification as one of the following values:

0: Begin; sent once at the start of the operation.

1: End; sent once at the end of the operation.

2: ItemBegin; sent at the start of processing each item.

3: ItemResult. Sent at the end of processing each item.

Result

Specifies an HRESULT value. If the unpin operation succeeds, this value is zero.

ResultText

Specifies a Windows message text string to be associated with the Result value.

Path

A string containing the UNC path of the item. This is an empty string if Reason is zero (Begin) or 1 (End).

If an unpin operation is canceled while in progress, files that have been unpinned up to that point will remain unpinned.

Requirements


Minimum supported client	Windows Vista
Minimum supported server	Windows Server 2008
Namespace	Root\CIMv2
Header	Cscobj.h
MOF	OfflineFilesWmiProvider.mof
DLL	CscObj.dll

Share via