Export (0) Print
Expand All
This topic has not yet been rated - Rate this topic

ReleaseStgMedium function

Frees the specified storage medium.

Syntax


void ReleaseStgMedium(
  _In_  LPSTGMEDIUM pMedium
);

Parameters

pMedium [in]

Pointer to the storage medium that is to be freed.

Return value

This function does not return a value.

Remarks

The ReleaseStgMedium function calls the appropriate method or function to release the specified storage medium. Use this function during data transfer operations where storage medium structures are parameters, such as IDataObject::GetData or IDataObject::SetData. In addition to identifying the type of the storage medium, this structure specifies the appropriate Release method for releasing the storage medium when it is no longer needed.

It is common to pass a STGMEDIUM from one body of code to another, such as in IDataObject::GetData, in which the one called can allocate a medium and return it to the caller. ReleaseStgMedium permits flexibility in whether the receiving body of code owns the medium, or whether the original provider of the medium still owns it, in which case the receiving code needs to inform the provider that it can free the medium.

When the original provider of the medium is responsible for freeing the medium, the provider calls ReleaseStgMedium, specifying the medium and the appropriate IUnknown pointer as the punkForRelease structure member. Depending on the type of storage medium being freed, one of the following actions is taken, followed by a call to the IUnknown::Release method on the specified IUnknown pointer.

MediumReleaseStgMedium Action
TYMED_HGLOBALNone.
TYMED_GDINone.
TYMED_ENHMFNone.
TYMED_MFPICTNone.
TYMED_FILEFrees the file name string using standard memory management mechanisms.
TYMED_ISTREAMCalls IStream::Release.
TYMED_ISTORAGECalls IStorage::Release.

 

The provider indicates that the receiver of the medium is responsible for freeing the medium by specifying NULL for the punkForRelease structure member. Then the receiver calls ReleaseStgMedium, which makes a call as described in the following table depending on the type of storage medium being freed.

MediumReleaseStgMedium Action
TYMED_HGLOBALCalls the GlobalFree function on the handle.
TYMED_GDICalls the DeleteObject function on the handle.
TYMED_ENHMFDeletes the enhanced metafile.
TYMED_MFPICTThe hMF that it contains is deleted with the DeleteMetaFile function; then the handle itself is passed to GlobalFree.
TYMED_FILEFrees the disk file by deleting it. Frees the file name string by using the standard memory management mechanisms.
TYMED_ISTREAMCalls IStream::Release.
TYMED_ISTORAGECalls IStorage::Release.

 

In either case, after the call to ReleaseStgMedium, the specified storage medium is invalid and can no longer be used.

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

Ole2.h

Library

Ole32.lib

DLL

Ole32.dll

See also

STGMEDIUM

 

 

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.