PSCoerceToCanonicalValue 함수(propsys.h)

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

구문

PSSTDAPI PSCoerceToCanonicalValue(
  [in]      REFPROPERTYKEY key,
  [in, out] PROPVARIANT    *ppropvar
);

매개 변수

[in] key

형식: REFPROPERTYKEY

값을 강제 변환할 속성을 식별하는 PROPERTYKEY 구조체에 대한 참조입니다.

[in, out] ppropvar

형식: PROPVARIANT*

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

반환 값

형식: HRESULT

가능한 반환 값은 다음과 같습니다.

설명

이 함수는 시스템의 IPropertyDescription::CoerceToCanonicalValue 구현에 대한 래퍼입니다.

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

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

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

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

1. 다음 값은 VT_EMPTY 변환됩니다.
   • 형식 VT_NULL 값입니다.
   • 포인터가 NULL인 VT_LPWSTR, VT_BSTR 또는 VT_LPSTR 형식의 값입니다.
   • 비어 있거나 공백으로 완전히 구성된 VT_LPWSTR, VT_BSTR 또는 VT_LPSTR 형식의 값입니다.
   • 형식의 값은 1601/01/02 자정 이전에 VT_FILETIME.
2. 값이 1단계 이후에 VT_EMPTY 형식이 아니면 속성 설명에 지정된 형식으로 변환됩니다. 속성 설명의 형식은 IPropertyDescription::GetPropertyType을 호출하여 가져올 수 있습니다. 속성 스키마가 속성 설명의 형식에 미치는 영향에 대한 자세한 내용은 typeInfo를 참조하세요. 변환은 다음과 같이 수행됩니다.
   • VT_LPWSTR, VT_BSTR 또는 VT_LPSTR 형식의 값이 VT_VECTOR | InitPropVariantFromStringAsVector를 사용하여 VT_LPWSTR.
   • 다른 모든 변환은 PropVariantChangeType을 사용하여 수행됩니다.
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 변환합니다.

    

예제

더 큰 프로그램의 일부로 포함할 다음 예제에서는 PSCoerceToCanonicalValue 를 사용하여 값을 PKEY_Keywords 필요한 형식으로 강제 변환하는 방법을 보여 줍니다.

// PROPVARIANT propvar;
// Assume variable propvar is initialized and valid.

HRESULT hr = PSCoerceToCanonicalValue(PKEY_Keywords, &propvar);

if (SUCCEEDED(hr))
{
    // The conversion succeeded and propvar now is of the correct type for 
    // PKEY_Keywords, or VT_EMPTY.
    PropVariantClear(&propvar);
}
else
{
    // The conversion failed and propvar is now VT_EMPTY.
}

요구 사항

추가 정보

IPropertyDescription

IShellItem2::GetPropertyStore

PropVariantChangeType

속성 설명 스키마

typeInfo