CfRegisterSyncRoot 함수(cfapi.h)

아티클
04/06/2023

동기화 공급자가 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의 최대 허용 길이는 4KB이고 SyncRootIdentity의 최대 허용 길이는 64KB입니다. 최대 길이를 초과하면 ERROR_INVALID_PARAMETER API가 실패합니다.

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 오류 코드를 반환합니다.

설명

동기화 공급자 설치 시간, 개별 사용자에 대해 처음 설정하거나 사용자가 다른 동기화 루트를 구성할 때 사용할 수 있습니다(이 시나리오가 지원되는 경우).

참고

두 개의 동기화 루트 트리는 겹칠 수 없습니다. 디렉터리 하드 링크는 파일 시스템에 의해 금지되므로 두 동기화 루트가 겹치는 유일한 방법은 직접 상위/하위 관계가 있는 경우입니다. 플랫폼은 지정된 볼륨에 등록된 모든 동기화 루트를 영구적으로 기억하고 겹치는 동기화 루트를 만들려는 시도에 실패합니다.

동기화 공급자는 등록 할 동기화 루트에 대한 WRITE_DATA 또는 WRITE_DAC 액세스 권한이 있어야 합니다. 그렇지 않으면 ERROR_CLOUD_FILE_ACCESS_DENIED 등록이 실패합니다.

동기화 공급자는 등록할 동기화 공급자 자체의 다양한 ID와 등록할 동기화 루트가 포함된 등록 레코드, 플랫폼에서 동기화 루트별로 동작을 조정하는 데 사용하는 정책 집합 및 동기화 공급자가 등록 작업을 더 세부적으로 제어할 수 있는 등록 플래그 집합을 제공해야 합니다.

명시적으로 선택 사항으로 호출하지 않는 한 모든 필드는 필수이며 이를 제공하지 않으면 잘못된 매개 변수 오류로 인해 API 호출이 실패합니다.

향후 확장이 예상되는 모든 구조체는 StructSize 필드로 시작됩니다. 호출자는 구조체 크기의 정확한 회계를 담당합니다.

이 플랫폼은 현재 다음 5가지 유형의 정책을 지원합니다.

수분 공급 정책

수화 정책을 사용하면 동기화 공급자가 플랫폼에서 자리 표시자 파일을 하이드레이션하는 방법을 제어할 수 있습니다. 기본 정책 및 정책 한정자 집합으로 구성됩니다.

기본 수화 정책에는 네 가지 값이 있습니다.

정책	설명
ALWAYS_FULL	플랫폼은 cfCreatePlaceholders, CfDehydratePlaceholder, 탈수 옵션이 있는 CfUpdatePlaceholder 및 탈수 옵션이 있는 CfConvertToPlaceholder를 포함하는 완전히 수 화되지 않은 자리 표시자를 생성할 수 있는 자리 표시자 작업을 ERROR_CLOUD_FILE_INVALID_REQUEST 실패합니다.
FULL	플랫폼에서 자리 표시자를 탈수할 수 있습니다. 플랫폼이 탈수된 자리 표시자에 대한 액세스를 감지하면 요청이 1 바이트만 요청하는 경우에도 사용자 IO 요청을 완료하기 전에 자리 표시자의 전체 콘텐츠를 로컬로 사용할 수 있는지 확인합니다.
진보적인	플랫폼에서 자리 표시자를 탈수할 수 있습니다. 플랫폼이 탈수된 자리 표시자에 대한 액세스를 감지하면 동기화 공급자로부터 충분한 데이터가 수신되었다고 판단되는 즉시 사용자 IO 요청을 완료합니다. 그러나 플랫폼은 자리 표시자의 전체 콘텐츠를 로컬로 사용할 수 있거나 자리 표시자의 마지막 사용자 핸들을 닫을 때까지 백그라운드에서 동기화 공급자로부터 자리 표시자의 나머지 콘텐츠를 계속 요청할 것을 약속합니다. 참고:PROGRESSIVE 를 옵트인하는 동기화 공급자는 수분 공급 콜백이 오프셋 `0`에서 순차적으로 도착한다고 가정하지 않을 수 있습니다. 즉, PROGRESSIVE 정책과 동기화 공급자는 자리 표시자에서 임의 검색을 처리해야 합니다.
PARTIAL	이 정책은 프로그레시브와 매우 유사하며, 유일한 차이점은 백그라운드에서 지속적인 수분 공급의 부족입니다.

현재 세 가지 정책 한정자가 지원됩니다. 일반적으로 한정자는 조합이 자체 충돌하지 않는 한 기본 정책 및 기타 정책 한정자와 혼합 및 일치시킬 수 있습니다.

한정자	Description
VALIDATION_REQUIRED	이 정책 한정자는 동기화 공급자에게 두 가지 보증을 제공합니다. 먼저 동기화 공급자가 반환한 데이터가 사용자 애플리케이션으로 반환되기 전에 항상 디스크에 유지되도록 보장합니다. 둘째, 동기화 공급자가 이전에 플랫폼에 반환한 것과 동일한 데이터를 검색하고 무결성의 유효성을 검사할 수 있습니다. 동기화 공급자가 무결성을 성공적으로 확인한 후에만 플랫폼이 사용자 IO 요청을 완료합니다. 이 한정자는 추가 디스크 IO의 비용으로 엔드 투 엔드 데이터 무결성을 지원하는 데 도움이 됩니다.
STREAMING_ALLOWED	이 정책 한정자는 동기화 공급자가 반환한 데이터를 로컬 디스크에 저장하지 않을 수 있는 권한을 플랫폼에 부여합니다. 이 정책 한정자는 VALIDATION_REQUIRED 함께 사용할 수 없습니다. 두 플래그가 모두 지정되면 ERROR_INVALID_PARAMETER API가 실패합니다.
AUTO_DEHYDRATION_ALLOWED	이 정책 한정자는 동기화 공급자의 도움 없이 동기화 중인 클라우드 파일 자리 표시자를 탈수할 수 있는 권한을 플랫폼에 부여합니다. 이 플래그가 없으면 플랫폼에서 CfDehydratePlaceholder 를 직접 호출할 수 없습니다. 대신 클라우드 파일 자리 표시자를 탈수하는 유일한 지원 방법은 파일의 고정된 특성을 지우고 파일의 고정되지 않은 특성을 설정한 다음 두 특성에 대한 디렉터리 변경 알림을 받은 후 동기화 엔진에서 실제 탈수 작업을 비동기적으로 수행하는 것입니다. 이 플래그를 지정하면 플랫폼이 동기화 중인 클라우드 파일 자리 표시자에서 CfDehydratePlaceholder 를 직접 호출할 수 있습니다. 동기화 공급자가 자동 탈수를 지원하는 것이 좋습니다.

인구 정책

채우기 정책을 사용하면 동기화 공급자가 플랫폼에서 자리 표시자 네임스페이스(디렉터리와 파일 모두)를 만드는 방법을 제어할 수 있습니다. 현재 한정자가 정의되지 않은 세 가지 기본 정책이 있습니다.

정책	설명
ALWAYS_FULL	플랫폼은 전체 이름 공간을 항상 로컬에서 사용할 수 있다고 가정합니다. 동기화 공급자에 디렉터리 열거형 요청을 전달하지 않습니다.
FULL	플랫폼이 완전히 채워지지 않은 디렉터리에 대한 액세스를 감지하면 동기화 공급자가 사용자 요청을 완료하기 전에 디렉터리 아래에 있는 모든 항목을 반환할 것을 요청합니다.
PARTIAL	플랫폼이 완전히 채워지지 않은 디렉터리에 대한 액세스를 검색하면 동기화 공급자의 사용자 애플리케이션에 필요한 항목만 요청합니다.

InSync 추적 정책

InSync 정책을 사용하면 동기화 공급자가 플랫폼이 자리 표시자에서 동기화 중 상태를 지워야 하는 시기를 제어할 수 있습니다. 플랫폼은 데이터 수정 시 항상 동기화 내를 지우는 것 외에도 현재 세 개의 파일 특성(ReadOnly, System 및 Hidden)과 두 개의 파일 시간(CreateTime 및 LastWriteTime)의 조합에 대한 변경 내용에 대해 동기화 중을 지울 수 있습니다. 이러한 정책은 파일 및 디렉터리에 별도로 적용할 수 있습니다.

하드 링크 정책

기본적으로 플랫폼은 모든 자리 표시자에 하드 링크를 만들 수 없습니다. 그러나 하드 링크를 처리할 수 있는 동기화 공급자는 허용된 정책을 통해 지원을 사용하도록 플랫폼에 지시할 수 있습니다. 이 정책을 사용하면 링크가 동일한 동기화 루트 아래에 있거나 동기화 루트가 없는 한 애플리케이션에서 파일 시스템에서 지원하는 만큼의 하드 링크를 만들 수 있습니다. 플랫폼은 첫 번째 동기화되지 않은 루트 링크가 도입될 때 자리 표시자를 강제로 하이드레이션하고 마지막 동기화 루트 내 링크가 제거될 때 자리 표시자를 일반 파일에 되돌리기. 정책과 호환되지 않는 하드링크 만들기는 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
라이브러리	CldApi.lib
DLL	CldApi.dll