Константы STGM

Константы STGM — это флаги, указывающие условия для создания и удаления объекта и режимы доступа для объекта. Константы STGM включены в интерфейсы IStorage, IStream и IPropertySetStorage , а также в функции StgCreateDocfile, StgCreateStorageEx, StgCreateDocfileOnILockBytes, StgOpenStorage и StgOpenStorageEx .

Эти элементы часто объединяются с помощью оператора OR. Они интерпретируются в группах, как указано в следующей таблице. Недопустимо использовать несколько элементов из одной группы.

Используйте флаг из группы создания при создании объекта, например stgCreateStorageEx или IStorage::CreateStream.

Дополнительные сведения о транзакциях см. в разделе Примечания.

Группа	Флаг	Значение
Access	STGM_READ	0x00000000L
	STGM_WRITE	0x00000001L
	STGM_READWRITE	0x00000002L
Совместное использование	STGM_SHARE_DENY_NONE	0x00000040L
	STGM_SHARE_DENY_READ	0x00000030L
	STGM_SHARE_DENY_WRITE	0x00000020L
	STGM_SHARE_EXCLUSIVE	0x00000010L
	STGM_PRIORITY	0x00040000L
Создание	STGM_CREATE	0x00001000L
	STGM_CONVERT	0x00020000L
	STGM_FAILIFTHERE	0x00000000L
Транзакции	STGM_DIRECT	0x00000000L
	STGM_TRANSACTED	0x00010000L
Производительность транзакций	STGM_NOSCRATCH	0x00100000L
	STGM_NOSNAPSHOT	0x00200000L
Прямой SWMR и простой	STGM_SIMPLE	0x08000000L
	STGM_DIRECT_SWMR	0x00400000L
Удаление при выпуске	STGM_DELETEONRELEASE	0x04000000L

STGM_READ

0x00000000L

Указывает, что объект доступен только для чтения, что означает, что изменения не могут быть внесены. Например, если объект потока открыт с STGM_READ, можно вызвать метод ISequentialStream::Read , а метод ISequentialStream::Write — нет. Аналогичным образом, если объект хранилища открыт с помощью STGM_READ, могут вызываться методы IStorage::OpenStream и IStorage::OpenStorage , но методы IStorage::CreateStream и IStorage::CreateStorage не могут.

STGM_WRITE

0x00000001L

Позволяет сохранить изменения в объекте , но не разрешает доступ к его данным. Предоставленные реализации интерфейсов IPropertyStorage и IPropertySetStorage не поддерживают этот режим только для записи.

STGM_READWRITE

0x00000002L

Обеспечивает доступ к данным объекта и их изменение. Например, если объект потока создается или открывается в этом режиме, можно вызвать как IStream::Read , так и IStream::Write. Имейте в виду, что эта константа не является простой двоичной операцией ИЛИSTGM_WRITE и STGM_READ элементов.

STGM_SHARE_DENY_NONE

0x00000040L

Указывает, что последующим открытиям объекта не запрещается доступ на чтение или запись. Если флаг из группы общего доступа не указан, предполагается, что этот флаг используется.

STGM_SHARE_DENY_READ

0x00000030L

Запрещает другим пользователям впоследствии открывать объект в режиме STGM_READ . Обычно он используется в корневом объекте хранилища.

STGM_SHARE_DENY_WRITE

0x00000020L

Запрещает другим пользователям впоследствии открывать объект для STGM_WRITE или STGM_READWRITE доступа. В режиме транзакций совместное использование STGM_SHARE_DENY_WRITE или STGM_SHARE_EXCLUSIVE может значительно повысить производительность, так как для них не требуются моментальные снимки. Дополнительные сведения о транзакциях см. в разделе Примечания.

STGM_SHARE_EXCLUSIVE

0x00000010L

Запрещает другим пользователям впоследствии открывать объект в любом режиме. Имейте в виду, что это значение не является простой побитовой операцией ИЛИSTGM_SHARE_DENY_READ и STGM_SHARE_DENY_WRITE значений . В режиме транзакций совместное использование STGM_SHARE_DENY_WRITE или STGM_SHARE_EXCLUSIVE может значительно повысить производительность, так как для них не требуются моментальные снимки. Дополнительные сведения о транзакциях см. в разделе Примечания.

STGM_PRIORITY

0x00040000L

Открывает объект хранилища с монопольным доступом к последней зафиксированной версии. Таким образом, другие пользователи не могут фиксировать изменения в объекте, пока он открыт в режиме приоритета. Вы получаете преимущества производительности для операций копирования, но не позволяете другим пользователям фиксировать изменения. Ограничьте время открытия объектов в режиме приоритета. Необходимо указать STGM_DIRECT и STGM_READ с режимом приоритета, а STGM_DELETEONRELEASE указать нельзя. STGM_DELETEONRELEASE допустимо только при создании корневого объекта, например при использовании StgCreateStorageEx. Это недопустимо при открытии существующего корневого объекта, например при использовании StgOpenStorageEx. Это также недопустимо при создании или открытии подэлемента, например при использовании IStorage::OpenStorage.

STGM_CREATE

0x00001000L

Указывает, что существующий объект хранилища или поток должны быть удалены до того, как новый объект заменит его. Новый объект создается при указании этого флага только в том случае, если существующий объект успешно удален.

Этот флаг используется при попытке создать:

• Объект хранилища на диске, но файл с таким именем существует.
• Объект внутри объекта хранилища, но объект с указанным именем существует.
• Существует объект массива байтов, но с указанным именем.

Этот флаг нельзя использовать с открытыми операциями, такими как StgOpenStorageEx или IStorage::OpenStream.

STGM_CONVERT

0x00020000L

Создает новый объект , сохраняя существующие данные в потоке с именем Contents. В случае объекта хранилища или массива байтов старые данные форматируются в поток независимо от того, содержит ли существующий файл или массив байтов объект многоуровневого хранилища. Этот флаг можно использовать только при создании корневого объекта хранилища. Его нельзя использовать в объекте хранилища; например, в IStorage::CreateStream. Также недопустимо использовать этот флаг и флаг STGM_DELETEONRELEASE одновременно.

STGM_FAILIFTHERE

0x00000000L

Вызывает сбой операции создания, если существует существующий объект с указанным именем. В этом случае возвращается STG_E_FILEALREADYEXISTS . Это режим создания по умолчанию; т. е. если не указан другой флаг создания, подразумевается STGM_FAILIFTHERE .

STGM_DIRECT

0x00000000L

Указывает, что в прямом режиме каждое изменение в элементе хранилища или потока записывается по мере его возникновения. Это значение по умолчанию, если не указано ни STGM_DIRECT, ни STGM_TRANSACTED.

STGM_TRANSACTED

0x00010000L

Указывает, что в режиме транзакций изменения буферизуются и записываются только при вызове явной операции фиксации. Чтобы игнорировать изменения, вызовите метод Revert в интерфейсе IStream, IStorage или IPropertyStorage . Реализация составных com-файлов IStorage не поддерживает потоки транзакций, что означает, что потоки можно открывать только в прямом режиме, и вы не можете отменить изменения изменения в них, однако поддерживаются хранилища с транзакциями. Реализации составных файлов, автономных файлов и файловой системы NTFS IPropertySetStorage аналогичным образом не поддерживают транзакцию простых наборов свойств, так как эти наборы свойств хранятся в потоках. Однако поддерживается транзакция неимплированных наборов свойств, которые можно создать, указав флаг PROPSETFLAG_NONSIMPLE в параметре grfFlagsобъекта IPropertySetStorage::Create.

STGM_NOSCRATCH

0x00100000L

Указывает, что в режиме транзакций временный временный файл обычно используется для сохранения изменений до вызова метода Commit . Указание STGM_NOSCRATCH позволяет использовать неиспользуемую часть исходного файла в качестве рабочего пространства вместо создания нового файла для этой цели. Это не влияет на данные в исходном файле, а в некоторых случаях может привести к повышению производительности. Недопустимо указывать этот флаг без указания STGM_TRANSACTED, и этот флаг можно использовать только в корневой открытой среде. Дополнительные сведения о режиме NoScratch см. в разделе Примечания.

STGM_NOSNAPSHOT

0x00200000L

Этот флаг используется при открытии объекта хранилища с STGM_TRANSACTED и без STGM_SHARE_EXCLUSIVE или STGM_SHARE_DENY_WRITE. В этом случае указание STGM_NOSNAPSHOT не позволяет системной реализации создать snapshot копию файла. Вместо этого изменения файла записываются в конец файла. Неиспользуемое пространство не освобождается, если во время фиксации не выполняется консолидация, и в файле есть только один текущий модуль записи. Если файл открыт в режиме без snapshot, другая операция открытия не может быть выполнена без указания STGM_NOSNAPSHOT. Этот флаг можно использовать только в операции открытия корневого каталога. Дополнительные сведения о режиме NoSnapshot см. в разделе Примечания.

STGM_SIMPLE

0x08000000L

Обеспечивает более быструю реализацию составного файла в ограниченном, но часто используемом варианте. Дополнительные сведения см. в разделе «Примечания».

STGM_DIRECT_SWMR

0x00400000L

Поддерживает прямой режим для операций с файлами с одним модулем записи и многочитанными файлами. Дополнительные сведения см. в разделе «Примечания».

STGM_DELETEONRELEASE

0x04000000L

Указывает, что базовый файл должен быть автоматически уничтожен при освобождении корневого объекта хранилища. Эта функция наиболее полезна для создания временных файлов. Этот флаг можно использовать только при создании корневого объекта, например stgCreateStorageEx. Это недопустимо при открытии корневого объекта, например в StgOpenStorageEx, а также при создании или открытии вложенного элемента, например в IStorage::CreateStream. Также недопустимо использовать этот флаг и флаг STGM_CONVERT одновременно.

Комментарии

Эти флаги можно объединить, но можно выбрать только один флаг из каждой группы связанных флагов. Как правило, для всех функций и методов, использующих эти константы, необходимо указать один флаг из каждой группы доступа и общего доступа. Флаги из других групп являются необязательными.

Режим транзакций

Если указан флаг STGM_DIRECT, в группах доступа и общего доступа может быть указан только один из следующих сочетаний флагов.

    STGM_READ      | STGM_SHARE_DENY_WRITE

    STGM_READWRITE | STGM_SHARE_EXCLUSIVE

    STGM_READ      | STGM_PRIORITY

Имейте в виду, что прямой режим подразумевается отсутствием STGM_TRANSACTED. То есть, если ни STGM_DIRECT , ни STGM_TRANSACTED не указаны, предполагается STGM_DIRECT .

При указании флага STGM_TRANSACTED объекты создаются или открываются в режиме транзакций. В этом режиме изменения объекта сохраняются только после фиксации. Например, изменения в объекте хранилища с транзакциями не сохраняются до вызова метода IStorage::Commit . Изменения в таком объекте хранилища будут потеряны, если объект хранилища освобождается (окончательный выпуск) перед вызовом метода Commit или если вызывается метод IStorage::Revert .

При создании или открытии объекта в режиме транзакций реализация должна хранить как исходные данные, так и обновления этих данных, чтобы при необходимости можно было отменить обновления. Обычно это выполняется путем записи изменений в временной области, пока они не будут зафиксированы, или путем создания копии, называемой snapshot, последних зафиксированных данных.

При открытии корневого объекта хранилища в режиме транзакций можно управлять расположением и поведением временных данных и snapshot копий, чтобы оптимизировать производительность с помощью флагов STGM_NOSCRATCH и STGM_NOSNAPSHOT. (Корневой объект хранилища получается, например, из функции StgOpenStorageEx ; объект хранения, полученный из метода IStorage::OpenStorage , является объектом подсранилище.) Как правило, временные данные и моментальные снимки хранятся во временных файлах отдельно от хранилища.

Влияние этих флагов зависит от количества читателей и (или) записей, обращаюющихся к корневому хранилищу.

В случае с одним модулем записи открывается объект хранилища в режиме транзакций для доступа на запись, и другой доступ к файлу не может быть. Это значит, что файл открывается с помощью STGM_TRANSACTED, доступа к STGM_WRITE или STGM_READWRITE и совместного использования STGM_SHARE_EXCLUSIVE. В этом случае изменения объекта хранилища записываются в область выполнения. После фиксации этих изменений они копируются в исходное хранилище. Таким образом, если в объект хранилища фактически не вносятся изменения, не будет никакой лишней передачи данных.

В случае с несколькими модулями записи объект хранилища с транзакциями открывается для доступа на запись, но используется совместно, чтобы разрешить другим модулям записи. То есть объект хранилища открывается с помощью STGM_TRANSACTED, доступа STGM_WRITE или STGM_READWRITE, а также совместного использования STGM_SHARE_DENY_READ. Если вместо этого указан общий доступ к STGM_SHARE_DENY_NONE , то используется вариант "с несколькими модулями записи, с несколькими средствами чтения". В таких случаях во время операции открытия будет выполнена snapshot исходных данных. Таким образом, даже если в хранилище фактически не вносятся изменения и (или) оно не открывается другим модулем записи одновременно, передача данных во время открытия по-прежнему необходима. В результате можно получить оптимальную производительность во время открытия, открыв объект хранилища в режиме STGM_SHARE_DENY_WRITE или STGM_SHARE_EXCLUSIVE . Дополнительные сведения о фиксации изменений при наличии нескольких модулей записи см. в разделе IStorage::Commit.

В случае с одним модулем записи и несколькими средствами чтения объект хранилища с транзакциями открывается для доступа на запись, но предоставляется совместно с читателями. То есть объект хранилища открывается модулем записи с STGM_TRANSACTED, доступом к STGM_READWRITE или STGM_WRITE и совместному использованию STGM_SHARE_DENY_WRITE. Хранилище открывается средствами чтения с STGM_TRANSACTED, доступом к STGM_READ и общим доступом к STGM_SHARE_DENY_NONE. В этом случае модуль записи использует временную область для хранения незафиксированных изменений. Как и в приведенных выше случаях, при создании snapshot копии данных читатель может нести снижение производительности во время открытия.

Как правило, временная область является временным файлом, отделенным от исходных данных. Если изменения фиксируются в исходном файле, данные должны передаваться из временного файла. Чтобы избежать такой передачи данных, можно указать флаг STGM_NOSCRATCH. При указании этого флага для временной области используются части файла объекта хранилища, а не отдельный временный файл. В результате фиксация изменений может быть выполнена быстро, так как требуется небольшая передача данных. Недостаток заключается в том, что файл хранилища может стать больше, чем в противном случае, так как он должен быть достаточно большим для исходных данных и временной области. Чтобы консолидировать данные и удалить эту ненужную область, повторно откройте корневое хранилище в режиме транзакций, но не устанавливая флаг STGM_NOSCRATCH . Затем вызовите IStorage::Commit с установленным флагом STGC_CONSOLIDATE .

Область snapshot, как и временная область, также, как правило, является временным файлом, и на это также может повлиять флаг STGM. При указании флага STGM_NOSNAPSHOT отдельный временный файл snapshot не создается. Вместо этого исходные данные никогда не изменяются, даже если на объект имеется один или несколько модулей записи. При фиксации изменений они добавляются в файл, но исходные данные остаются без изменений. Этот режим повышает эффективность, так как сокращает время выполнения, устраняя необходимость создания snapshot во время операции открытия. Однако использование этого режима может привести к созданию очень большого файла хранилища, так как данные в файле никогда не могут быть перезаписаны. Это не ограничивает размер файлов, открытых в режиме NoSnapshot.

Direct Single-Writer, режим Multiple-Reader

Как описано, можно использовать один модуль записи и несколько модулей чтения объекта хранилища, если этот объект открыт в режиме транзакций. Кроме того, можно реализовать регистр с одним модулем записи в режиме прямого чтения, указав флаг STGM_DIRECT_SWMR .

В режиме STGM_DIRECT_SWMR один вызывающий объект может открыть объект для доступа для чтения и записи, а другие вызывающие объекты одновременно открывают файл для доступа только для чтения. Недопустимо использовать этот флаг в сочетании с флагом STGM_TRANSACTED . В этом режиме модуль записи открывает объект со следующими флагами:

| STGM_DIRECT_SWMR | STGM_READWRITE STGM_SHARE_DENYWRITE

и каждый из модулей чтения открывает объект со следующими флагами:

| STGM_DIRECT_SWMR | STGM_READ STGM_SHARE_DENY_NONE

В этом режиме для изменения объекта хранилища модуль записи должен получить монопольный доступ к объекту . Это возможно, если все читатели закрыли его. Модуль записи использует интерфейс IDirectWriterLock для получения этого монопольного доступа.

Простой режим

Простой режим (STGM_SIMPLE) полезен для приложений, выполняющих полные операции сохранения. Она эффективна, но имеет следующие ограничения:

• Для вложенных журналов не поддерживается.
• Объект хранилища и потоковые объекты, полученные из него, не могут быть маршалированы.
• Каждый поток имеет минимальный размер. Если при освобождении потока в поток записывается меньше минимального числа байтов, поток расширяется до минимального размера. Например, минимальный размер для конкретной реализации IStream составляет 4 КБ. Создается поток, в который записывается 1 КБ. В окончательном выпуске этого IStream размер потока будет автоматически увеличен до 4 КБ. Затем при открытии потока и вызове метода IStream::Stat будет отображаться размер 4 КБ.
• Не все методы IStorage или IStream будут поддерживаться реализацией. Дополнительные сведения см. в разделах IStorage — реализация составного файла и IStream — реализация составного файла.

Маршалинг — это процесс упаковки, распаковки и отправки параметров метода интерфейса через границы потока или процесса в удаленном вызове процедур (RPC). Дополнительные сведения см. в разделах Сведения о маршале и Маршалинг интерфейса.

При получении объекта хранилища с помощью операции Создания в простом режиме:

• Элементы потока можно создавать, но не открывать.
• При создании элемента потока путем вызова IStorage::CreateStream невозможно создать другой поток, пока этот объект потока не будет освобожден.
• После записи всех потоков вызовите метод IStorage::Commit для очистки изменений.

Когда объект хранилища получается операцией Open в простом режиме:

• Одновременно можно открыть только один элемент потока.
• Невозможно изменить размер потока путем вызова метода IStream::SetSize или путем поиска или записи за пределами конца потока. Тем не менее, поскольку все потоки имеют минимальный размер, можно использовать поток до этого размера, даже если в него изначально было записано меньше данных. Чтобы определить размер потока, используйте метод IStream::Stat .

Имейте в виду, что если элемент хранилища изменяется объектом хранения, который не находится в простом режиме, снова невозможно будет открыть этот элемент хранения в простом режиме.

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Заголовок	ObjBase.h

См. также раздел

ISequentialStream::Read

IStorage

StgCreateDocfile

StgCreateDocfileOnILockBytes

StgCreateStorageEx

StgOpenStorage

StgOpenStorageEx

StgOpenStorageOnILockBytes