The CreateStreamOnHGlobal function creates a stream object stored in global memory. The memory 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.

Syntax

WINOLEAPI CreateStreamOnHGlobal(
  __in   HGLOBAL hGlobal,
  __in   BOOL fDeleteOnRelease,
  __out  LPSTREAM *ppstm
);

Parameters

hGlobal [in]

The memory handle allocated by the GlobalAlloc function.

Note  The handle must be allocated as movable and nondiscardable.

If the handle is 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]

A value that indicates whether the underlying handle for this stream object should be automatically freed when the stream object is released. If set to FALSE, the caller must free the hGlobal after the final release. If set to TRUE, the final release will automatically free the hGlobal parameter.

ppstm [out]

The address of IStream* pointer variable that receives the interface pointer to the new stream object. Its value cannot be NULL.

Return Value

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 initial contents of the stream are the current contents of the memory block provided in the hGlobal parameter. If the hGlobal parameter 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 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, follow the call to this function with a call to the IStream::SetSize method.

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

If the caller sets the fDeleteOnRelease parameter to FALSE, then the caller must also free the hGlobal after the final release. If the caller sets the fDeleteOnRelease parameter to TRUE, the final release will automatically free the hGlobal as shown in the following example code.

if(pData->fDeleteOnRelease)
	{
	Verify(0==GlobalFree(pData->hGlobal));
	}

The memory handle passed as the hGlobal parameter must be allocated as movable and discardable, as shown in the following example:

HGLOBAL	hMem = ::GlobalAlloc(GMEM_MOVEABLE,iSize);
if (!hMem)
	AfxThrowMemoryException();
LPVOID pImage = ::GlobalLock(hMem);
... // Fill memory
::GlobalUnlock(hMem);

// Convert internal data if there is any
CComPtr<IStream> spStream;
HRESULT hr = ::CreateStreamOnHGlobal(hMem,FALSE,&spStream);

CreateStreamOnHGlobal will accept a memory handle allocated with GMEM_FIXED, but in that case the system might reallocate the memory. If the memory handle was allocated with GMEM_FIXED and fDeleteOnRelease is FALSE, then the caller must call GetHGlobalFromStream to get the correct handle in order to free it.

Requirements

See Also

GetHGlobalFromStream
IStream::SetSize
IStream - Compound File Implementation

Send comments about this topic to Microsoft

Build date: 11/20/2008