Función StgOpenStorageOnILockBytes (coml2api.h)

  • Artículo

La función StgOpenStorageOnILockBytes abre un objeto de almacenamiento existente que no reside en un archivo de disco, sino que tiene una matriz de bytes subyacente proporcionada por el autor de la llamada.

Sintaxis

HRESULT StgOpenStorageOnILockBytes(
  [in]  ILockBytes *plkbyt,
  [in]  IStorage   *pstgPriority,
  [in]  DWORD      grfMode,
  [in]  SNB        snbExclude,
  [in]  DWORD      reserved,
  [out] IStorage   **ppstgOpen
);

Parámetros

[in] plkbyt

Puntero ILockBytes al objeto de matriz de bytes subyacente que contiene el objeto de almacenamiento que se va a abrir.

[in] pstgPriority

Puntero a la interfaz IStorage que debe ser NULL. Si no es NULL, este parámetro se usa como se describe a continuación en la sección Comentarios.

Después de que stgOpenStorageOnILockBytes devuelva, es posible que el objeto de almacenamiento especificado en pStgPriority se haya liberado y ya no se debe usar.

[in] grfMode

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

[in] snbExclude

Puede ser NULL. Si no es NULL, este parámetro apunta a un bloque de elementos de este almacenamiento que se van a excluir cuando se abre el objeto de almacenamiento. Esta exclusión se produce independientemente de si se produce una copia de instantánea en la apertura.

[in] reserved

Indica reservado para uso futuro; debe ser cero.

[out] ppstgOpen

Apunta a la ubicación de un puntero IStorage al almacenamiento abierto cuando se devuelve correctamente.

Valor devuelto

La función StgOpenStorageOnILockBytes 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 . Consulte Estrategias de control de errores y Control de errores desconocidos.

Comentarios

StgOpenStorageOnILockBytes abre el objeto de almacenamiento raíz especificado. Un puntero a la interfaz IStorage del objeto de almacenamiento abierto se proporciona a través del parámetro ppstgOpen .

El objeto de almacenamiento debe haber sido creado previamente por la función StgCreateDocfileOnILockBytes .

Excepto para especificar un objeto byte-array proporcionado por el programador, StgOpenStorageOnILockBytes es similar a la función StgOpenStorage . El objeto de almacenamiento 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.

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

El parámetro pStgPriority está pensado como una comodidad para los autores de llamadas que reemplazan a un objeto de almacenamiento existente, a menudo uno abierto en modo de prioridad, con un nuevo objeto de almacenamiento abierto en la misma matriz de bytes. A diferencia del parámetro pStgPriority de StgOpenStorage, este parámetro no afecta a la operación abierta realizada por StgOpenStorageOnILockBytes y es simplemente un objeto de almacenamiento existente que el autor de la llamada desea liberar. Los autores de llamadas siempre deben pasar NULL para este parámetro porque StgOpenStorageOnILockBytes libera el objeto en algunas circunstancias y no lo libera en otras circunstancias. El autor de la llamada puede duplicar el uso del parámetro pStgPriority de una manera más segura liberando el objeto antes de llamar a StgOpenStorageOnILockBytes, como se muestra en el ejemplo siguiente:

// Replacement for:
// HRESULT hr = StgOpenStorageOnILockBytes(
//         plkbyt, pStgPriority, grfMode, NULL, 0, &pstgNew);

pStgPriority->Release();
pStgPriority = NULL;
hr = StgOpenStorage(plkbyt, NULL, grfMode, NULL, 0, &pstgNew);

Para obtener más información, consulte StgOpenStorage.

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

Consulte también

StgCreateDocfileOnILockBytes

StgOpenStorage