StgOpenStorageEx

[This is preliminary documentation and subject to change.]

Opens an existing root storage object in the file system. You can use this function to open compound files and regular files. Nested storage objects can only be opened using their parent's IStorage::OpenStorage method.

HRESULT StgOpenStorageEx(
  const WCHAR * pwcsName,   //Points to the path of the file 
                            // containing storage object
  DWORD grfMode,         //Specifies the access mode for the object
  STGFMT stgfmt,        //Specifies the storage file format
  DWORD grfAttrs,        //Reserved; must be zero
  void * reserved1,        //Reserved; must be zero
  void * reserved2,        //Reserved; must be zero
  REFIID riid,        //Specifies the GUID of the interface pointer
  void ** ppObjectOpen,        //Address of an interface pointer
);
 

Parameters

pwcsName

[in] Points to the path of the file containing the storage object.

grfMode

[in] Specifies the access mode to use when opening the storage object. For more information, see the STGM enumeration. If the caller specifies transacted mode together with STGM_CREATE or STGM_CONVERT, the overwrite or conversion takes place at the time the storage object is opened and therefore is not revertible.

stgfmt

[in] Specifies the storage file format. For more information, see the STGFMT enumeration.

grfAttrs

[in] Reserved for future use; must be zero.

reserved1

[in] Reserved for future use; must be zero.

reserved2

[in] Reserved for future use; must be zero.

riid

[in] Specifies the GUID of the interface pointer to return.

ppObjectOpen

[out] Address of an interface pointer variable that receives a pointer for an interface on the storage object being opened; contains NULL if operation failed.

Return Values

S_OK

Indicates the storage object was successfully opened.

STG_E_INVALIDPOINTER

Indicates bad pointer in the ppObjectOpen parameter.

STG_E_INVALIDPARAMETER

Indicates invalid value for the grfAttrs, reserved1, reserved2, grfMode, or stgfmt parameters.

E_NOINTERFACE

Indicates that the specified interface is not supported.

STG_E_INVALIDFLAG

Indicates bad flag combination in the grfMode pointer (includes both STGM_DELETEONRELEASE and STGM_CONVERT flags).

STG_E_INVALIDNAME

Indicates bad name in the pwcsName parameter.

STG_E_INVALIDFUNCTION

Indicates the grfMode is set to STGM_DELETEONRELEASE.

STG_E_LOCKVIOLATION

Access denied because another caller has the file open and locked.

STG_E_SHAREVIOLATION

Access denied because another caller has the file open and locked.

STG_E_UNIMPLEMENTEDFUNCTION

Indicates the StgOpenStorageEx function is not implemented by the operating system. In this case, use the StgOpenStorage function instead.

This function can also return any file system errors or Win32 errors wrapped in an HRESULT.

Remarks

StgOpenStorageEx is a superset of the StgOpenStorage function, and should be used by new code. Future enhancements to Windows structured storage will be exposed through this function.

The StgOpenStorageEx function opens the specified root storage object according to the access mode in the grfMode parameter, and, if successful, supplies an interface pointer for the opened storage object in the ppObjectOpen parameter.

When you open a file, the system selects a structured storage implementation depending on what STGFMT flag you specify and on what type of drive the file is stored. See the STGFMT documentation for more information.

You can use the StgOpenStorageEx function to get access to the root storage of a structured storage document, the contents stream of a flat file, or the property set storage of any file that supports property sets. For information about which interface identifiers (IIDs) are supported for the different STGFMT values, see the STGFMT enumeration.

To support the simple mode for saving a storage object with no substorages, the StgOpenStorageEx function accepts the following flag combinations as valid modes in the grfMode parameter: STGM_SIMPLE|STGM_READWRITE|STGM_SHARE_EXCLUSIVE and STGM_SIMPLE|STGM_READ|STGM_SHARE_EXCLUSIVE.

To support the Single-Writer/Multi-Reader Direct mode, the StgOpenStorageEx function accepts the following flag combinations as valid modes in the grfMode parameter: STGM_READWRITE|STGM_SHARE_DENY_WRITE and STGM_READ|STGM_SHARE_DENY_NONE.

Note  Opening a storage object in read and/or write mode without denying writer permissions to others (the grfMode parameter specifies STGM_SHARE_DENY_WRITE) can be a time-consuming operation since the StgOpenStorageEx call must make a snapshot copy of the entire storage object.

Applications often try to open storage objects with the following access permissions:

STGM_READ_WRITE | STGM_SHARE_DENY_WRITE 
    // transacted vs. direct mode omitted for exposition 
 

If the application succeeds, it never needs to make a snapshot copy. If it fails, the application can revert to using the permissions and make a snapshot copy:

STGM_READ_WRITE 
    // transacted vs. direct mode omitted for exposition 
 

In this case, the application should prompt the user before doing a time-consuming copy. Alternatively, if the document sharing semantics implied by the access modes are appropriate, the application could try to open the storage as follows:

STGM_READ | STGM_SHARE_DENY_WRITE 
    // transacted vs. direct mode omitted for exposition 
 

In this case, if the application succeeds, a snapshot copy will not have been made (because STGM_SHARE_DENY_WRITE was specified, denying others write access).

To reduce the expense of making a snapshot copy, applications can open storage objects in priority mode (grfMode specifies STGM_PRIORITY).

QuickInfo

  Windows NT: Use version 5.0 or later.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in objbase.h.

See Also

IStorage, StgCreateDocfile, StgCreateStorageEx, StgOpenStorage