CfConvertToPlaceholder 関数 (cfapi.h)
同期ルート ディレクトリ ツリーの下にある既存のプレースホルダー以外のファイルまたはディレクトリをプレースホルダーに変換します。 これは、たとえば、新しいローカル ファイルまたはディレクトリがクライアントに表示され、同期プロバイダーがクラウドへの同期を完了した後などに便利です。 ファイル システム メタデータ (タイムスタンプ、ファイル サイズなど) を渡すためのパラメーターがないことに注意してください。これらはローカル ファイルから逐語的に取得されます。
構文
HRESULT CfConvertToPlaceholder(
[in] HANDLE FileHandle,
[in, optional] LPCVOID FileIdentity,
[in] DWORD FileIdentityLength,
[in] CF_CONVERT_FLAGS ConvertFlags,
[out, optional] USN *ConvertUsn,
[in, out, optional] LPOVERLAPPED Overlapped
);
パラメーター
[in] FileHandle
変換するファイルまたはディレクトリを処理します。
[in, optional] FileIdentity
呼び出し元によって提供される不透明なファイルまたはディレクトリ情報を含むユーザー モード バッファー。 呼び出し元が同時にファイルを退避しない場合、または呼び出し元がディレクトリを変換している場合は省略可能です。 FileIdentity は、すべてのコールバックで同期プロバイダーに返されます。 サイズが 4 KB を超えることはできません。
[in] FileIdentityLength
FileIdentity の長さ (バイト単位)。
[in] ConvertFlags
プレースホルダー変換フラグ。 ConvertFlags は、次の値に設定できます。
| フラグ | 説明 |
|---|---|
| CF_CONVERT_FLAG_MARK_IN_SYNC | これが指定されている場合、プラットフォームは、ファイルの変換が成功したときに、変換されたプレースホルダーをクラウドと同期しているとしてマークします。 |
| CF_CONVERT_FLAG_DEHYDRATE | これはファイルにのみ適用されます。 指定すると、プラットフォームはファイルをプレースホルダーに変換した後、ファイルを正常に退避します。 このフラグを指定する場合、またはデータの破損が発生する可能性がある場合は、呼び出し元が排他的ハンドルを取得する必要があります。 プラットフォームでは、ハンドルの排他性は検証されないことに注意してください。 |
| CF_CONVERT_FLAG_ENABLE_ON_DEMAND_POPULATION | これはディレクトリにのみ適用されます。 指定すると、変換されたプレースホルダー ディレクトリに部分的に設定されたマークが付けられます。これにより、後でアクセスすると、同期プロバイダーに FETCH_PLACEHOLDERS コールバックが送信されます。 |
| CF_CONVERT_FLAG_ALWAYS_FULL | これはプレースホルダー ファイルでのみ有効です。 このフラグを持つプレースホルダーにファイルが変換されると、プレースホルダーは常に完全としてマークされます。 このようなプレースホルダーを退避しようとすると、エラー コード ERROR_CLOUD_FILE_DEHYDRATION_DISALLOWEDで失敗します。 |
| CF_CONVERT_FLAG_FORCE_CONVERT_TO_CLOUD_FILE | このプラットフォームを指定すると、同期エンジンは非クラウド ファイル プレースホルダー (別の再解析タグ/データを持つ) をクラウド ファイル プレースホルダーにアトミックに変換できます。 通常、API はプレースホルダー以外のファイルからプレースホルダーへの変換に失敗します。 組み合わせ (CF_CONVERT_FLAG_FORCE_CONVERT_TO_CLOUD_FILE |CF_CONVERT_FLAG_DEHYDRATE) は、特定のプロバイダーが別のプラットフォームからクラウド ファイル プラットフォームに移行し、古いプラットフォーム上のハイドレートされたプレースホルダーをクラウド ファイル プラットフォーム上の脱水プレースホルダーにアトミックに変換する場合の移行シナリオで特に便利です。 完全なプレースホルダーをクラウド ファイル プレースホルダーに変換するには、このフラグのみを渡す必要があります。 古いプラットフォームで完全なファイルが通常のプレースホルダー以外のファイルとして実装されている場合、このフラグは必要ありません。 ディレクトリでこのフラグを渡すと、ディレクトリもクラウド ファイルに変換されますが、 DEHYDRATE フラグはディレクトリには適用されません。 ポリシー CF_PLACEHOLDER_MANAGEMENT_POLICY_CONVERT_TO_UNRESTRICTED が CfRegisterSyncRoot で指定された場合でも、クラウド ファイル同期ルートに登録または接続されているプロセスのみがこのフラグを指定できます。 メモ：フラグは、CfGetPlatformInfo から取得された PlatformVersion.IntegrationNumber が以上の0x500場合にのみサポートされます。 |
[out, optional] ConvertUsn
指定すると、変換アクションが実行された後の最終的な USN 値になります。
[in, out, optional] Overlapped
指定し、非同期 の FileHandle と組み合わせると、 Overlapped を使用すると、プラットフォームは CfConvertToPlaceholder 呼び出しを非同期的に実行できます。 詳細については、「 解説 」を参照してください。
指定しない場合、プラットフォームは、ハンドルの作成方法に関係なく、API 呼び出しを同期的に実行します。
戻り値
この関数が成功すると、 が返されます S_OK。 そうでない場合は、HRESULT エラー コードを返します。
注釈
ファイルの場合、呼び出し元は、ファイルを同時に退避させる場合、またはデータ破損が発生する可能性がある場合に、ファイルに対する排他的ハンドルを取得する必要があります。 ユーザー アプリケーションへの影響を最小限に抑えるために、呼び出し元は、share-nothing ハンドルを使用するのではなく、適切な oplock を使用して ( CfOpenFileWithOplock 経由で) 排他性を取得することを強くお勧めします。
プレースホルダーを変換するには:
- 変換するファイルまたはディレクトリは、登録済みの同期ルート ツリーに含まれている必要があります。同期ルート ディレクトリ自体、または任意の子孫ディレクトリを指定できます。それ以外の場合は、 の呼び出しは 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 |