Структурированное хранилище в MAPI
Область применения: Outlook 2013 | Outlook 2016
Структурированное хранилище — это иерархическая организация хранилища, представленная с помощью COM. В структурированной среде хранения хранилище организовано в два или три типа объектов:
объекты Stream
Блокировка объектов байтов
Объекты хранилища
Stream и байт блокировки — это объекты более низкого уровня, которые напрямую обращаются к данным. Stream объекты реализуют интерфейс IStream, который определяет методы чтения, записи, позиционирования и копирования байтов данных. Объекты блокировки байтов реализуют другой COM-интерфейс ILockBytes для доступа к данным с массивом байтов. Массивы байтов обычно используются для предоставления настраиваемого доступа к базовому хранилищу.
Объекты хранилища размещаются на слоях поверх объектов потока или блокировки байтов; они могут содержать один или несколько из этих объектов, а также другие объекты хранилища. Объекты хранилища реализуют интерфейс IStorage , который определяет методы создания вложенных объектов, доступа к ней и обслуживания.
Так как IStream, ILockBytes и IStorage являются COM-интерфейсами, а не интерфейсами MAPI, их методы возвращают значения ошибок COM, а не MAPI. Клиенты и поставщики услуг, вызывающие методы в этих интерфейсах, должны использовать функцию API MapStorageSCode для преобразования этих значений в значения ошибок MAPI. Дополнительные сведения см. в разделе MapStorageSCode.
Клиенты и поставщики услуг используют структурированное хранилище для работы со свойствами, которые слишком велики для поддержки с помощью методов IMAPIProp , обычно больших строковых и двоичных свойств. Одним из распространенных способов доступа клиентов или поставщиков услуг является указание IStream или IStorage в качестве идентификатора интерфейса при вызове метода IMAPIProp::OpenProperty . Например, клиенты вызывают OpenProperty с PR_ATTACH_DATA_BIN в качестве тега свойства и IID_IStream в качестве идентификатора интерфейса для доступа к двоичному вложению в сообщении.
Клиенты и поставщики услуг могут реализовывать собственные объекты потока и хранилища или вызывать функции API для доступа к реализациям, предоставляемым MAPI или COM. Так как предоставленные реализации служат большинству целей, клиентам и поставщикам услуг редко требуется создавать собственные.
Когда клиент вызывает OpenProperty для объекта MAPI для доступа к одному из его свойств через объект хранилища, поставщик услуг обычно открывает объект хранилища в прямом режиме. Однако это типичное, а не обязательное поведение. Клиенты должны предполагать, что все объекты хранилища, открытые или созданные поставщиками услуг, выполняются с транзакциями и требуют вызова IStorage::Commit. Кроме того, следует помнить, что изменения в объектах хранилища не будут постоянными, пока они не вызовут IMAPIProp::SaveChanges после окончательной фиксации для сохранения объекта MAPI. Дополнительные сведения см. в разделе IMAPIProp::SaveChanges.
MAPI и COM предоставляют несколько функций API для определения хранилища и потокового объекта или доступа к ней. Часто используемые функции описаны в следующей таблице.
Функции для доступа к объектам хранилища и Stream
| Function | Описание |
|---|---|
|
HrIStorageFromStream |
Создает объект хранилища для доступа к объекту потока или блокировки байтов. |
|
OpenIMsgOnIStg |
Создает объект сообщения для доступа к объекту хранилища. |
|
OpenStreamOnFile |
Создает объект потока для доступа к файлу. |
|
WrapCompressedRTFStream |
Создает объект потока, содержащий сжатую или несжатую версию потока, содержащего форматированный текст сообщения. |
Получение имен потоков в заданном подчиненном журнале
Вызовите метод IStorage::EnumElements подчиненного, чтобы получить интерфейс IEnumSTATSTG .
Вызовите IEnumSTATSTG::Next с максимально большим количеством структур STATSTG за раз. Если вы запрашиваете 100 за раз, next обычно возвращает S_FALSE с содержимым pceltFetched задано число, которое было фактически извлечено.
Проверьте наличие структур STATSTG , помеченных STGTY_STREAM.
Отпустите параметр pwcsName .
Создание объекта хранилища для доступа к существующему потоку или объекту блокировки байтов
- Клиенты вызывают HrIStorageFromStream.
Создание объекта сообщения для доступа к существующему объекту хранилища
- Поставщики услуг и клиенты вызывают OpenIMsgOnIStg. Созданный объект сообщения отличается от объектов сообщений, обычно создаваемых поставщиками хранилища сообщений, тем, что он не поддерживает все методы интерфейса IMessage : IMAPIProp , такие как IMessage::SubmitMessage. Необязательный входной параметр для OpenIMsgOnIStg — это функция обратного вызова, которая соответствует прототипу MSGCALLRELEASE . Эта функция вызывается новым объектом message, когда количество ссылок сообщения достигает нуля. Реализация функции MSGCALLRELEASE может быть полезна для выполнения окончательной обработки до полного удаления нового сообщения.
OpenStreamOnFile обычно используется для хранения файловых вложений, так как он создает поток, который считывает и записывает в файл. OpenProperty с PR_ATTACH_DATA_BIN в качестве тега свойства создает поток для хранения данных двоичного вложения.
Сжатие или распаковка потока, содержащего текст сообщения в формате форматированного текста
- Клиенты вызывают WrapCompressedRTFStream. WrapCompressedRTFStream создает поток, который обтекает поток RTF. Поток-оболочка реализует не все методы IStream ; исключены следующие методы: Seek, SetSize, Revert, LockRegion, UnlockRegion, Stat и Clone. Это связано с тем, что объекты потока, созданные с помощью WrapCompressedRTFStream , не поддерживают setSize или Stat. Простой способ увеличить или получить их размер не так просто. Лучшая стратегия заключается в выборе разумного размера буфера и чтении или записи в цикле.
Примечание.
COM имеет реализацию объекта хранилища на основе массива байтов, который возвращает объект IEnumSTATSTG из метода EnumElements , который является проблематичным. В частности, метод QueryInterface работает неправильно. Поставщики служб, реализующие собственные объекты хранилища с помощью реализации COM, должны создать тонкую оболочку для объекта IEnumSTATSTG , который перенаправляет вызовы в базовые методы IEnumSTATSTG , но реализует собственные методы AddRef, Release, QueryInterface и Clone .