Implementación de archivos IPropertyStorage-Compound
La implementación COM de la arquitectura de Almacenamiento estructurado se denomina archivos compuestos. Los objetos de almacenamiento implementados en archivos compuestos incluyen una implementación de IPropertyStorage, la interfaz que administra un único conjunto de propiedades persistente e IPropertySetStorage, la interfaz que administra grupos de conjuntos de propiedades persistentes. Para obtener más información sobre la interfaz IPropertyStorage, vea Consideraciones sobre el almacenamiento de propiedades y IPropertyStorage.
Para obtener un puntero a la implementación de archivo compuesto de IPropertyStorage, llame a StgCreateStorageEx para crear un nuevo objeto de archivo compuesto o StgOpenStorageEx para abrir un objeto de archivo compuesto creado anteriormente. En el caso de StgCreateStorageEx, el parámetro stgfmt debe establecerse en STGFMT_STORAGE. En el caso de StgOpenStorageEx, el parámetro stgfmt debe establecerse en STGFMT_STORAGE o STGFMT_ANY. En ambos casos, el parámetro riid debe establecerse en IID_IPropertySetStorage. Ambas funciones proporcionan un puntero a la interfaz IPropertySetStorage del objeto. Al llamar al método Create o Open de esa interfaz, obtendrá un puntero a la interfaz IPropertyStorage , que puede usar para llamar a cualquiera de sus métodos.
Una manera alternativa de obtener un puntero a la implementación de archivo compuesto de IPropertySetStorage es llamar a las funciones StgCreateDocfile y StgOpenStorage anteriores, o especificar un parámetro riid de IID_IStorage a la función StgCreateStorageEx o StgOpenStorageEx . En cualquier caso, se devuelve un puntero a la interfaz IStorage del objeto. Con los conjuntos de propiedades persistentes, llame a QueryInterface para la interfaz IPropertySetStorage , especificando el nombre definido por el encabezado para el identificador de interfaz (IID) IID_IPropertySetStorage.
Casos en los que se debe usar
Use IPropertyStorage para administrar las propiedades dentro de un único conjunto de propiedades. Sus métodos admiten la lectura, escritura y eliminación de propiedades y los nombres de cadena opcionales que se pueden asociar a identificadores de propiedad. Otros métodos admiten las operaciones de confirmación estándar y reversión del almacenamiento. También hay un método que permite establecer las horas asociadas al almacenamiento de propiedades y otra que permite la asignación de un CLSID que se puede usar para asociar otro código, como el código de interfaz de usuario, con el conjunto de propiedades. Al llamar al método Enum , se proporciona un puntero a la implementación de archivo compuesto de IEnumSTATPROPSTG, que permite enumerar las propiedades del conjunto.
Nota
Si obtiene un puntero a IPropertyStorage mediante una llamada a StgCreateDocfile, StgCreateStorageEx, StgOpenStorage o StgOpenStorageEx en un almacenamiento de conjunto de propiedades en modo simple, los métodos IPropertyStorage cumplen las reglas de secuencias de modo simple. El almacenamiento del conjunto de propiedades es el modo simple si se obtuvo para un archivo que se creó o abrió con la marca STGM_SIMPLE. En este caso, no siempre es posible hacer que la secuencia subyacente sea mayor y no es posible reemplazar las propiedades existentes por propiedades más grandes. Para obtener más información, vea IPropertySetStorage-Compound File Implementation( Implementación de archivos compuestos de IPropertySetStorage).
IPropertyStorage y almacenamiento en caché
La implementación de archivo compuesto de IPropertyStorage almacena en caché los conjuntos de propiedades abiertos en memoria para mejorar el rendimiento. Como resultado, los cambios en un conjunto de propiedades no se escriben en el archivo compuesto hasta que se llame a los métodos Commit o Release (última referencia).
Conjuntos de propiedades de modo simple
Un objeto de almacenamiento de propiedades está en modo simple si se crea a partir de un objeto de almacenamiento de conjunto de propiedades en modo simple. Por ejemplo, un objeto de almacenamiento del conjunto de propiedades estaría en modo simple si se obtuviera de la función StgOpenStorageEx , con la marca STGM_SIMPLE establecida en el parámetro grfMode . Tenga en cuenta que "modo simple" no está relacionado con "conjuntos de propiedades simples". Un conjunto de propiedades es sencillo si se crea llamando a IPropertySetStorage::Create con la marca PROPSETFLAG_NONSIMPLE establecida en el parámetro grfFlags . Para obtener más información sobre los conjuntos de propiedades simples y nomples, vea Objetos de almacenamiento y secuencia para un conjunto de propiedades.
Cuando se crea un objeto de almacenamiento de propiedades en modo simple, no hay restricciones en su uso. Cuando se abre un objeto de almacenamiento de propiedades en modo simple existente, no se puede crecer el objeto de secuencia subyacente que almacena el conjunto de propiedades. Por lo tanto, no siempre es posible modificar este objeto de almacenamiento de propiedades si el cambio requiere una secuencia mayor.
Formatos de conjunto de propiedades
La implementación de archivo compuesto de IPropertyStorage admite los formatos de serialización de conjuntos de propiedades de la versión 0 y la versión 1. El formato de la versión 1 es compatible con equipos que se ejecutan en Windows 2000. Para obtener más información, vea Serialización del conjunto de propiedades. Los conjuntos de propiedades se crean en formato de versión 0 y permanecen en ese formato a menos que se soliciten nuevas características. Cuando esto ocurre, el formato se actualiza a la versión 1.
Por ejemplo, si se crea un conjunto de propiedades con la marca PROPSETFLAG_DEFAULT, su formato es la versión 0. Siempre que los tipos de propiedad que cumplan el formato de la versión 0 se escriban y lean desde ese conjunto de propiedades, el conjunto de propiedades permanece en formato de versión 0. Si se escribe un tipo de propiedad de versión 1 en el conjunto de propiedades, el conjunto de propiedades se actualiza automáticamente a la versión 1. Posteriormente, las implementaciones que reconocen solo la versión 0 no pueden leer ese conjunto de propiedades.
Tipos IPropertyStorage y Variant
La implementación de archivo compuesto de IPropertyStorage no admite los tipos de variante VT_UNKNOWN o VT_DISPATCH en el miembro vt de la estructura PROPVARIANT .
En la tabla siguiente se enumeran los tipos de variante que se admiten en safeArray; es decir, estos valores se pueden combinar con VT_ARRAY en el miembro vt de la estructura PROPVARIANT .
Tipos de variante admitidos en SafeArray por la implementación de archivos compuestos de 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
Cuando VT_VARIANT se combina con VT_ARRAY, el propio SafeArray contiene estructuras PROPVARIANT . Sin embargo, los tipos de estos elementos deben tomarse de la lista anterior, no se pueden VT_VARIANT y no pueden incluir los indicadores de VT_VECTOR, VT_ARRAY o VT_BYREF.
Métodos IPropertyStorage
La implementación de archivo compuesto de IPropertyStorage admite los métodos siguientes:
-
Lee las propiedades especificadas en la matriz rgpspec y proporciona los valores de todas las propiedades válidas en la matriz rgvar de PROPVARIANTs. En la implementación del archivo compuesto COM, los identificadores de propiedad duplicados que hacen referencia a los tipos de secuencia o almacenamiento dan lugar a varias llamadas a IStorage::OpenStream o IStorage::OpenStorage y el éxito o error de ReadMultiple depende de la capacidad de la implementación de almacenamiento subyacente para compartir operaciones de apertura. Dado que en un archivo compuesto STGM_SHARE_EXCLUSIVE se fuerza, se producirá un error en varios intentos abiertos. No se admite la apertura del mismo objeto de almacenamiento más de una vez desde el mismo almacenamiento primario. Se debe especificar la marca STGM_SHARE_EXCLUSIVE.
Además, para garantizar la operación segura para subprocesos si se solicita la misma propiedad con valores de flujo o almacenamiento varias veces a través del mismo puntero IPropertyStorage en la implementación del archivo compuesto COM, la operación de apertura se realizará correctamente o producirá un error en función de si la propiedad ya está abierta y si el sistema de archivos subyacente controla varias aperturas de una secuencia o almacenamiento. Por lo tanto, la operación ReadMultiple en una propiedad con valores de almacenamiento o de flujo siempre da como resultado una llamada a IStorage::OpenStream o IStorage::OpenStorage, que pasa el acceso (STGM_READWRITE, etc.) y las marcas de recurso compartido (STGM_SHARE_EXCLUSIVE, etc.) especificadas cuando se abrió o creó el conjunto de propiedades original.
Si se produce un error en el método, los valores escritos en rgvar[] no están definidos. Si algunas propiedades con valores de almacenamiento o de secuencia se abren correctamente, pero se produce un error antes de que se complete la ejecución, se deben liberar antes de que el método devuelva.
-
Escribe las propiedades especificadas en la matriz rgpspec[], asignándolas las etiquetas y valores PROPVARIANT especificados en rgvar[]. A las propiedades que ya existen se les asignan los valores PROPVARIANT especificados. Las propiedades que no existen actualmente se crean.
-
Elimina las propiedades especificadas en rgpspec[].
-
Lee los nombres de cadena existentes asociados a los identificadores de propiedad especificados en la matriz rgpropid[].
-
Asigna nombres de cadena especificados en la matriz rglpwstrName a los identificadores de propiedad especificados en la matriz rgpropid .
-
Elimina los nombres de propiedad de las propiedades especificadas en la matriz rgpropid[].
-
Establece el CLSID del flujo de conjunto de propiedades. En la implementación del archivo compuesto, al establecer el CLSID en un conjunto de propiedades nomple (uno que puede contener legalmente propiedades con valores de almacenamiento o de flujo, como se describe en IPropertySetStorage::Create) también establece el CLSID en el substorage subyacente para que se pueda obtener a través de una llamada a IStorage::Stat.
-
Para los conjuntos de propiedades simples y nomples, vacía la imagen de memoria del conjunto de propiedades en el almacenamiento subyacente. Además, para los conjuntos de propiedades en modo de transacción nomple, este método realiza una confirmación (como en IStorage::Commit) en el almacenamiento que contiene el conjunto de propiedades.
-
En el caso de los conjuntos de propiedades nomples, llama al método Revert del almacenamiento subyacente y vuelve a abrir la secuencia "contents". Para conjuntos de propiedades simples, esta interfaz siempre devuelve S_OK. Los conjuntos de propiedades nomples son aquellos que se crearon con la marca PROPSETFLAG_NONSIMPLE en el método IPropertySetStorage::Create . Para obtener más información, vea Objetos de almacenamiento y secuencia para un conjunto de propiedades .
-
Construye una instancia de IEnumSTATPROPSTG, los métodos de los que se puede llamar para enumerar las estructuras STATPROPSTG que proporcionan información sobre cada una de las propiedades del conjunto. Esta implementación crea una matriz en la que se lee todo el conjunto de propiedades y que se puede compartir cuando se llama a IEnumSTATPROPSTG::Clone . Los cambios realizados en el conjunto de propiedades no se reflejan en una instancia IEnumSTATPROPSTG abierta. Para ver estos cambios, se debe construir una nueva instancia de este enumerador.
-
Rellena los miembros de una estructura STATPROPSETSTG , que contiene datos sobre el conjunto de propiedades en su conjunto. A cambio, proporciona un puntero a la estructura . En el caso de los conjuntos de almacenamiento nompleados, esta implementación llama a IStorage::Stat (o IStream::Stat) para obtener las horas del almacenamiento o la secuencia subyacentes. En el caso de conjuntos de almacenamiento simples, no se mantiene ningún tiempo.
-
En el caso de los conjuntos de propiedades nomples, establece las horas admitidas por el almacenamiento subyacente. La implementación del almacenamiento de archivos compuesto admite las tres: modificación, acceso y creación. Esta implementación de SetTimes llama al método IStorage::SetElementTimes del almacenamiento subyacente para recuperar estas horas.
Temas relacionados