ホーム › UI.Shell.PropertiesSystem › PSGetNamedPropertyFromPropertyStorage

PSGetNamedPropertyFromPropertyStorage

関数

シリアル化記憶域から名前指定で値を取得する。

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

シグネチャ

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

HRESULT PSGetNamedPropertyFromPropertyStorage(
    PCUSERIALIZEDPROPSTORAGE psps,
    DWORD cb,
    LPCWSTR pszName,
    PROPVARIANT* ppropvar
);

パラメーター

名前	型	方向	説明
psps	PCUSERIALIZEDPROPSTORAGE	in	シリアル化されたプロパティを格納している、割り当て済みバッファーへのポインター。このバッファーを取得するには IPersistSerializedPropStorage::GetPropertyStorage を呼び出します。
cb	DWORD	in	psps が指す USERIALIZESPROPSTORAGE バッファーのサイズ (バイト単位)。
pszName	LPCWSTR	in	プロパティの名前を格納した、null で終わる Unicode 文字列へのポインター。
ppropvar	PROPVARIANT*	out	この関数から制御が戻るときに、要求された値が格納されます。

戻り値の型: HRESULT

公式ドキュメント

シリアル化されたプロパティストレージから、プロパティ名を指定して値を取得します。

戻り値

型: PSSTDAPI

成功した場合は S_OK を返します。それ以外の場合はエラー値を返します。

解説(Remarks)

この関数は、呼び出し元のアプリケーションが既にシリアル化されたプロパティストレージを保持していて、そこから取得する必要のあるプロパティがごく少数である場合に呼び出すことを想定しています。多数のプロパティを取得する必要がある場合は、PSCreateMemoryPropertyStore を呼び出してメモリプロパティストアを作成し、IPersistSerializedPropStorage::SetPropertyStorage を呼び出してプロパティストアを初期化したうえで、INamedPropertyStore または IPropertyStore を使用してプロパティを取得すると、パフォーマンスを向上させることができます。

PSGetNamedPropertyFromPropertyStorage は、IPersistSerializedPropStorage のシステム実装によって作成されたシリアル化バッファーに対してのみ動作することに注意してください。まず PSCreateMemoryPropertyStore を呼び出してメモリプロパティストアを取得する必要があります。そのストアは、IPersistSerializedPropStorage インターフェイスを使用してシリアル化バッファーを作成できます。

SERIALIZEDPROPSTORAGE は不透明なシリアル化データ構造であり、その形式は将来変更される可能性がありますが、それ以前の形式も以降のバージョンの Windows でサポートされます。この形式は不透明であるため、アプリケーションはシリアル化バッファーへのアクセスや操作にサポートされているプロパティストレージ API を使用してください (IPersistSerializedPropStorage および PSGetPropertyFromPropertyStorage を参照してください)。

例

次の例は、より大きなプログラムの一部として使用するもので、PSGetNamedPropertyFromPropertyStorage を使用してシリアル化されたプロパティストレージから値を読み取る方法を示しています。

// SERIALIZEDPROPSTORAGE *pStorage;
// DWORD cbStorage;
// 変数 pStorage と cbStorage は初期化済みで有効であるものとします。  
PROPVARIANT propvar;

HRESULT hr = PSGetNamedPropertyFromPropertyStorage(pStorage, cb, L"MyProperty", &propvar);

if (SUCCEEDED(hr))
{
    // propvar が有効になりました。
 
    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 PSGetNamedPropertyFromPropertyStorage(
    PCUSERIALIZEDPROPSTORAGE psps,
    DWORD cb,
    LPCWSTR pszName,
    PROPVARIANT* ppropvar
);

[DllImport("PROPSYS.dll", ExactSpelling = true)]
static extern int PSGetNamedPropertyFromPropertyStorage(
    IntPtr psps,   // PCUSERIALIZEDPROPSTORAGE
    uint cb,   // DWORD
    [MarshalAs(UnmanagedType.LPWStr)] string pszName,   // LPCWSTR
    IntPtr ppropvar   // PROPVARIANT* out
);

<DllImport("PROPSYS.dll", ExactSpelling:=True)>
Public Shared Function PSGetNamedPropertyFromPropertyStorage(
    psps As IntPtr,   ' PCUSERIALIZEDPROPSTORAGE
    cb As UInteger,   ' DWORD
    <MarshalAs(UnmanagedType.LPWStr)> pszName As String,   ' LPCWSTR
    ppropvar As IntPtr   ' PROPVARIANT* out
) As Integer
End Function

' psps : PCUSERIALIZEDPROPSTORAGE
' cb : DWORD
' pszName : LPCWSTR
' ppropvar : PROPVARIANT* out
Declare PtrSafe Function PSGetNamedPropertyFromPropertyStorage Lib "propsys" ( _
    ByVal psps As LongPtr, _
    ByVal cb As Long, _
    ByVal pszName As LongPtr, _
    ByVal ppropvar As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

PSGetNamedPropertyFromPropertyStorage = ctypes.windll.propsys.PSGetNamedPropertyFromPropertyStorage
PSGetNamedPropertyFromPropertyStorage.restype = ctypes.c_int
PSGetNamedPropertyFromPropertyStorage.argtypes = [
    ctypes.c_ssize_t,  # psps : PCUSERIALIZEDPROPSTORAGE
    wintypes.DWORD,  # cb : DWORD
    wintypes.LPCWSTR,  # pszName : LPCWSTR
    ctypes.c_void_p,  # ppropvar : PROPVARIANT* out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('PROPSYS.dll')
PSGetNamedPropertyFromPropertyStorage = Fiddle::Function.new(
  lib['PSGetNamedPropertyFromPropertyStorage'],
  [
    Fiddle::TYPE_INTPTR_T,  # psps : PCUSERIALIZEDPROPSTORAGE
    -Fiddle::TYPE_INT,  # cb : DWORD
    Fiddle::TYPE_VOIDP,  # pszName : LPCWSTR
    Fiddle::TYPE_VOIDP,  # ppropvar : PROPVARIANT* out
  ],
  Fiddle::TYPE_INT)

#[link(name = "propsys")]
extern "system" {
    fn PSGetNamedPropertyFromPropertyStorage(
        psps: isize,  // PCUSERIALIZEDPROPSTORAGE
        cb: u32,  // DWORD
        pszName: *const u16,  // LPCWSTR
        ppropvar: *mut PROPVARIANT  // PROPVARIANT* out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("PROPSYS.dll")]
public static extern int PSGetNamedPropertyFromPropertyStorage(IntPtr psps, uint cb, [MarshalAs(UnmanagedType.LPWStr)] string pszName, IntPtr ppropvar);
"@
$api = Add-Type -MemberDefinition $sig -Name 'PROPSYS_PSGetNamedPropertyFromPropertyStorage' -Namespace Win32 -PassThru
# $api::PSGetNamedPropertyFromPropertyStorage(psps, cb, pszName, ppropvar)

#uselib "PROPSYS.dll"
#func global PSGetNamedPropertyFromPropertyStorage "PSGetNamedPropertyFromPropertyStorage" sptr, sptr, sptr, sptr
; PSGetNamedPropertyFromPropertyStorage psps, cb, pszName, varptr(ppropvar)   ; 戻り値は stat
; psps : PCUSERIALIZEDPROPSTORAGE -> "sptr"
; cb : DWORD -> "sptr"
; pszName : LPCWSTR -> "sptr"
; ppropvar : PROPVARIANT* out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

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