StgOpenStorage

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

HRESULT StgOpenStorage(

const WCHAR * pwcsName,	//Points to the pathname of the file containing storage object
IStorage * pstgPriority,	//Points to a previous opening of a root storage object
DWORD grfMode,	//Specifies the access mode for the object
SNB snbExclude,	//Points to an SNB structure specifying elements to be excluded
DWORD reserved,	//Reserved; must be zero
IStorage ** ppstgOpen	//Points to location for returning the storage object
);

Parameters

pwcsName

Points to the pathname of the storage object to open. This parameter is ignored if the pStgPriority parameter is not NULL.

pstgPriority

Most often NULL. If not NULL, this parameter is used instead of the pwcsName parameter to specify 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. Use the one specified in the ppStgOpen parameter instead.

grfMode

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

snbExclude

If not NULL, this parameter points to a block of elements in this storage that are to be excluded as the storage object is opened. This exclusion occurs independent of whether a snapshot copy happens on the open. May be NULL.

reserved

Indicates reserved for future use; must be zero.

ppstgOpen

Points to the location where the opened storage is placed.

Return Values

S_OK

Indicates the storage object was successfully opened.

STG_E_FILENOTFOUND

Indicates the specified file does not exist.

STG_E_ACCESSDENIED

Indicates insufficient access to open file. Exclusions specified without read-write permissions or attempt to open file with conflicting permissions to a simultaneous open.

STG_E_FILEALREADYEXISTS

Indicates the file exists but is not a storage object.

STG_E_TOOMANYOPENFILES

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

STG_E_INSUFFICIENTMEMORY

Indicates the storage object was not opened due to a lack of memory.

STG_E_INVALIDNAME

Indicates bad name in the pwcsName parameter or the snbExclude parameter.

STG_E_INVALIDPOINTER

Indicates bad pointer in one of the parameters: snbExclude, pwcsName, pstgPriority, or ppStgOpen.

STG_E_INVALIDFLAG

Indicates bad flag combination in the grfMode parameter.

STG_E_INVALIDFUNCTION

Indicates STGM_DELETEONRELEASE specified in the grfMode parameter.

STG_E_OLDDLL

Indicates the DLL being used to open this storage object is a version prior to the one used to create it.

STG_E_OLDFORMAT

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

File system error return values.

Comments

This function opens the specified root storage object according to the access mode in the grfMode parameter. A pointer to the opened storage object is returned through the ppstgOpen parameter.

Note 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 be a time consuming operation since the StgOpenStorage call must make a snapshot of the entire storage object.

Applications will 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 will never need 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 will be 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.

Software for developers

Delphi Components
.Net Components
Software for Android Developers

More information resources

MegaDetailed.Net
Unix Manual Pages
Delphi Examples

Databases for Amazon shops developers

Amazon Categories Database
Browse Nodes Database