CfRegisterSyncRoot 関数 (cfapi.h)
1 回限りの同期ルート登録を実行します。これにより、同期プロバイダーは、 SyncRootPath にルート化されたディレクトリ ツリー構造全体を、管理する独自のディレクトリ ツリー構造として要求できます。
構文
HRESULT CfRegisterSyncRoot(
[in] LPCWSTR SyncRootPath,
[in] const CF_SYNC_REGISTRATION *Registration,
[in] const CF_SYNC_POLICIES *Policies,
[in] CF_REGISTER_FLAGS RegisterFlags
);
パラメーター
[in] SyncRootPath
登録する同期ルートへのパス。
[in] Registration
登録する同期プロバイダーと同期ルートに関する情報が含まれます。
ProviderName と ProviderVersion は、それぞれ最大 255 文字のエンド ユーザー向け文字列です。
SyncRootIdentity と FileIdentity はどちらも省略可能であり、指定されていない場合は、対応するバッファー長も に設定する0必要があります。 これらは、同期プロバイダーが任意のデータを同期ルートに永続的に関連付ける方法です。
プラットフォームは、同期プロバイダーへのコールバックで SyncRootIdentity を同期プロバイダーに返します。 同期ルート FileIdentity BLOB は、コールバックのサブジェクトが同期ルート自体である場合にのみ提供されます。
この機能は同期プロバイダーの利便性のみを目的として提供されており、両方の BLOB には同期プロバイダーの外部で特別な意味はありません。
FileIdentity の最大許容長は 4 KB で、SyncRootIdentity の最大許容長は 64 KB です。 いずれかの最大長を超えると、API は ERROR_INVALID_PARAMETER で失敗します。
ProviderId は、特定の同期プロバイダーを識別するための GUID です。 これはオプションです。 指定しない場合、プラットフォームは ProviderName 文字列の MD5 ハッシュを使用して GUID を生成します。 この情報は、同期プロバイダーが異なる ProviderName 文字列を使用して同期ルートを登録する場合でも、同じ同期プロバイダーからのアクティビティをより効率的かつ正確に関連付けることができるよう、テレメトリにのみ使用されます。 同期プロバイダーは、同期製品のすべてのバージョンに対して常に同じ GUID を指定することをお勧めします。 ただし、同期プロバイダーは、最適なユーザー エクスペリエンスのために異なる ProviderName 文字列を自由に選択できます。
[in] Policies
登録する同期ルートのポリシー。
[in] RegisterFlags
以前と新しい同期ルートを登録するためのフラグ。
| フラグ | 説明 |
|---|---|
| CF_REGISTER_FLAG_UPDATE | 同期プロバイダーは 、CF_REGISTER_FLAG_UPDATE を渡して、以前に登録した同期ルート ID とポリシーを再登録できます。 |
| CF_REGISTER_FLAG_DISABLE_ON_DEMAND_POPULATION_ON_ROOT | オンデマンド ディレクトリ/フォルダーの作成動作は、作成ポリシーによってグローバルに制御されます。 このフラグを使用すると、同期プロバイダーは、同期ルートの下にある他のすべてのディレクトリに対してオンデマンドの作成をオンにしたまま、同期ルート自体に対してオンデマンドの作成動作をオプトアウトできます。 これは、同期プロバイダーが同期ルートの直接の子ファイル/ディレクトリを事前に設定する場合に便利です。 |
| CF_REGISTER_FLAG_MARK_IN_SYNC_ON_ROOT | このフラグを使用すると、同期プロバイダーは、同期ルートを登録時に同時に同期で登録するようにマークできます。 別の方法は、後で同期ルートで CfSetInSyncState を呼び出す方法です。 |
戻り値
この関数が成功すると、 が返されます S_OK。 そうでない場合は、HRESULT エラー コードを返します。
注釈
これは、同期プロバイダーのインストール時、個々のユーザーの初回設定時、またはユーザーが別の同期ルートを構成するときに使用できます (このシナリオがサポートされている場合)。
注意
2 つの同期ルート ツリーは重複できません。 ディレクトリ ハード リンクはファイル システムによって禁止されているため、2 つの同期ルートが重複する唯一の方法は、直接の先祖/子孫関係がある場合です。 プラットフォームは、特定のボリュームに登録されているすべての同期ルートを永続的に記憶し、重複する同期ルートを作成しようとして失敗する責任があります。
同期プロバイダーには、登録する同期ルートへの WRITE_DATA または WRITE_DAC アクセス権が必要です。または、 ERROR_CLOUD_FILE_ACCESS_DENIEDで登録が失敗します。
同期プロバイダーは、同期プロバイダー自体と登録する同期ルートのさまざまな ID、同期ルートごとに動作を調整するためにプラットフォームが使用する一連のポリシー、および同期プロバイダーによる登録操作を細かく制御できる登録フラグのセットを含む登録レコードを提供する必要があります。
省略可能として明示的に呼び出されない限り、すべてのフィールドは必須であり、指定しないと、API 呼び出しが無効なパラメーター エラーで失敗します。
将来の拡張機能が必要なすべての構造体は、 StructSize フィールドで始まります。 呼び出し元は、構造サイズの正確なアカウンティングを担当します。
このプラットフォームでは現在、次の 5 種類の ポリシーがサポートされています。
ハイドレーション ポリシー
ハイドレーション ポリシーを使用すると、同期プロバイダーは、プラットフォームによってプレースホルダー ファイルをハイドレートする方法を制御できます。 これは、プライマリ ポリシーと一連のポリシー修飾子で構成されます。
プライマリ ハイドレーション ポリシーには、次の 4 つの異なる値があります。
| ポリシー | 説明 |
|---|---|
| ALWAYS_FULL | プラットフォームは( ERROR_CLOUD_FILE_INVALID_REQUEST)、完全にハイドレートされていないプレースホルダーになる可能性のあるプレースホルダー操作 ( CfCreatePlaceholders、 CfDehydratePlaceholder、脱水オプションを持つ CfUpdatePlaceholder 、脱水オプションを使用した CfConvertToPlaceholder など) に失敗します。 |
| FULL | プラットフォームでは、プレースホルダーを脱水できます。 プラットフォームが脱水プレースホルダーへのアクセスを検出すると、要求が 1 バイトのみを要求している場合でも、ユーザー IO 要求を完了する前に、プレースホルダーの完全なコンテンツをローカルで使用できるようになります。 |
| プログレッシブ | プラットフォームでは、プレースホルダーを脱水できます。 プラットフォームが脱水プレースホルダーへのアクセスを検出すると、十分なデータが同期プロバイダーから受信されると判断されるとすぐに、ユーザー IO 要求が完了します。 ただし、プレースホルダーの完全なコンテンツがローカルで利用可能になるか、プレースホルダーの最後のユーザー ハンドルが閉じられるまで、プラットフォームはバックグラウンドで同期プロバイダーにプレースホルダー内の残りのコンテンツを要求し続けます。 メモ：PROGRESSIVE をオプトインする同期プロバイダーでは、ハイドレーション コールバックがオフセット 0から順番に到着するとは想定されない場合があります。 言い換えると、 プログレッシブ ポリシーを使用した同期プロバイダーは、プレースホルダーのランダム シークを処理することが期待されます。 |
| PARTIAL | このポリシーは プログレッシブとよく似ていますが、唯一の違いは、バックグラウンドでの継続的な水分補給の欠如です。 |
現在、3 つのポリシー修飾子がサポートされています。 一般に、修飾子は、組み合わせが自己競合しない限り、プライマリ ポリシーや他のポリシー修飾子と混合して照合できます。
| 修飾子 | 説明 |
|---|---|
| VALIDATION_REQUIRED | このポリシー修飾子は、同期プロバイダーに 2 つの保証を提供します。 最初に、同期プロバイダーによって返されたデータが、ユーザー アプリケーションに返される前に常にディスクに保持されることを保証します。 次に、同期プロバイダーは、以前にプラットフォームに返したのと同じデータを取得し、その整合性を検証できます。 同期プロバイダーによる整合性の確認が成功した場合にのみ、プラットフォームはユーザー IO 要求を完了します。 この修飾子は、余分なディスク IO を犠牲にして、エンドツーエンドのデータ整合性をサポートするのに役立ちます。 |
| STREAMING_ALLOWED | このポリシー修飾子は、同期プロバイダーによって返されたデータをローカル ディスクに格納しないアクセス許可をプラットフォームに付与します。 このポリシー修飾子は、 VALIDATION_REQUIREDと相互に排他的です。 両方のフラグが指定されている場合、 API は ERROR_INVALID_PARAMETER で失敗します。 |
| AUTO_DEHYDRATION_ALLOWED | このポリシー修飾子は、同期プロバイダーの助けを借りずに、同期中のクラウド ファイル プレースホルダーを退避するアクセス許可をプラットフォームに付与します。 このフラグがないと、プラットフォームは CfDehydratePlaceholder を直接呼び出すことはできません。 代わりに、クラウド ファイル プレースホルダーを退避する唯一の方法は、ファイルのピン留めされた属性をクリアし、ファイルのピン留めされていない属性を設定し、2 つの属性のディレクトリ変更通知を受信した後、同期エンジンによって実際の退避が非同期的に実行されることです。 このフラグを指定すると、プラットフォームは、同期中のクラウド ファイル プレースホルダーで CfDehydratePlaceholder を直接呼び出すことができます。 同期プロバイダーは、自動脱水をサポートすることをお勧めします。 |
作成ポリシー
作成ポリシーを使用すると、同期プロバイダーは、プラットフォームによってプレースホルダー名前空間 (ディレクトリとファイルの両方) を作成する方法を制御できます。 現在、修飾子が定義されていない 3 つの主要なポリシーがあります。
| ポリシー | 説明 |
|---|---|
| ALWAYS_FULL | プラットフォームでは、完全なネーム スペースは常にローカルで使用できるものとします。 ディレクトリ列挙要求は同期プロバイダーに転送されません。 |
| FULL | プラットフォームは、完全に設定されていないディレクトリへのアクセスを検出すると、ユーザー要求を完了する前に、同期プロバイダーがディレクトリの下のすべてのエントリを返すように要求します。 |
| PARTIAL | プラットフォームは、完全に設定されていないディレクトリへのアクセスを検出すると、ユーザー アプリケーションに必要なエントリのみを同期プロバイダーに要求します。 |
InSync 追跡ポリシー
InSync ポリシーを使用すると、同期プロバイダーは、プラットフォームがプレースホルダーの同期中の状態をいつクリアするかを制御できます。 プラットフォームは、データ変更で常に同期中をクリアするだけでなく、現在、3 つのファイル属性 (ReadOnly、 System、 Hidden) と 2 つのファイル時刻 (CreateTime と LastWriteTime) の任意の組み合わせの変更に対する同期をクリアできます。 これらのポリシーは、ファイルとディレクトリに個別に適用できます。
ハードリンク ポリシー
既定では、プラットフォームでは、プレースホルダーにハード リンクを作成できません。 ただし、ハード リンクを処理できる同期プロバイダーは、 許可された ポリシーを使用してサポートを有効にするようにプラットフォームに指示できます。 このポリシーを使用すると、同じ同期ルートまたは同期ルートがない限り、アプリケーションはファイル システムがサポートする限り多くのハード リンクを作成できます。 プラットフォームは、最初の out-of-sync-root リンクが導入されたときにプレースホルダーを強制的にハイドレートし、最後の同期ルート内リンクが削除されたときにプレースホルダーを通常のファイルに戻します。 ポリシーと互換性のないハードリンクの作成は、 STATUS_CLOUD_FILES_INCOMPATIBLE_HARDLINKSで失敗します。 ポリシーと互換性のないプレースホルダー操作も 、STATUS_CLOUD_FILES_INCOMPATIBLE_HARDLINKSで失敗します。
プレースホルダー管理ポリシー
既定では、同期プロバイダーのみが同期ルートでプレースホルダー管理操作を実行できます。 同期プロバイダー以外のプロセスでは、同期ルートが非アクティブである場合 、つまり同期ルートが同期プロバイダーによって接続されていない場合にのみ、プレースホルダー管理操作を実行できます。 これらのポリシーを有効にすると、同期プロバイダー以外のプロセスがアクティブな同期ルートでそれぞれのプレースホルダー管理操作を実行できるようになります。 CF_PLACEHOLDER_MANAGEMENT_POLICY_DEFAULT は、接続されている同期プロバイダーのみがプレースホルダー管理操作を実行できるようにする既定のポリシーです。 次のポリシーは任意の組み合わせで指定できます。
| ポリシー | 説明 |
|---|---|
| CF_PLACEHOLDER_MANAGEMENT_POLICY_CREATE_UNRESTRICTED | 登録中にこのポリシーを指定すると、 CfCreatePlaceholders を呼び出すことによって、任意のプロセスでアクティブな同期ルート内にプレースホルダーを作成できます。 |
| CF_PLACEHOLDER_MANAGEMENT_POLICY_CONVERT_UNRESTRICTED | 登録時にこのポリシーを指定すると、どのプロセスでも 、CfConvertToPlaceholder を呼び出すことによって、アクティブな同期ルート内のファイルまたはディレクトリをプレースホルダーに変換できます。 |
| CF_PLACEHOLDER_MANAGEMENT_POLICY_UPDATE_UNRESTRICTED | 登録中にこのポリシーを指定すると、どのプロセスでも CfUpdatePlaceholder を呼び出すことによって、アクティブな同期ルート内のプレースホルダーを更新できます。 |
注意
これらのフラグは、CfGetPlatformInfo から取得した PlatformVersion.IntegrationNumber が以上の0x310場合にのみサポートされます。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 10バージョン 1709 [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows Server 2016 [デスクトップ アプリのみ] |
| 対象プラットフォーム | Windows |
| ヘッダー | cfapi.h |
| Library | CldApi.lib |
| [DLL] | CldApi.dll |
こちらもご覧ください
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示