CfUpdatePlaceholder 함수(cfapi.h)

이 API는 기존 자리 표시자의 특성을 변경합니다. 이 API의 가장 가능성이 높은 사용은 파일이 클라우드에서 수정되고 동기화 공급자가 해당 수정의 효과를 자리 표시자에 통합하려는 경우입니다. 이 시나리오를 지원하기 위해 호출자는 적용할 새 파일 시스템 메타데이터(타임스탬프, 파일 크기 등)를 전달하거나 새 FileIdentity Blob을 전달할 수 있습니다.

구문

HRESULT CfUpdatePlaceholder(
  [in]                HANDLE               FileHandle,
  [in, optional]      const CF_FS_METADATA *FsMetadata,
  [in, optional]      LPCVOID              FileIdentity,
  [in]                DWORD                FileIdentityLength,
  [in, optional]      const CF_FILE_RANGE  *DehydrateRangeArray,
  [in]                DWORD                DehydrateRangeCount,
  [in]                CF_UPDATE_FLAGS      UpdateFlags,
  [in, out, optional] USN                  *UpdateUsn,
  [in, out, optional] LPOVERLAPPED         Overlapped
);

매개 변수

[in] FileHandle

FileHandle 은 메타데이터를 업데이트할 파일 또는 디렉터리에 대한 핸들입니다. 파일의 경우 호출자는 파일을 동시에 탈수하려는 경우 파일에 대한 배타적 핸들을 획득해야 합니다. 그렇지 않으면 데이터 손상이 발생할 수 있습니다. 사용자 애플리케이션에 미치는 영향을 최소화하려면 호출자가 공유 없음 핸들을 사용하는 것이 아니라 적절한 oplock( CfOpenFileWithOplock을 통해)을 사용하여 배타성을 얻는 것이 좋습니다.

[in, optional] FsMetadata

FsMetadata 에는 모든 타임스탬프, 파일 특성 및 파일 크기(디렉터리에 대한 선택 사항)를 포함하여 업데이트할 자리 표시자에 대한 파일 시스템 메타데이터가 포함되어 있습니다. 옵션 필드입니다. 제공되지 않으면 이러한 모든 필드는 호출 후에 그대로 유지됩니다.

• 0타임스탬프 필드(CreationTime, LastAccessTime, LastWriteTime 및 ChangeTime)의 값은 파일의 현재 타임스탬프를 변경하지 않음을 의미합니다.
• FileAttributes의 값은 0 파일의 현재 파일 특성이 변경되지 않음을 의미합니다.
• FileSize에는 특별한 값이 없습니다. FileSize의 0 값은 파일 크기를 0로 자립니다.

[in, optional] FileIdentity

FileIdentity 는 호출자가 제공한 불투명 파일 또는 디렉터리 정보를 포함하는 사용자 모드 버퍼입니다. FileIdentity Blob의 크기는 4KB를 초과하면 안 됩니다. FileIdentity 는 모든 콜백에서 동기화 공급자에 다시 전달됩니다. 업데이트가 필요하지 않거나 호출자가 업데이트할 자리 표시자에서 FileIdentity Blob을 제거하려는 경우 선택 사항입니다.

[in] FileIdentityLength

FileIdentity의 길이(바이트)입니다.

[in, optional] DehydrateRangeArray

이 배열은 업데이트 후 더 이상 유효한 것으로 간주되지 않는 기존 자리 표시자의 범위를 지정합니다.

이 매개 변수의 가장 간단한 사용은 단일 범위를 전달하여 플랫폼에 데이터의 전체 바이트 범위가 잘못되었다는 것을 알리는 것입니다. 이 매개 변수의 더 복잡한 사용은 유효하지 않은 것으로 간주되는 일련의 불연속 범위를 제공하는 것입니다. 이는 동기화 공급자가 하위 파일 수준에서 변경 내용을 구분할 수 있음을 의미합니다. 모든 오프셋과 길이는 PAGE_SIZE 정렬되어야 합니다. 플랫폼은 지정된 모든 범위가 업데이트의 일부로 탈수되도록 합니다. 범위의 탈수에 실패하면 API는 파일 내용이 찢어지는 대신 실패합니다.

참고

오프셋 0 및 길이 CF_EOF 있는 단일 범위를 전달하면 전체 파일이 무효화됩니다. 플래그 CF_UPDATE_FLAG_DEHYDRATE 전달하는 것과 같은 효과가 있습니다. 또한 CF_UPDATE_FLAG_DEHYDRATE 전달하면 DehydrateRangeArray 가 자동으로 삭제됩니다.

[in] DehydrateRangeCount

자리 표시자 데이터의 일련의 불연속 탈수RangeArray 파티션의 수입니다.

[in] UpdateFlags

자리 표시자에 대한 플래그를 업데이트합니다. UpdateFlags는 다음 값으로 설정할 수 있습니다.

플래그	설명
CF_UPDATE_FLAG_VERIFY_IN_SYNC	IN_SYNC 특성이 현재 자리 표시자에 설정되어 있지 않으면 업데이트가 실패합니다. 이는 클라우드에서 로컬 자리 표시자로 변경 내용을 동기화하는 것과 자리 표시자의 데이터 스트림이 로컬로 수정되는 경합을 방지하기 위한 것입니다.
CF_UPDATE_FLAG_MARK_IN_SYNC	플랫폼은 성공적인 업데이트 자리 표시자 작업 시 자리 표시자를 동기화 중으로 표시합니다.
CF_UPDATE_FLAG_DEHYDRATE	파일에만 적용됩니다. 지정된 경우 플랫폼은 자리 표시자를 성공적으로 업데이트한 후 파일을 탈수합니다. 이 플래그를 지정하거나 데이터 손상이 발생할 수 있는 경우 호출자는 배타적 핸들을 획득해야 합니다. 플랫폼은 핸들의 배타성의 유효성을 검사하지 않습니다.
CF_UPDATE_FLAG_ENABLE_ON_DEMAND_POPULATION	디렉터리에만 적용됩니다. 지정된 경우 업데이트된 자리 표시자 디렉터리가 부분적으로 채워진 것으로 표시되므로 나중에 액세스하면 동기화 공급자에게 FETCH_PLACEHOLDERS 콜백이 전송됩니다.
CF_UPDATE_FLAG_DISABLE_ON_DEMAND_POPULATION	디렉터리에만 적용됩니다. 지정된 경우 업데이트된 자리 표시자 디렉터리가 완전히 채워져 동기화 공급자에 대한 콜백 없이 플랫폼에서 향후 액세스를 처리하도록 표시합니다.
CF_UPDATE_FLAG_REMOVE_FILE_IDENTITY	FileIdentity 및 FileIdentityLength 는 무시되며 플랫폼은 성공적인 업데이트 호출 시 자리 표시자에서 기존 파일 ID Blob을 제거합니다.
CF_UPDATE_FLAG_CLEAR_IN_SYNC	플랫폼은 성공적인 업데이트 자리 표시자 작업 시 자리 표시자를 동기화되지 않음으로 표시합니다.
CF_UPDATE_FLAG_REMOVE_PROPERTY	플랫폼은 자리 표시자에서 기존의 모든 내재 속성을 제거합니다.
CF_UPDATE_FLAG_PASSTHROUGH_FS_METADATA	플랫폼은 필터링 없이 파일 시스템에 CF_FS_METADATA 전달합니다. 그렇지 않으면 플랫폼은 값 0이 인 필드 설정을 건너뜁니다.
CF_UPDATE_FLAG_ALWAYS_FULL	자리 표시자 파일에만 적용됩니다. 지정하면 업데이트할 자리 표시자가 항상 가득 찼습니다. 수화되면 이러한 자리 표시자 파일을 탈수하려는 시도는 오류 코드 ERROR_CLOUD_FILE_DEHYDRATION_DISALLOWED 실패합니다.
CF_UPDATE_FLAG_ALLOW_PARTIAL	자리 표시자 파일에만 적용됩니다. 지정하면 자리 표시자 파일의 항상 전체 상태가 지워지므로 다시 탈수될 수 있습니다. CF_UPDATE_FLAG_ALWAYS_FULL 함께 이 플래그를 지정하는 것은 잘못되었으며 결과적으로 ERROR_CLOUD_FILE_INVALID_REQUEST 오류 코드가 반환됩니다.

[in, out, optional] UpdateUsn

입력에서 UpdateUsn은 파일에 전달된 것과 동일한 USN 값이 있는 경우에만 업데이트를 수행하도록 플랫폼에 지시합니다. 이는 CF_UPDATE_FLAG_VERIFY_IN_SYNC 유사한 용도로 사용되지만 로컬 메타데이터 변경 내용도 포함합니다. 입력에서 의 USN 값 0 에 포인터를 전달하는 것은 포인터를 전달하는 NULL 것과 같습니다.

반환 시 UpdateUsn 은 업데이트 작업이 수행된 후 최종 USN 값을 받습니다.

[in, out, optional] Overlapped

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

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

반환 값

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

설명

자리 표시자를 업데이트하려면 다음을 수행합니다.

• 업데이트할 자리 표시자는 등록된 동기화 루트 트리에 포함되어야 합니다. 동기화 루트 디렉터리 자체 또는 하위 디렉터리일 수 있습니다. 그렇지 않으면 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

CF_UPDATE_FLAGS