MkParseDisplayName

関数

表示名文字列を解析してモニカーに変換する。

DLLOLE32.dll呼出規約winapi対応OSWindows 2000 以降

シグネチャ

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

HRESULT MkParseDisplayName(
    IBindCtx* pbc,
    LPCWSTR szUserName,
    DWORD* pchEaten,
    IMoniker** ppmk
);

パラメーター

名前	型	方向	説明
pbc	IBindCtx*	in	このバインド操作で使用するバインドコンテキストオブジェクト上の IBindCtx インターフェイスへのポインター。
szUserName	LPCWSTR	in	解析対象の表示名へのポインター。
pchEaten	DWORD*	out	消費された szUserName の文字数へのポインター。関数が成功した場合、*pchEaten は szUserName の長さになります。それ以外の場合は、正常に解析された文字数になります。
ppmk	IMoniker**	out	szUserName から構築されたモニカーへのインターフェイスポインターを受け取る IMoniker* ポインター変数のアドレス。成功した場合、関数はモニカーに対して AddRef を呼び出しており、呼び出し側は Release を呼び出す責任があります。エラーが発生した場合、指定したインターフェイスポインターには、エラー発生前にメソッドが作成できた範囲のモニカーが格納されます。

戻り値の型: HRESULT

公式ドキュメント

文字列を、その文字列が指す名前のオブジェクトを識別するモニカーに変換します。

戻り値

この関数は、標準的な戻り値 E_OUTOFMEMORY のほか、次の値を返すことがあります。

戻り値	説明
S_OK	解析操作が成功し、モニカーが作成されました。
MK_E_SYNTAX	ファイル名の構文エラー、または生成された複合モニカーの構文エラーです。

この関数は、IMoniker::BindToObject、IOleItemContainer::GetObject、または IParseDisplayName::ParseDisplayName が返すいずれかのエラー値を返すこともあります。

解説(Remarks)

MkParseDisplayName 関数は、人間が読める名前を、リンクソースを識別するために使用できるモニカーに解析します。生成されるモニカーは、単純モニカー(ファイルモニカーなど)の場合もあれば、構成要素となるモニカーの断片から成る汎用複合モニカーの場合もあります。たとえば、表示名 "c:\mydir\somefile!item 1" は

次の汎用複合モニカーに解析できます: ("c:\mydir\somefile" に基づく FileMoniker) + ("item 1" に基づく ItemMoniker)。

MkParseDisplayName の最も一般的な用途は、標準の [リンク] ダイアログボックスの実装です。これにより、エンドユーザーは文字列を入力してリンクオブジェクトのソースを指定できます。アプリケーションがリモート参照(ドキュメント外の要素への参照)を許可するマクロ言語をサポートしている場合にも、MkParseDisplayName の呼び出しが必要になることがあります。

表示名の解析では、バインド操作中に有効化されるのと同じオブジェクトを有効化する必要が生じることが多いため、(パフォーマンスの面で)バインドと同程度のコストがかかる場合があります。解析操作中にバインドされたオブジェクトは、この関数に渡されたバインドコンテキストにキャッシュされます。MkParseDisplayName が返したモニカーをバインドする予定がある場合は、関数の戻り後すぐに同じバインドコンテキストを使用してバインドするのが最善です。これにより、オブジェクトを2回有効化する必要がなくなります。

MkParseDisplayName は、解釈できる範囲の表示名をモニカーに解析します。続いて関数は、新しく作成されたモニカーに対して IMoniker::ParseDisplayName を呼び出し、表示名の残りを渡します。ParseDisplayName が返したモニカーは既存のモニカーの末尾に合成され、表示名に未解析の部分が残っている場合は、合成結果に対して ParseDisplayName が呼び出されます。この処理は、表示名全体が解析されるまで繰り返されます。

MkParseDisplayName は、表示名の先頭を解析するために次の方法を順に試み、最初に成功したものを使用します。

関数は、有効なファイル名文字のみで構成される表示名のすべてのプレフィックスに対応するファイルモニカーを、実行中オブジェクトテーブル(Running Object Table)内で探します。この方法では、まだ保存されていないドキュメントを識別できます。
関数は、有効なファイル名文字のみで構成される表示名の最大プレフィックスを調べ、その名前で OLE 1 ドキュメントが登録されているかどうかを確認します。この場合、返されるモニカーは OLE 2 の OLE 1 互換レイヤーが提供する内部モニカーです。
関数はファイルシステムを参照し、表示名のプレフィックスが既存のファイルと一致するかどうかを確認します。ファイル名は、ドライブ絶対指定、ドライブ相対指定、作業ディレクトリ相対指定のいずれかであるか、または明示的なネットワーク共有名で始まることができます。これが一般的なケースです。
表示名の先頭文字が '@' の場合、関数はその直後に続く、有効な ProgID 構文に準拠する最長の文字列を見つけます。関数は、CLSIDFromProgID 関数を使用してこの文字列を CLSID に変換します。CLSID が OLE 2 クラスを表す場合、関数は対応するクラスオブジェクトを読み込み、IParseDisplayName インターフェイスポインターを要求します。次に、得られた IParseDisplayName インターフェイスに、'@' で始まる文字列全体が解析対象として渡されます。CLSID が OLE 1 クラスを表す場合、関数は ProgID に続く文字列を、filename|item 構文を持つ OLE1/DDE リンク指定子として扱います。

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

各言語での呼び出し定義

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

HRESULT MkParseDisplayName(
    IBindCtx* pbc,
    LPCWSTR szUserName,
    DWORD* pchEaten,
    IMoniker** ppmk
);

[DllImport("OLE32.dll", ExactSpelling = true)]
static extern int MkParseDisplayName(
    IntPtr pbc,   // IBindCtx*
    [MarshalAs(UnmanagedType.LPWStr)] string szUserName,   // LPCWSTR
    out uint pchEaten,   // DWORD* out
    IntPtr ppmk   // IMoniker** out
);

<DllImport("OLE32.dll", ExactSpelling:=True)>
Public Shared Function MkParseDisplayName(
    pbc As IntPtr,   ' IBindCtx*
    <MarshalAs(UnmanagedType.LPWStr)> szUserName As String,   ' LPCWSTR
    <Out> ByRef pchEaten As UInteger,   ' DWORD* out
    ppmk As IntPtr   ' IMoniker** out
) As Integer
End Function

' pbc : IBindCtx*
' szUserName : LPCWSTR
' pchEaten : DWORD* out
' ppmk : IMoniker** out
Declare PtrSafe Function MkParseDisplayName Lib "ole32" ( _
    ByVal pbc As LongPtr, _
    ByVal szUserName As LongPtr, _
    ByRef pchEaten As Long, _
    ByVal ppmk As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

MkParseDisplayName = ctypes.windll.ole32.MkParseDisplayName
MkParseDisplayName.restype = ctypes.c_int
MkParseDisplayName.argtypes = [
    ctypes.c_void_p,  # pbc : IBindCtx*
    wintypes.LPCWSTR,  # szUserName : LPCWSTR
    ctypes.POINTER(wintypes.DWORD),  # pchEaten : DWORD* out
    ctypes.c_void_p,  # ppmk : IMoniker** out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('OLE32.dll')
MkParseDisplayName = Fiddle::Function.new(
  lib['MkParseDisplayName'],
  [
    Fiddle::TYPE_VOIDP,  # pbc : IBindCtx*
    Fiddle::TYPE_VOIDP,  # szUserName : LPCWSTR
    Fiddle::TYPE_VOIDP,  # pchEaten : DWORD* out
    Fiddle::TYPE_VOIDP,  # ppmk : IMoniker** out
  ],
  Fiddle::TYPE_INT)

#[link(name = "ole32")]
extern "system" {
    fn MkParseDisplayName(
        pbc: *mut core::ffi::c_void,  // IBindCtx*
        szUserName: *const u16,  // LPCWSTR
        pchEaten: *mut u32,  // DWORD* out
        ppmk: *mut *mut core::ffi::c_void  // IMoniker** out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("OLE32.dll")]
public static extern int MkParseDisplayName(IntPtr pbc, [MarshalAs(UnmanagedType.LPWStr)] string szUserName, out uint pchEaten, IntPtr ppmk);
"@
$api = Add-Type -MemberDefinition $sig -Name 'OLE32_MkParseDisplayName' -Namespace Win32 -PassThru
# $api::MkParseDisplayName(pbc, szUserName, pchEaten, ppmk)

#uselib "OLE32.dll"
#func global MkParseDisplayName "MkParseDisplayName" sptr, sptr, sptr, sptr
; MkParseDisplayName pbc, szUserName, varptr(pchEaten), ppmk   ; 戻り値は stat
; pbc : IBindCtx* -> "sptr"
; szUserName : LPCWSTR -> "sptr"
; pchEaten : DWORD* out -> "sptr"
; ppmk : IMoniker** out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "OLE32.dll"
#cfunc global MkParseDisplayName "MkParseDisplayName" sptr, wstr, var, sptr
; res = MkParseDisplayName(pbc, szUserName, pchEaten, ppmk)
; pbc : IBindCtx* -> "sptr"
; szUserName : LPCWSTR -> "wstr"
; pchEaten : DWORD* out -> "var"
; ppmk : IMoniker** out -> "sptr"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "OLE32.dll"
#cfunc global MkParseDisplayName "MkParseDisplayName" sptr, wstr, sptr, sptr
; res = MkParseDisplayName(pbc, szUserName, varptr(pchEaten), ppmk)
; pbc : IBindCtx* -> "sptr"
; szUserName : LPCWSTR -> "wstr"
; pchEaten : DWORD* out -> "sptr"
; ppmk : IMoniker** out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。