CreateStreamOnHGlobal

Creates a stream object stored in global memory.

WINOLEAPI CreateStreamOnHGlobal(
  HGLOBAL hGlobal,         //Memory handle for the stream object
  BOOL fDeleteOnRelease,   //Whether to free memory when the object 
                           // is released
  LPSTREAM * ppstm         //Address of output variable that 
                           // receives the IStream 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, the CreateStreamOnHGlobal function internally allocates a new shared memory block of size zero.

fDeleteOnRelease

[in] Whether the underlying handle for this stream object should be automatically freed when the stream object is released.

ppstm

[out] Address of IStream* pointer variable that receives the interface pointer to the new stream object. Its value cannot be NULL.

Return Values

This function supports the standard return values E_INVALIDARG and E_OUTOFMEMORY, as well as the following:

S_OK

The stream object was created successfully.

Remarks

The CreateStreamOnHGlobal function creates a stream object in memory that supports the OLE implementation of the IStream interface. The returned stream object supports both reading and writing, is not transacted, and does not support locking.

The initial contents of the stream are the current contents of the memory block provided in the hGlobal parameter. If the hGlobal paramter is NULL, this function internally allocates memory.

The current contents of the memory block are undisturbed by the creation of the new stream object. Thus, you can use this function to open an existing stream in memory.

The initial size of the stream is the size of the memory handle returned by the Win32 GlobalSize function. Because of rounding, this is not necessarily the same size that was originally allocated for the handle. If the logical size of the stream is important, you should follow the call to this function with a call to the IStream::SetSize method.

After you have created the stream object with CreateStreamOnHGlobal, you can call GetHGlobalFromStream to get the global memory handle associated with the stream object.

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

CreateStreamOnHGlobal, GetHGlobalFromStream, IStream::SetSize, GlobalSize in Win32