CreateILockBytesOnHGlobal

Creates a byte array object that allows you use global memory as the physical device underneath a compound file implementation. This object supports an OLE implementation of the ILockBytes interface.

WINOLEAPI CreateILockBytesOnHGlobal(

HGLOBAL hGlobal,

//Memory handle for the byte array object

BOOL fDeleteOnRelease,

//Whether to free memory when the object is released

ILockBytes ** ppLkbyt

//Indirect pointer to the new byte array object

);

Parameters

hGlobal: [in] Memory handle allocated by the GlobalAlloc function. The handle must be allocated as moveable and nondiscardable. If the handle is to be shared between processes, it must also be allocated as shared. New handles should be allocated with a size of zero. If hGlobal is NULL, CreateILockBytesOnHGlobal internally allocates a new shared memory block of size zero.
fDeleteOnRelease: [in] IWhether the underlying handle for this byte array object should be automatically freed when the object is released.
ppLkbyt: [out] Indirect pointer to the ILockBytes interface on the new byte array object.

Return Values

This function supports the standard return values E_INVALIDARG and

E_OUTOFMEMORY, as well as the following:

S_OK: The byte array object was created successfully.

Remarks

The CreateILockBytesOnHGlobal function creates a byte array object based on global memory. This object supports an OLE implementation of the ILockBytes interface, and is intended to be used as the basis for a compound file. You can then use the supplied ILockBytes pointer in a call to the StgCreateDocfileOnILockBytes function to build a compound file on top of this byte array object. The ILockBytes instance calls the GlobalReAlloc function to grow the memory block as needed.

The current contents of the memory block are undisturbed by the creation of the new byte array object. After creating the ILockBytes instance, you can use the StgOpenStorageOnILockBytes function to reopen a previously existing storage object already contained in the memory block. You can also call GetHGlobalFromILockBytes to get the global memory handle associated with the byte array object created by CreateILockBytesOnHGlobal.

Note If you free the hGlobal memory handle, the byte array object is no longer valid. You must call the ILockBytes::Release method before freeing the memory handle.

The value of the hGlobal parameter can be changed by a subsequent call to the GlobalReAlloc function; thus, you cannot rely on this value after the byte array object is created.

HGLOBAL hGlobal,	//Memory handle for the byte array object
BOOL fDeleteOnRelease,	//Whether to free memory when the object is released
ILockBytes ** ppLkbyt	//Indirect pointer to the new byte array object
);