Función StgCreateDocfile (coml2api.h)

La función StgCreateDocfile crea un nuevo objeto de almacenamiento de archivos compuestos mediante la implementación del archivo compuesto proporcionado por COM para la interfaz IStorage .

Sintaxis

HRESULT StgCreateDocfile(
  [in]  const WCHAR *pwcsName,
  [in]  DWORD       grfMode,
  [in]  DWORD       reserved,
  [out] IStorage    **ppstgOpen
);

Parámetros

[in] pwcsName

Puntero a un nombre de cadena Unicode terminado en null para el archivo compuesto 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 compuesto temporal con un nombre único.

[in] grfMode

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] reserved

Reservado para uso futuro; debe ser cero.

[out] ppstgOpen

Puntero a la ubicación del puntero IStorage al nuevo objeto de almacenamiento.

Valor devuelto

StgCreateDocfile 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

La función StgCreateDocfile crea un nuevo objeto de almacenamiento mediante la implementación de archivo compuesto proporcionado por COM para la interfaz IStorage . El nombre del archivo compuesto abierto se puede recuperar llamando al método IStorage::Stat .

StgCreateDocfile 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, vea Constantes STGM.

Si el archivo compuesto se abre en modo transaccionado (el parámetro grfMode especifica STGM_TRANSACTED) y ya existe un archivo con este nombre, el archivo existente no se modifica hasta que se confirmen todos los cambios pendientes. Si el proceso de llamada no tiene acceso de escritura al archivo existente (debido al control de acceso en el sistema de archivos), el parámetro grfMode solo puede especificar STGM_READ y no STGM_WRITE o STGM_READWRITE. El nuevo archivo compuesto abierto resultante todavía se puede escribir en, pero se producirá un error en una operación de confirmación posterior (en modo transaccionado, los permisos de escritura se aplican en el momento de la confirmació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. Esto se puede usar en aplicaciones que requieren una implementación de archivo compuesto con varios flujos y sin almacenamientos. El modo simple no admite todos los métodos en IStorage. Para obtener más información, vea Constantes STGM.

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

StgCreateDocfile se puede usar 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, probablemente uno que 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 .

Requisitos

Consulte también

Constantes STGM

StgCreateDocFileOnILockBytes

StgCreateStorageEx