Expand Minimize

StgCreateDocfileOnILockBytes function

The StgCreateDocfileOnILockBytes function creates and opens a new compound file storage object on top of a byte-array object provided by the caller. The storage object supports the COM-provided, compound-file implementation for the IStorage interface.

Syntax


HRESULT StgCreateDocfileOnILockBytes(
  _In_   ILockBytes *plkbyt,
  _In_   DWORD grfMode,
  _In_   DWORD reserved,
  _Out_  IStorage **ppstgOpen
);

Parameters

plkbyt [in]

A pointer to the ILockBytes interface on the underlying byte-array object on which to create a compound file.

grfMode [in]

Specifies the access mode to use when opening the new compound file. For more information, see STGM Constants and the Remarks section below.

reserved [in]

Reserved for future use; must be zero.

ppstgOpen [out]

A pointer to the location of the IStorage pointer on the new storage object.

Return value

S_OK

Indicates that the compound file was successfully created.

STG_E_ACCESSDENIED

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

STG_E_FILEALREADYEXISTS

Indicates that the compound file already exists and the grfMode parameter is set to STGM_FAILIFTHERE.

STG_E_INSUFFICIENTMEMORY

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

STG_E_INVALIDPOINTER

Indicates that a non-valid pointer was in the pLkbyt parameter or the ppStgOpen parameter.

STG_E_INVALIDFLAG

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

STG_E_TOOMANYOPENFILES

Indicates that the storage object was not created due to a lack of file handles.

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_S_CONVERTED

Indicates that the compound file was successfully converted. The original byte-array object was successfully converted to IStorage format.

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

Remarks

The StgCreateDocfileOnILockBytes function creates a storage object on top of a byte array object using the COM-provided, compound-file implementation of the IStorage interface. StgCreateDocfileOnILockBytes can be used to store a document in an arbitrary data store, such as memory or a relational database. The byte array (indicated by the pLkbyt parameter, which points to the ILockBytes interface on the object) is used for the underlying storage in place of a disk file.

Except for specifying a programmer-provided byte-array object, StgCreateDocfileOnILockBytes is similar to the StgCreateDocfile function.

The newly created compound file 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.

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

For conversion purposes, the file is considered to already exist. As a result, it is not useful to use the STGM_FAILIFTHERE value, because it causes an error to be returned. However, both STGM_CREATE and STGM_CONVERT remain useful.

The ability to build a compound file on top of a byte-array object is provided to support having the data (underneath an IStorage and IStream tree structure) live in a nonpersistent space. Given this capability, there is nothing preventing a document that is stored in a file from using this facility. For example, a container might do this to minimize the impact on its file format caused by adopting COM. However, it is recommended that COM documents adopt the IStorage interface for their own outer-level storage. This has the following advantages:

  • The storage structure of the document is the same as its storage structure when it is an embedded object, reducing the number of cases the application needs to handle.
  • One can write tools to access the OLE embedded and linked objects within the document without special knowledge of the document's file format. An example of such a tool is a copy utility that copies all the documents included in a container containing linked objects. A copy utility like this needs access to the contained links to determine the extent of files to be copied.
  • The IStorage implementation addresses the problem of how to commit the changes to the file. An application using the ILockBytes interface must handle these issues itself.

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

StgCreateDocfile

 

 

Community Additions

ADD
Show:
© 2014 Microsoft