CfSetPinState 函式 (cfapi.h)

這會設定佔位元的釘選狀態，用來代表使用者的意圖。 任何應用程式 (不只是同步提供者) 可以呼叫此函式。

語法

HRESULT CfSetPinState(
  [in]                HANDLE           FileHandle,
  [in]                CF_PIN_STATE     PinState,
  [in]                CF_SET_PIN_FLAGS PinFlags,
  [in, out, optional] LPOVERLAPPED     Overlapped
);

參數

[in] FileHandle

佔位元檔案的句柄。 平臺會正確同步處理作業與其他作用中要求。 屬性或無存取句柄已足夠。 呼叫端必須具有佔位符 的READ_DATA 或 WRITE_DAC 存取權，否則作業將會因為 STATUS_CLOUD_FILE_ACCESS_DENIED而失敗。

[in] PinState

佔位元檔案的釘選狀態。 如需有效的 PinState 值清單，請參閱 CF_PIN_STATE。

[in] PinFlags

釘選狀態旗標。 PinFlags 可以設定為下列值：

• 如果指定 了CF_PIN_FLAG_RECURSE ，平臺會將釘選狀態套用至 FileHandle ，而且每個檔案會以遞歸方式套用到它下方， (只有在 FileHandle 是目錄) 的句柄時才相關。
• 如果指定 CF_PIN_FLAG_RECURSE_ONLY ，平臺會將釘選狀態以遞歸方式套用至 FileHandle 下方的每個檔案，但不會套用至 FileHandle 本身。
• 如果指定 了CF_PIN_FLAG_RECURSE_STOP_ERROR ，平臺會在遇到第一個錯誤時停止遞歸。 否則，平臺會略過錯誤並繼續遞歸。

[in, out, optional] Overlapped

允許以異步方式執行呼叫。 如需詳細資訊 ，請參閱 一節。

傳回值

如果函式成功，則會傳 S_OK回 。 否則，它會傳回 HRESULT 錯誤碼。

備註

當指定並結合異步 FileHandle 時， 重疊 可讓平臺以異步方式執行呼叫。

呼叫端必須已初始化重疊的結構，並包含要等候的事件。 如果這會傳回 HRESULT_FROM_WIN32 (ERROR_IO_PENDING) ，則呼叫端可以使用 GetOverlappedResult 等候。 如果未指定，不論句柄的建立方式為何，平臺都會同步執行 API 呼叫。

規格需求

另請參閱

GetOverlappedResult

CF_PIN_STATE

CF_SET_PIN_FLAGS