Función StgCreateDocfileOnILockBytes (coml2api.h)

La función StgCreateDocfileOnILockBytes crea y abre un nuevo objeto de almacenamiento de archivos compuesto sobre un objeto de matriz de bytes proporcionado por el autor de la llamada. El objeto de almacenamiento admite la implementación de archivo compuesto proporcionado por COM para la interfaz IStorage .

Sintaxis

HRESULT StgCreateDocfileOnILockBytes(
  [in]  ILockBytes *plkbyt,
  [in]  DWORD      grfMode,
  [in]  DWORD      reserved,
  [out] IStorage   **ppstgOpen
);

Parámetros

[in] plkbyt

Puntero a la interfaz ILockBytes en el objeto de matriz de bytes subyacente en el que se va a crear un archivo compuesto.

[in] grfMode

Especifica el modo de acceso que se va a usar al abrir el nuevo archivo compuesto. Para obtener más información, vea StGM Constants (Constantes STGM ) y la sección Comentarios a continuación.

[in] reserved

Reservado para uso futuro; debe ser cero.

[out] ppstgOpen

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

Valor devuelto

La función StgCreateDocfileOnILockBytes también puede devolver cualquier error del sistema de archivos, o errores del sistema ajustados en un HRESULT o valores devueltos por la interfaz ILockBytes . Para obtener más información, vea Estrategias de control de errores y Control de errores desconocidos.

Comentarios

La función StgCreateDocfileOnILockBytes crea un objeto de almacenamiento sobre un objeto de matriz de bytes mediante la implementación de archivo compuesto proporcionado por COM de la interfaz IStorage . StgCreateDocfileOnILockBytes se puede usar para almacenar un documento en un almacén de datos arbitrario, como la memoria o una base de datos relacional. La matriz de bytes (indicada por el parámetro pLkbyt , que apunta a la interfaz ILockBytes del objeto) se usa para el almacenamiento subyacente en lugar de un archivo de disco.

Excepto para especificar un objeto byte-array proporcionado por el programador, StgCreateDocfileOnILockBytes es similar a la función StgCreateDocfile .

El archivo compuesto recién creado se abre según los modos de acceso en el parámetro grfMode , sujeto a las siguientes restricciones:

El comportamiento del modo de uso compartido y el aislamiento transaccional dependen de la implementación de ILockBytes que admita LockRegion y UnlockRegion con LOCK_ONLYONCE semántica. Las implementaciones pueden indicar que el almacenamiento estructurado admite esta funcionalidad estableciendo el bit de LOCK_ONLYONCE en el miembro grfLocksSupported de STATSTG. Si una implementación de ILockBytes no admite esta funcionalidad, no se aplicarán modos de uso compartido y las confirmaciones transaccionales de nivel raíz no se coordinarán correctamente con otras instancias transaccionales abiertas en la misma matriz de bytes. Las aplicaciones que usan una implementación de ILockBytes que no admite el bloqueo de regiones, como la implementación createStreamOnHGlobal , deben evitar abrir varias instancias simultáneas en la misma matriz de bytes.

StgCreateDocfileOnILockBytes no admite el modo simple. La marca STGM_SIMPLE , si está presente, se omite.

Con fines de conversión, el archivo se considera que ya existe. Como resultado, no es útil usar el valor de STGM_FAILIFTHERE , ya que hace que se devuelva un error. Sin embargo, tanto STGM_CREATE como STGM_CONVERT siguen siendo útiles.

La capacidad de crear un archivo compuesto sobre un objeto de matriz de bytes se proporciona para admitir que los datos (debajo de una estructura de árbol IStorage e IStream ) residan en un espacio no persistente. Dada esta funcionalidad, no hay nada que impida que un documento almacenado en un archivo use esta instalación. Por ejemplo, un contenedor podría hacer esto para minimizar el impacto en su formato de archivo causado por la adopción de COM. Sin embargo, se recomienda que los documentos COM adopten la interfaz IStorage para su propio almacenamiento de nivel externo. Esto tiene las ventajas siguientes:

• La estructura de almacenamiento del documento es la misma que su estructura de almacenamiento cuando es un objeto incrustado, lo que reduce el número de casos que la aplicación necesita controlar.
• Puede escribir herramientas para acceder a los objetos incrustados y vinculados OLE dentro del documento sin tener conocimientos especiales sobre el formato de archivo del documento. Un ejemplo de esta herramienta es una utilidad de copia que copia todos los documentos incluidos en un contenedor que contiene objetos vinculados. Una utilidad de copia como esta necesita acceso a los vínculos contenidos para determinar la extensión de los archivos que se van a copiar.
• La implementación de IStorage soluciona el problema de cómo confirmar los cambios en el archivo. Una aplicación que use la interfaz ILockBytes debe controlar estos problemas.

Requisitos

Consulte también

StgCreateDocfile