다음을 통해 공유

PSCoerceToCanonicalValue 함수(propsys.h)

  • 아티클

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

구문

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

매개 변수

[in] key

형식: REFPROPERTYKEY

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

[in, out] ppropvar

형식: PROPVARIANT*

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

반환 값

형식: HRESULT

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

반환 코드 Description
S_OK
 함수가 성공했습니다. 이제 ppropvar에 지정된 속성 값이 정식 형식입니다.
INPLACE_S_TRUNCATED
 ppropvar에 의해 지정된 속성 값은 이제 잘린 정식 형식입니다.
E_INVALIDARG
 ppropvar 매개 변수가 잘못되었습니다. PROPVARIANT 구조가 지워졌습니다.
TYPE_E_TYPEMISMATCH
 값의 형식에서 속성 설명의 형식으로 강제 변환할 수 없습니다. PROPVARIANT 구조가 지워졌습니다.
기타 오류 코드
 값의 형식에서 속성 설명의 형식으로 강제 변환할 수 없습니다. PROPVARIANT 구조가 지워졌습니다.

설명

이 함수는 시스템의 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를 참조하세요. 변환은 다음과 같이 수행됩니다.
  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.
}

요구 사항

요구 사항 값
지원되는 최소 클라이언트 WINDOWS XP SP2, Windows Vista [데스크톱 앱만 해당]
지원되는 최소 서버 Windows Server 2003 SP1 [데스크톱 앱만 해당]
대상 플랫폼 Windows
헤더 propsys.h
라이브러리 Propsys.lib
DLL Propsys.dll(버전 6.0 이상)
재배포 가능 파일 WDS(Windows 데스크톱 검색) 3.0

추가 정보

IPropertyDescription

IShellItem2::GetPropertyStore

PropVariantChangeType

속성 설명 스키마

typeInfo