Export (0) Print
Expand All
This topic has not yet been rated - Rate this topic

StgOpenStorageOnILockBytes function

The StgOpenStorageOnILockBytes 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


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

Parameters

plkbyt [in]

ILockBytes pointer to the underlying byte array object that contains the storage object to be opened.

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 StgOpenStorageOnILockBytes 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. For more information, see STGM Constants and the Remarks section below.

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 independently of whether a snapshot copy happens on the open.

reserved [in]

Indicates reserved for future use; must be zero.

ppstgOpen [out]

Points to the location of an IStorage pointer to the opened storage on successful return.

Return value

S_OK

The storage object was successfully opened.

STG_E_FILENOTFOUND

The specified byte array does not exist.

STG_E_ACCESSDENIED

Access denied because the caller has insufficient permission, 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

The byte array 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

Either pwcsName or snbExclude contains an invalid name.

STG_E_INVALIDPOINTER

Either snbExclude, pwcsName, pstgPriority, or ppStgOpen contains a non-valid pointer.

STG_E_INVALIDFLAG

The grfMode parameter contains a non-valid flag combination.

STG_E_INVALIDFUNCTION

The access mode STGM_DELETEONRELEASE was specified in the grfMode parameter.

STG_E_OLDDLL

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

STG_E_OLDFORMAT

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

The StgOpenStorageOnILockBytes function can also return any file system errors, or system errors wrapped in an HRESULT, or ILockBytes interface error return values. See Error Handling Strategies and Handling Unknown Errors.

Remarks

StgOpenStorageOnILockBytes opens the specified root storage object. A pointer to the IStorage interface on the opened storage object is supplied through the ppstgOpen parameter.

The storage object must have been previously created by the StgCreateDocfileOnILockBytes function.

Except for specifying a programmer-provided byte-array object, StgOpenStorageOnILockBytes is similar to the StgOpenStorage function. The storage object is opened according to the access modes in the grfMode parameter, subject to the following restrictions:

Sharing mode behavior and transactional isolation depend on the ILockBytes implementation supporting LockRegion and UnlockRegion with LOCK_ONLYONCE semantics. Implementations can indicate to structured storage they support this functionality by setting the LOCK_ONLYONCE bit in the grfLocksSupported member of STATSTG. If an ILockBytes implementation does not support this functionality, sharing modes will not be enforced, and root-level transactional commits will not coordinate properly with other transactional instances opened on the same byte array. Applications that use an ILockBytes implementation that does not support region locking, such as the CreateStreamOnHGlobal implementation, should avoid opening multiple concurrent instances on the same byte array.

StgOpenStorageOnILockBytes does not support simple mode. The STGM_SIMPLE flag, if present, is ignored.

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 byte array. Unlike the pStgPriority parameter of StgOpenStorage, this parameter does not affect the open operation performed by StgOpenStorageOnILockBytes and is simply an existing storage object the caller would like released. Callers should always pass NULL for this parameter because StgOpenStorageOnILockBytes releases the object under some circumstances, and does not release it under other circumstances. The use of the pStgPriority parameter can be duplicated by the caller in a safer manner by instead releasing the object before calling StgOpenStorageOnILockBytes, as shown in the following example:

// Replacement for:
// HRESULT hr = StgOpenStorageOnILockBytes(
//         plkbyt, pStgPriority, grfMode, NULL, 0, &pstgNew);

pStgPriority->Release();
pStgPriority = NULL;
hr = StgOpenStorage(plkbyt, NULL, grfMode, NULL, 0, &pstgNew);
    

For more information, refer to StgOpenStorage.

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps | Windows Store apps]

Minimum supported server

Windows 2000 Server [desktop apps | Windows Store apps]

Header

Objbase.h

Library

Ole32.lib

DLL

Ole32.dll

See also

StgOpenStorage
StgCreateDocfileOnILockBytes

 

 

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.