IPropertyDescription::CoerceToCanonicalValue 메서드(propsys.h)

  • 아티클

속성 설명에 따라 값을 정식 값으로 강제 변환합니다.

구문

HRESULT CoerceToCanonicalValue(
  [in, out] PROPVARIANT *ppropvar
);

매개 변수

[in, out] ppropvar

형식: PROPVARIANT*

항목에서 는 원래 값을 포함하는 PROPVARIANT 구조체에 대한 포인터를 포함합니다. 이 메서드가 반환되면 정식 값이 포함됩니다.

반환 값

형식: HRESULT

오류 코드가 INPLACE_S_TRUNCATED 또는 E_INVALIDARG 않으면 값의 형식에서 속성 설명의 형식으로 강제 변환할 수 없으며 PROPVARIANT 구조가 지워졌습니다.

가능한 결과에는 다음이 포함됩니다.

반환 코드 Description
S_OK
 함수가 성공했습니다. 이제 ppropvar에 지정된 속성 값이 정식 형식입니다.
INPLACE_S_TRUNCATED
 ppropvar에 의해 지정된 속성 값은 이제 잘린 정식 형식입니다.
E_INVALIDARG
 ppropvar 매개 변수가 잘못되었습니다. PROPVARIANT 구조가 지워졌습니다.

설명

자세한 내용은 속성의 . propdesc 파일에서 typeInfo 요소의 type 특성을 참조하세요.

대부분의 속성 설명은 해당 값이 사용할 형식을 지정합니다. 예를 들어 System.Title에 대한 속성 설명은 System.Title 값이 를 사용하도록 VT_LPWSTR지정합니다. 이 메서드는 값을 이 형식으로 강제 변환하고 결과를 정식 형식으로 강제 변환합니다.

이 메서드가 실패하면 입력 PROPVARIANT 구조에서 PropVariantClear를 이미 호출한 것입니다. 이 메서드가 성공한 경우에만 구조체가 더 이상 필요하지 않을 때 ppropvar에서 PropVariantClear를 호출하는 호출 애플리케이션입니다.

이 메서드에서 수행하는 강제 변환은 IPropertyStore::GetValue 및 IPropertyStore::SetValue 호출 중에 속성 시스템에서도 수행됩니다. 애플리케이션은 강제 변환을 수행하기 위해 속성 시스템에 의존하거나 이 메서드를 사용하여 애플리케이션이 선택한 시간에 강제 변환을 수행할 수 있습니다.

강제 변환은 다음과 같이 4단계로 수행됩니다.

  1. 다음 값은 로 VT_EMPTY변환됩니다.
    • 형식 VT_NULL의 값입니다.
    • 형식 VT_LPWSTR, VT_BSTR의 값이거나 VT_LPSTR 포인터가 NULL인 값입니다.
    • 형식 VT_LPWSTR, VT_BSTR의 값이거나 VT_LPSTR 비어 있거나 공백으로 완전히 구성됩니다.
    • 1601/01/02 자정 이전 형식 VT_FILETIME 의 값입니다.
  2. 값이 1단계 이후 형식 VT_EMPTY 이 아니면 속성 설명에 지정된 형식으로 변환됩니다. 속성 설명의 형식은 IPropertyDescription::GetPropertyType을 사용하여 가져올 수 있습니다. 속성 스키마가 속성 설명의 형식에 미치는 영향에 대한 자세한 내용은 typeInfo 를 참조하세요. 변환은 다음과 같이 수행됩니다.
  3. 2단계와 3단계 후에는 값이 형식에 따라 정식 형식으로 강제 변환됩니다. 정식 양식은 다음 표에 요약되어 있습니다.
    값 형식 정식 양식
    VT_EMPTY 항상 정식.
    VT_LPWSTR
    • 선행 또는 후행 공백이 없습니다. 문자열이 비어 있지 않습니다. 문자열이 NULL이 아닌 경우 L"Alice")을 입력합니다.
    • 트리 속성인 경우(즉, typeInfo 요소의 isTreeProperty 특성이 TRUE인 경우), 선행 또는 후행 슬래시(/)가 없어야 하고, 텍스트와 슬래시 사이에 공백이 없어야 하며, 연속 슬래시(/)가 두 개 있으면 안 됩니다. 예를 들어 L"Friend/Bob"
    • 강제 변환은 불필요한 문자를 제거하고 콘텐츠가 없으면 발생 VT_EMPTY 합니다.
    VT_VECTOR | VT_LPWSTR
    • 벡터의 각 문자열은 위에 나열된 규칙을 VT_LPWSTR 준수해야 합니다. 또한 벡터에는 중복 항목이 없고 null 포인터가 없어야 합니다.
    • 트리 속성인 경우 값이 다른 값의 상위 항목이 될 수 없습니다. 예를 들어 는 L"Friend" L"Friend/Bob"의 상위 항목입니다.
    • 콘텐츠가 없으면 강제 변환은 중복 및 상위 문자를 제거하고 를 생성합니다 VT_EMPTY.
     
  4. 해당하는 경우 속성 설명 형식 열거형에 대해 값을 확인합니다. 다음 검사가 적용되었습니다.
    열거형 형식 값 형식 정식 양식
    불연속 또는 범위 지정 VT_EMPTY 항상 정식
    불연속 VT_LPWSTR 문자열은 속성에 허용되는 열거형 문자열 중 하나와 일치합니다. 비교는 대/소문자를 구분하지 않습니다. 그렇지 않은 경우 값을 로 변환합니다 VT_EMPTY.
    불연속 숫자 숫자는 속성에 허용되는 열거형 값 중 하나와 일치합니다. 그렇지 않은 경우 값을 로 변환합니다 VT_EMPTY.
    불연속 VT_VECTOR | VT_LPWSTR 벡터의 각 문자열은 속성에 허용되는 열거형 문자열 중 하나와 일치합니다. 비교는 대/소문자를 구분하지 않습니다. 그렇지 않은 경우 벡터에서 해당 문자열을 제거합니다. 결과 벡터가 비어 있으면 값을 VT_EMPTY로 변환합니다.
    불연속 VT_VECTOR | 숫자 벡터의 각 숫자는 속성에 허용되는 열거형 값 중 하나와 일치합니다. 그렇지 않은 경우 벡터에서 해당 번호를 제거합니다. 결과 벡터가 비어 있으면 값을 VT_EMPTY로 변환합니다.
    원거리 VT_LPWSTR 문자열은 속성에 허용되는 범위에 있습니다. 비교는 대/소문자를 구분합니다. 그렇지 않은 경우 값을 로 변환합니다 VT_EMPTY.
    원거리 숫자 이 숫자는 속성에 허용되는 범위에 있습니다. 그렇지 않은 경우 값을 VT_EMPTY 변환합니다.
    원거리 VT_VECTOR | VT_LPWSTR 벡터의 각 문자열은 속성에 허용되는 범위에 있습니다. 비교는 대/소문자를 구분합니다. 그렇지 않은 경우 벡터에서 해당 문자열을 제거합니다. 결과 벡터가 비어 있으면 값을 VT_EMPTY로 변환합니다.
    원거리 VT_VECTOR | 숫자 벡터의 각 숫자는 속성에 허용되는 범위에 있습니다. 그렇지 않은 경우 벡터에서 해당 번호를 제거합니다. 결과 벡터가 비어 있으면 값을 VT_EMPTY 변환합니다.
     

요구 사항

요구 사항 값
지원되는 최소 클라이언트 Windows Vista [데스크톱 앱만 해당]
지원되는 최소 서버 Windows Server 2008 [데스크톱 앱만 해당]
대상 플랫폼 Windows
헤더 propsys.h

추가 정보

IPropertyDescription

속성 설명 스키마