StGM (constantes)

Artículo
06/13/2023

Las constantes STGM son marcas que indican condiciones para crear y eliminar el objeto y los modos de acceso para el objeto. Las constantes STGM se incluyen en las interfaces IStorage, IStream e IPropertySetStorage y en las funciones StgCreateDocfile, StgCreateStorageEx, StgCreateDocfileOnILockBytes, StgOpenStorage y StgOpenStorageEx.

Estos elementos suelen combinarse mediante un operador OR. Se interpretan en grupos como se muestra en la tabla siguiente. No es válido usar más de un elemento de un único grupo.

Use una marca del grupo de creación al crear un objeto, como con StgCreateStorageEx o IStorage::CreateStream.

Para obtener más información sobre las transacciones, vea la sección Comentarios.

Grupo	Marca	Value
Access	STGM_READ	0x00000000L
	STGM_WRITE	0x00000001L
	STGM_READWRITE	0x00000002L
Uso compartido	STGM_SHARE_DENY_NONE	0x00000040L
	STGM_SHARE_DENY_READ	0x00000030L
	STGM_SHARE_DENY_WRITE	0x00000020L
	STGM_SHARE_EXCLUSIVE	0x00000010L
	STGM_PRIORITY	0x00040000L
Creación	STGM_CREATE	0x00001000L
	STGM_CONVERT	0x00020000L
	STGM_FAILIFTHERE	0x00000000L
Transacciones	STGM_DIRECT	0x00000000L
	STGM_TRANSACTED	0x00010000L
Rendimiento de transacciones	STGM_NOSCRATCH	0x00100000L
	STGM_NOSNAPSHOT	0x00200000L
Direct SWMR y Simple	STGM_SIMPLE	0x08000000L
	STGM_DIRECT_SWMR	0x00400000L
Eliminar al lanzamiento	STGM_DELETEONRELEASE	0x04000000L

STGM_READ

0x00000000L
Indica que el objeto es de solo lectura, lo que significa que no se pueden realizar modificaciones. Por ejemplo, si se abre un objeto de secuencia con STGM_READ, se puede llamar al método ISequentialStream::Read , pero es posible que el método ISequentialStream::Write no lo haga. Del mismo modo, si se abre un objeto de almacenamiento con STGM_READ, se puede llamar a los métodos IStorage::OpenStream e IStorage::OpenStorage , pero los métodos IStorage::CreateStream e IStorage::CreateStorage no.

STGM_WRITE

0x00000001L
Permite guardar los cambios en el objeto, pero no permite el acceso a sus datos. Las implementaciones proporcionadas de las interfaces IPropertyStorage e IPropertySetStorage no admiten este modo de solo escritura.

STGM_READWRITE

0x00000002L
Permite el acceso y la modificación de los datos de objeto. Por ejemplo, si se crea o abre un objeto de secuencia en este modo, es posible llamar a IStream::Read e IStream::Write. Tenga en cuenta que esta constante no es una operación OR binaria simple de los elementos STGM_WRITE y STGM_READ .

STGM_SHARE_DENY_NONE

0x00000040L
Especifica que no se deniega el acceso de lectura o escritura a las aperturas posteriores del objeto. Si no se especifica ninguna marca del grupo de uso compartido, se asume esta marca.

STGM_SHARE_DENY_READ

0x00000030L
Impide que otros usuarios abran posteriormente el objeto en modo STGM_READ . Normalmente se usa en un objeto de almacenamiento raíz.

STGM_SHARE_DENY_WRITE

0x00000020L
Impide que otros usuarios abran posteriormente el objeto para el acceso STGM_WRITE o STGM_READWRITE . En el modo de transacción, el uso compartido de STGM_SHARE_DENY_WRITE o STGM_SHARE_EXCLUSIVE puede mejorar significativamente el rendimiento porque no requieren instantáneas. Para obtener más información sobre las transacciones, vea la sección Comentarios.

STGM_SHARE_EXCLUSIVE

0x00000010L
Impide que otros usuarios abran posteriormente el objeto en cualquier modo. Tenga en cuenta que este valor no es una operación OR bit a bit simple de los valores de STGM_SHARE_DENY_READ y STGM_SHARE_DENY_WRITE . En el modo de transacción, el uso compartido de STGM_SHARE_DENY_WRITE o STGM_SHARE_EXCLUSIVE puede mejorar significativamente el rendimiento porque no requieren instantáneas. Para obtener más información sobre las transacciones, vea la sección Comentarios.

STGM_PRIORITY

0x00040000L
Abre el objeto de almacenamiento con acceso exclusivo a la versión confirmada más recientemente. Por lo tanto, otros usuarios no pueden confirmar los cambios en el objeto mientras lo tiene abierto en modo de prioridad. Obtiene ventajas de rendimiento para las operaciones de copia, pero impide que otros usuarios confirmen cambios. Limite el tiempo que los objetos están abiertos en modo de prioridad. Debe especificar STGM_DIRECT y STGM_READ con el modo de prioridad y no puede especificar STGM_DELETEONRELEASE. STGM_DELETEONRELEASE solo es válido al crear un objeto raíz, como con StgCreateStorageEx. No es válido al abrir un objeto raíz existente, como con StgOpenStorageEx. Tampoco es válido al crear o abrir un subelemento, como con IStorage::OpenStorage.

STGM_CREATE

0x00001000L
Indica que se debe quitar un objeto de almacenamiento o secuencia existente antes de que el nuevo objeto lo reemplace. Se crea un nuevo objeto cuando se especifica esta marca solo si el objeto existente se ha quitado correctamente.

Esta marca se usa al intentar crear:

Objeto de almacenamiento en un disco, pero existe un archivo de ese nombre.

Objeto dentro de un objeto de almacenamiento, pero existe un objeto con el nombre especificado.

Existe un objeto de matriz de bytes, pero existe uno con el nombre especificado.

Esta marca no se puede usar con operaciones abiertas, como StgOpenStorageEx o IStorage::OpenStream.

STGM_CONVERT

0x00020000L
Crea el nuevo objeto a la vez que conserva los datos existentes en una secuencia denominada "Contenido". En el caso de un objeto de almacenamiento o una matriz de bytes, los datos antiguos tienen formato en una secuencia, independientemente de si el archivo o matriz de bytes existente contiene actualmente un objeto de almacenamiento en capas. Esta marca solo se puede usar al crear un objeto de almacenamiento raíz. No se puede usar dentro de un objeto de almacenamiento; por ejemplo, en IStorage::CreateStream. Tampoco es válido usar esta marca y la marca STGM_DELETEONRELEASE simultáneamente.

STGM_FAILIFTHERE

0x00000000L
Hace que se produzca un error en la operación de creación si existe un objeto existente con el nombre especificado. En este caso, se devuelve STG_E_FILEALREADYEXISTS . Este es el modo de creación predeterminado; es decir, si no se especifica ninguna otra marca de creación, STGM_FAILIFTHERE está implícito.

STGM_DIRECT

0x00000000L
Indica que, en modo directo, cada cambio en un elemento de flujo o almacenamiento se escribe a medida que se produce. Este es el valor predeterminado si no se especifica ni STGM_DIRECTni STGM_TRANSACTED .

STGM_TRANSACTED

0x00010000L
Indica que, en modo de transacción, los cambios se almacenan en búfer y solo se escriben si se llama a una operación de confirmación explícita. Para omitir los cambios, llame al método Revert en la interfaz IStream, IStorage o IPropertyStorage . La implementación de archivos compuestos COM de IStorage no admite secuencias transaccionadas, lo que significa que las secuencias solo se pueden abrir en modo directo y no se pueden revertir los cambios a ellos, pero se admiten los almacenamientos con transacciones. Las implementaciones del sistema de archivos NTFS, independiente y de archivo compuesto de IPropertySetStorage no admiten conjuntos de propiedades simples y transacciones, ya que estos conjuntos de propiedades se almacenan en secuencias. Sin embargo, se admiten las transacciones de conjuntos de propiedades nomples, que se pueden crear especificando la marca PROPSETFLAG_NONSIMPLE en el parámetro grfFlags de IPropertySetStorage::Create.

STGM_NOSCRATCH

0x00100000L
Indica que, en modo de transacción, normalmente se usa un archivo temporal temporal para guardar modificaciones hasta que se llama al método Commit . Especificar STGM_NOSCRATCH permite usar la parte no utilizada del archivo original como espacio de trabajo en lugar de crear un nuevo archivo para ese fin. Esto no afecta a los datos del archivo original y, en ciertos casos, puede dar lugar a un rendimiento mejorado. No es válido especificar esta marca sin especificar también STGM_TRANSACTED, y esta marca solo se puede usar en una raíz abierta. Para obtener más información sobre el modo NoScratch, vea la sección Comentarios.

STGM_NOSNAPSHOT

0x00200000L
Esta marca se usa al abrir un objeto de almacenamiento con STGM_TRANSACTED y sin STGM_SHARE_EXCLUSIVE ni STGM_SHARE_DENY_WRITE. En este caso, especificar STGM_NOSNAPSHOT impide que la implementación proporcionada por el sistema cree una copia de instantánea del archivo. En su lugar, los cambios en el archivo se escriben al final del archivo. El espacio sin usar no se reclama a menos que se realice la consolidación durante la confirmación y solo haya un escritor actual en el archivo. Cuando el archivo se abre sin modo de instantánea, no se puede realizar otra operación de apertura sin especificar STGM_NOSNAPSHOT. Esta marca solo se puede usar en una operación de apertura raíz. Para obtener más información sobre el modo NoSnapshot, vea la sección Comentarios.

STGM_SIMPLE

0x08000000L
Proporciona una implementación más rápida de un archivo compuesto en un caso limitado, pero usado con frecuencia. Para obtener más información, vea la sección Comentarios.

STGM_DIRECT_SWMR

0x00400000L
Admite el modo directo para las operaciones de archivos de escritura única y multireader. Para obtener más información, vea la sección Comentarios.

STGM_DELETEONRELEASE

0x04000000L
Indica que el archivo subyacente se destruirá automáticamente cuando se libere el objeto de almacenamiento raíz. Esta característica es más útil para crear archivos temporales. Esta marca solo se puede usar al crear un objeto raíz, como con StgCreateStorageEx. No es válido al abrir un objeto raíz, como con StgOpenStorageEx, o al crear o abrir un subelemento, como con IStorage::CreateStream. Tampoco es válido usar esta marca y la marca STGM_CONVERT simultáneamente.

Observaciones

Puede combinar estas marcas, pero solo puede elegir una marca de cada grupo de marcas relacionadas. Normalmente, se debe especificar una marca de cada uno de los grupos de acceso y uso compartido para todas las funciones y métodos que usan estas constantes. Las marcas de otros grupos son opcionales.

Modo de transacción

Cuando se especifica la marca STGM_DIRECT, solo se puede especificar una de las siguientes combinaciones de marcas desde los grupos de acceso y uso compartido.

    STGM_READ      | STGM_SHARE_DENY_WRITE

    STGM_READWRITE | STGM_SHARE_EXCLUSIVE

    STGM_READ      | STGM_PRIORITY

Tenga en cuenta que el modo directo está implícito en la ausencia de STGM_TRANSACTED. Es decir, si no se especifica ni STGM_DIRECTni STGM_TRANSACTED , se supone STGM_DIRECT .

Cuando se especifica la marca STGM_TRANSACTED , los objetos se crean o abren en modo de transacción. En este modo, los cambios en un objeto no se conservan hasta que se confirman. Por ejemplo, los cambios en un objeto de almacenamiento de transacciones no se conservan hasta que se llama al método IStorage::Commit . Los cambios en este objeto de almacenamiento se perderán si se libera el objeto de almacenamiento (versión final) antes de llamar al método Commit o si se llama al método IStorage::Revert .

Cuando se crea o abre un objeto en modo de transacción, la implementación debe mantener los datos originales y las actualizaciones de estos datos, de modo que las actualizaciones se puedan revertir si es necesario. Normalmente, esto se realiza escribiendo cambios en un área temporal hasta que se confirmen o creando una copia, denominada instantánea, de los datos confirmados más recientemente.

Cuando se abre un objeto de almacenamiento raíz en modo de transacción, la ubicación y el comportamiento de los datos temporal y las copias de instantáneas se pueden controlar para optimizar el rendimiento con las marcas STGM_NOSCRATCH y STGM_NOSNAPSHOT . (Un objeto de almacenamiento raíz se obtiene de, por ejemplo, la función StgOpenStorageEx ; un objeto de almacenamiento obtenido del método IStorage::OpenStorage es un objeto de substorage). Normalmente, los datos y las instantáneas temporal se almacenan en archivos temporales, separados del almacenamiento.

El efecto de estas marcas depende del número de lectores o escritores que acceden al almacenamiento raíz.

En el caso de "escritor único", se abre un objeto de almacenamiento en modo de transacción para el acceso de escritura y no puede haber ningún otro acceso al archivo. Es decir, el archivo se abre con STGM_TRANSACTED, acceso a STGM_WRITE o STGM_READWRITE y uso compartido de STGM_SHARE_EXCLUSIVE. En este caso, los cambios en el objeto de almacenamiento se escriben en el área temporal. Cuando se confirman esos cambios, se copian en el almacenamiento original. Por lo tanto, si no se realizan cambios en el objeto de almacenamiento, no habrá ninguna transferencia de datos innecesaria.

En el caso "multiple-writer", se abre un objeto de almacenamiento de transacciones para el acceso de escritura, pero se comparte en , por ejemplo, para permitir otros escritores. Es decir, el objeto de almacenamiento se abre con STGM_TRANSACTED, acceso de STGM_WRITE o STGM_READWRITE y uso compartido de STGM_SHARE_DENY_READ. Si se especifica en su lugar el uso compartido de STGM_SHARE_DENY_NONE, el caso es "multiple-writer, multiple-reader". En estos casos, se realizará una instantánea de los datos originales durante la operación abierta. Por lo tanto, aunque no se realicen cambios en el almacenamiento o no se abra realmente mediante otro escritor simultáneamente, la transferencia de datos sigue siendo necesaria durante la apertura. Como resultado, se puede obtener el mejor rendimiento en tiempo abierto abriendo el objeto de almacenamiento en STGM_SHARE_DENY_WRITE o STGM_SHARE_EXCLUSIVE modos. Para obtener más información sobre cómo se confirman los cambios cuando hay varios escritores, vea IStorage::Commit.

En el caso "single-writer, multiple-reader", se abre un objeto de almacenamiento de transacciones para el acceso de escritura, pero se comparte con lectores. Es decir, el escritor abre el objeto de almacenamiento con STGM_TRANSACTED, acceso de STGM_READWRITE o STGM_WRITE y uso compartido de STGM_SHARE_DENY_WRITE. Los lectores abren el almacenamiento con STGM_TRANSACTED, acceso de STGM_READ y uso compartido de STGM_SHARE_DENY_NONE. En este caso, el escritor usa el área temporal para almacenar los cambios no confirmados. Como en los casos anteriores, el lector incurre en una penalización de rendimiento en tiempo abierto mientras se crea una copia de instantánea de los datos.

Normalmente, el área temporal es un archivo temporal, independiente de los datos originales. Cuando los cambios se confirman en el archivo original, los datos se deben transferir desde el archivo temporal. Para evitar esta transferencia de datos, se puede especificar la marca STGM_NOSCRATCH. Cuando se especifica esta marca, se usan partes del archivo de objeto de almacenamiento para el área temporal, en lugar de un archivo temporal independiente. Como resultado, la confirmación de cambios se puede realizar rápidamente, ya que se requiere poca transferencia de datos. La desventaja es que el archivo de almacenamiento puede ser mayor que lo que de otro modo sería, ya que debe crecer para ser lo suficientemente grande como para los datos originales y el área temporal. Para consolidar los datos y quitar este área innecesaria, vuelva a abrir el almacenamiento raíz en modo transaccionado, pero sin establecer la marca STGM_NOSCRATCH . A continuación, llame a IStorage::Commit con la marca STGC_CONSOLIDATE establecida.

El área de instantáneas, como el área temporal, también es, normalmente, un archivo temporal y esto también puede verse afectado con una marca STGM. Al especificar la marca STGM_NOSNAPSHOT , no se crea un archivo de instantánea temporal independiente. En su lugar, los datos originales nunca se modifican, incluso si hay uno o más escritores por objeto. Cuando se confirman los cambios, se agregan al archivo, pero los datos originales permanecen intactos. Este modo aumenta la eficacia porque reduce el tiempo de ejecución eliminando el requisito de crear una instantánea durante la operación abierta. Sin embargo, el uso de este modo puede dar lugar a un archivo de almacenamiento muy grande porque los datos del archivo nunca se pueden sobrescribir. Este no es un límite para el tamaño de los archivos abiertos en modo NoSnapshot.

Direct Single-Writer, modo de Multiple-Reader

Como se describe, es posible tener un único escritor y varios lectores de un objeto de almacenamiento, si ese objeto se abre en modo transaccionado. También es posible lograr el caso de un solo escritor, multireader en modo directo, especificando la marca STGM_DIRECT_SWMR .

En STGM_DIRECT_SWMR modo, es posible que un autor de la llamada abra un objeto para el acceso de lectura y escritura, mientras que otros autores de llamadas tienen el archivo abierto simultáneamente para el acceso de solo lectura. No es válido usar esta marca en combinación con la marca STGM_TRANSACTED . En este modo, el escritor abre el objeto con las marcas siguientes:

| STGM_DIRECT_SWMR | STGM_READWRITE STGM_SHARE_DENYWRITE

y cada uno de los lectores abre el objeto con estas marcas:

| STGM_DIRECT_SWMR | STGM_READ STGM_SHARE_DENY_NONE

En este modo, para modificar el objeto de almacenamiento, el escritor debe obtener acceso exclusivo al objeto . Esto es posible cuando todos los lectores lo han cerrado. El escritor usa la interfaz IDirectWriterLock para obtener este acceso exclusivo.

Modo simple

El modo simple (STGM_SIMPLE) es útil para las aplicaciones que realizan operaciones de guardado completas. Es eficaz, pero tiene las siguientes restricciones:

No existe compatibilidad con substorages.
El objeto de almacenamiento y los objetos de secuencia obtenidos de él no se pueden serializar.
Cada secuencia tiene un tamaño mínimo. Si se escriben menos de los bytes mínimos en una secuencia cuando se libera la secuencia, la secuencia se extiende al tamaño mínimo. Por ejemplo, el tamaño mínimo de una implementación de IStream determinada es de 4 KB. Se crea una secuencia y se escriben 1 KB en ella. En la versión final de ese IStream, el tamaño de la secuencia se extenderá automáticamente a 4 KB. Posteriormente, al abrir la secuencia y llamar al método IStream::Stat se mostrará un tamaño de 4 KB.
No todos los métodos de IStorage o IStream serán compatibles con la implementación. Para obtener más información, vea IStorage: implementación de archivos compuestos e Implementación de archivos compuestos de IStream.

La serialización es el proceso de empaquetado, desempaquetado y envío de parámetros del método de interfaz a través de los límites de subprocesos o procesos dentro de una llamada a procedimiento remoto (RPC). Para obtener más información, vea Serialización de detalles y serialización de interfaz.

Cuando se obtiene un objeto de almacenamiento mediante una operación Create en modo simple:

Se pueden crear elementos stream, pero no abiertos.
Cuando se crea un elemento de secuencia llamando a IStorage::CreateStream, no es posible crear otra secuencia hasta que se libere ese objeto de secuencia.
Una vez escritas todas las secuencias, llame a IStorage::Commit para vaciar los cambios.

Cuando un objeto de almacenamiento se obtiene mediante una operación Open en modo simple:

Es posible abrir solo un elemento de secuencia a la vez.
No es posible cambiar el tamaño de una secuencia llamando al método IStream::SetSize o buscando o escribiendo más allá del final de la secuencia. Sin embargo, dado que todas las secuencias tienen un tamaño mínimo, es posible usar la secuencia hasta ese tamaño, incluso si se escribieron originalmente menos datos en él. Para determinar el tamaño de una secuencia, use el método IStream::Stat .

Tenga en cuenta que, si un objeto de almacenamiento no está en modo simple, no será posible, de nuevo, abrir ese elemento de almacenamiento en modo simple.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Encabezado	ObjBase.h

Vea también

ISequentialStream::Read
IStorage
StgCreateDocfile
StgCreateDocfileOnILockBytes
StgCreateStorageEx
StgOpenStorage
StgOpenStorageEx
StgOpenStorageOnILockBytes