StgOpenStorage
This function opens an existing root storage object in the file system. You can use this function to open compound files, but you cannot use it to open directories, files, or summary catalogs. Nested storage objects can only be opened using their parents IStorage::OpenStorage method.
WINOLEAPI StgOpenStorage(
const WCHAR *pwcsName,
IStorage *pstgPriority,
DWORD grfMode,
SNB snbExclude,
DWORD reserved,
IStorage **ppstgOpen
);
Parameters
pwcsName
[in] Pointer to the path of the file containing the storage object to open. This parameter is ignored if the pStgPriority parameter is not NULL.pstgPriority
[in] Most often NULL. If not NULL, this parameter is used instead of the pwcsName parameter to specify the pointer to the IStorage interface on the storage object to open. It points to a previous opening of a root storage object, most often one that was opened in priority mode.After the StgOpenStorage function returns, the storage object specified in the pStgPriority parameter on function entry is invalid, and can no longer be used. Instead, use the one specified in the ppStgOpen parameter instead.
[in] Specifies the access mode to use to open the storage object.
grfMode
[in] Specifies the access mode to use to open the storage object.snbExclude
[in] If not NULL, this parameter points to a block of elements in the storage that are to be excluded as the storage object is opened. The exclusion occurs independent of whether a snapshot copy happens on the open. May be NULL.reserved
[in] Reserved for future use; set to zero.ppstgOpen
[out] Pointer to the IStorage* pointer variable that receives the interface pointer to the opened storage.
Return Values
One of the values described in the following table is returned.
| Value | Description |
|---|---|
| S_OK | The storage object was successfully opened. |
| STG_E_FILENOTFOUND | The specified file does not exist. |
| STG_E_ACCESSDENIED | Access was denied because the caller had insufficient permission, or another caller had the file open and locked. |
| STG_E_LOCKVIOLATION | Access was denied because another caller had the file open and locked. |
| STG_E_SHAREVIOLATION | Access was denied because another caller had the file open and locked. |
| STG_E_FILEALREADYEXISTS | The file exists but is not a storage object. |
| STG_E_TOOMANYOPENFILES | The storage object was not opened because there are too many open files. |
| STG_E_INSUFFICIENTMEMORY | The storage object was not opened due to a lack of memory. |
| STG_E_INVALIDNAME | There is a bad name in the pwcsName parameter. |
| STG_E_INVALIDPOINTER | There is a bad pointer in the snbExclude, pwcsName, pstgPriority, or ppStgOpen parameter. |
| STG_E_INVALIDFLAG | There is a bad flag combination in the grfMode parameter. |
| STG_E_INVALIDFUNCTION | STGM_DELETEONRELEASE was specified in the grfMode parameter. |
| STG_E_OLDFORMAT | The storage object being opened was created by the Beta 1 storage provider. This format is no longer supported. |
| STG_E_NOTSIMPLEFORMAT | 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 being used to open this storage object is a version prior to the one used to create it. |
| STG_E_PATHNOTFOUND | The specified path does not exist. |
This function can also return any file system errors or Win32 errors wrapped in an HRESULT.
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 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 following flag combinations are valid modes in the grfMode parameter: STGM_READWRITE|STGM_SHARE_DENY_WRITE and STGM_READ|STGM_SHARE_DENY_NONE.
Opening a storage object in read and/or write mode without denying writer permission to others (the grfMode parameter specifies STGM_SHARE_DENY_WRITE) can be a time-consuming operation since the StgOpenStorage call must make a snapshot 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 do 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).
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 only useful to applications whose documents do not require constant access to their storage objects while they are active.
Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.
Requirements
| Runs on | Versions | Defined in | Include | Link to |
|---|---|---|---|---|
| Windows CE OS | 2.0 and later | Objbase.h | Ole232.lib |
Note This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.
See Also
Last updated on Tuesday, July 13, 2004
© 1992-2000 Microsoft Corporation. All rights reserved.