CF_OPERATION_PARAMETERS 結構 (cfapi.h)

發行項
02/23/2024

佔位元檔案或資料夾上作業的詳細參數。此結構中提供的數據是作業 CF_OPERATION_TYPE 特有的。

語法

typedef struct CF_OPERATION_PARAMETERS {
  ULONG ParamSize;
  union {
    struct {
      CF_OPERATION_TRANSFER_DATA_FLAGS Flags;
      NTSTATUS                         CompletionStatus;
      LPCVOID                          Buffer;
      LARGE_INTEGER                    Offset;
      LARGE_INTEGER                    Length;
    } TransferData;
    struct {
      CF_OPERATION_RETRIEVE_DATA_FLAGS Flags;
      LPVOID                           Buffer;
      LARGE_INTEGER                    Offset;
      LARGE_INTEGER                    Length;
      LARGE_INTEGER                    ReturnedLength;
    } RetrieveData;
    struct {
      CF_OPERATION_ACK_DATA_FLAGS Flags;
      NTSTATUS                    CompletionStatus;
      LARGE_INTEGER               Offset;
      LARGE_INTEGER               Length;
    } AckData;
    struct {
      CF_OPERATION_RESTART_HYDRATION_FLAGS Flags;
      const CF_FS_METADATA                 *FsMetadata;
      LPCVOID                              FileIdentity;
      DWORD                                FileIdentityLength;
    } RestartHydration;
    struct {
      CF_OPERATION_TRANSFER_PLACEHOLDERS_FLAGS Flags;
      NTSTATUS                                 CompletionStatus;
      LARGE_INTEGER                            PlaceholderTotalCount;
      CF_PLACEHOLDER_CREATE_INFO               *PlaceholderArray;
      DWORD                                    PlaceholderCount;
      DWORD                                    EntriesProcessed;
    } TransferPlaceholders;
    struct {
      CF_OPERATION_ACK_DEHYDRATE_FLAGS Flags;
      NTSTATUS                         CompletionStatus;
      LPCVOID                          FileIdentity;
      DWORD                            FileIdentityLength;
    } AckDehydrate;
    struct {
      CF_OPERATION_ACK_RENAME_FLAGS Flags;
      NTSTATUS                      CompletionStatus;
    } AckRename;
    struct {
      CF_OPERATION_ACK_DELETE_FLAGS Flags;
      NTSTATUS                      CompletionStatus;
    } AckDelete;
  } DUMMYUNIONNAME;
} CF_OPERATION_PARAMETERS;

成員

ParamSize

DUMMYUNIONNAME

DUMMYUNIONNAME.TransferData

同步提供者會執行 TRANSFER_DATA 來凍結佔位符檔案。此作業可以做為 回應FETCH_DATA 回呼、 VALIDATE_DATA 回呼，或作為任何回呼內容外部預先佔式背景凍結工作的一部分來執行。

此 API 僅適用於支援小於 ALWAYS_FULL凍結原則的同步提供者。否則，作業將會失敗，並 ERROR_CLOUD_FILE_INVALID_REQUEST。

同步提供者必須有 WRITE_DATA 或 WRITE_DAC 存取要執行 TRANSFER_DATA 作業的檔案。否則作業將會失敗 ，並ERROR_CLOUD_FILE_ACCESS_DENIED。

若要執行這項作業：

OpInfo.Type 必須設定為 CF_OPERATION_TYPE_TRANSFER_DATA。
OpParams.ParamSize 必須設定為 OpParams.TransferData 的確切大小加上 OpParams.TransferData 的位移。
OpParams.TransferData.Flags 必須設定為 CF_OPERATION_TRANSFER_DATA_FLAG_NONE。
如果同步提供者想要將數據傳送至佔位符檔案，則 OpParams.TransferData.CompletionStatus 必須設定為STATUS_SUCCESS。如果同步提供者因任何原因而無法處理凍結要求，且不想重新啟動凍結，則必須在 CompletionStatus 中設定STATUS_CLOUD_FILE_* 狀態。除了STATUS_SUCCESS以外，任何傳回STATUS_CLOUD_FILE_* 範圍以外的狀態代碼，都會由平臺轉換成STATUS_CLOUD_FILE_UNSUCCESSFUL。
OpParams.TransferData.Buffer 如果 OpParams.TransferData.CompletionStatus為STATUS_SUCCESS ，且至少應為 OpParams.TransferData.Length 字節，則必須指向有效的使用者模式緩衝區;否則會忽略緩衝區欄位。
OpParams.TransferData.Offset 和 OpParams.TransferData.Length 描述同步提供者正在傳輸數據的佔位符範圍。同步提供者不需要依照單次要求傳回所有數據。同步提供者也可以傳回比要求更多的數據。例如，基於效能或其他原因，同步提供者可以決定過度讀取。同步提供者也可以重複執行多個 TRANSFER_DATA 作業，以回應相同的 FETCH_DATA 回呼。唯一的需求是，除非所描述的範圍以邏輯檔案大小結尾 (EoF) 對齊 4KB，否則長度不需要對齊 4KB，只要產生的範圍結束於邏輯檔案大小或超過邏輯檔案大小即可。

工作完成時：

如果同步提供者未在同步根註冊時間指定 VALIDATION_REQUIRED 。

在成功的傳輸案例中，任何擱置的使用者 IO 都會要求收到所有必要位元組的佔位符檔案，因為傳輸將會完成;否則，將會更新不完整的使用者 IO 要求，以反映最新的凍結狀態。在失敗的傳輸案例中，佔位符檔案上任何與範圍重疊的暫止使用者 IO 要求，都會因為 OpParams.TransferData.CompletionStatus 而失敗。

如果同步提供者在同步根註冊時間指定 VALIDATION_REQUIRED ，則平臺不會再執行任何處理，直到同步提供者透過 ACK_DATA 作業以正面方式認可範圍中的數據為止。

DUMMYUNIONNAME.TransferData.Flags

用於傳輸數據的旗標。這必須設定為 CF_OPERATION_TRANSFER_DATA_FLAG_NONE。如需詳細資訊，請參閱CF_OPERATION_TRANSFER_DATA_FLAGS 。

DUMMYUNIONNAME.TransferData.CompletionStatus

傳輸數據的狀態。如果同步提供者想要將數據傳送至佔位符檔案，則必須將此設定為 STATUS_SUCCESS 。如果同步提供者因任何原因而無法處理凍結要求，且不想重新啟動凍結，則必須在 CompletionStatus 中設定STATUS_CLOUD_FILE_* 狀態。除了STATUS_SUCCESS以外，任何傳回STATUS_CLOUD_FILE_* 範圍以外的狀態代碼，都會由平臺轉換成STATUS_CLOUD_FILE_UNSUCCESSFUL。

DUMMYUNIONNAME.TransferData.Buffer

有效的使用者模式緩衝區。如果 CompletionStatus是STATUS_SUCCESS 且至少必須是 Length 位元組，這必須指向有效的使用者模式緩衝區。否則，會忽略緩衝區欄位。

DUMMYUNIONNAME.TransferData.Offset

與 Length 搭配使用的位移，用來描述傳輸數據的佔位元元範圍。它會描述同步提供者正在傳送數據的佔位元範圍。同步提供者不需要依照單次要求傳回所有數據。同步提供者也可以傳回比要求更多的數據。例如，基於效能或其他原因，同步提供者可以決定過度讀取。同步提供者也可以重複執行多個 TRANSFER_DATA 作業，以回應相同的 FETCH_DATA 回呼。位移必須對齊 4KB。

DUMMYUNIONNAME.TransferData.Length

緩衝區的位元組長度。長度必須對齊 4KB，除非所述的範圍以邏輯檔案大小結尾 (EoF) ，在此情況下，只要產生的範圍結束於邏輯檔案大小或超過邏輯檔案大小，則長度不需要對齊 4KB。即使 CompletionStatus 不是 STATUS_SUCCESS，此字段也應該設定為有效的值。

DUMMYUNIONNAME.RetrieveData

同步提供者會在佔位元元凍結過程中執行 RETRIEVE_DATA 作業，以驗證先前傳輸至佔位符的數據完整性。此作業可以做為 回應FETCH_DATA 回呼、 VALIDATE_DATA 回呼，或作為任何回呼內容外部預先佔式背景凍結工作的一部分來執行。

此 API 僅適用於支援小於 ALWAYS_FULL凍結原則的同步提供者。否則，作業將會因為 STATUS_CLOUD_FILE_NOT_SUPPORTED而失敗。

同步提供者必須在同步根註冊時間指定凍結原則修飾詞 VALIDATE_REQUIRED ，才能執行這項作業。否則，作業將會因為 STATUS_CLOUD_FILE_NOT_SUPPORTED而失敗。

同步提供者必須有 READ_DATA 或 WRITE_DAC 存取要執行 RETRIEVE_DATA 作業的檔案。否則，作業將會因為 STATUS_CLOUD_FILE_ACCESS_DENIED而失敗。

若要執行這項作業：

OpInfo.Type 必須設定為 CF_OPERATION_TYPE_RETRIEVE_DATA。
OpParams.ParamSize 必須設定為 OpParams.RetrieveData 的確切大小加上 OpParams.RetrieveData 的位移。
OpParams.RetrieveData.Flags 必須設定為 CF_OPERATION_RETRIEVE_DATA_FLAG_NONE。
OpParams.RetrieveData.Buffer 必須指向有效的使用者模式緩衝區，且至少為 OpParams.RetrieveData.Length 位元組。作業成功完成時，它會透過 TRANSFER_DATA接收先前傳輸至佔位符的數據。
OpParams.RetrieveData.Offset 和 OpParams.RetrieveData.Length 描述同步提供者正在擷取數據的佔位符範圍。要求的範圍必須在RETRIEVE_DATA作業之前，由TRANSFER_DATA作業完全凍結，否則作業將會因為STATUS_CLOUD_FILE_INVALID_REQUEST而失敗。位移和長度都是 4KB 對齊，除非所述的範圍以邏輯檔案大小結尾 (EoF) ，在此情況下，長度不需要對齊 4KB，只要長度結束或超過邏輯檔案大小即可。
OpParams.RetrieveData.ReturnedLength 會接收成功完成作業時所擷取的實際位元組數目。

DUMMYUNIONNAME.RetrieveData.Flags

擷取數據的旗標。這必須設定為 CF_OPERATION_RETRIEVE_DATA_FLAG_NONE。如需詳細資訊，請參閱CF_OPERATION_RETRIEVE_DATA_FLAGS 。

DUMMYUNIONNAME.RetrieveData.Buffer

這必須指向有效的使用者模式緩衝區，且至少為 Length 位元組。作業成功完成時，它會透過 TRANSFER_DATA接收先前傳輸至佔位符的數據。

DUMMYUNIONNAME.RetrieveData.Offset

與 Length 搭配使用的位移，描述從佔位元符擷取的數據範圍。它會描述同步提供者正在擷取數據的佔位元範圍。要求的範圍必須在RETRIEVE_DATA作業之前，由TRANSFER_DATA作業完全凍結，否則作業將會因為STATUS_CLOUD_FILE_INVALID_REQUEST而失敗。位移必須對齊 4KB。

DUMMYUNIONNAME.RetrieveData.Length

緩衝區的位元組長度。除非所述的範圍以邏輯檔案大小結尾 (EoF) ，否則長度不一定是 4KB 對齊，只要其結束於邏輯檔案大小或超過邏輯檔案大小，則長度就不需要對齊 4KB。

DUMMYUNIONNAME.RetrieveData.ReturnedLength

成功完成作業時擷取的位元組數目。

DUMMYUNIONNAME.AckData

同步提供者會在驗證先前傳輸至平台的數據完整性之後，在佔位元元凍結過程中執行 ACK_DATA 作業。此作業可以做為 回應FETCH_DATA 回呼、 VALIDATE_DATA 回呼，或作為任何回呼內容外部預先佔式背景凍結工作的一部分來執行。

此 API 僅適用於支援小於 ALWAYS_FULL凍結原則的同步提供者。否則，作業將會因為 STATUS_CLOUD_FILE_NOT_SUPPORTED而失敗。

同步提供者必須在同步根註冊時間指定凍結原則修飾詞 VALIDATE_REQUIRED ，才能執行這項作業。否則，作業將會因為 STATUS_CLOUD_FILE_NOT_SUPPORTED而失敗。

同步提供者必須有 READ_DATA 或 WRITE_DAC 存取要執行 ACK_DATA 作業的檔案。否則，作業將會因為 STATUS_CLOUD_FILE_ACCESS_DENIED而失敗。

若要執行這項作業：

OpInfo.Type 必須設定為 CF_OPERATION_TYPE_ACK_DATA。
OpParams.ParamSize 必須設定為 OpParams.AckData 的確切大小加上 OpParams.AckData 的 Offset。
OpParams.AckData.Flags 必須設定為 CF_OPERATION_ACK_DATA_FLAG_NONE。
如果同步提供者驗證要認可範圍內的數據，則必須將OpParams.AckData.CompletionStatus 設定為STATUS_SUCCESS。如果同步提供者因為任何原因而無法驗證數據，而且不想重新啟動凍結，則必須在 CompletionStatus 中設定STATUS_CLOUD_FILE_* 狀態。除了STATUS_SUCCESS以外，任何傳回STATUS_CLOUD_FILE_* 範圍以外的狀態代碼，都會由平臺轉換成STATUS_CLOUD_FILE_UNSUCCESSFUL。
OpParams.AckData.Offset 和 OpParams.AckData.Length 描述佔位符中的範圍，其數據將由同步提供者認可。在作業之前，要求的範圍不需要由 TRANSFER_DATA 作業完全凍結。位移和長度都是 4KB 對齊，除非所述的範圍以邏輯檔案大小結束， (EoF) ，在此情況下，長度不需要對齊 4KB，只要其結束於邏輯檔案大小或超過邏輯檔案大小。
的長度-1，表示為CF_EOF，表示無限大 (也就是檔案) 結尾。

成功 ACK_DATA 作業時，佔位符檔案上收到所有必要位元組的任何擱置中使用者 IO 要求都會完成 ACK_DATA 作業;否則，將會更新不完整的使用者 IO 要求，以反映最新的凍結狀態。在失敗 的ACK_DATA 案例中，佔位符檔案上與範圍重疊的任何擱置中使用者 IO 要求，都會 因為 CompletionStatus 而失敗。

DUMMYUNIONNAME.AckData.Flags

通知數據的旗標。這必須設定為 CF_OPERATION_ACK_DATA_FLAG_NONE。如需詳細資訊，請參閱CF_OPERATION_ACK_DATA_FLAGS 。

DUMMYUNIONNAME.AckData.CompletionStatus

數據通知的完成狀態。如果同步提供者驗證要認可範圍內的數據是好的，則必須將此設定為 STATUS_SUCCESS 。如果同步提供者因為任何原因而無法驗證數據，而且不想重新啟動凍結，則必須在 CompletionStatus 中設定STATUS_CLOUD_FILE_* 狀態。除了STATUS_SUCCESS以外，任何傳回STATUS_CLOUD_FILE_* 範圍以外的狀態代碼，都會由平臺轉換成STATUS_CLOUD_FILE_UNSUCCESSFUL。

DUMMYUNIONNAME.AckData.Offset

要認可之佔位元數據的位元組位移。 Offset 描述佔位元中的範圍，其數據將由同步提供者認可。在作業之前，要求的範圍不需要由 TRANSFER_DATA 作業完全凍結。位移必須對齊 4KB。

DUMMYUNIONNAME.AckData.Length

要認可之佔位元中的數據位元組長度。除非所述的範圍以邏輯檔案大小結尾 (EoF) 對齊 4KB，在此情況下，只要長度以邏輯檔案大小結束或超過邏輯檔案大小，則長度不一定要對齊 4KB。的長度-1，表示為CF_EOF，表示無限大 (也就是檔案) 結尾。

DUMMYUNIONNAME.RestartHydration

同步提供者會執行 RESTART_HYDRATION 作業，以重新啟動進行中的凍結。此作業可以做為 回應FETCH_DATA 回呼、 VALIDATE_DATA 回呼，或作為任何回呼內容外部預先佔式背景凍結工作的一部分來執行。

此 API 僅適用於支援完整凍結原則的同步提供者。否則，作業將會因為 STATUS_CLOUD_FILE_NOT_SUPPORTED而失敗。

同步提供者必須有 WRITE_DATA 或 WRITE_DAC 存取要執行 RESTART_HYDRATION 作業的檔案。否則，作業將會失敗 ，並STATUS_CLOUD_FILE_ACCESS_DENIED。

若要執行這項作業：

OpInfo.Type 必須設定為 CF_OPERATION_TYPE_RESTART_HYDRATION。
OpParams.ParamSize 必須設定為 OpParams.RestartHydration 的確切大小加上 OpParams.RestartHydration 的 Offset。
OpParams.RestartHydration.Flags 必須設定為 CF_OPERATION_RESTART_HYDRATION_FLAG_NONE 或 CF_OPERATION_RESTART_HYDRATION_FLAG_MARK_IN_SYNC。
- 如果指定 CF_OPERATION_RESTART_HYDRATION_FLAG_MARK_IN_SYNC ，佔位元會在成功 RESTART_HYDRATION 作業時標示為同步處理。
OpParams.RestartHydration.FsMetadata 是選擇性的。提供時：
- 0時間戳欄位中的值 (CreationTime、LastAccessTime、LastWriteTime 和 ChangeTime) 表示檔案上目前的時間戳沒有任何變更。
- 0FileAttributes 中的值表示檔案上目前的檔案屬性沒有任何變更。
- FileSize 中沒有特殊值。 0FileSize 中的值會將檔案大小截斷為 0。
OpParams.RestartHydration.FileIdentity 和 OpParams.RestartHydration.FileIdentityLength 是選擇性的。提供時，新的身分識別將會保存在檔案上。否則，目前的檔案身分識別會維持不變。

當同步提供者判斷佔位元中的磁碟數據實際上無效，且不適合滿足 I/O 要求時，同步提供者會呼叫此 API。典型的案例是，基於某些原因擷取的數據失敗了總和檢查碼驗證。另一個使用案例是在凍結過程中，檔案內容實際上已在雲端中更新 (，而且同步提供者無法從對應至本機佔位元元版本的雲端擷取歷程記錄內容) 。

成功重新啟動時，如果有任何，佔位元將會完全解除凍結並更新為新的元數據。如果有任何擱置的使用者 IO 要求，將會重新處理，就像他們剛到達一樣，因此同步提供者會收到與先前同步提供者收到的回呼完全相同的新回呼。

不過，如果因為任何原因而重新啟動失敗，則佔位元可能會因為發生錯誤的位置而留下不具決定性的狀態，而且佔位元上所有擱置的使用者 IO 要求都會失敗，並出現相同的錯誤。在此案例中，平台保證的唯一事項是未來的使用者存取佔位符檔案會觸發相同的回呼。

DUMMYUNIONNAME.RestartHydration.Flags

重新啟動佔位元凍結的旗標。這必須設定為 CF_OPERATION_RESTART_HYDRATION_FLAG_NONE 或 CF_OPERATION_RESTART_HYDRATION_FLAG_MARK_IN_SYNC。如果指定 CF_OPERATION_RESTART_HYDRATION_FLAG_MARK_IN_SYNC ，佔位元會在成功 RESTART_HYDRATION 作業時標示為同步處理。如需詳細資訊，請參閱CF_OPERATION_RESTART_HYDRATION_FLAGS 。

DUMMYUNIONNAME.RestartHydration.FsMetadata

選擇性。包含檔案元數據的更新。指定時：

0時間戳欄位中的值 (CreationTime、LastAccessTime、LastWriteTime 和 ChangeTime) 表示檔案上目前的時間戳沒有任何變更。
0FileAttributes 中的值表示檔案上目前檔案屬性沒有任何變更。
FileSize 中沒有特殊值。 0FileSize 中的值會將檔案大小截斷為 0。

DUMMYUNIONNAME.RestartHydration.FileIdentity

選擇性。提供時，檔案身分識別會更新為此值。否則，它會維持不變。

DUMMYUNIONNAME.RestartHydration.FileIdentityLength

選擇性。這會指定 FileIdentity 的長度。

DUMMYUNIONNAME.TransferPlaceholders

DUMMYUNIONNAME.TransferPlaceholders.Flags

用於傳輸佔位元的旗標。如需詳細資訊，請參閱CF_OPERATION_TRANSFER_PLACEHOLDERS_FLAGS 。

DUMMYUNIONNAME.TransferPlaceholders.CompletionStatus

傳輸佔位元元作業的完成狀態。

DUMMYUNIONNAME.TransferPlaceholders.PlaceholderTotalCount

佔位元總數。

DUMMYUNIONNAME.TransferPlaceholders.PlaceholderArray

要傳送的佔位元元陣列。

DUMMYUNIONNAME.TransferPlaceholders.PlaceholderCount

正在傳輸的佔位元元數目。

DUMMYUNIONNAME.TransferPlaceholders.EntriesProcessed

已處理的佔位元元專案。

DUMMYUNIONNAME.AckDehydrate

DUMMYUNIONNAME.AckDehydrate.Flags

已解除凍結的數據通知旗標。如需詳細資訊，請參閱CF_OPERATION_ACK_DEHYDRATE_FLAGS 。

DUMMYUNIONNAME.AckDehydrate.CompletionStatus

認可解除凍結作業的完成狀態。如果同步提供者能夠允許解除凍結繼續，則必須將此設定為 STATUS_SUCCESS 。如果同步提供者因為任何原因而想要禁止解除凍結，則必須在 CompletionStatus 中設定STATUS_CLOUD_FILE_* 狀態。除了STATUS_SUCCESS以外，任何傳回STATUS_CLOUD_FILE_* 範圍以外的狀態代碼，都會由平臺轉換成STATUS_CLOUD_FILE_UNSUCCESSFUL。

DUMMYUNIONNAME.AckDehydrate.FileIdentity

要確認已解除凍結數據的佔位符檔案檔案身分識別。

DUMMYUNIONNAME.AckDehydrate.FileIdentityLength

FileIdentity 的長度，以位元組為單位。

DUMMYUNIONNAME.AckRename

DUMMYUNIONNAME.AckRename.Flags

確認重新命名佔位符旗標。如需詳細資訊，請參閱CF_OPERATION_ACK_RENAME_FLAGS 。

DUMMYUNIONNAME.AckRename.CompletionStatus

認可重新命名作業的完成狀態。如果同步提供者能夠允許重新命名作業繼續，則必須將此設定為 STATUS_SUCCESS 。如果同步提供者因為任何原因而想要不允許重新命名，則必須在 CompletionStatus 中設定STATUS_CLOUD_FILE_* 狀態。除了STATUS_SUCCESS以外，任何傳回STATUS_CLOUD_FILE_* 範圍以外的狀態代碼，都會由平臺轉換成STATUS_CLOUD_FILE_UNSUCCESSFUL。

DUMMYUNIONNAME.AckDelete

DUMMYUNIONNAME.AckDelete.Flags

認可刪除旗標。如需詳細資訊，請參閱CF_OPERATION_ACK_DELETE_FLAGS 。

DUMMYUNIONNAME.AckDelete.CompletionStatus

認可刪除作業的完成狀態。如果同步提供者能夠允許刪除作業繼續，則必須將此設定為 STATUS_SUCCESS 。如果同步提供者因為任何原因而想要不允許刪除，則必須在 CompletionStatus 中設定STATUS_CLOUD_FILE_* 狀態。除了STATUS_SUCCESS以外，任何傳回STATUS_CLOUD_FILE_* 範圍以外的狀態代碼，都會由平臺轉換成STATUS_CLOUD_FILE_UNSUCCESSFUL。

規格需求

需求	值
最低支援的用戶端	Windows 10 版本 1709 [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2016 [僅限傳統型應用程式]
標頭	cfapi.h

另請參閱

CfExecute

CF_OPERATION_TRANSFER_DATA_FLAGS

CF_OPERATION_RETRIEVE_DATA_FLAGS

共用方式為

CF_OPERATION_PARAMETERS 結構 (cfapi.h)

語法

成員

規格需求

另請參閱

意見反應

其他資源