CfCreatePlaceholders 함수(cfapi.h)

동기화 루트 디렉터리 트리 아래에 하나 이상의 새 자리 표시자 파일 또는 디렉터리를 만듭니다.

구문

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(4KB로 정의됨)를 초과하면 안 됩니다. 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

자리 표시자 배열의 자리 표시자 수입니다.

[in] CreateFlags

자리 표시자 만들기를 구성하기 위한 플래그입니다. CreateFlags는 다음 값으로 설정할 수 있습니다.

• CF_CREATE_FLAG_NONE API가 오류가 발생한 경우에도 배열의 모든 항목을 처리하는 기본 모드입니다.
• CF_CREATE_FLAG_STOP_ON_ERROR 자리 표시자 만들기가 실패하면 API가 즉시 반환됩니다. 이 경우 API는 실패 코드를 반환합니다.

[out] EntriesProcessed

실패한 항목을 포함하여 처리된 항목의 수입니다. CF_CREATE_FLAG_STOP_ON_ERROR CreateFlags에 지정되지 않은 경우 API는 발생한 첫 번째 오류 코드를 반환하지만 가능한 한 많은 항목을 계속 처리합니다. 그런 다음 호출자가 배열을 검사하여 실패한 자리 표시자 만들기를 확인해야 합니다.

반환 값

이 함수가 성공하면 를 반환합니다 S_OK. 그러지 않으면 HRESULT 오류 코드를 반환합니다.

설명

CreateFile을 사용하여 새 파일을 만든 다음 CfConvertToPlaceholder를 사용하여 자리 표시자로 변환하는 것과 비교하면 이 함수를 사용하여 자리 표시자를 만드는 것이 좋습니다. 둘 다 효율성을 위해 그리고 파일이 자리 표시자가 아닌 시간 창을 제거하기 때문입니다. 또한 함수는 일괄 처리로 여러 파일 또는 디렉터리를 만들 수 있으며 더 효율적일 수도 있습니다.

이 함수는 클라우드에서 클라이언트까지 파일 또는 디렉터리의 초기 동기화를 수행하거나 새로 만든 단일 파일 또는 디렉터리를 클라우드에서 동기화할 때 유용합니다.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows 10 버전 1709 [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2016 [데스크톱 앱만 해당]
대상 플랫폼	Windows
헤더	cfapi.h
라이브러리	CldApi.lib
DLL	CldApi.dll

추가 정보

CreateFile

CfConvertToPlaceholder