ホーム › UI.Shell › AssocGetDetailsOfPropKey

AssocGetDetailsOfPropKey

関数

シェルアイテムから指定プロパティキーの値を取得する。

DLLSHELL32.dll呼出規約winapi対応OSWindows Vista 以降

シグネチャ

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

HRESULT AssocGetDetailsOfPropKey(
    IShellFolder* psf,
    ITEMIDLIST* pidl,
    const PROPERTYKEY* pkey,
    VARIANT* pv,
    BOOL* pfFoundPropKey   // optional
);

パラメーター

名前	型	方向	説明
psf	IShellFolder*	in	ファイル関連付けのプロパティキーの詳細を取得する対象となるシェルフォルダーへのポインター。
pidl	ITEMIDLIST*	in	ファイル関連付けを要求する子項目の PIDL。
pkey	PROPERTYKEY*	in	取得対象のプロパティキーへのポインター。
pv	VARIANT*	out	この関数が戻るとき、指定したプロパティキーの詳細を格納します。
pfFoundPropKey	BOOL*	outoptional	この関数が戻るとき、プロパティキーが見つかった場合は TRUE、見つからなかった場合は FALSE となるフラグを格納します。

戻り値の型: HRESULT

公式ドキュメント

名前空間拡張 (Namespace Extensions) が提供するファイル関連付け情報を使用して、指定したプロパティキーの値を取得します。

戻り値

型: HRESULT

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

解説(Remarks)

この関数は、 IShellFolder 名前空間拡張 (Namespace Extensions) の実装者のみが使用するものです。その他の呼び出し側アプリケーションは、 PROPERTYKEY の値を取得するために IShellFolder2::GetDetailsEx を使用してください。この関数は、 IShellFolder 名前空間拡張の実装者が使用するためのものです。

提供される名前空間拡張は、次の 3 つのいずれかの方法でこの API の使用をサポートする必要があります。

提供される名前空間拡張が、IShellFolder::GetUIObjectOf(..., IID_IQueryAssociations, ...) を実装することで、その項目に対する IQueryAssociations インターフェイスの取得をサポートしている場合、AssocGetDetailsOfPropKey は提供されたファイル関連付け API を使用してプロパティキーの値を取得します。
提供される名前空間拡張が、IShellFolder::GetAttributesOf から項目に対して SFGAO_FILESYSTEM を返し、かつその項目の解析名 (parsing name) を提供する場合、AssocGetDetailsOfPropKey は標準のファイルシステム関連付けを使用してプロパティキーの値を取得します。
提供される名前空間拡張が、IShellFolder::GetAttributesOf から項目に対して SFGAO_FOLDER | SFGAO_BROWSABLE を返す場合、AssocGetDetailsOfPropKey はフォルダー用のファイル関連付け (ASSOCCLASS_FOLDER) を使用してプロパティキーの値を取得します。

実装中の ShellFolder に、ファイル関連付けの仕組みを通じて拡張可能な項目が含まれている場合、この関数を使用して、特定のファイル関連付けに対して宣言された PropertyKeys を取得できます。たとえば、特定のシェルフォルダーが詳細ペインを駆動しており、そのペインに表示されるプロパティをサードパーティのファイル名拡張子によって制御したい場合、この関数を使用して PKEY_PropList_PreviewDetails を返すことができます。このキーは、そのファイル名拡張子に対してレジストリで宣言された、セミコロン区切りのプロパティの一覧を値として持ちます。レジストリには、ファイル名拡張子で定義されたプロパティの一覧があります。この一覧には、次のものが含まれます (これらに限定されません)。

PKEY_PropList_PreviewDetails
PKEY_PropList_PreviewTitle
PKEY_PropList_FullDetails
PKEY_PropList_TileInfo
PKEY_PropList_ExtendedTileInfo
PKEY_PropList_InfoTip
PKEY_PropList_QuickTip
PKEY_PropList_FileOperationPrompt
PKEY_PropList_ConflictPrompt
PKEY_PropList_SetDefaultsFor
PKEY_PropList_NonPersonal
PKEY_NewMenuPreferredTypes
PKEY_NewMenuAllowedTypes

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

各言語での呼び出し定義

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

HRESULT AssocGetDetailsOfPropKey(
    IShellFolder* psf,
    ITEMIDLIST* pidl,
    const PROPERTYKEY* pkey,
    VARIANT* pv,
    BOOL* pfFoundPropKey   // optional
);

[DllImport("SHELL32.dll", ExactSpelling = true)]
static extern int AssocGetDetailsOfPropKey(
    IntPtr psf,   // IShellFolder*
    IntPtr pidl,   // ITEMIDLIST*
    IntPtr pkey,   // PROPERTYKEY*
    IntPtr pv,   // VARIANT* out
    IntPtr pfFoundPropKey   // BOOL* optional, out
);

<DllImport("SHELL32.dll", ExactSpelling:=True)>
Public Shared Function AssocGetDetailsOfPropKey(
    psf As IntPtr,   ' IShellFolder*
    pidl As IntPtr,   ' ITEMIDLIST*
    pkey As IntPtr,   ' PROPERTYKEY*
    pv As IntPtr,   ' VARIANT* out
    pfFoundPropKey As IntPtr   ' BOOL* optional, out
) As Integer
End Function

' psf : IShellFolder*
' pidl : ITEMIDLIST*
' pkey : PROPERTYKEY*
' pv : VARIANT* out
' pfFoundPropKey : BOOL* optional, out
Declare PtrSafe Function AssocGetDetailsOfPropKey Lib "shell32" ( _
    ByVal psf As LongPtr, _
    ByVal pidl As LongPtr, _
    ByVal pkey As LongPtr, _
    ByVal pv As LongPtr, _
    ByVal pfFoundPropKey As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

AssocGetDetailsOfPropKey = ctypes.windll.shell32.AssocGetDetailsOfPropKey
AssocGetDetailsOfPropKey.restype = ctypes.c_int
AssocGetDetailsOfPropKey.argtypes = [
    ctypes.c_void_p,  # psf : IShellFolder*
    ctypes.c_void_p,  # pidl : ITEMIDLIST*
    ctypes.c_void_p,  # pkey : PROPERTYKEY*
    ctypes.c_void_p,  # pv : VARIANT* out
    ctypes.c_void_p,  # pfFoundPropKey : BOOL* optional, out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('SHELL32.dll')
AssocGetDetailsOfPropKey = Fiddle::Function.new(
  lib['AssocGetDetailsOfPropKey'],
  [
    Fiddle::TYPE_VOIDP,  # psf : IShellFolder*
    Fiddle::TYPE_VOIDP,  # pidl : ITEMIDLIST*
    Fiddle::TYPE_VOIDP,  # pkey : PROPERTYKEY*
    Fiddle::TYPE_VOIDP,  # pv : VARIANT* out
    Fiddle::TYPE_VOIDP,  # pfFoundPropKey : BOOL* optional, out
  ],
  Fiddle::TYPE_INT)

#[link(name = "shell32")]
extern "system" {
    fn AssocGetDetailsOfPropKey(
        psf: *mut core::ffi::c_void,  // IShellFolder*
        pidl: *mut ITEMIDLIST,  // ITEMIDLIST*
        pkey: *const PROPERTYKEY,  // PROPERTYKEY*
        pv: *mut VARIANT,  // VARIANT* out
        pfFoundPropKey: *mut i32  // BOOL* optional, out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("SHELL32.dll")]
public static extern int AssocGetDetailsOfPropKey(IntPtr psf, IntPtr pidl, IntPtr pkey, IntPtr pv, IntPtr pfFoundPropKey);
"@
$api = Add-Type -MemberDefinition $sig -Name 'SHELL32_AssocGetDetailsOfPropKey' -Namespace Win32 -PassThru
# $api::AssocGetDetailsOfPropKey(psf, pidl, pkey, pv, pfFoundPropKey)

#uselib "SHELL32.dll"
#func global AssocGetDetailsOfPropKey "AssocGetDetailsOfPropKey" sptr, sptr, sptr, sptr, sptr
; AssocGetDetailsOfPropKey psf, varptr(pidl), varptr(pkey), varptr(pv), varptr(pfFoundPropKey)   ; 戻り値は stat
; psf : IShellFolder* -> "sptr"
; pidl : ITEMIDLIST* -> "sptr"
; pkey : PROPERTYKEY* -> "sptr"
; pv : VARIANT* out -> "sptr"
; pfFoundPropKey : BOOL* optional, out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "SHELL32.dll"
#cfunc global AssocGetDetailsOfPropKey "AssocGetDetailsOfPropKey" sptr, var, var, var, var
; res = AssocGetDetailsOfPropKey(psf, pidl, pkey, pv, pfFoundPropKey)
; psf : IShellFolder* -> "sptr"
; pidl : ITEMIDLIST* -> "var"
; pkey : PROPERTYKEY* -> "var"
; pv : VARIANT* out -> "var"
; pfFoundPropKey : BOOL* optional, out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "SHELL32.dll"
#cfunc global AssocGetDetailsOfPropKey "AssocGetDetailsOfPropKey" sptr, sptr, sptr, sptr, sptr
; res = AssocGetDetailsOfPropKey(psf, varptr(pidl), varptr(pkey), varptr(pv), varptr(pfFoundPropKey))
; psf : IShellFolder* -> "sptr"
; pidl : ITEMIDLIST* -> "sptr"
; pkey : PROPERTYKEY* -> "sptr"
; pv : VARIANT* out -> "sptr"
; pfFoundPropKey : BOOL* optional, out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。