реализация файла IPropertyStorage-Compound
Реализация COM архитектуры структурированного хранилища называется составных файлов. Объекты хранилища, реализованные в составных файлах, включают реализацию IPropertyStorage, интерфейс, который управляет одним набором постоянных свойств, и IPropertySetStorage, интерфейс, который управляет группами постоянных наборов свойств. Дополнительные сведения об интерфейсе IPropertyStorage см. в IPropertyStorage и рекомендации по хранилищу свойств.
Чтобы получить указатель на составную реализацию файла 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. В любом случае возвращается указатель на интерфейса IStor age объекта. При использовании постоянных наборов свойств вызовите QueryInterfaceдля интерфейса IPropertySetStorage, указав имя, определенное заголовком для IID_IPropertySetStorage идентификатора интерфейса (IID).
Когда следует использовать
Используйте IPropertyStorage для управления свойствами в одном наборе свойств. Его методы поддерживают чтение, запись и удаление как свойств, так и необязательные имена строк, которые могут быть связаны с идентификаторами свойств. Другие методы поддерживают стандартные операции фиксации и восстановления хранилища. Существует также метод, позволяющий задать время, связанное с хранилищем свойств, и другой, который разрешает назначение CLSID, который можно использовать для связывания другого кода, например кода пользовательского интерфейса, с набором свойств. Вызов метода Enum предоставляет указатель на составную реализацию файла IEnumSTATPROPSTG, что позволяет перечислить свойства в наборе.
Заметка
Если вы получите указатель на IPropertyStorage путем вызова StgCreateDocfile, StgCreateStorageEx, StgOpenStorage или StgOpenStorageEx в хранилище свойств простого режима, методы IPropertyStorage соответствуют правилам простых потоков. Хранилище набора свойств является простым режимом, если он был получен для файла, созданного или открытого с помощью флага STGM_SIMPLE. В этом случае невозможно сделать базовый поток более большим, и невозможно заменить существующие свойства большими свойствами. Дополнительные сведения см. в IPropertySetStorage-Compoundреализации файлов.
IPropertyStorage и кэширование
Составная реализация файла IPropertyStorage кэширует открытые наборы свойств в памяти, чтобы повысить производительность. В результате изменения набора свойств не записываются в составной файл, пока методы Commit или Release (последняя ссылка).
Наборы свойств simple Mode
Объект хранилища свойств находится в простом режиме, если он создается из объекта хранилища набора свойств простого режима. Например, объект хранилища набора свойств будет находиться в простом режиме, если он был получен из функции stgOpenStorageEx с флагом STGM_SIMPLE в параметре grfMode. Обратите внимание, что "простой режим" не связан с "простыми наборами свойств". Набор свойств прост, если он создается путем вызова IPropertySetStorage::Create с флагом PROPSETFLAG_NONSIMPLE, заданным в параметре grfFlags. Дополнительные сведения о простых и неимплевых наборах свойств см. в разделе хранилища и объектов Stream для набора свойств.
При создании объекта хранилища свойств простого режима нет ограничений на его использование. Когда открывается существующий объект хранилища свойств простого режима, базовый объект потока, в который хранится набор свойств, невозможно увеличить. Следовательно, невозможно изменить такой объект хранилища свойств, если для изменения требуется более крупный поток.
Форматы набора свойств
Реализация составного файла IPropertyStorage поддерживает форматы сериализации набора свойств версии 0 и версии 1. Формат версии 1 поддерживается на компьютерах под управлением Windows 2000. Дополнительные сведения см. в сериализации набора свойств. Наборы свойств создаются в формате 0 и остаются в этом формате, если новые функции не запрашиваются. При этом формат обновляется до версии 1.
Например, если набор свойств создается с флагом PROPSETFLAG_DEFAULT, его формат — версия 0. Если типы свойств, соответствующие формату версии 0, записываются и считываются из этого набора свойств, набор свойств остается в формате версии 0. Если тип свойства версии 1 записывается в набор свойств, набор свойств автоматически обновляется до версии 1. Впоследствии этот набор свойств больше не может читаться реализациями, которые распознают только версию 0.
IPropertyStorage и типы вариантов
Реализация составного файла IPropertyStorage не поддерживает типы вариантов VT_UNKNOWN или VT_DISPATCH в элементе vt структуры PROPVARIAN T.
В следующей таблице перечислены типы вариантов, поддерживаемые в SafeArray; То есть эти значения можно объединить с VT_ARRAY в элементе vt vt структуры PROPVARIANT.
Типы вариантов, поддерживаемые в 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 в наборе свойств, отличных отimple (который может юридически содержать свойства хранилища или значения потока, как описано в IPropertySetStorage::Create) также задает CLSID в базовом подзаборе, чтобы его можно было получить с помощью вызова IStorage::Stat.
-
Для простых и неимплевых наборов свойств сбрасывает образ памяти в базовое хранилище. Кроме того, для наборов свойств transacted-mode nonsimple этот метод выполняет фиксацию (как в IStorage::Commit) в хранилище, которое содержит набор свойств.
-
Только для наборов свойств nonsimple вызывает метод Revert базового хранилища и повторно открывает поток "содержимое". Для простых наборов свойств этот интерфейс всегда возвращает S_OK. Наборы свойств nonsimple — это те, которые были созданы с помощью флага PROPSETFLAG_NONSIMPLE в метод е IPropertySetStorage::Create. Дополнительные сведения см. в разделе хранилища и потоковой передачи объектов для набора свойств.
-
Создает экземпляр IEnumSTATPROPSTG, методы которого можно вызывать для перечисления структур STATPROPSTG, которые предоставляют сведения о каждом из свойств в наборе. Эта реализация создает массив, в который выполняется чтение всего набора свойств и который можно совместно использовать при вызове IEnumSTATPROPSTG::Clone. Изменения набора свойств не отражаются в открытом экземпляре IEnumSTATPROPSTG. Чтобы увидеть такие изменения, необходимо создать новый экземпляр перечислителя.
-
Заполняет элементы структуры STATPROPSETSTG, которая содержит данные о наборе свойств в целом. При возврате предоставляет указатель на структуру. Для наборов хранилища, отличных от неимплей, эта реализация вызывает IStorage::Stat (или IStream::Stat), чтобы получить время от базового хранилища или потока. Для простых наборов хранилища время не сохраняется.
-
Только для наборов свойств nonsimple задает время, поддерживаемое базовым хранилищем. Реализация составного хранилища файлов поддерживает все три: изменение, доступ и создание. Эта реализация SetTimes вызывает метод IStorage::SetElementTimes базового хранилища, чтобы получить это время.
Связанные разделы