CreateStreamOnHGlobal

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function creates a stream object stored in global memory.

Syntax

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

Parameters

• hGlobal
  [in] Memory handle allocated by the GlobalAlloc function.

  The handle must be allocated as movable 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 the IStream* pointer variable that receives the interface pointer to the new stream object.

  Its value cannot be NULL.

Return Value

The following HRESULT values can be returned.

Remarks

The CreateStreamOnHGlobal function creates a stream object in memory that supports the OLE implementation of the IStream interface.

The returned stream object

• Supports reading and writing
• Is not transacted
• 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 parameter is NULL, this function internally allocates memory.

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

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 create the stream object with CreateStreamOnHGlobal, you can call GetHGlobalFromStream to get the global memory handle associated with the stream object.

To determine whether the platform supports this function, see Determining Supported COM APIs.

Requirements

See Also

Reference

Automation Functions
IStream
IStream
IStream::SetSize
GetHGlobalFromStream

Concepts

Determining Supported COM APIs