ホーム › UI.Shell › AssocQueryStringByKeyW

AssocQueryStringByKeyW

関数

レジストリキー指定で関連付けの文字列情報を取得する。

DLLSHLWAPI.dll文字セットUnicode (-W)呼出規約winapi対応OSWindows 2000 以降

シグネチャ

// SHLWAPI.dll  (Unicode / -W)
#include <windows.h>

HRESULT AssocQueryStringByKeyW(
    ASSOCF flags,
    ASSOCSTR str,
    HKEY hkAssoc,
    LPCWSTR pszExtra,   // optional
    LPWSTR pszOut,   // optional
    DWORD* pcchOut
);

パラメーター

名前	型	方向	説明
flags	ASSOCF	in	検索を制御するために使用できるフラグです。ASSOCF 値の任意の組み合わせを指定できますが、ASSOCF_INIT 値は 1 つしか含められません。
str	ASSOCSTR	in	返される文字列の種類を指定する ASSOCSTR 値です。
hkAssoc	HKEY	in	ルートキーとして使用するキーの HKEY 値です。検索はこのキーの配下のみを対象とします。
pszExtra	LPCWSTR	inoptional	文字列の場所に関する追加情報を含む、省略可能な null 終端文字列へのポインターです。通常は open などのシェル動詞 (verb) に設定します。使用しない場合は、このパラメーターを NULL に設定します。
pszOut	LPWSTR	outoptional	要求された文字列を返すために使用する null 終端文字列へのポインターです。必要なバッファーサイズを取得するには、このパラメーターを NULL に設定します。
pcchOut	DWORD*	inout	値へのポインターです。入力時には pszOut バッファー内の文字数を指定します。関数が返ると、バッファーに格納された文字数を指します。 flags に ASSOCF_NOTRUNCATE フラグが設定されており、かつ pszOut で指定したバッファーが小さすぎる場合、関数は E_POINTER を返し、この値には必要なバッファーサイズが設定されます。 pszOut が NULL の場合、関数は S_FALSE を返し、pcchOut は必要なバッファーサイズを指します。

戻り値の型: HRESULT

公式ドキュメント

指定したキーを起点として、レジストリからファイルの関連付けに関する文字列を検索して取得します。(Unicode)

戻り値

型: HRESULT

標準的な COM エラー値を返します。次の値が含まれます:

エラー	意味
S_OK	成功しました。
E_POINTER	pszOut バッファーが小さすぎて、文字列全体を保持できません。
S_FALSE	pszOut が NULL です。pcchOut には必要なバッファーサイズが格納されます。

解説(Remarks)

この関数は IQueryAssociations インターフェイスのラッパーです。このインターフェイスを使用する処理を簡素化することを目的としています。ファイルの関連付け関数がどのように動作するかについての詳細は、IQueryAssociations を参照してください。

メモ

shlwapi.h ヘッダーは AssocQueryStringByKey を、UNICODE プリプロセッサ定数の定義に基づいてこの関数の ANSI 版または Unicode 版を自動的に選択するエイリアスとして定義しています。エンコーディング非依存のエイリアスの使用を、エンコーディング非依存ではないコードと混在させると、不一致が生じてコンパイルエラーや実行時エラーを引き起こす可能性があります。詳細については、関数プロトタイプの規約を参照してください。

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

各言語での呼び出し定義

// SHLWAPI.dll  (Unicode / -W)
#include <windows.h>

HRESULT AssocQueryStringByKeyW(
    ASSOCF flags,
    ASSOCSTR str,
    HKEY hkAssoc,
    LPCWSTR pszExtra,   // optional
    LPWSTR pszOut,   // optional
    DWORD* pcchOut
);

[DllImport("SHLWAPI.dll", CharSet = CharSet.Unicode, ExactSpelling = true)]
static extern int AssocQueryStringByKeyW(
    uint flags,   // ASSOCF
    int str,   // ASSOCSTR
    IntPtr hkAssoc,   // HKEY
    [MarshalAs(UnmanagedType.LPWStr)] string pszExtra,   // LPCWSTR optional
    [MarshalAs(UnmanagedType.LPWStr)] System.Text.StringBuilder pszOut,   // LPWSTR optional, out
    ref uint pcchOut   // DWORD* in/out
);

<DllImport("SHLWAPI.dll", CharSet:=CharSet.Unicode, ExactSpelling:=True)>
Public Shared Function AssocQueryStringByKeyW(
    flags As UInteger,   ' ASSOCF
    str As Integer,   ' ASSOCSTR
    hkAssoc As IntPtr,   ' HKEY
    <MarshalAs(UnmanagedType.LPWStr)> pszExtra As String,   ' LPCWSTR optional
    <MarshalAs(UnmanagedType.LPWStr)> pszOut As System.Text.StringBuilder,   ' LPWSTR optional, out
    ByRef pcchOut As UInteger   ' DWORD* in/out
) As Integer
End Function

' flags : ASSOCF
' str : ASSOCSTR
' hkAssoc : HKEY
' pszExtra : LPCWSTR optional
' pszOut : LPWSTR optional, out
' pcchOut : DWORD* in/out
Declare PtrSafe Function AssocQueryStringByKeyW Lib "shlwapi" ( _
    ByVal flags As Long, _
    ByVal str As Long, _
    ByVal hkAssoc As LongPtr, _
    ByVal pszExtra As LongPtr, _
    ByVal pszOut As LongPtr, _
    ByRef pcchOut As Long) As Long
' Unicode(W): 文字列は ByVal As LongPtr とし StrPtr(unicodeStr) を渡す
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

AssocQueryStringByKeyW = ctypes.windll.shlwapi.AssocQueryStringByKeyW
AssocQueryStringByKeyW.restype = ctypes.c_int
AssocQueryStringByKeyW.argtypes = [
    wintypes.DWORD,  # flags : ASSOCF
    ctypes.c_int,  # str : ASSOCSTR
    wintypes.HANDLE,  # hkAssoc : HKEY
    wintypes.LPCWSTR,  # pszExtra : LPCWSTR optional
    wintypes.LPWSTR,  # pszOut : LPWSTR optional, out
    ctypes.POINTER(wintypes.DWORD),  # pcchOut : DWORD* in/out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('SHLWAPI.dll')
AssocQueryStringByKeyW = Fiddle::Function.new(
  lib['AssocQueryStringByKeyW'],
  [
    -Fiddle::TYPE_INT,  # flags : ASSOCF
    Fiddle::TYPE_INT,  # str : ASSOCSTR
    Fiddle::TYPE_VOIDP,  # hkAssoc : HKEY
    Fiddle::TYPE_VOIDP,  # pszExtra : LPCWSTR optional
    Fiddle::TYPE_VOIDP,  # pszOut : LPWSTR optional, out
    Fiddle::TYPE_VOIDP,  # pcchOut : DWORD* in/out
  ],
  Fiddle::TYPE_INT)
# Wide strings: pass str.encode("UTF-16LE") + "\x00\x00"

#[link(name = "shlwapi")]
extern "system" {
    fn AssocQueryStringByKeyW(
        flags: u32,  // ASSOCF
        str: i32,  // ASSOCSTR
        hkAssoc: *mut core::ffi::c_void,  // HKEY
        pszExtra: *const u16,  // LPCWSTR optional
        pszOut: *mut u16,  // LPWSTR optional, out
        pcchOut: *mut u32  // DWORD* in/out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("SHLWAPI.dll", CharSet = CharSet.Unicode)]
public static extern int AssocQueryStringByKeyW(uint flags, int str, IntPtr hkAssoc, [MarshalAs(UnmanagedType.LPWStr)] string pszExtra, [MarshalAs(UnmanagedType.LPWStr)] System.Text.StringBuilder pszOut, ref uint pcchOut);
"@
$api = Add-Type -MemberDefinition $sig -Name 'SHLWAPI_AssocQueryStringByKeyW' -Namespace Win32 -PassThru
# $api::AssocQueryStringByKeyW(flags, str, hkAssoc, pszExtra, pszOut, pcchOut)

#uselib "SHLWAPI.dll"
#func global AssocQueryStringByKeyW "AssocQueryStringByKeyW" wptr, wptr, wptr, wptr, wptr, wptr
; AssocQueryStringByKeyW flags, str, hkAssoc, pszExtra, varptr(pszOut), varptr(pcchOut)   ; 戻り値は stat
; flags : ASSOCF -> "wptr"
; str : ASSOCSTR -> "wptr"
; hkAssoc : HKEY -> "wptr"
; pszExtra : LPCWSTR optional -> "wptr"
; pszOut : LPWSTR optional, out -> "wptr"
; pcchOut : DWORD* in/out -> "wptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "SHLWAPI.dll"
#cfunc global AssocQueryStringByKeyW "AssocQueryStringByKeyW" int, int, sptr, wstr, var, var
; res = AssocQueryStringByKeyW(flags, str, hkAssoc, pszExtra, pszOut, pcchOut)
; flags : ASSOCF -> "int"
; str : ASSOCSTR -> "int"
; hkAssoc : HKEY -> "sptr"
; pszExtra : LPCWSTR optional -> "wstr"
; pszOut : LPWSTR optional, out -> "var"
; pcchOut : DWORD* in/out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "SHLWAPI.dll"
#cfunc global AssocQueryStringByKeyW "AssocQueryStringByKeyW" int, int, sptr, wstr, sptr, sptr
; res = AssocQueryStringByKeyW(flags, str, hkAssoc, pszExtra, varptr(pszOut), varptr(pcchOut))
; flags : ASSOCF -> "int"
; str : ASSOCSTR -> "int"
; hkAssoc : HKEY -> "sptr"
; pszExtra : LPCWSTR optional -> "wstr"
; pszOut : LPWSTR optional, out -> "sptr"
; pcchOut : DWORD* in/out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。