Función StgCreateStorageEx (coml2api.h)

Artículo
08/22/2023

La función StgCreateStorageEx crea un nuevo objeto de almacenamiento mediante una implementación proporcionada para las interfaces IStorage o IPropertySetStorage . Para abrir un archivo existente, use la función StgOpenStorageEx en su lugar.

Las aplicaciones escritas para Windows 2000, Windows Server 2003 y Windows XP deben usar StgCreateStorageEx en lugar de StgCreateDocfile para aprovechar las características mejoradas de Almacenamiento estructurado de Windows 2000 y Windows XP.

Sintaxis

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

Parámetros

[in] pwcsName

Puntero a la ruta de acceso del archivo que se va a crear. Se pasa sininterpretado al sistema de archivos. Puede ser un nombre relativo o NULL. Si es NULL, se asigna un archivo temporal con un nombre único. Si no es NULL, el tamaño de cadena no debe superar MAX_PATH caracteres.

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

[in] grfMode

Valor que especifica el modo de acceso que se va a usar al abrir el nuevo objeto de almacenamiento. Para obtener más información, vea Constantes STGM. Si el autor de la llamada especifica el modo transaccionado junto con STGM_CREATE o STGM_CONVERT, se produce la sobrescritura o conversión 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 de STGM_NOSNAPSHOT, ya que se requiere una copia de instantánea cuando se sobrescribe o se convierte un archivo en el modo transaccionado.

[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 .

Valores de parámetros	Significado
STGFMT_DOCFILE	0 o FILE_FLAG_NO_BUFFERING. Para obtener más información, consulte 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	Debe ser 0.

[in] pStgOptions

El parámetro pStgOptions solo es válido si el parámetro stgfmt está establecido en STGFMT_DOCFILE. Si el parámetro stgfmt se establece en STGFMT_DOCFILE, pStgOptions apunta a la estructura STGOPTIONS , que especifica características del objeto de almacenamiento, como el tamaño del sector. Este parámetro puede ser NULL, que crea un objeto de almacenamiento con un tamaño de sector predeterminado de 512 bytes. Si no es NULL, el miembro ulSectorSize debe establecerse en 512 o 4096. Si se establece en 4096, es posible que no se especifique STGM_SIMPLE en el parámetro grfMode . El miembro usVersion debe establecerse antes de llamar a StgCreateStorageEx. Para obtener más información, consulte STGOPTIONS.

[in] pSecurityDescriptor

Permite establecer las ACL cuando se crea el archivo. Si no es NULL, debe ser un puntero a la estructura SECURITY_ATTRIBUTES . Consulte CreateFile para obtener información sobre cómo establecer ACL en archivos.

Windows Server 2003, Windows 2000 Server, Windows XP y Windows 2000 Professional: El valor debe ser NULL.

[in] riid

Valor que especifica el identificador de interfaz (IID) del puntero de interfaz que se va a devolver. Este IID puede ser para la interfaz IStorage o la interfaz IPropertySetStorage .

[out] ppObjectOpen

Puntero a una variable de puntero de interfaz que recibe un puntero para una interfaz en el nuevo objeto de almacenamiento; 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

Cuando una aplicación modifica su archivo, normalmente crea una copia del original. La función StgCreateStorageEx es una manera de crear una copia. Esta función funciona indirectamente con la API de duplicación del sistema de archivos de cifrado (EFS). Al usar esta función, deberá establecer las opciones para el almacenamiento de archivos en la estructura STGOPTIONS .

StgCreateStorageEx es un superconjunto de la función StgCreateDocfile y debe usarse mediante código nuevo. Las futuras mejoras en Structured Storage se mostrarán a través de la función StgCreateStorageEx . Consulte la sección Requisitos siguientes para obtener información sobre las plataformas compatibles.

La función StgCreateStorageEx crea un nuevo objeto de almacenamiento mediante una de las implementaciones de almacenamiento estructuradas proporcionadas por el sistema. Esta función se puede usar para obtener una
Implementación de archivos compuestos de IStorage, una implementación de archivo compuesto IPropertySetStorage o para obtener una implementación NTFS de IPropertySetStorage.

Cuando se crea un nuevo archivo, la implementación de almacenamiento usada depende de la marca que especifique y del tipo de unidad en la que se almacena el archivo. Para obtener más información, vea la enumeración STGFMT .

StgCreateStorageEx crea el archivo si no existe. Si existe, el uso de las marcas STGM_CREATE, STGM_CONVERT y STGM_FAILIFTHERE en el parámetro grfMode indican cómo continuar. Para obtener más información sobre estos valores, vea Constantes STGM. No es válido, en modo directo, especificar el modo STGM_READ en el parámetro grfMode (el modo directo se indica sin especificar la marca STGM_TRANSACTED). Esta función no se puede usar para abrir un archivo existente; use la función StgOpenStorageEx en su lugar.

Puede usar la función StgCreateStorageEx para obtener 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. Consulte la documentación de STGFMT para obtener información sobre qué IID se admiten para diferentes valores STGFMT .

Cuando se crea un archivo con esta función para acceder 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 se crea un archivo compuesto en modo transaccionado (especificando STGM_TRANSACTED) y modo de solo lectura (especificando STGM_READ), es posible realizar cambios en 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.

Especificar STGM_SIMPLE proporciona una implementación mucho más rápida de un objeto de archivo compuesto en un caso limitado, pero frecuentemente usado que implica aplicaciones que requieren una implementación de archivos compuestas con varios flujos y sin almacenamientos. Para obtener más información, vea Constantes STGM. No es válido especificar que STGM_TRANSACTED si se especifica STGM_SIMPLE.

El modo simple no admite todos los métodos en IStorage. En concreto, en modo simple, los métodos IStorage admitidos son CreateStream, Commit y SetClass , así como los métodos COM IUnknown de QueryInterface, AddRef y Release. Además, SetElementTimes se admite con un nombre NULL , lo que permite a las aplicaciones establecer horas en un almacenamiento raíz. Todos los demás métodos de IStorage devuelven STG_E_INVALIDFUNCTION.

Si el parámetro grfMode especifica STGM_TRANSACTED y aún no existe ningún archivo con el nombre especificado por el parámetro pwcsName , el archivo se crea inmediatamente. En un sistema de archivos controlado por acceso, el llamador debe tener permisos de escritura para el directorio del sistema de archivos en el que se crea el archivo compuesto. Si no se especifica STGM_TRANSACTED y se especifica STGM_CREATE, se destruye un archivo existente con el mismo nombre antes de crear el nuevo archivo.

También puede usar StgCreateStorageEx para crear un archivo compuesto temporal pasando un valor NULL para el parámetro pwcsName . Sin embargo, estos archivos solo son temporales en el sentido de que tienen un nombre único proporcionado por el sistema, uno que probablemente no tenga sentido para el usuario. El autor de la llamada es responsable de eliminar el archivo temporal cuando termine con él, a menos que se especifique STGM_DELETEONRELEASE para el parámetro grfMode . Para obtener más información sobre estas marcas, vea Constantes STGM.

Requisitos


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 (incluya Objbase.h)
Library	Ole32.lib
Archivo DLL	Ole32.dll