Función StgOpenStorageEx (coml2api.h)

Artículo
08/22/2023

La función StgOpenStorageEx abre un objeto de almacenamiento raíz existente en el sistema de archivos. Use esta función para abrir archivos compuestos y archivos normales. Para crear un archivo, use la función StgCreateStorageEx .

Nota Para usar mejoras, todas las aplicaciones de Windows 2000, Windows XP y Windows Server 2003 deben llamar a StgOpenStorageEx, en lugar de StgOpenStorage. La función StgOpenStorage se usa para la compatibilidad con Windows 2000 y las aplicaciones anteriores.

Sintaxis

HRESULT StgOpenStorageEx(
  [in]      const WCHAR          *pwcsName,
  [in]      DWORD                grfMode,
  [in]      DWORD                stgfmt,
  [in]      DWORD                grfAttrs,
  [in, out] STGOPTIONS           *pStgOptions,
  [in]      PSECURITY_DESCRIPTOR pSecurityDescriptor,
  [in]      REFIID               riid,
  [out]     void                 **ppObjectOpen
);

Parámetros

[in] pwcsName

Puntero a la ruta de acceso del archivo de cadena Unicode terminado en null que contiene el objeto de almacenamiento. Este tamaño de cadena no puede superar MAX_PATH caracteres.

Windows Server 2003 y Windows XP/2000: A diferencia de la función CreateFile , no se puede superar el límite de MAX_PATH mediante el prefijo "\?".

[in] grfMode

Valor que especifica el modo de acceso para abrir el nuevo objeto de almacenamiento. Para obtener más información, vea Constantes STGM. Si el autor de la llamada especifica el modo de transacción junto con STGM_CREATE o STGM_CONVERT, la sobrescritura o conversión se produce cuando se llama a la operación de confirmación para el almacenamiento raíz. Si no se llama a IStorage::Commit para el objeto de almacenamiento raíz, se restaurará el contenido anterior del archivo. STGM_CREATE y STGM_CONVERT no se pueden combinar con la marca STGM_NOSNAPSHOT , ya que se requiere una copia de instantánea cuando se sobrescribe o se convierte un archivo en modo de transacción.

Si el objeto de almacenamiento se abre en modo directo (STGM_DIRECT) con acceso a STGM_WRITE o STGM_READWRITE, el modo de uso compartido debe ser STGM_SHARE_EXCLUSIVE a menos que se especifique el modo de STGM_DIRECT_SWMR . Para obtener más información, vea la sección Comentarios. Si el objeto de almacenamiento se abre en modo directo con acceso a STGM_READ, el modo de uso compartido debe ser STGM_SHARE_EXCLUSIVE o STGM_SHARE_DENY_WRITE, a menos que se especifique STGM_PRIORITY o STGM_DIRECT_SWMR . Para obtener más información, vea la sección Comentarios.

El modo en el que se abre un archivo puede afectar al rendimiento de la implementación. Para obtener más información, consulte Límites de implementación de archivos compuestos.

[in] stgfmt

Valor que especifica el formato de archivo de almacenamiento. Para obtener más información, vea la enumeración STGFMT .

[in] grfAttrs

Valor que depende del valor del parámetro stgfmt .

STGFMT_DOCFILE debe ser cero (0) o FILE_FLAG_NO_BUFFERING. Para obtener más información sobre este valor, vea CreateFile. Si el tamaño del sector del archivo, especificado en pStgOptions, no es un número entero múltiplo del tamaño del sector físico del disco subyacente, se producirá un error en esta operación. Todos los demás valores de stgfmt deben ser cero.

[in, out] pStgOptions

Puntero a una estructura STGOPTIONS que contiene datos sobre el objeto de almacenamiento abierto. El parámetro pStgOptions solo es válido si el parámetro stgfmt está establecido en STGFMT_DOCFILE. El miembro usVersion debe establecerse antes de llamar a StgOpenStorageEx. Para obtener más información, consulte la estructura STGOPTIONS .

[in] pSecurityDescriptor

Reservados; debe ser cero.

[in] riid

Valor que especifica el GUID del puntero de interfaz que se va a devolver. También puede ser el valor especificado por el encabezado de IID_IStorage para obtener la interfaz IStorage o para IID_IPropertySetStorage para obtener la interfaz IPropertySetStorage .

[out] ppObjectOpen

Dirección de una variable de puntero de interfaz que recibe un puntero para una interfaz en el objeto de almacenamiento abierto; contiene NULL si se produjo un error en la operación.

Valor devuelto

Esta función también puede devolver cualquier error del sistema de archivos o errores del sistema encapsulados en un HRESULT. Para obtener más información, vea Estrategias de control de errores y control de errores desconocidos.

Comentarios

StgOpenStorageEx es un superconjunto de la función StgOpenStorage y el código nuevo debe usarse. Las mejoras futuras en el almacenamiento estructurado se exponen a través de esta función. Para obtener más información sobre las plataformas admitidas, consulte la sección Requisitos.

La función StgOpenStorageEx abre el objeto de almacenamiento raíz especificado según el modo de acceso en el parámetro grfMode y, si se ejecuta correctamente, proporciona un puntero de interfaz para el objeto de almacenamiento abierto en el parámetro ppObjectOpen . Esta función se puede usar para obtener una implementación de archivo compuesto de IStorage, una implementación de archivo compuesto IPropertySetStorage o una
Implementación del sistema de archivos NTFS de IPropertySetStorage.

Al abrir un archivo, el sistema selecciona una implementación de almacenamiento estructurado en función de la marca STGFMT que especifique en el tipo de archivo y en el tipo de unidad donde se almacena el archivo.

Use la función StgOpenStorageEx para tener acceso al almacenamiento raíz de un documento de almacenamiento estructurado o al almacenamiento del conjunto de propiedades de cualquier archivo que admita conjuntos de propiedades. Para obtener más información sobre qué identificadores de interfaz (IID) se admiten para los distintos valores STGFMT , vea STGFMT.

Cuando se abre un archivo con esta función para tener acceso a la implementación del conjunto de propiedades NTFS, se aplican reglas de uso compartido especiales. Para obtener más información, vea Implementación de IPropertySetStorage-NTFS.

Si un archivo compuesto se abre en modo de transacción, especificando STGM_TRANSACTED y modo de solo lectura, especificando STGM_READ, es posible cambiar el objeto de almacenamiento devuelto. Por ejemplo, es posible llamar a IStorage::CreateStream. Sin embargo, no es posible confirmar esos cambios mediante una llamada a IStorage::Commit. Por lo tanto, estos cambios se perderán.

No es válido usar las marcas STGM_CREATE, STGM_DELETEONRELEASE o STGM_CONVERT en el parámetro grfMode para esta función.

Para admitir el modo simple para guardar un objeto de almacenamiento sin substorages, la función StgOpenStorageEx acepta una de las dos combinaciones de marcas siguientes como modos válidos en el parámetro grfMode :

    STGM_SIMPLE | STGM_READWRITE | STGM_SHARE_EXCLUSIVE

    STGM_SIMPLE | STGM_READ | STGM_SHARE_EXCLUSIVE

Para admitir el sistema de escritura único, multireader, modo directo, la primera combinación de marcas es el parámetro grfMode válido para el escritor. La segunda combinación de marcas es válida para los lectores.

    STGM_DIRECT_SWMR | STGM_READWRITE | STGM_SHARE_DENY_WRITE

    STGM_DIRECT_SWMR | STGM_READ | STGM_SHARE_DENY_NONE

Para obtener más información sobre el modo simple y los modos de escritura única o de varios lectores, vea StGM Constants( Constantes STGM).

Nota Abrir un objeto de almacenamiento en modo de transacción en modo de lectura o escritura sin denegar permisos de escritura a otros (por ejemplo, el parámetro grfMode especifica STGM_SHARE_DENY_WRITE) puede llevar mucho tiempo porque la llamada StgOpenStorageEx debe crear una copia de instantánea de todo el objeto de almacenamiento.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000 Professional [aplicaciones de escritorio \| Aplicaciones para UWP]
Servidor mínimo compatible	Windows 2000 Server [aplicaciones de escritorio \| Aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	coml2api.h (include Objbase.h)
Library	Ole32.lib
Archivo DLL	Ole32.dll