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  //Address of output variable that receives 
                         // the ILockBytes interface pointer
);
 

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] Address of ILockBytes* pointer variable that receives the interface pointer to 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.

QuickInfo

  Windows NT: Use version 3.1 or later.
  Windows: Use Windows 95 or later.
  Windows CE: Unsupported.
  Header: Declared in ole2.h.
  Import Library: Included as a resource in ole32.dll.

See Also

StgOpenStorageOnILockBytes, GetHGlobalFromILockBytes, ILockBytes