StgOpenStorage function

The StgOpenStorage function opens an existing root storage object in the file system. Use this function to open compound files. Do not use it to open directories, files, or summary catalogs. Nested storage objects can only be opened using their parent IStorage::OpenStorage method.

Syntax

HRESULT StgOpenStorage(
  _In_  const WCHAR    *pwcsName,
  _In_        IStorage *pstgPriority,
  _In_        DWORD    grfMode,
  _In_        SNB      snbExclude,
  _In_        DWORD    reserved,
  _Out_       IStorage **ppstgOpen
);

Parameters

pwcsName [in]

A pointer to the path of the null-terminated Unicode string file that contains the storage object to open. This parameter is ignored if the pstgPriority parameter is not NULL.

pstgPriority [in]

A pointer to the IStorage interface that should be NULL. If not NULL, this parameter is used as described below in the Remarks section.

After StgOpenStorage returns, the storage object specified in pStgPriority may have been released and should no longer be used.

grfMode [in]

Specifies the access mode to use to open the storage object.

snbExclude [in]

If not NULL, pointer to a block of elements in the storage to be excluded as the storage object is opened. The exclusion occurs regardless of whether a snapshot copy happens on the open. Can be NULL.

reserved [in]

Indicates reserved for future use; must be zero.

ppstgOpen [out]

A pointer to a IStorage* pointer variable that receives the interface pointer to the opened storage.

Return value

S_OK

Indicates that the storage object was successfully opened.

STG_E_FILENOTFOUND

Indicates that the specified file does not exist.

STG_E_ACCESSDENIED

Access denied because the caller does not have enough permissions, or another caller has the file open and locked.

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_FILEALREADYEXISTS

Indicates that the file exists but is not a storage object.

STG_E_TOOMANYOPENFILES

Indicates that the storage object was not opened because there are too many open files.

STG_E_INSUFFICIENTMEMORY

Indicates that the storage object was not opened due to inadequate memory.

STG_E_INVALIDNAME

Indicates a non-valid name in the pwcsName parameter.

STG_E_INVALIDPOINTER

Indicates a non-valid pointer in one of the parameters: snbExclude, pwcsName, pstgPriority, or ppStgOpen.

STG_E_INVALIDFLAG

Indicates a non-valid flag combination in the grfMode parameter.

STG_E_INVALIDFUNCTION

Indicates STGM_DELETEONRELEASE specified in the grfMode parameter.

STG_E_OLDFORMAT

Indicates that the storage object being opened was created by the Beta 1 storage provider. This format is no longer supported.

STG_E_NOTSIMPLEFORMAT

Indicates that the STGM_SIMPLE flag was specified in the grfMode parameter and the storage object being opened was not written in simple mode.

STG_E_OLDDLL

The DLL used to open this storage object is a version of the DLL that is older than the one used to create it.

STG_E_PATHNOTFOUND

Specified path does not exist.

STG_E_SHAREVIOLATION

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

The StgOpenStorage function can also return any file system errors or system errors wrapped in an HRESULT. For more information, see Error Handling Strategies and Handling Unknown Errors.

Remarks

The StgOpenStorage function opens the specified root storage object according to the access mode in the grfMode parameter, and, if successful, supplies an IStorage pointer to the opened storage object in the ppstgOpen parameter.

To support the simple mode for saving a storage object with no substorages, the StgOpenStorage function accepts one of the following two flag combinations as valid modes in the grfMode parameter.

    STGM_SIMPLE | STGM_READWRITE | STGM_SHARE_EXCLUSIVE

    STGM_SIMPLE | STGM_READ | STGM_SHARE_EXCLUSIVE

To support the single-writer, multireader, direct mode, the first flag combination is the valid grfMode parameter for the writer. The second flag combination is valid for readers.

    STGM_DIRECT_SWMR | STGM_READWRITE | STGM_SHARE_DENY_WRITE

    STGM_DIRECT_SWMR | STGM_READ | STGM_SHARE_DENY_NONE

In direct mode, one of the following three combinations are valid.

    STGM_DIRECT | STGM_READWRITE | STGM_SHARE_EXCLUSIVE

    STGM_DIRECT | STGM_READ | STGM_SHARE_DENY_WRITE

    STGM_DIRECT | STGM_READ | STGM_SHARE_EXCLUSIVE

Applications often try to open storage objects with the following access permissions. If the application succeeds, it never needs to make a snapshot copy.

STGM_READWRITE | STGM_SHARE_DENY_WRITE 
    // transacted versus direct mode omitted for exposition 

The application can revert to using the permissions and make a snapshot copy, if the previous access permissions fail. The application should prompt the user before making a time-consuming copy.

STGM_READWRITE 
    // transacted versus direct mode omitted for exposition 

If the document-sharing semantics implied by the access modes are appropriate, the application could try to open the storage as follows. 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).

STGM_READ | STGM_SHARE_DENY_WRITE 
    // transacted versus direct mode omitted for exposition 

The snbExclude parameter specifies a set of element names in this storage object that are to be emptied as the storage object is opened: streams are set to a length of zero; storage objects have all their elements removed. By excluding certain streams, the expense of making a snapshot copy can be significantly reduced. Almost always, this approach is used after first opening the storage object in priority mode, then completely reading the now-excluded elements into memory. This earlier priority-mode opening of the storage object should be passed through the pstgPriority parameter to remove the exclusion implied by priority mode. The calling application is responsible for rewriting the contents of excluded items before committing. Thus, this technique is most likely useful only to applications whose documents do not require constant access to their storage objects while they are active.

The pstgPriority parameter is intended as a convenience for callers replacing an existing storage object, often one opened in priority mode, with a new storage object opened on the same file but in a different mode. When pstgPriority is not NULL, it is used to specify the file name instead of pwcsName, which is ignored. However, it is recommended that applications always pass NULL for pstgPriority because StgOpenStorage releases the object under some circumstances, and does not release it under other circumstances. In particular, if the function returns a failure result, it is not possible for the caller to determine whether or not the storage object was released.

The functionality of the pstgPriority parameter can be duplicated by the caller in a safer manner as shown in the following example:

// 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);
}     

Requirements

See also

IStorage

StgCreateDocfile

StgOpenStorageEx