CfCreatePlaceholders 関数 (cfapi.h)

  • [アーティクル]

同期ルート ディレクトリ ツリーの下に 1 つ以上の新しいプレースホルダー ファイルまたはディレクトリを作成します。

構文

HRESULT CfCreatePlaceholders(
  [in]      LPCWSTR                    BaseDirectoryPath,
  [in, out] CF_PLACEHOLDER_CREATE_INFO *PlaceholderArray,
  [in]      DWORD                      PlaceholderCount,
  [in]      CF_CREATE_FLAGS            CreateFlags,
  [out]     PDWORD                     EntriesProcessed
);

パラメーター

[in] BaseDirectoryPath

プレースホルダーが作成されるローカル ディレクトリへのパス。 パスを指定するときは、次の点に注意してください。

  • このパスは、登録済みの同期ルート ツリーに含まれている必要があります。 同期ルート ディレクトリ自体、または任意の子孫ディレクトリを指定できます。 それ以外の場合、呼び出しは STATUS_CLOUD_FILE_NOT_UNDER_SYNC_ROOTで失敗します。
  • 同期ルートは、 CF_HYDRATION_POLICY_ALWAYS_FULLされていない有効なハイドレーション ポリシーに登録する必要があります。そうしないと、呼び出しは STATUS_CLOUD_FILE_NOT_SUPPORTEDで失敗します。
  • 呼び出し元は 、プレースホルダーを 作成しようとしているベース ディレクトリへのWRITE_DATAまたは WRITE_DAC アクセス権を持っている必要があります。 それ以外の場合、 操作はSTATUS_CLOUD_FILE_ACCESS_DENIEDで失敗します。

[in, out] PlaceholderArray

正常に作成されると、 PlaceholderArray には最終的な USN 値とメッセージが STATUS_OK 含まれます。 戻り値の場合、この配列には、プレースホルダーが作成されたかどうかを示す HRESULT 値が含まれます。 PlaceholderArray は 、 BaseDirectoryPath を基準にして作成されるプレースホルダーの配列を指します。 配列内の各エントリには、次のフィールドが含まれます。

  • RelativeFileName は、作成する子プレースホルダー (ファイルとディレクトリの両方) の名前です。
  • FsMetadata には、作成するプレースホルダーに関するファイル システム メタデータが含まれます。これには、すべてのタイムスタンプ、ファイル属性、ファイル サイズ (ディレクトリの場合は省略可能) が含まれます。
  • FileIdentity と FileIdentityLength は、同期プロバイダーによって提供される不透明なファイル情報を含むユーザー モード バッファーを記述します。 FileIdentity BLOB のサイズは、CF_PLACEHOLDER_MAX_FILE_IDENTITY_LENGTH (4 KB に定義) を超えないようにしてください。 FileIdentity は、すべてのコールバックで同期プロバイダーに返されます。 これは、ファイルの必須フィールドです。

同期プロバイダーは、プレースホルダーごとに次のフラグまたはそれらの組み合わせを選択できます。

  • CF_PLACEHOLDER_CREATE_FLAG_DISABLE_ON_DEMAND_POPULATION - このフラグは、子プレースホルダー ディレクトリにのみ適用されます。 フラグが存在する場合、新しく作成された子プレースホルダー ディレクトリは、すべての子がローカルに存在すると見なされるため、将来アクセスしても 、FETCH_PLACEHOLDERS コールバックはトリガーされません。 フラグがない場合、新しく作成されたプレースホルダー ディレクトリは部分的と見なされ、今後のアクセスによって FETCH_PLACEHOLDERSがトリガーされます。
  • CF_PLACEHOLDER_CREATE_FLAG_MARK_IN_SYNC - このフラグは、プレースホルダー ファイルとディレクトリの両方に適用されます。 このフラグが存在する場合、新しく作成されたプレースホルダーは 、TRANSFER_PLACEHOLDERS 操作の一部として同期中としてマークされます。
  • CF_PLACEHOLDER_CREATE_FLAG_ALWAYS_FULL - このフラグはプレースホルダー ファイルにのみ適用されます。 プレースホルダー ディレクトリに設定できますが、効果はありません。 このフラグが存在する場合、新しく作成されたプレースホルダーは常に完全としてマークされます。 ハイドレートされると、このようなファイル プレースホルダーを退避しようとすると、エラー コード ERROR_CLOUD_FILE_DEHYDRATION_DISALLOWEDで失敗します。

[in] PlaceholderCount

PlaceholderArray 内のプレースホルダーの数。

[in] CreateFlags

プレースホルダーの作成を構成するためのフラグ。 CreateFlags は、次の値に設定できます。

  • CF_CREATE_FLAG_NONE は、エラーが発生した場合でも API が配列内のすべてのエントリを処理する既定のモードです。
  • CF_CREATE_FLAG_STOP_ON_ERROR 、プレースホルダーの作成に失敗した場合に API がすぐに返されます。 その場合、API はエラー コードを返します。

[out] EntriesProcessed

処理されたエントリの数 (失敗したエントリを含む)。 CreateFlags でCF_CREATE_FLAG_STOP_ON_ERRORが指定されていない場合、API は最初に発生したエラー コードを返しますが、可能な限り多くのエントリの処理を続行します。その後、呼び出し元は配列を検査して、失敗したプレースホルダーの作成を確認する必要があります。

戻り値

この関数が成功すると、 が返されます S_OK。 そうでない場合は、HRESULT エラー コードを返します。

注釈

CreateFile を使用して新しいファイルを作成し、CfConvertToPlaceholder を使用してプレースホルダーに変換する場合と比べて、この関数を使用してプレースホルダーを作成することをお勧めします。は、効率と、ファイルがプレースホルダーではない時間枠を排除するためです。 関数は、バッチ内に複数のファイルまたはディレクトリを作成することもできます。これは、より効率的な場合もあります。

この関数は、クラウドからクライアントへのファイルまたはディレクトリの初期同期を実行する場合、または新しく作成した単一のファイルまたはディレクトリをクラウドから同期する場合に便利です。

要件

要件 値
サポートされている最小のクライアント Windows 10、バージョン 1709 [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows Server 2016 [デスクトップ アプリのみ]
対象プラットフォーム Windows
ヘッダー cfapi.h
Library CldApi.lib
[DLL] CldApi.dll

こちらもご覧ください

CreateFile

CfConvertToPlaceholder