ReleaseStgMedium
A version of this page is also available for
4/8/2010
This function frees the specified storage medium.
Syntax
void ReleaseStgMedium(
STGMEDIUM* pmedium
);
Parameters
- pmedium
[in] Pointer to the storage medium that is to be freed.
Return Value
None.
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.
In addition to identifying the type of 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, 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 must 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 Release method on the specified IUnknown pointer.
| Medium | ReleaseStgMedium action |
|---|---|
TYMED_HGLOBAL |
None. |
TYMED_GDI |
None. |
TYMED_ENHMF |
None. |
TYMED_MFPICT |
None. |
TYMED_FILE |
Frees the file name string using standard memory management mechanisms. |
TYMED_ISTREAM |
Calls IStream::Release. |
TYMED_ISTORAGE |
Calls 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.
| Medium | ReleaseStgMedium action |
|---|---|
TYMED_HGLOBAL |
Calls the LocalFree function on the handle. |
TYMED_GDI |
Calls the Microsoft® Win32® DeleteObject function on the handle. |
TYMED_ENHMF |
Deletes the enhanced metafile. |
TYMED_FILE |
Frees the disk file by deleting it. Frees the file name string by using the standard memory management paradigm. |
TYMED_ISTREAM |
Calls IStream::Release. |
TYMED_ISTORAGE |
Calls IStorage::Release. |
In either case, after the call to ReleaseStgMedium, the specified storage medium is invalid and can no longer be used.
To determine whether the platform supports this function, see Determining Supported COM APIs.
Requirements
| Header | ole2.h |
| Library | ole32.lib |
| Windows Embedded CE | Windows CE 2.10 and later |
| Windows Mobile | Windows Mobile Version 5.0 and later |
See Also
Reference
Automation Functions
STGMEDIUM
IUnknown::Release
IUnknown
Concepts
Determining Supported COM APIs