Реализация файла IPropertyStorage-Compound
Com-реализация архитектуры структурированного хранилища называется составной файлами. Объекты хранения, реализованные в составных файлах, включают реализацию интерфейса IPropertyStorage, который управляет одним постоянным набором свойств, и IPropertySetStorage, интерфейса, который управляет группами постоянных наборов свойств. Дополнительные сведения об интерфейсе IPropertyStorage см. в разделах IPropertyStorage и Property Storage Considerations.
Чтобы получить указатель на реализацию составного файла IPropertyStorage, вызовите StgCreateStorageEx , чтобы создать новый составной файловый объект, или StgOpenStorageEx , чтобы открыть ранее созданный составной файловый объект. В случае StgCreateStorageExпараметру stgfmt следует задать значение STGFMT_STORAGE. В случае StgOpenStorageExпараметру stgfmt следует задать значение STGFMT_STORAGE или STGFMT_ANY. В обоих случаях параметру riid следует задать значение IID_IPropertySetStorage. Обе функции предоставляют указатель на интерфейс объекта IPropertySetStorage . Вызвав метод Create или Open этого интерфейса, вы получите указатель на интерфейс IPropertyStorage , который можно использовать для вызова любого из его методов.
Альтернативным способом получения указателя на реализацию составного файла IPropertySetStorage является вызов старых функций StgCreateDocfile и StgOpenStorage или указание параметра riid IID_IStorage функции StgCreateStorageEx или StgOpenStorageEx . В любом случае возвращается указатель на интерфейс IStorage объекта. При использовании постоянных наборов свойств вызовите QueryInterface для интерфейса IPropertySetStorage , указав определенное заголовком имя для идентификатора интерфейса (IID) IID_IPropertySetStorage.
Назначение
Используйте IPropertyStorage для управления свойствами в одном наборе свойств. Его методы поддерживают чтение, запись и удаление свойств и необязательных строковых имен, которые могут быть связаны с идентификаторами свойств. Другие методы поддерживают стандартные операции фиксации и отменить изменения хранения. Существует также метод, позволяющий задать время, связанное с хранилищем свойств, и другой, который позволяет назначать ИДЕНТИФИКАТОР CLSID, который можно использовать для связывания другого кода, например кода пользовательского интерфейса, с набором свойств. Вызов метода Enum предоставляет указатель на реализацию составного файла IEnumSTATPROPSTG, которая позволяет перечислять свойства в наборе.
Примечание
Если вы получаете указатель на IPropertyStorage путем вызова StgCreateDocfile, StgCreateStorageEx, StgOpenStorage или StgOpenStorageEx в хранилище набора свойств простого режима, методы IPropertyStorage соответствуют правилам потоков в простом режиме. Хранилище набора свойств является простым, если оно было получено для файла, который был создан или открыт с флагом STGM_SIMPLE. В этом случае не всегда можно увеличить базовый поток и заменить существующие свойства более крупными свойствами. Дополнительные сведения см. в разделе Реализация составного файла IPropertySetStorage.
IPropertyStorage и кэширование
Реализация составного файла IPropertyStorage кэширует открытые наборы свойств в памяти для повышения производительности. В результате изменения набора свойств не записываются в составной файл до тех пор, пока не будут вызваны методы Commit или Release (последняя ссылка).
Наборы свойств простого режима
Объект хранилища свойств находится в простом режиме, если он создается из объекта хранения набора свойств простого режима. Например, объект хранилища набора свойств будет находиться в простом режиме, если он был получен из функции StgOpenStorageEx с флагом STGM_SIMPLE, установленным в параметре grfMode . Обратите внимание, что "простой режим" не связан с "простыми наборами свойств". Набор свойств прост, если он создается путем вызова IPropertySetStorage::Create с флагом PROPSETFLAG_NONSIMPLE, установленным в параметре grfFlags . Дополнительные сведения о простых и неимплях наборах свойств см. в разделе Storage and Stream Objects for a Property Set.
При создании объекта хранилища свойств простого режима нет никаких ограничений на его использование. При открытии существующего объекта хранилища свойств в простом режиме невозможно создать базовый объект потока, в котором хранится набор свойств. Следовательно, изменить такой объект хранилища свойств не всегда возможно, если для изменения требуется более крупный поток.
Форматы набора свойств
Реализация составного файла IPropertyStorage поддерживает форматы сериализации наборов свойств версии 0 и версии 1. Формат версии 1 поддерживается на компьютерах под управлением Windows 2000. Дополнительные сведения см. в разделе Сериализация набора свойств. Наборы свойств создаются в формате версии 0 и остаются в этом формате, если не будут запрошены новые функции. В этом случае формат обновляется до версии 1.
Например, если набор свойств создается с флагом PROPSETFLAG_DEFAULT, его формат — версия 0. Пока типы свойств, соответствующие формату версии 0, записываются и считываются из этого набора свойств, набор свойств остается в формате версии 0. Если тип свойства версии 1 записывается в набор свойств, набор свойств автоматически обновляется до версии 1. Впоследствии этот набор свойств больше не может быть прочитан реализациями, которые распознают только версию 0.
Типы IPropertyStorage и Variant
Реализация составного файла IPropertyStorage не поддерживает типы вариантов VT_UNKNOWN или VT_DISPATCH в элементе vt структуры PROPVARIANT .
В следующей таблице перечислены вариантные типы, поддерживаемые в SafeArray; то есть эти значения можно объединить с VT_ARRAY в элементе vt структуры PROPVARIANT .
Типы variant, поддерживаемые в SafeArray реализацией составного файла IPropertyStorage
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
Когда VT_VARIANT сочетается с VT_ARRAY, safeArray сам содержит структуры PROPVARIANT . Однако типы этих элементов должны быть взяты из предыдущего списка, не могут быть VT_VARIANT и включать индикаторы VT_VECTOR, VT_ARRAY или VT_BYREF.
Методы IPropertyStorage
Реализация составного файла IPropertyStorage поддерживает следующие методы:
-
Считывает свойства, указанные в массиве rgpspec , и предоставляет значения всех допустимых свойств в массиве rgvar PROPVARIANTs. В реализации составного com-файла повторяющиеся идентификаторы свойств, ссылающиеся на поток или типы хранилища, приводят к нескольким вызовам IStorage::OpenStream или IStorage::OpenStorage , а успех или сбой ReadMultiple зависит от способности базовой реализации хранилища совместно использовать операции открытия. Так как в составном файле STGM_SHARE_EXCLUSIVE является принудительным, несколько открытых попыток завершатся ошибкой. Открытие одного и того же объекта хранилища несколько раз из одного родительского хранилища не поддерживается. Необходимо указать флаг STGM_SHARE_EXCLUSIVE.
Кроме того, чтобы обеспечить потокобезопасную операцию, если одно и то же свойство с значением потока или хранилища запрашивается несколько раз через один и тот же указатель IPropertyStorage в реализации составного com-файла, операция открытия будет выполнена или завершится сбоем в зависимости от того, открыто ли свойство уже и обрабатывает ли базовая файловая система несколько открытий потока или хранилища. Таким образом, операция ReadMultiple в свойстве со значением потока или хранилища всегда приводит к вызову IStorage::OpenStream или IStorage::OpenStorage, который передает доступ (STGM_READWRITE и т. д.) и флаги общего доступа (STGM_SHARE_EXCLUSIVE и т. д.), указанные при открытии или создании исходного набора свойств.
Если метод завершается сбоем, значения, записанные в rgvar[], не определены. Если некоторые свойства, возвращаемые потоком или хранилищем, успешно открыты, но до завершения выполнения возникает ошибка, они должны быть освобождены до возврата метода.
-
Записывает свойства, указанные в массиве rgpspec[], присваивая им теги PROPVARIANT и значения, указанные в rgvar[]. Уже существующим свойствам присваиваются указанные значения PROPVARIANT . Создаются свойства, которые в настоящее время не существуют.
-
Удаляет свойства, указанные в rgpspec[].
-
Считывает существующие строковые имена, связанные с идентификаторами свойств, указанными в массиве rgpropid[].
-
Присваивает имена строк, указанные в массиве rglpwstrName идентификаторам свойств, указанным в массиве rgpropid .
-
Удаляет имена свойств, указанных в массиве rgpropid[].
-
Задает ИДЕНТИФИКАТОР CLSID потока набора свойств. В реализации составного файла задание CLSID в неимплярном наборе свойств (который может содержать свойства с значением хранилища или потока, как описано в разделе IPropertySetStorage::Create) также задает ИДЕНТИФИКАТОР CLSID для базового подчиненного хранилища, чтобы его можно было получить с помощью вызова IStorage::Stat.
-
Как для простых, так и для неимпляционных наборов свойств сбрасывает образ памяти набора свойств в базовое хранилище. Кроме того, для неимплированных наборов свойств в режиме транзакций этот метод выполняет фиксацию (как в IStorage::Commit) в хранилище, которое содержит набор свойств.
-
Только для неимплейных наборов свойств вызывает метод Revert базового хранилища и повторно открывает поток "содержимое". Для простых наборов свойств этот интерфейс всегда возвращает S_OK. Наборы свойств nonsimple — это наборы свойств, созданные с помощью флага PROPSETFLAG_NONSIMPLE в методе IPropertySetStorage::Create . Дополнительные сведения см. в разделе Storage and Stream Objects for a Property Set .
-
Создает экземпляр IEnumSTATPROPSTG, методы которого можно вызвать для перечисления структур STATPROPSTG , предоставляющих сведения о каждом из свойств в наборе. Эта реализация создает массив, в который считывается весь набор свойств и который можно совместно использовать при вызове метода IEnumSTATPROPSTG::Clone . Изменения набора свойств не отражаются в открытом экземпляре IEnumSTATPROPSTG . Чтобы увидеть такие изменения, необходимо создать новый экземпляр этого перечислителя.
-
Заполняет элементы структуры STATPROPSETSTG , которая содержит данные о наборе свойств в целом. При возврате передает указатель на структуру. Для неимплейных наборов хранилищ эта реализация вызывает IStorage::Stat (или IStream::Stat), чтобы получить время из базового хранилища или потока. Для простых наборов хранилища время не поддерживается.
-
Только для неимплейных наборов свойств задает время, поддерживаемое базовым хранилищем. Реализация составного хранилища файлов поддерживает все три типа: изменение, доступ и создание. Эта реализация SetTimes вызывает метод IStorage::SetElementTimes базового хранилища, чтобы получить эти значения времени.
Связанные темы