windows_programming_notes.nbk: Home | Index | Next Page: CREATESTRUCT | Previous Page: CreateSolidBrush

 CreateStreamOnHGlobal

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.

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

Parameters

• hGlobal
  The memory handle allocated by the GlobalAlloc function. 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
  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
  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 Microsoft 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, 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));
    }

Requirements

• Client
  Requires Windows Vista, Windows XP, Windows 2000 Professional, Windows NT Workstation 3.1 and later, Windows Me, Windows 98, or Windows 95.
• Server
  Requires Windows Server 2008, Windows Server 2003, Windows 2000 Server, or Windows NT Server 3.1 and later.
• Header
  Declared in Ole2.h.
• Library
  Use Ole32.lib.
• DLL
  Requires Ole32.dll.

windows_programming_notes.nbk: Home | Index | Next Page: CREATESTRUCT | Previous Page: CreateSolidBrush

Notebook exported on Monday, 7 July 2008, 18:56:50 PM Eastern Daylight Time