CfUpdatePlaceholder 関数 (cfapi.h)
この API は、既存のプレースホルダーの特性を変更します。 この API の最も可能性の高い用途は、クラウドでファイルが変更され、同期プロバイダーがその変更の効果をプレースホルダーに組み込みたい場合です。 このシナリオをサポートするために、呼び出し元は、適用する新しいファイル システム メタデータ (タイムスタンプ、ファイル サイズなど) や新しい FileIdentity BLOB を渡すことができます。
構文
HRESULT CfUpdatePlaceholder(
[in] HANDLE FileHandle,
[in, optional] const CF_FS_METADATA *FsMetadata,
[in, optional] LPCVOID FileIdentity,
[in] DWORD FileIdentityLength,
[in, optional] const CF_FILE_RANGE *DehydrateRangeArray,
[in] DWORD DehydrateRangeCount,
[in] CF_UPDATE_FLAGS UpdateFlags,
[in, out, optional] USN *UpdateUsn,
[in, out, optional] LPOVERLAPPED Overlapped
);
パラメーター
[in] FileHandle
FileHandle は、メタデータが更新されるファイルまたはディレクトリへのハンドルです。 ファイルの場合、呼び出し元は、ファイルを同時に退避させる場合、またはデータ破損が発生する可能性がある場合に、ファイルに対する排他的ハンドルを取得する必要があります。 ユーザー アプリケーションへの影響を最小限に抑えるために、呼び出し元は、share-nothing ハンドルを使用するのではなく、適切な oplock を使用して ( CfOpenFileWithOplock 経由で) 排他性を取得することを強くお勧めします。
[in, optional] FsMetadata
FsMetadata には、すべてのタイムスタンプ、ファイル属性、ファイル サイズ (ディレクトリの場合は省略可能) など、更新するプレースホルダーに関するファイル システム メタデータが含まれています。 これフィールドは必須ではありません。 指定しない場合、これらのフィールドはすべて呼び出し後もそのまま残ります。
0タイムスタンプ フィールドの値 (CreationTime、LastAccessTime、LastWriteTime、ChangeTime) は、ファイルの現在のタイムスタンプに変更がないことを意味します。- FileAttributes の値は
0、ファイルの現在のファイル属性に変更がないことを意味します。 - FileSize には特別な値はありません。FileSize の値は
0、ファイル サイズを に0切り捨てます。
[in, optional] FileIdentity
FileIdentity は、呼び出し元によって提供される不透明なファイルまたはディレクトリ情報を含むユーザー モード バッファーです。 FileIdentity BLOB のサイズは 4 KB を超えないようにしてください。 FileIdentity は、すべてのコールバックで同期プロバイダーに返されます。 これは、更新が必要ない場合、または呼び出し元が更新するプレースホルダーから FileIdentity BLOB を削除する場合は省略可能です。
[in] FileIdentityLength
FileIdentity の長さ (バイト単位)。
[in, optional] DehydrateRangeArray
この配列は、更新後に有効と見なされなくなる既存のプレースホルダーの範囲を指定します。
このパラメーターの最も簡単な使用方法は、1 つの範囲を渡し、データのバイト範囲全体が無効になったことをプラットフォームに伝えることです。 このパラメーターのより複雑な使用方法は、無効と見なされる一連の不連続範囲を提供することです。 これは、同期プロバイダーがサブファイル レベルで変更を区別できることを意味します。 すべてのオフセットと長さは、[整列 ] PAGE_SIZE する必要があります。 プラットフォームでは、指定されたすべての範囲が更新プログラムの一部として退避されます。 任意の範囲の退避に失敗した場合、API は失敗し、ファイルの内容が破損します。
注意
Offset 0 と Length CF_EOF で 1 つの範囲を渡すと、ファイル全体が無効になります。これは、代わりにフラグ CF_UPDATE_FLAG_DEHYDRATE を渡すのと同じ効果があります。 また、 CF_UPDATE_FLAG_DEHYDRATE を渡すと 、DehydrateRangeArray が自動的に削除されます
[in] DehydrateRangeCount
プレースホルダー データの一連の個別の DehydrateRangeArray パーティションの数。
[in] UpdateFlags
プレースホルダーのフラグを更新します。 UpdateFlags は、次の値に設定できます。
| フラグ | 説明 |
|---|---|
| CF_UPDATE_FLAG_VERIFY_IN_SYNC | IN_SYNC属性がプレースホルダーに現在設定されていない場合、更新は失敗します。 これは、クラウドからローカル プレースホルダーへの変更の同期と、プレースホルダーのデータ ストリームがローカルに変更されるのを防ぐためです。 |
| CF_UPDATE_FLAG_MARK_IN_SYNC | プラットフォームでは、更新プレースホルダー操作が成功すると、プレースホルダーが同期中としてマークされます。 |
| CF_UPDATE_FLAG_DEHYDRATE | ファイルにのみ適用されます。 指定すると、プラットフォームはプレースホルダーを正常に更新した後にファイルを退避します。 このフラグを指定する場合、またはデータの破損が発生する可能性がある場合は、呼び出し元が排他的ハンドルを取得する必要があります。 プラットフォームでは、ハンドルの排他性は検証されないことに注意してください。 |
| CF_UPDATE_FLAG_ENABLE_ON_DEMAND_POPULATION | ディレクトリにのみ適用されます。 指定すると、更新されたプレースホルダー ディレクトリが部分的に設定され、そのディレクトリに今後アクセスすると、同期プロバイダーに FETCH_PLACEHOLDERS コールバックが送信されます。 |
| CF_UPDATE_FLAG_DISABLE_ON_DEMAND_POPULATION | ディレクトリにのみ適用されます。 指定すると、更新されたプレースホルダー ディレクトリが完全に設定され、そのディレクトリへの今後のアクセスが、同期プロバイダーへのコールバックなしでプラットフォームによって処理されるようにマークされます。 |
| CF_UPDATE_FLAG_REMOVE_FILE_IDENTITY | FileIdentity と FileIdentityLength は無視され、プラットフォームは更新呼び出しが成功するとプレースホルダーの既存のファイル ID BLOB を削除します。 |
| CF_UPDATE_FLAG_CLEAR_IN_SYNC | プラットフォームでは、更新プレースホルダー操作が正常に行われると、プレースホルダーが同期していないとマークされます。 |
| CF_UPDATE_FLAG_REMOVE_PROPERTY | プラットフォームは、プレースホルダーの既存の extrinsic プロパティをすべて削除します。 |
| CF_UPDATE_FLAG_PASSTHROUGH_FS_METADATA | プラットフォームは、フィルター処理を行わずに CF_FS_METADATA をファイル システムに渡します。それ以外の場合、プラットフォームは値が である 0フィールドの設定をスキップします。 |
| CF_UPDATE_FLAG_ALWAYS_FULL | プレースホルダー ファイルでのみ有効です。 指定すると、更新するプレースホルダーは常に完全としてマークされます。 ハイドレートされると、このようなプレースホルダー ファイルを退避しようとすると、エラー コード ERROR_CLOUD_FILE_DEHYDRATION_DISALLOWEDで失敗します。 |
| CF_UPDATE_FLAG_ALLOW_PARTIAL | プレースホルダー ファイルでのみ有効です。 指定すると、プレースホルダー ファイルの常に完全な状態 (存在する場合) がクリアされるため、再び退避できます。 このフラグを CF_UPDATE_FLAG_ALWAYS_FULL と共に指定することは無効であり、結果としてエラー コード ERROR_CLOUD_FILE_INVALID_REQUEST が返されます。 |
[in, out, optional] UpdateUsn
入力時に、 UpdateUsn は、ファイルに渡されたものと同じ USN 値が残っている場合にのみ、更新を実行するようにプラットフォームに指示します。 これは、 CF_UPDATE_FLAG_VERIFY_IN_SYNC と同様の目的を果たしますが、ローカル メタデータの変更も含まれます。 入力時に の USN 値 0 にポインターを渡すことは、ポインターを渡すのと NULL 同じです。
返された UpdateUsn は、更新 アクションが実行された後に最終的な USN 値を受け取ります。
[in, out, optional] Overlapped
指定し、非同期 の FileHandle と組み合わせると、 Overlapped を使用すると、プラットフォームは CfUpdatePlaceholder 呼び出しを非同期的に実行できます。 詳細については、「 解説 」を参照してください。
指定しない場合、プラットフォームは、ハンドルの作成方法に関係なく、API 呼び出しを同期的に実行します。
戻り値
この関数が成功すると、 が返されます S_OK。 そうでない場合は、HRESULT エラー コードを返します。
注釈
プレースホルダーを更新するには:
- 更新するプレースホルダーは、登録済みの同期ルート ツリーに含まれている必要があります。同期ルート ディレクトリ自体、または任意の子孫ディレクトリを指定できます。それ以外の場合、呼び出しは HRESULT(ERROR_CLOUD_FILE_NOT_UNDER_SYNC_ROOT) で失敗します。
- 脱水が要求された場合、同期ルートは 、CF_HYDRATION_POLICY_ALWAYS_FULLされていない有効なハイドレーション ポリシーに登録する必要があります。それ以外の場合、呼び出しは HRESULT(ERROR_CLOUD_FILE_NOT_SUPPORTED) で失敗します。
- 退避が要求された場合は、プレースホルダーをローカルに固定しないでください。または、 HRESULT(ERROR_CLOUD_FILE_PINNED) を使用して呼び出しが失敗します。
- 退避が要求された場合、プレースホルダーは同期している必要があります。または、 HRESULT(ERROR_CLOUD_FILE_NOT_IN_SYNC) で呼び出しが失敗します。
- 呼び出し元は、更新するプレースホルダーへの WRITE_DATA または WRITE_DAC アクセス権を持っている必要があります。 それ以外の場合、 操作は HRESULT(ERROR_CLOUD_FILE_ACCESS_DENIED) で失敗します。
非同期的に Overlapped を使用しているときに API から HRESULT_FROM_WIN32(ERROR_IO_PENDING) が返された場合、呼び出し元は GetOverlappedResult を使用して待機できます。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 10、バージョン 1709 [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows Server 2016 [デスクトップ アプリのみ] |
| 対象プラットフォーム | Windows |
| ヘッダー | cfapi.h |
| Library | CldApi.lib |
| [DLL] | CldApi.dll |