| UID | title | description | helpviewer_keywords | old-location | tech.root | ms.assetid | ms.date | ms.keywords | req.header | req.include-header | req.target-type | req.target-min-winverclnt | req.target-min-winversvr | req.kmdf-ver | req.umdf-ver | req.ddi-compliance | req.unicode-ansi | req.idl | req.max-support | req.namespace | req.assembly | req.type-library | req.lib | req.dll | req.irql | targetos | req.typenames | req.redist | ms.custom | f1_keywords | dev_langs | topic_type | api_type | api_location | api_name | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
NF:propvarutil.PropVariantToStringAlloc |
PropVariantToStringAlloc function (propvarutil.h) |
Extracts a string property value from a PROPVARIANT structure. |
|
properties\PropVariantToStringAlloc.htm |
properties |
5e47cc72-4179-4ebe-8700-87861146b3d7 |
12/05/2018 |
PropVariantToStringAlloc, PropVariantToStringAlloc function [Windows Properties], _shell_PropVariantToStringAlloc, properties.PropVariantToStringAlloc, propvarutil/PropVariantToStringAlloc, shell.PropVariantToStringAlloc |
propvarutil.h |
Windows |
Windows XP with SP2, Windows Vista [desktop apps only] |
Windows Server 2003 with SP1 [desktop apps only] |
Propsys.lib |
Propsys.dll (version 6.0 or later) |
Windows |
Windows Desktop Search (WDS) 3.0 |
19H1 |
|
|
|
|
|
|
Extracts a string property value from a PROPVARIANT structure.
Type: REFPROPVARIANT
Reference to a source PROPVARIANT structure.
Type: PWSTR*
When this function returns, contains a pointer to the extracted property value if one exists.
Type: HRESULT
If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.
This helper function is used in places where the calling application expects a PROPVARIANT to hold a string value.
If the source PROPVARIANT has type VT_LPWSTR or VT_BSTR, this function extracts the string into a newly allocated buffer. Otherwise, it attempts to convert the value in the PROPVARIANT structure into a string. If a conversion is not possible, PropVariantToStringAlloc will return a failure code and set ppszOut to NULL. See PropVariantChangeType for a list of possible conversions. Of note, VT_EMPTY is successfully converted to an allocated buffer containing "".
The calling application is responsible for using CoTaskMemFree to release the string pointed to by ppszOut when it is no longer needed.
In addition to the conversions provided by PropVariantChangeType, the following special cases apply to PropVariantToStringAlloc.
- Vector-valued PROPVARIANTs are converted to strings by separating each element with using "; ". For example, PropVariantToStringAlloc converts a vector of 3 integers, {3, 1, 4}, to the string "3; 1; 4". The semicolon is independent of the current locale.
- VT_BLOB, VT_STREAM, VT_STREAMED_OBJECT, and VT_UNKNOWN values are converted to strings using an unsupported encoding. It is not possible to decode strings created in this way and the format may change in the future.
// IPropertyStore *ppropstore;
// Assume variable ppropstore is initialized and valid
PROPVARIANT propvar = {0};
HRESULT hr = ppropstore->GetValue(PKEY_Title, &propvar);
if (SUCCEEDED(hr))
{
// PKEY_Title is expected to produce a VT_LPWSTR or VT_EMPTY value.
// PropVariantToStringAlloc will convert VT_EMPTY to "".
LPWSTR pszTitle;
hr = PropVariantToString(propvar, &pszTitle);
if (SUCCEEDED(hr))
{
// pszTitle is now valid
}
else
{
// pszTitle is always NULL
}
PropVariantClear(&propvar);
}