ホーム › UI.Shell › PropVariantToStrRet

PropVariantToStrRet

関数

PROPVARIANTをSTRRET構造体に変換する。

DLLPROPSYS.dll呼出規約winapi対応OSWindows XP 以降

シグネチャ

// PROPSYS.dll
#include <windows.h>

HRESULT PropVariantToStrRet(
    const PROPVARIANT* propvar,
    STRRET* pstrret
);

パラメーター

名前	型	方向	説明
propvar	PROPVARIANT*	in	ソースとなる PROPVARIANT 構造体への参照です。
pstrret	STRRET*	out	STRRET 構造体を指します。この関数が返るとき、構造体は抽出された文字列のコピーを保持するように初期化されています。

戻り値の型: HRESULT

公式ドキュメント

PROPVARIANT 構造体から文字列を抽出し、STRRET 構造体に格納します。

戻り値

型: HRESULT

この関数が成功した場合は S_OK を返します。失敗した場合は HRESULT エラーコードを返します。

解説(Remarks)

このヘルパー関数は、PROPVARIANT 構造体内の文字列値を STRRET 構造体に変換したいアプリケーションで使用されます。たとえば、IShellFolder::GetDisplayNameOf を実装するアプリケーションにとって、この関数は有用です。

ソースの PROPVARIANT が VT_LPWSTR または VT_BSTR 型である場合、この関数は文字列を抽出して STRRET 構造体に格納します。それ以外の場合は、PROPVARIANT 構造体内の値を文字列に変換しようと試みます。変換が不可能な場合、PropVariantToString は失敗コードを返します。可能な変換の一覧については、PropVariantChangeType を参照してください。特に、VT_EMPTY は "" に正常に変換されます。

PropVariantChangeType が提供する変換に加えて、PropVariantToString には次の特別なケースが適用されます。

ベクトル値の PROPVARIANT は、各要素を "; " で区切ることによって文字列に変換されます。たとえば、PropVariantToString は 3 個の整数からなるベクトル {3, 1, 4} を文字列 "3; 1; 4" に変換します。このセミコロンは現在のロケールに依存しません。
VT_BLOB、VT_STREAM、VT_STREAMED_OBJECT、および VT_UNKNOWN の値は、サポートされていないエンコーディングを使用して文字列に変換されます。この方法で作成された文字列をデコードすることはできず、その形式は将来変更される可能性があります。

抽出が成功すると、この関数は STRRET 構造体の uType メンバーを STRRET_WSTR で初期化し、その構造体の pOleStr メンバーを、割り当てられた文字列のコピーを指すように設定します。呼び出し側のアプリケーションは、この文字列が不要になったときに CoTaskMemFree または StrRetToStr を使用して解放する責任があります。

例

より大きなプログラムの一部として組み込まれる次の例は、PropVariantToString を使用して PROPVARIANT 内の文字列値にアクセスする方法を示しています。

// IPropertyStore *ppropstore;

// Assume variable ppropstore is initialized and valid

PROPVARIANT propvar = {0};

HRESULT hr = ppropstore->GetValue(PKEY_FileName, &propvar);

if (SUCCEEDED(hr))

{

    // PKEY_FileName is expected to produce a VT_LPWSTR or VT_EMPTY value.

    // PropVariantToStrRet will convert VT_EMPTY to "".

    // If this were an implementation of IShellFolder::GetDisplayNameOf, strName would be a parameter and the caller would free the memory associated with the STRRET

    STRRET strName;

    hr = PropVariantToStrRet(propvar, &strName);

    if (SUCCEEDED(hr))

    {

        // strName is now valid

 

        if (strName.uType == STRRET_WSTR)

        {

            CoTaskMemFree(strName.pOleStr);

        }

    }

    else

    {

        // the extraction failed

    }

    PropVariantClear(&propvar);

}

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// PROPSYS.dll
#include <windows.h>

HRESULT PropVariantToStrRet(
    const PROPVARIANT* propvar,
    STRRET* pstrret
);

[DllImport("PROPSYS.dll", ExactSpelling = true)]
static extern int PropVariantToStrRet(
    IntPtr propvar,   // PROPVARIANT*
    IntPtr pstrret   // STRRET* out
);

<DllImport("PROPSYS.dll", ExactSpelling:=True)>
Public Shared Function PropVariantToStrRet(
    propvar As IntPtr,   ' PROPVARIANT*
    pstrret As IntPtr   ' STRRET* out
) As Integer
End Function

' propvar : PROPVARIANT*
' pstrret : STRRET* out
Declare PtrSafe Function PropVariantToStrRet Lib "propsys" ( _
    ByVal propvar As LongPtr, _
    ByVal pstrret As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

PropVariantToStrRet = ctypes.windll.propsys.PropVariantToStrRet
PropVariantToStrRet.restype = ctypes.c_int
PropVariantToStrRet.argtypes = [
    ctypes.c_void_p,  # propvar : PROPVARIANT*
    ctypes.c_void_p,  # pstrret : STRRET* out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('PROPSYS.dll')
PropVariantToStrRet = Fiddle::Function.new(
  lib['PropVariantToStrRet'],
  [
    Fiddle::TYPE_VOIDP,  # propvar : PROPVARIANT*
    Fiddle::TYPE_VOIDP,  # pstrret : STRRET* out
  ],
  Fiddle::TYPE_INT)

#[link(name = "propsys")]
extern "system" {
    fn PropVariantToStrRet(
        propvar: *const PROPVARIANT,  // PROPVARIANT*
        pstrret: *mut STRRET  // STRRET* out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("PROPSYS.dll")]
public static extern int PropVariantToStrRet(IntPtr propvar, IntPtr pstrret);
"@
$api = Add-Type -MemberDefinition $sig -Name 'PROPSYS_PropVariantToStrRet' -Namespace Win32 -PassThru
# $api::PropVariantToStrRet(propvar, pstrret)

#uselib "PROPSYS.dll"
#func global PropVariantToStrRet "PropVariantToStrRet" sptr, sptr
; PropVariantToStrRet varptr(propvar), varptr(pstrret)   ; 戻り値は stat
; propvar : PROPVARIANT* -> "sptr"
; pstrret : STRRET* out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "PROPSYS.dll"
#cfunc global PropVariantToStrRet "PropVariantToStrRet" var, var
; res = PropVariantToStrRet(propvar, pstrret)
; propvar : PROPVARIANT* -> "var"
; pstrret : STRRET* out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "PROPSYS.dll"
#cfunc global PropVariantToStrRet "PropVariantToStrRet" sptr, sptr
; res = PropVariantToStrRet(varptr(propvar), varptr(pstrret))
; propvar : PROPVARIANT* -> "sptr"
; pstrret : STRRET* out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。