다음을 통해 공유


PROPVARIANT 구조체(propidlbase.h)

PROPVARIANT 구조체는 IPropertyStorageReadMultipleWriteMultiple 메서드에서 속성 집합에 있는 속성의 형식 태그 및 값을 정의하는 데 사용됩니다.

PROPVARIANT 구조체는 IPropertyStoreGetValueSetValue 메서드에서도 사용됩니다. 이 메서드는 Windows Vista에서 항목 속성을 프로그래밍하는 기본 방법으로 IPropertySetStorage를 대체합니다. 자세한 내용은 속성 처리기를 참조하세요.

5명의 멤버가 있습니다. 첫 번째 멤버, 값 형식 태그 및 마지막 멤버인 속성 값이 중요합니다. 중간 3개 멤버는 나중에 사용하도록 예약되어 있습니다.

참고 일부 컴파일러가 이제 bool을 키워드(keyword) 인식하기 때문에 이 구조체의 이전 정의에서 bool 멤버의 이름이 boolVal로 바뀌었습니다.
 
참고 아래에 정의된 PROPVARIANT 구조에는 버전 1 속성 집합 serialization 형식으로 직렬화할 수 있는 형식이 포함됩니다. 버전 1 형식은 버전 0 형식에 허용되는 모든 형식과 일부 추가 형식을 지원합니다. 추가된 형식은 아래 주석 필드에 "버전 1"을 포함합니다. 버전 1 속성 집합이 의도된 경우에만 이러한 형식을 사용합니다. 자세한 내용은 속성 집합 serialization을 참조하세요.
 
PROPVARIANT 구조체는 다음과 같이 정의됩니다.

구문

typedef struct tagPROPVARIANT {
  union {
    typedef struct {
      VARTYPE      vt;
      PROPVAR_PAD1 wReserved1;
      PROPVAR_PAD2 wReserved2;
      PROPVAR_PAD3 wReserved3;
      union {
        CHAR              cVal;
        UCHAR             bVal;
        SHORT             iVal;
        USHORT            uiVal;
        LONG              lVal;
        ULONG             ulVal;
        INT               intVal;
        UINT              uintVal;
        LARGE_INTEGER     hVal;
        ULARGE_INTEGER    uhVal;
        FLOAT             fltVal;
        DOUBLE            dblVal;
        VARIANT_BOOL      boolVal;
        VARIANT_BOOL      __OBSOLETE__VARIANT_BOOL;
        SCODE             scode;
        CY                cyVal;
        DATE              date;
        FILETIME          filetime;
        CLSID             *puuid;
        CLIPDATA          *pclipdata;
        BSTR              bstrVal;
        BSTRBLOB          bstrblobVal;
        BLOB              blob;
        LPSTR             pszVal;
        LPWSTR            pwszVal;
        IUnknown          *punkVal;
        IDispatch         *pdispVal;
        IStream           *pStream;
        IStorage          *pStorage;
        LPVERSIONEDSTREAM pVersionedStream;
        LPSAFEARRAY       parray;
        CAC               cac;
        CAUB              caub;
        CAI               cai;
        CAUI              caui;
        CAL               cal;
        CAUL              caul;
        CAH               cah;
        CAUH              cauh;
        CAFLT             caflt;
        CADBL             cadbl;
        CABOOL            cabool;
        CASCODE           cascode;
        CACY              cacy;
        CADATE            cadate;
        CAFILETIME        cafiletime;
        CACLSID           cauuid;
        CACLIPDATA        caclipdata;
        CABSTR            cabstr;
        CABSTRBLOB        cabstrblob;
        CALPSTR           calpstr;
        CALPWSTR          calpwstr;
        CAPROPVARIANT     capropvar;
        CHAR              *pcVal;
        UCHAR             *pbVal;
        SHORT             *piVal;
        USHORT            *puiVal;
        LONG              *plVal;
        ULONG             *pulVal;
        INT               *pintVal;
        UINT              *puintVal;
        FLOAT             *pfltVal;
        DOUBLE            *pdblVal;
        VARIANT_BOOL      *pboolVal;
        DECIMAL           *pdecVal;
        SCODE             *pscode;
        CY                *pcyVal;
        DATE              *pdate;
        BSTR              *pbstrVal;
        IUnknown          **ppunkVal;
        IDispatch         **ppdispVal;
        LPSAFEARRAY       *pparray;
        PROPVARIANT       *pvarVal;
      };
    } tag_inner_PROPVARIANT, PROPVARIANT, *LPPROPVARIANT;
    DECIMAL decVal;
  };
} PROPVARIANT, *LPPROPVARIANT;

멤버

tag_inner_PROPVARIANT

tag_inner_PROPVARIANT.vt

tag_inner_PROPVARIANT.wReserved1

tag_inner_PROPVARIANT.wReserved2

tag_inner_PROPVARIANT.wReserved3

tag_inner_PROPVARIANT.cVal

tag_inner_PROPVARIANT.bVal

tag_inner_PROPVARIANT.iVal

tag_inner_PROPVARIANT.uiVal

tag_inner_PROPVARIANT.lVal

tag_inner_PROPVARIANT.ulVal

tag_inner_PROPVARIANT.intVal

tag_inner_PROPVARIANT.uintVal

tag_inner_PROPVARIANT.hVal

tag_inner_PROPVARIANT.uhVal

tag_inner_PROPVARIANT.fltVal

tag_inner_PROPVARIANT.dblVal

tag_inner_PROPVARIANT.boolVal

tag_inner_PROPVARIANT.__OBSOLETE__VARIANT_BOOL

tag_inner_PROPVARIANT.scode

tag_inner_PROPVARIANT.cyVal

tag_inner_PROPVARIANT.date

tag_inner_PROPVARIANT.filetime

tag_inner_PROPVARIANT.puuid

tag_inner_PROPVARIANT.pclipdata

tag_inner_PROPVARIANT.bstrVal

tag_inner_PROPVARIANT.bstrblobVal

tag_inner_PROPVARIANT.blob

tag_inner_PROPVARIANT.pszVal

tag_inner_PROPVARIANT.pwszVal

tag_inner_PROPVARIANT.punkVal

tag_inner_PROPVARIANT.pdispVal

tag_inner_PROPVARIANT.pStream

tag_inner_PROPVARIANT.pStorage

tag_inner_PROPVARIANT.pVersionedStream

tag_inner_PROPVARIANT.parray

tag_inner_PROPVARIANT.cac

tag_inner_PROPVARIANT.caub

tag_inner_PROPVARIANT.cai

tag_inner_PROPVARIANT.caui

tag_inner_PROPVARIANT.cal

tag_inner_PROPVARIANT.caul

tag_inner_PROPVARIANT.cah

tag_inner_PROPVARIANT.cauh

tag_inner_PROPVARIANT.caflt

tag_inner_PROPVARIANT.cadbl

tag_inner_PROPVARIANT.cabool

tag_inner_PROPVARIANT.cascode

tag_inner_PROPVARIANT.cacy

tag_inner_PROPVARIANT.cadate

tag_inner_PROPVARIANT.cafiletime

tag_inner_PROPVARIANT.cauuid

tag_inner_PROPVARIANT.caclipdata

tag_inner_PROPVARIANT.cabstr

tag_inner_PROPVARIANT.cabstrblob

tag_inner_PROPVARIANT.calpstr

tag_inner_PROPVARIANT.calpwstr

tag_inner_PROPVARIANT.capropvar

tag_inner_PROPVARIANT.pcVal

tag_inner_PROPVARIANT.pbVal

tag_inner_PROPVARIANT.piVal

tag_inner_PROPVARIANT.puiVal

tag_inner_PROPVARIANT.plVal

tag_inner_PROPVARIANT.pulVal

tag_inner_PROPVARIANT.pintVal

tag_inner_PROPVARIANT.puintVal

tag_inner_PROPVARIANT.pfltVal

tag_inner_PROPVARIANT.pdblVal

tag_inner_PROPVARIANT.pboolVal

tag_inner_PROPVARIANT.pdecVal

tag_inner_PROPVARIANT.pscode

tag_inner_PROPVARIANT.pcyVal

tag_inner_PROPVARIANT.pdate

tag_inner_PROPVARIANT.pbstrVal

tag_inner_PROPVARIANT.ppunkVal

tag_inner_PROPVARIANT.ppdispVal

tag_inner_PROPVARIANT.pparray

tag_inner_PROPVARIANT.pvarVal

decVal

설명

PROPVARIANT 구조체는 VT_DECIMAL 값을 보유할 수도 있습니다.

    DECIMAL       decVal;        //VT_DECIMAL

그러나 DECIMAL 구조체의 값에는 특별한 처리가 필요합니다. DECIMAL 구조체는 전체 PROPVARIANT 구조체와 크기가 동일하며 다른 모든 형식의 값을 보유하는 공용 구조체에 맞지 않습니다. 대신 DECIMAL 구조체의 값은 예약 필드 및 vt 멤버를 포함하여 전체 PROPVARIANT 구조를 차지합니다. 그러나 DECIMAL 구조체의 첫 번째 멤버는 사용되지 않으며 PROPVARIANT 구조체의 vt 멤버와 크기가 같습니다. 따라서 Win32의 Propidl.h 헤더 파일에서 PROPVARIANT 구조 선언은 PROPVARIANT 구조체의 시작 부분에 해당하는 방식으로 decVal 멤버를 정의합니다. 따라서 DECIMAL 구조체의 값을 PROPVARIANT 구조체에 넣려면 값을 decVal 멤버에 로드해야 하며 vt 멤버는 다른 값과 마찬가지로 VT_DECIMAL 설정됩니다.

PROPVARIANTIPropertyStorage 인터페이스를 통해 속성 값을 읽고 쓰는 기본 데이터 형식입니다.

PROPVARIANT 데이터 형식은 OLE2에서 자동화의 일부로 정의된 VARIANT 데이터 형식과 관련이 있습니다. 몇 가지 정의는 다음과 같이 Automation에서 재사용됩니다.

typedef struct  tagCY {
    unsigned long      Lo;
    long               Hi;
    } CY;
 
typedef struct  tagDEC {
    USHORT             wReserved;
    BYTE               scale;
    BYTE               sign;
    ULONG              Hi32;
    ULONGLONG          Lo64;
    } DECIMAL;
 
typedef struct  tagSAFEARRAYBOUND {
    ULONG              cElements;
    LONG               lLbound;
    } SAFEARRAYBOUND;
 
typedef struct  tagSAFEARRAY {
    USHORT             cDims;
    USHORT             fFeatures;
    ULONG              cbElements;
    ULONG              cLocks;
    PVOID              pvData;
    SAFEARRAYBOUND     rgsabound [ * ];
    } SAFEARRAY;
 
typedef CY             CURRENCY;
typedef short          VARIANT_BOOL;
typedef unsigned short VARTYPE;
typedef double         DATE;
typedef OLECHAR*       BSTR;

또한 일부 형식은 PROPVARIANT 구조에 고유합니다.

typedef struct  tagCLIPDATA {
    // cbSize is the size of the buffer pointed to 
    // by pClipData, plus sizeof(ulClipFmt)
    ULONG              cbSize;
    long               ulClipFmt;
    BYTE*              pClipData;
    } CLIPDATA;

고유한 PROPVARIANT 형식 중에는 다른 데이터 형식의 계산된 배열을 정의하는 여러 데이터 형식이 있습니다. 계산된 모든 배열의 데이터 형식은 문자 CA(예: CAUB)로 시작하고 OR 연산자 vt 값(요소의 VarType 및 VT_VECTOROR 연산자)을 갖습니다. 계산된 배열 구조체에는 다음과 같은 형식이 있습니다(여기서 name 은 계산된 배열의 특정 이름임).

#define TYPEDEF_CA(type, name) 
 
    typedef struct tag ## name {\
        ULONG cElems;\
        type *pElems;\
        } name
Propvariant 형식 코드 Propvariant 멤버 값 표현
VT_EMPTY 0 없음 형식 표시기가 VT_EMPTY 속성에는 연결된 데이터가 없습니다. 즉, 값의 크기가 0입니다.
VT_NULL 1 없음 이는 NULL에 대한 포인터와 같습니다.
VT_I1 16 cVal 부인 1 바이트 정수입니다.
VT_UI1 17 bVal 부호 없는 1 바이트 정수입니다.
VT_I2 2 iVal 부가된 2바이트 정수 값을 나타내는 2바이트입니다.
VT_UI2 18 uiVal 부호 없는 2 바이트 정수입니다.
VT_I4 3 lVal 부인 4 바이트 정수 값입니다.
VT_UI4 19 ulVal 4 바이트 부호 없는 정수입니다.
VT_INT 22 intVal 부호 있는 4 바이트 정수 값( VT_I4)입니다.
VT_UINT 23 uintVal 부호 없는 4 바이트 정수( VT_UI4 해당)
VT_I8 20 hVal 8 바이트 부인 정수입니다.
VT_UI8 21 uhVal 8 바이트 부호 없는 정수입니다.
VT_R4 4 fltVal 32비트 IEEE 부동 소수점 값입니다.
VT_R8 5 dblVal 64비트 IEEE 부동 소수점 값입니다.
VT_BOOL 11 boolVal (이전 디자인의 부울 ) 부울 값은 0(FALSE) 또는 -1(TRUE)을 포함하는 WORD입니다.
VT_ERROR 10 Scode 상태 코드를 포함하는 DWORD입니다.
VT_CY 6 cyVal 8 바이트 2의 보수 정수(10,000으로 크기 조정). 이 형식은 일반적으로 통화 금액에 사용됩니다.
VT_DATE 7 date 1899년 12월 31일 이후의 일 수(초가 아님)를 나타내는 64비트 부동 소수점 숫자입니다. 예를 들어 1900년 1월 1일은 2.0, 1900년 1월 2일은 3.0 등입니다. 이는 VT_R8 동일한 표현으로 저장됩니다.
VT_FILETIME 64 Filetime Win32에서 정의한 64비트 FILETIME 구조체입니다. 모든 시간을 UTC(유니버설 좌표 시간)에 저장하는 것이 좋습니다.
VT_CLSID 72 puuid CLSID(클래스 식별자) 또는 기타 GUID(Globally Unique Identifier)에 대한 포인터입니다.
VT_CF 71 pclipdata 위에서 설명한 CLIPDATA 구조체에 대한 포인터입니다.
VT_BSTR 8 bstrVal null로 끝나는 유니코드 문자열에 대한 포인터입니다. 문자열 바로 앞에 바이트 수를 나타내는 DWORD 가 있지만 bstrVal 은 이 DWORD 를 지나 문자열의 첫 번째 문자를 가리킵니다. BSTR은 Automation SysAllocString 및 SysFreeString 호출을 사용하여 할당되고 해제되어야 합니다.
VT_BSTR_BLOB 0xfff bstrblobVal 시스템에서만 사용됩니다.
VT_BLOB 65 blob DWORD 바이트 수, 그 뒤에 많은 바이트 데이터가 잇습니다. 바이트 수에는 개수 자체의 길이에 대한 4바이트가 포함되지 않습니다. 빈 Blob 멤버의 개수는 0, 0바이트입니다. 이는 VT_BSTR 값과 비슷하지만 데이터 끝에 null 바이트를 보장하지는 않습니다.
VT_BLOBOBJECT 70 blob VT_STREAMED_OBJECT 표시되는 동일한 표현의 직렬화된 개체를 포함하는 Blob 멤버입니다. 즉, 클래스 식별자 형식과 해당 클래스의 초기화 데이터 형식인 DWORD 바이트 수(바이트 수에 자체 크기가 포함되지 않음)입니다.

VT_BLOB_OBJECT VT_STREAMED_OBJECT 간의 유일한 중요한 차이점은 전자는 후자가 가질 시스템 수준 스토리지 오버헤드가 없으므로 작은 개체의 수와 관련된 시나리오에 더 적합하다는 것입니다.

VT_LPSTR 30 pszVal 시스템 기본 코드 페이지에서 null로 끝나는 ANSI 문자열에 대한 포인터입니다.
VT_LPWSTR 31 pwszVal 사용자 기본 로캘에서 null로 끝나는 유니코드 문자열에 대한 포인터입니다.
VT_UNKNOWN 13 punkVal 새로 만들기.
VT_DISPATCH 9 pdispVal 새로 만들기.
VT_STREAM 66 pStream "Contents" 스트림의 형제인 스트림을 나타내는 IStream 인터페이스에 대한 포인터입니다.
VT_STREAMED_OBJECT 68 pStream VT_STREAM 마찬가지로 스트림에 CLSID와 클래스에 대한 초기화 데이터인 직렬화된 개체가 포함되어 있음을 나타냅니다. 스트림은 속성 집합을 포함하는 "Contents" 스트림의 형제입니다.
VT_STORAGE 67 pStorage "Contents" 스트림의 형제인 스토리지 개체를 나타내는 IStorage 인터페이스에 대한 포인터입니다.
VT_STORED_OBJECT 69 pStorage VT_STORAGE 마찬가지로 지정된 IStorage에 로드 가능한 개체가 포함되어 있음을 나타냅니다.
VT_VERSIONED_STREAM 73 pVersionedStream GUID 버전이 있는 스트림입니다.
VT_DECIMAL 14 decVal DECIMAL 구조체입니다.
VT_VECTOR 0x1000 Ca* 형식 표시기가 OR 연산자를 사용하여 VT_VECTOR 결합된 경우 값은 계산된 배열 값 중 하나입니다. 그러면 요소의 DWORD 개수가 생성되고 그 뒤에 값의 지정된 반복에 대한 포인터가 표시됩니다.

예를 들어 VT_LPSTR VT_VECTOR| 형식 표시기의 DWORD 요소 수와 LPSTR 요소 배열에 대한 포인터가 있습니다.

VT_VECTOROR 연산자가 결합할 수 있는 형식은 VT_I1VT_UI1, VT_I2, VT_UI2, VT_BOOL, VT_I4, VT_UI4, VT_R4, VT_R8, VT_ERROR, VT_I8, VT_UI8, VT_CY, VT_DATE, VT_FILETIME, VT_CLSID, VT_CF, VT_BSTR, VT_LPSTR, VT_LPWSTRVT_VARIANT. VT_VECTORVT_BSTR_BLOB OR산으로 결합할 수도 있지만 시스템용으로만 사용됩니다.

VT_ARRAY 0x2000 Parray 형식 표시기가 OR 연산자에 의해 VT_ARRAY 결합된 경우 값은 SAFEARRAY에 대한 포인터입니다. VT_ARRAYVT_I1, VT_UI1, VT_I2, VT_UI2, VT_I4, VT_UI4, VT_INT, VT_UINT, VT_R4, VT_R8, VT_BOOL, VT_DECIMAL, VT_ERROR, VT_CY, VT_DATE, VT_BSTR, VT_DISPATCH, VT_UNKNOWN, VT_VARIANT 데이터 형식으로 OR을 사용할 수 있습니다. VT_ARRAYVT_VECTOR OR을 사용할 수 없습니다.
VT_BYREF 0x4000 P* 형식 표시기가 OR 연산자에 의해 VT_BYREF 결합된 경우 값은 참조입니다. 참조 형식은 C++의 참조 형식(예: "int&")과 유사한 데이터에 대한 참조로 해석됩니다.

VT_BYREF VT_I1, VT_UI1, VT_I2, VT_UI2, VT_I4, VT_UI4, VT_INT, VT_UINT, VT_R4, VT_R8, VT_BOOL, VT_DECIMAL, VT_ERROR, VT_CY, VT_DATE, VT_BSTR, VT_UNKNOWN, VT_DISPATCH, VT_ARRAY, VT_VARIANT 형식으로 OR을 사용할 수 있습니다.

VT_VARIANT 12 capropvar DWORD 형식 표시기 뒤에 해당 값이 잇습니다. VT_VARIANT VT_VECTOR 또는 VT_BYREF 사용할 수 있습니다.
VT_TYPEMASK 0xFFF   원시 VT 값을 추출하기 위해 VT_VECTOR 및 기타 한정자에 대한 마스크로 사용됩니다.
 

태그 VT_CF 저장된 클립보드 형식 식별자는 특정 데이터 형식에 대한 pClipData 포인터를 사용하여 CLIPDATA 구조체의 ulClipFmt 멤버에서 식별된 5가지 표현 중 하나를 사용합니다.

ulClipFmt pClipData
-1L 기본 제공 Windows 클립보드 형식 값이 포함된 DWORD 입니다.
-2L Macintosh 클립보드 형식 값이 포함된 DWORD 입니다.
-3l FMTID(형식 식별자)를 포함하는 GUID입니다. 이는 거의 사용되지 않습니다.
양수 값 RegisterClipboardFormat 함수에 전달하는 데 적합한 Windows 클립보드 형식 이름을 포함하는 null로 끝나는 문자열입니다. 이 함수는 새 클립보드 형식을 등록합니다. 지정된 이름의 등록된 형식이 이미 있는 경우 새 형식이 등록되지 않고 반환 값이 기존 형식을 식별합니다. 이렇게 하면 둘 이상의 애플리케이션이 동일한 등록된 클립보드 형식을 사용하여 데이터를 복사하여 붙여넣을 수 있습니다. 형식 이름 비교는 대/소문자를 구분하지 않으며 0xC000부터 0xFFFF 범위의 값으로 식별됩니다. 문자열의 문자에 사용되는 코드 페이지는 코드 페이지 표시기를 기준으로 합니다. 여기서 "양수 값"은 끝에 null 바이트를 포함하여 문자열 길이입니다. 레지스터 클립보드 형식을 클립보드에 배치하거나 클립보드에서 검색하는 경우 개체에 대한 핸들을 제공하는 HGLOBAL 데이터 형식 값 형식이어야 합니다.
0L 데이터가 없습니다(거의 사용되지 않음).
 

ulClipFmt 멤버의 값이 -1이면 데이터는 기본 제공 Windows 형식의 형식입니다. 이 경우 pClipData가 가리키는 버퍼의 첫 번째 DWORD는 클립보드 형식 식별자입니다(예: CF_METAFILEPICT). CF_METAFILEPCT 경우 다음은 METAFILEPICT 구조체의 변형입니다(DWORD 데이터 형식이 아닌 WORD 사용). 즉, 이 데이터는 다음과 같은 형식입니다.

struct PACKEDMETA
{
    WORD mm;
    WORD xExt;
    WORD yExt
    WORD reserved;
};

METAFILEPICT 구조체가 메타파일 데이터인 후 SetMetaFileBitsEx 함수에 전달하기에 적합합니다. 이 함수는 제공된 데이터에서 메모리 기반 Windows 형식 메타파일을 만듭니다. 이 함수는 16비트 버전의 Windows와의 호환성을 위해 제공됩니다. Win32 기반 애플리케이션은 SetEnhMetaFileBits 함수를 사용해야 합니다. 이 함수는 지정된 고급 형식 메타파일의 내용을 검색하고 버퍼에 복사합니다. 함수가 성공하고 버퍼 포인터가 NULL이면 반환 값은 향상된 메타파일의 크기(바이트)입니다. 함수가 성공하고 버퍼 포인터가 유효한 포인터인 경우 반환 값은 버퍼에 복사된 바이트 수입니다. 함수가 실패하면 반환 값은 0입니다.

레지스터 클립보드 형식이 클립보드에 배치되거나 클립보드에서 검색되는 경우 HGLOBAL 값 형식이어야 합니다.

요구 사항

요구 사항
지원되는 최소 클라이언트 Windows 2000 Professional [데스크톱 앱 | UWP 앱]
지원되는 최소 서버 Windows 2000 Server [데스크톱 앱 | UWP 앱]
머리글 propidlbase.h(Propidl.h 포함)