Export (0) Print
Expand All

Pin method of the Win32_OfflineFilesCache class

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

When a file is pinned, it is cached in the local Offline Files store. Unlike files that are automatically cached, pinned files are protected from automatic eviction when additional cache space is needed.

Syntax


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

Parameters

Paths [in]

Array of strings, each of which contains the qualified UNC path of a file or directory to be pinned.

Flags

Controls the behavior of the pin operation. May be one or more of the following flags.

Flag ValueMeaning
OfflineFilesPinControlFlagFill
0x00000001

Fills the item in addition to pinning it. This results in the item being fully cached as part of the pin operation. If this flag is not set, the item is only pinned and must wait to be filled by some other means of synchronization. Note that the Offline Files service periodically fills files in the background. If immediate offline availability is not necessary, it may be better (performance-wise) to not set this flag and let the service fill the file in the background.

OfflineFilesPinControlFlagPinLinkTargets
0x00000010

Normally, when a shell link (type LNK) is pinned, its target is not automatically pinned. When this flag is set, pinning a LNK file automatically pins its target if the target is a file. If the target is a directory, the target is never pinned automatically.

OfflineFilesPinControlFlagForUser
0x00000020

Pins 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 pinned 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

Pins 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 pinned by its Group Policy extension.

OfflineFilesPinControlFlagForAll
0x00000080

Pins the items for all users of the local machine. While the pinned state applies to all users, the ability to access a pinned file depends on the user's access rights to that file computed while online.

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 pin operation to avoid sharing violations in the event that an application wishes to open a file that is currently open for the pin operation. When that scenario occurs and this flag is set, the pin 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

If one or more of the paths provided refers to a directory or shared folder, this argument indicates whether all children (files and subdirectories) are to be pinned as well. If this parameter is TRUE, all children are pinned recursively. If this parameter is FALSE, only the directory itself is pinned, not its children. When the next synchronization operation occurs, all children are pinned recursively.

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]

ItemDescription

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 pin 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 a pin operation is canceled while in progress, files that have been pinned up to that point will remain pinned.

Requirements

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Namespace

\root\cimv2

MOF

OfflineFilesWmiProvider.mof

DLL

Cscobj.dll

See also

Win32_OfflineFilesCache

 

 

Show:
© 2014 Microsoft