IPropertyStorage::WriteMultiple 메서드(propidl.h)

아티클
03/01/2024

WriteMultiple 메서드는 지정된 속성 그룹을 현재 속성 집합에 씁니다. 지정된 이름 또는 속성 식별자가 있는 속성이 이미 있는 경우 속성 값의 이전 형식과 새 형식이 다른 경우에도 대체됩니다. 지정된 이름 또는 속성 ID의 속성이 없으면 만들어집니다.

구문

HRESULT WriteMultiple(
  [in] ULONG                cpspec,
  [in] const PROPSPEC []    rgpspec,
  [in] const PROPVARIANT [] rgpropvar,
  [in] PROPID               propidNameFirst
);

매개 변수

[in] cpspec

설정된 속성 수입니다. 이 매개 변수의 값은 0으로 설정할 수 있습니다. 그러나 이렇게 하면 속성이 기록되지 않을 때 메서드의 목적이 무효화됩니다.

[in] rgpspec

속성이 설정된 속성 ID(PROPSPEC)의 배열입니다. 이러한 항목은 특정 순서가 아니어야 하며 중복 항목이 포함될 수 있지만 마지막으로 지정된 속성 ID는 적용됩니다. 속성 ID와 문자열 이름의 혼합이 허용됩니다.

[in] rgpropvar

작성할 속성 값이 포함된 PROPVARIANT 구조체의 배열(cpspec 크기)입니다. 배열은 cpspec에서 지정한 크기여야 합니다.

[in] propidNameFirst

rgpspec 매개 변수가 현재 속성 ID가 없는 문자열 이름 속성을 지정하는 경우 메서드가 할당해야 하는 속성 ID의 최소값입니다. 지정된 모든 문자열 이름 속성이 이 집합에 이미 있으므로 속성 ID가 이미 있는 경우 이 값은 무시됩니다. 무시하지 않는 경우 이 값은 2보다 크거나 같아야 하며 0x80000000 미만이어야 합니다. 속성 ID 0 및 1 및 0x80000000 이상은 특별히 사용하도록 예약되어 있습니다.

반환 값

이 메서드는 다음 외에도 E_UNEXPECTED 표준 반환 값을 지원합니다.

이 함수는 HRESULT 데이터 형식으로 래핑된 파일 시스템 오류 또는 Win32 오류를 반환할 수도 있습니다. 자세한 내용은 오류 처리 전략을 참조하세요.

설명

지정된 속성이 이미 있는 경우 속성 값의 이전 형식과 새 형식이 다른 경우에도 해당 값은 rgpspec에 지정된 값으로 바뀝니다. 지정된 속성이 아직 없으면 해당 속성이 만들어집니다. 변경 내용은 IPropertyStorage::Commit이 호출될 때까지 기본 스토리지에 유지되지 않습니다.

속성 이름은 속성 집합의 특수 사전 섹션에 저장되며, 이러한 이름은 속성 ID에 매핑됩니다. 모든 속성에는 ID가 있지만 이름은 선택 사항입니다. 문자열 이름은 PROPSPEC 구조체의 ulKind 멤버에 PRSPEC_LPWSTR 지정하여 제공됩니다. 속성에 문자열 이름이 제공되고 이름이 사전에 아직 없는 경우 메서드는 속성 ID를 할당하고 속성 ID와 이름을 사전에 추가합니다. 속성 ID는 속성 집합의 다른 ID와 충돌하지 않는 방식으로 할당됩니다. 속성 ID의 값도 propidNameFirst 매개 변수에 지정된 값보다 작지 않습니다. rgpspec 매개 변수가 현재 속성 ID가 없는 문자열 이름 속성을 지정하는 경우 propidNameFirst 매개 변수는 WriteMultiple 메서드가 할당해야 하는 속성 ID의 최소값을 지정합니다.

새 속성 집합이 만들어지면 특수 코드 페이지(속성 ID 1) 및 로캘 ID(속성 ID 0x80000000) 속성이 속성 집합에 자동으로 기록됩니다. 이후에는 헤더 정의 PID_CODEPAGE 및 PID_LOCALE 값으로 속성 ID를 지정하여 IPropertyStorage::ReadMultiple 메서드를 사용하여 이러한 속성을 읽을 수 있습니다. 속성 집합이 비어 있지 않거나 코드 페이지 및 로캘 ID 속성 외에 하나 이상의 속성이 있거나 사전에 이름이 하나 이상 있는 경우 IPropertyStorage::WriteMultiple을 호출하여 특수 코드 페이지 및 로캘 ID 속성을 수정할 수 없습니다. 그러나 속성 집합이 비어 있으면 이러한 특수 속성 중 하나 또는 둘 다를 수정할 수 있습니다.

rgspec 배열의 요소가 0xffffffff(PID_ILLEGAL)의 PRSPEC_PROPID 값으로 설정된 경우 rgvar 배열의 해당 값은 IPropertyStorage::WriteMultiple에서 무시됩니다. 예를 들어 이 메서드가 cspec 매개 변수를 3으로 설정하지만 rgpspec[1].prspec 이 PRSPEC_PROPID 설정되고 rgpspec[1].propid 가 PID_ILLEGAL 설정되면 두 개의 속성만 기록됩니다. rgpropvar[1] 요소는 자동으로 무시됩니다.

PropVariantInit 매크로를 사용하여 PROPVARIANT 구조를 초기화합니다.

비심플 속성에 대한 데이터를 포함하지 않는 속성 집합은 Windows NT 4.0 이하의 경우 크기가 256KB로 제한됩니다. Windows 2000, Windows XP 및 Windows Server 2003의 경우 OLE 속성 집합은 1MB로 제한됩니다. 이러한 제한을 초과하면 작업이 실패하고 호출자가 오류 메시지를 받습니다. 메모리 누수 또는 오버런의 가능성은 없습니다. 자세한 내용은 속성 집합 관리를 참조하세요.

PROPSETFLAG_CASE_SENSITIVE IPropertySetStorage::Create에 전달되지 않는 한 속성 집합 이름은 대/소문자를 구분하지 않습니다. IPropertyStorage::WriteMultiple에서 해당 이름으로 속성을 지정하면 속성 집합의 이름을 대/소문자를 구분하지 않습니다. 대/소문자를 구분하지 않는 문자열을 비교하려면 문자열의 로캘을 알고 있어야 합니다. 자세한 내용은 IPropertyStorage::WritePropertyNames를 참조하세요.

자세한 내용은 속성 스토리지 고려 사항을 참조하세요.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows 2000 Professional [데스크톱 앱 \| UWP 앱]
지원되는 최소 서버	Windows 2000 Server [데스크톱 앱 \| UWP 앱]
대상 플랫폼	Windows
헤더	propidl.h(Objbase.h, Propidlbase.h 포함)
라이브러리	Uuid.lib
DLL	Ole32.dll