Serializacja zestawu właściwości

Istnieją dwie wersje formatu serializacji zestawu właściwości. Oryginalna specyfikacja opisuje wersję 0 formatu. Aby uzyskać więcej informacji, zobacz format wersji. Wersja 1 rozszerza oryginalną wersję. Wszystkie zestawy właściwości w wersji 0 są prawidłowe jako zestawy właściwości w wersji 1. Pole Format Version w nagłówku zestawu właściwości serializowanej wskazuje wersję.

Poniższe elementy identyfikują różnice między formatami serializacji właściwości w wersji 0 i wersji 1.

• Obsługa nowych wartości VARTYPE. Aby uzyskać więcej informacji na temat wartości VARTYPE i sposobu ich używania, zobacz temat IDispatch Data Types and Structures oraz STRUKTURY PROPVARIANT.

  Następujące wartości VARTYPE nie są obsługiwane w zestawach właściwości w wersji 0, ale są obsługiwane w wersji 1:

  VT_I1

  VT_VECTOR | VT_I1

  VT_INT

  VT_UINT

  VT_DECIMAL

  Ponadto w zestawie właściwości można serializować safearrays. Obecność elementu SafeArray jest wskazywana przez połączony bit VT_ARRAY przy użyciu operacji OR lub, a elementy tablicy w vt składowej struktury PROPVARIANT. Na przykład liczba całkowita ze znakiem 4 bajtów ma typ VT_ARRAY | VT_I4.

  Następujące typy elementów są prawidłowe dla klasy SafeArray w serializowanym zestawie właściwości:

  VT_I1	VT_UI1	VT_I2	VT_UI2
  VT_I4	VT_UI4	VT_INT	VT_UINT
  VT_R4	VT_R8	VT_CY	VT_DATE
  VT_BSTR	VT_BOOL	VT_DECIMAL	VT_ERROR
  VT_VARIANT

  Po określeniu typu danych VT_VARIANT wskazuje, że sam plik SafeArray przechowuje struktury PROPVARIANT. Typy tych elementów muszą pochodzić z powyższej listy, z wyjątkiem tego, że nie mogą zawierać zagnieżdżonych typów VT_VARIANT.

  Należy pamiętać, że implementacje IPropertyStorage muszą być w stanie bezpiecznie odzyskać, zwracając błąd po napotkaniu nowego typu; na przykład typy VARENUM.

• Nazwy właściwości uwzględniających wielkość liter. Nazwy właściwości, na przykład określone w IPropertyStorage::WritePropertyNames metodzie, nie są uwzględniane wielkości liter w zestawach właściwości w wersji 0. W zestawach właściwości w wersji 1 nazwy właściwości mogą być uwzględniane w wielkości liter w zależności od wartości nowej właściwości Zachowanie.

  Właściwość Zachowanie jest identyfikator właściwości 0x80000003 z typem VT_UI4. Jeśli ustawiono najniższy bit tej wartości, w nazwach zestawów właściwości jest rozróżniana wielkość liter. Ustaw flagę PROPSETFLAG_CASE_SENSITIVE w grfFlags parametru IPropertySetStorage::Create, aby określić zestaw właściwości uwzględniających wielkość liter.

• Długie nazwy właściwości. Nazwy właściwości dla zestawów właściwości w wersji 0 muszą być mniejsze lub równe 256 znaków, w tym terminator ciągu, dla zestawów właściwości na stronie kodowej Unicode. Jeśli nie znajduje się na stronie kodowej Unicode, muszą być mniejsze niż 256 bajtów. Z drugiej strony zestawy właściwości w wersji 1 mogą mieć nazwy właściwości o nieograniczonej długości, chociaż są one nadal ograniczone przez ogólny limit rozmiaru zestawu właściwości 256 kilobajtów (KB).

Zaleca się, aby implementacje IPropertyStorage tworzyć i obsługiwać zestawy właściwości w wersji 0 domyślnie. Jeśli obiekt wywołujący następnie zażąda funkcji specyficznej dla formatu wersji 1, tylko wtedy należy zaktualizować wersję zestawu właściwości. Jeśli na przykład jest zapisywana właściwość typu VT_ARRAY lub długa nazwa właściwości jest zapisywana, implementacja powinna zaktualizować format zestawu właściwości na wersję 1. Jeden wyjątek od tej wskazówki występuje, jeśli wartość wyliczenia PROPSETFLAG_CASE_SENSITIVE jest określona w wywołaniu IPropertySetStorage::Create. W takim przypadku zestaw właściwości musi zostać utworzony jako zestaw właściwości w wersji 1.