Константы STGM

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

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

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

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

STGM_READ

0x000000000L

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

STGM_WRITE

0x000000001L

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

STGM_READWRITE

0x000000002L

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

STGM_SHARE_DENY_NONE

0x000000040L

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

STGM_SHARE_DENY_READ

0x000000030L

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

STGM_SHARE_DENY_WRITE

0x000000020L

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

STGM_SHARE_EXCLUSIVE

0x00000010L

Запрещает другим пользователям открывать объект в любом режиме. Имейте в виду, что это значение не является простой побитовой операцией ORSTGM_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

0x0002000L

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

STGM_FAILIFTHERE

0x000000000L

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

STGM_DIRECT

0x000000000L

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

STGM_TRANSACTED

0x00010000L

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

STGM_NOSCRATCH

0x00100000L

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

STGM_NOSNAPSHOT

0x00200000L

Этот флаг используется при открытии объекта хранилища с STGM_TRANSACTED и без STGM_SHARE_EXCLUSIVE или STGM_SHARE_DENY_WRITE. В этом случае указание STGM_NOSNAPSHOT запрещает системной реализации создавать копию моментального снимка файла. Вместо этого изменения файла записываются в конец файла. Неиспользуемое пространство не освобождается, если во время фиксации не выполняется консолидация, а в файле существует только один текущий модуль записи. При открытии файла в режиме моментального снимка невозможно выполнить другую операцию открытия без указания 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 .

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

Когда объект корневого хранилища открывается в режиме транзакций, расположение и поведение с нуля данных и копии моментальных снимков можно управлять для оптимизации производительности с помощью флагов 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 , то это "несколько операций записи, несколько читателей". В таких случаях моментальный снимок исходных данных будет выполнен во время открытой операции. Таким образом, даже если изменения в хранилище не вносятся и (или) не открываются другим средством записи одновременно, передача данных по-прежнему необходима во время открытия. В результате можно получить лучшую производительность во время открытия, открыв объект хранилища в 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. В этом случае модуль записи использует царапную область для хранения незафиксированных изменений. Как и в приведенных выше случаях, средство чтения вызывает штраф за производительность во время открытия во время создания копии моментальных снимков данных.

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

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

Прямой режим записи с одним Multiple-Reader

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

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

| STGM_DIRECT_SWMR | STGM_READWRITESTGM_SHARE_DENYWRITE

и каждый из читателей открывает объект с этими флагами:

| STGM_DIRECT_SWMR | STGM_READSTGM_SHARE_DENY_NONE

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

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

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

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

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

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

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

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

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

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

Требования

См. также

ISequentialStream::Read

IStorage

StgCreateDocfile

StgCreateDocfileOnILockBytes

StgCreateStorageEx

StgOpenStorage

StgOpenStorageEx

StgOpenStorageOnILockBytes