Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function opens an existing storage object that does not reside in a disk file, but instead has an underlying byte array provided by the caller.

Syntax 

WINOLEAPI StgOpenStorageOnILockBytes( 
  ILockBytes* 
plkbyt, 
  IStorage* 
pStgPriority, 
  DWORD 
grfMode, 
  SNB 
snbExclude, 
  DWORD 
reserved, 
  IStorage** 
ppstgOpen 
);

Parameters

plkbyt

[in] ILockBytespointer to the underlying byte array object that contains the storage object to be opened.

pStgPriority

[in] Most often NULL. If not NULL, this parameter is used instead of the plkbytparameter to specify the storage object to open. In this case, it points to the IStorageinterface on a previously opened root storage object, most often one that was opened in priority mode.

After the StgOpenStorageOnILockBytesfunction returns, the storage object specified in the pStgPriorityparameter on function entry is invalid, and can no longer be used; use the one specified in the ppStgOpenparameter instead.

grfMode

[in] Specifies the access mode to use to open the storage object.

snbExclude

[in] Can be NULL. 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.

reserved

[in] Reserved for future use; set to zero.

ppstgOpen

[out] Pointer to the location of an IStoragepointer to the opened storage on successful return.

Return Value

One of the values described in the following table is returned.

Value Description

S_OK

Indicates that the storage object was successfully opened.

STG_E_FILENOTFOUND

Indicates that the specified byte array does not exist.

STG_E_ACCESSDENIED

Indicates that access was denied because the caller has insufficient permission, or another caller has the file open and locked.

STG_E_LOCKVIOLATION

Indicates that access was denied because another caller has the file open and locked.

STG_E_SHAREVIOLATION

Indicates that access was denied because another caller has the file open and locked.

STG_E_FILEALREADYEXISTS

Indicates that the byte array 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 a lack of memory.

STG_E_INVALIDNAME

Indicates that either pwcsNameor snbExcludecontains an invalid name.

STG_E_INVALIDPOINTER

Indicates that snbExclude, pwcsName, pstgPriority, or ppStgOpencontains an invalid pointer.

STG_E_INVALIDFLAG

Indicates that the grfModeparameter contains a bad flag combination.

STG_E_INVALIDFUNCTION

Indicates that the access mode STGM_DELETEONRELEASE was specified in the grfModeparameter.

STG_E_OLDDLL

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

STG_E_OLDFORMAT

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

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

Remarks

The StgCreateDocfileOnILockBytesand StgOpenStorageOnILockBytesfunctions are not available for the non-desktop compatible implementation by means of CESYSGEN.

StgOpenStorageOnILockBytesopens the specified root storage object. The storage object is opened according to the access mode in the grfModeparameter. A pointer to the IStorageinterface on the opened storage object is supplied through the ppstgOpenparameter.

The storage object must have been previously created by the StgCreateDocfileOnILockBytesfunction.

Except for specifying a programmer-provided byte-array object, StgOpenStorageOnILockBytesis similar to the StgOpenStoragefunction. For more information, see StgOpenStorage.

Passing into this function any invalid and, under some circumstances, NULL pointers results in unexpected termination of the application.

To determine whether the platform supports this function, see Determining Supported COM APIs.

Requirements

Header objbase.h
Library ole32.lib
Windows Embedded CE Windows CE 2.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also