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 는 모든 콜백에서 동기화 공급자에게 다시 전달됩니다. 크기가 4KB를 초과할 수 없습니다.

[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) 은 특정 공급자가 다른 플랫폼에서 클라우드 파일 플랫폼으로 마이그레이션하고 이전 플랫폼의 수화된 자리 표시자를 클라우드 파일 플랫폼의 탈수된 자리 표시자로 원자성으로 변환하려는 경우 마이그레이션 시나리오에서 특히 유용합니다. 전체 자리 표시자를 클라우드 파일 자리 표시자로 변환하려면 이 플래그만 전달해야 합니다. 이전 플랫폼에서 전체 파일을 일반 자리 표시자가 아닌 파일로 구현하는 경우 이 플래그는 필요하지 않습니다. 디렉터리에 이 플래그를 전달하면 디렉토리에도 디렉토리가 적용되지 않지만 디렉터 리도 클라우드 파일로 변환됩니다. 정책 CF_PLACEHOLDER_MANAGEMENT_POLICY_CONVERT_TO_UNRESTRICTEDCfRegisterSyncRoot로 지정한 경우에도 클라우드 파일 동기화 루트에 등록/연결된 프로세스만 이 플래그를 지정할 수 있습니다. 참고: 플래그는 CfGetPlatformInfo에서 가져온 가 이상인 경우에만 PlatformVersion.IntegrationNumber 지원됩니다0x500.

[out, optional] ConvertUsn

지정된 경우 변환 작업이 수행된 후의 최종 USN 값입니다.

[in, out, optional] Overlapped

지정되고 비동기 FileHandle과 결합된 경우 Overlapped 를 사용하면 플랫폼에서 CfConvertToPlaceholder 호출을 비동기적으로 수행할 수 있습니다. 자세한 내용은 설명을 참조하세요 .

지정하지 않으면 플랫폼은 핸들을 만든 방법에 관계없이 동기적으로 API 호출을 수행합니다.

반환 값

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

설명

파일의 경우 호출자는 파일을 동시에 탈수하거나 데이터 손상이 발생할 수 있는 경우 파일에 대한 배타적 핸들을 획득해야 합니다. 사용자 애플리케이션에 미치는 영향을 최소화하려면 호출자가 공유 없음 핸들을 사용하는 것이 아니라 적절한 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)로 작업이 실패합니다.

겹침을 비동기적으로 사용할 때 API가 HRESULT_FROM_WIN32(ERROR_IO_PENDING)를 반환하는 경우 호출자는 GetOverlappedResult를 사용하여 대기할 수 있습니다.

요구 사항

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

추가 정보

CfOpenFileWithOplock

GetOverlappedResult