Función StgOpenStorage (coml2api.h)

  • Artículo

La función StgOpenStorage abre un objeto de almacenamiento raíz existente en el sistema de archivos. Use esta función para abrir archivos compuestos. No lo use para abrir directorios, archivos o catálogos de resumen. Los objetos de almacenamiento anidados solo se pueden abrir mediante su método primario IStorage::OpenStorage .

Nota Las aplicaciones deben usar la nueva función StgOpenStorageEx, en lugar de StgOpenStorage, para aprovechar las características mejoradas y de Almacenamiento estructurado de Windows. Esta función, StgOpenStorage, sigue existiendo por compatibilidad con las aplicaciones que se ejecutan en Windows 2000.
 

Sintaxis

HRESULT StgOpenStorage(
  [in]  const WCHAR *pwcsName,
  [in]  IStorage    *pstgPriority,
  [in]  DWORD       grfMode,
  [in]  SNB         snbExclude,
  [in]  DWORD       reserved,
  [out] IStorage    **ppstgOpen
);

Parámetros

[in] pwcsName

Puntero a la ruta de acceso del archivo de cadena Unicode terminado en null que contiene el objeto de almacenamiento que se va a abrir. Este parámetro se omite si el parámetro pstgPriority no es NULL.

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

[in] snbExclude

Si no es NULL, puntero a un bloque de elementos del almacenamiento que se va a excluir cuando se abre el objeto de almacenamiento. La exclusión se produce independientemente de si se produce una copia de instantánea en la apertura. Puede ser NULL.

[in] reserved

Indica reservado para uso futuro; debe ser cero.

[out] ppstgOpen

Puntero a una variable de puntero IStorage* que recibe el puntero de interfaz al almacenamiento abierto.

Valor devuelto

La función StgOpenStorage 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 StgOpenStorage 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 IStorage al objeto de almacenamiento abierto en el parámetro ppstgOpen .

Para admitir el modo simple para guardar un objeto de almacenamiento sin substorages, la función StgOpenStorage 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

En el modo directo, una de las tres combinaciones siguientes es válida.

    STGM_DIRECT | STGM_READWRITE | STGM_SHARE_EXCLUSIVE

    STGM_DIRECT | STGM_READ | STGM_SHARE_DENY_WRITE

    STGM_DIRECT | STGM_READ | STGM_SHARE_EXCLUSIVE
Nota Abrir un objeto de almacenamiento en modo de lectura y escritura sin denegar el permiso de escritura a otros (el parámetro grfMode especifica STGM_SHARE_DENY_WRITE) puede ser una operación que consume mucho tiempo porque la llamada StgOpenStorage debe realizar una instantánea de todo el objeto de almacenamiento.
 
Las aplicaciones suelen intentar abrir objetos de almacenamiento con los siguientes permisos de acceso. Si la aplicación se realiza correctamente, nunca debe realizar una copia de instantánea. 
STGM_READWRITE | STGM_SHARE_DENY_WRITE 
    // transacted versus direct mode omitted for exposition

La aplicación puede revertir al uso de los permisos y realizar una copia de instantánea, si se produce un error en los permisos de acceso anteriores. La aplicación debe preguntar al usuario antes de realizar una copia que consume mucho tiempo.

STGM_READWRITE 
    // transacted versus direct mode omitted for exposition

Si la semántica de uso compartido de documentos implícita por los modos de acceso son adecuadas, la aplicación podría intentar abrir el almacenamiento como se indica a continuación. En este caso, si la aplicación se realiza correctamente, no se habrá realizado una copia de instantáneas (porque se especificó STGM_SHARE_DENY_WRITE , denegando el acceso de escritura a otros usuarios).

STGM_READ | STGM_SHARE_DENY_WRITE 
    // transacted versus direct mode omitted for exposition
Nota Para reducir el gasto de realizar una copia de instantáneas, las aplicaciones pueden abrir objetos de almacenamiento en modo de prioridad (grfMode especifica STGM_PRIORITY).
 
El parámetro snbExclude especifica un conjunto de nombres de elemento en este objeto de almacenamiento que se van a vaciar cuando se abre el objeto de almacenamiento: las secuencias se establecen en una longitud de cero; los objetos de almacenamiento tienen quitados todos sus elementos. Al excluir determinados flujos, el gasto de realizar una copia de instantánea se puede reducir significativamente. Casi siempre, este enfoque se usa después de abrir por primera vez el objeto de almacenamiento en modo de prioridad y, a continuación, leer completamente los elementos excluidos ahora en la memoria. Esta apertura del modo de prioridad anterior del objeto de almacenamiento debe pasarse a través del parámetro pstgPriority para quitar la exclusión implícita por el modo de prioridad. La aplicación que realiza la llamada es responsable de volver a escribir el contenido de los elementos excluidos antes de confirmar. Por lo tanto, esta técnica es muy útil solo para las aplicaciones cuyos documentos no requieren acceso constante a sus objetos de almacenamiento mientras están activos.

El parámetro pstgPriority está pensado como una comodidad para los autores de llamadas que reemplazan un objeto de almacenamiento existente, a menudo uno abierto en modo de prioridad, con un nuevo objeto de almacenamiento abierto en el mismo archivo, pero en un modo diferente. Cuando pstgPriority no es NULL, se usa para especificar el nombre de archivo en lugar de pwcsName, que se omite. Sin embargo, se recomienda que las aplicaciones siempre pasen NULL para pstgPriority porque StgOpenStorage libera el objeto en algunas circunstancias y no lo libera en otras circunstancias. En concreto, si la función devuelve un resultado de error, no es posible que el autor de la llamada determine si se liberó o no el objeto de almacenamiento.

El autor de la llamada puede duplicar la funcionalidad del parámetro pstgPriority de una manera más segura, como se muestra en el ejemplo siguiente:

// Replacement for:
// HRESULT hr = StgOpenStorage(
//         NULL, pstgPriority, grfMode, NULL, 0, &pstgNew);

STATSTG statstg;
HRESULT hr = pstgPriority->Stat(&statstg, 0);
pStgPriority->Release();
pStgPriority = NULL;
if (SUCCEEDED(hr))
{
    hr = StgOpenStorage(statstg.pwcsName, NULL, grfMode, NULL, 0, &pstgNew);
}

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

Consulte también

IStorage

StgCreateDocfile

StgOpenStorageEx