Win32 API 日本語リファレンス
ホーム › UI.Shell › IShellBrowser

IShellBrowser

COM
📘 Microsoft Learn (日本語) · English
IID000214e2-0000-0000-c000-000000000046継承元IOleWindow自前メソッド開始 vtbl5

公式ドキュメント

Shell ビュー(IShellView を実装するオブジェクト)のホストによって実装されます。ホストしているビューや、Explorer ウィンドウのコンテキストで実行されるその他のオブジェクトに対してサービスを提供するメソッドを公開します。

解説(Remarks)

Windows エクスプローラーと ファイルを開く コモンダイアログボックスは、このインターフェイスの実装例です。これは、拡張機能によって公開される IShellView インターフェイスと対になるものです。

ブラウザーのサイトチェーンにアクセスできるオブジェクトは、IServiceProvider::QueryService を使用し、SID_STopLevelBrowser や SID_SCommDlgBrowser などのサービス ID を指定することで、IShellBrowser 上のブラウザーへの参照を取得できます。

Windows 7 以降。Windows エクスプローラーのコンテキストメニューは、サービス ID SID_SInPlaceBrowser を指定して IServiceProvider::QueryService を使用することで、インプレースナビゲーションをサポートできます。

メソッド 13

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 5 HRESULT InsertMenusSB(HMENU hmenuShared, OLEMENUGROUPWIDTHS* lpMenuWidths)

拡張された名前空間が表示または使用されているときに表示される複合メニューに、コンテナーが自身のメニューグループを挿入できるようにします。

hmenuSharedHMENUin空のメニューへのハンドル。
lpMenuWidthsOLEMENUGROUPWIDTHS*inout6 個の LONG 値からなる OLEMENUGROUPWIDTHS 配列のアドレス。コンテナーは、File、View、Window の各メニューグループに提供したメニュー要素の数を反映するために、要素 0、2、4 を埋めます。

戻り値

型: HRESULT

成功した場合は S_OK を返し、それ以外の場合は COM で定義されたエラー値を返します。

解説(Remarks)

このメソッドは IOleInPlaceFrame::InsertMenus メソッドに似ています。Windows エクスプローラーは、File メニューグループに File および Edit ドロップダウンメニューを、Container メニューグループに View および Tools メニューを、Window メニューグループに Help メニューを配置します。各ドロップダウンメニューには、FCIDM_MENU_FILE/EDIT/VIEW/TOOLS/HELP という一意の識別子が付けられます。ビューは、これらのサブメニューに識別子によってメニュー項目を挿入できます。これは OLE のインプレースアクティベーションの仕組みとは異なります。ビューが Windows エクスプローラーのサブメニューまたは自身のサブメニューに挿入するメニューのコマンド識別子は、FCIDM_SHVIEWFIRST から FCIDM_SHVIEWLAST の範囲でなければなりません。

呼び出し側アプリケーションへの注意

このメソッドは、名前空間拡張機能が最初にアクティブ化されるときに、フレームレベルのユーザーインターフェイスに自身のメニューを挿入するために呼び出されます。

オブジェクトアプリケーションは、コンテナーに対して、hmenuShared パラメーターで指定されたメニューに自身のメニューを追加し、lpMenuWidths パラメーターが指す OLEMENUGROUPWIDTHS 配列にグループ数を設定するよう要求します。その後、オブジェクトアプリケーションは自身のメニューとカウントを追加します。オブジェクトは、複合メニューを構築するために必要な回数だけ IOleInPlaceFrame::InsertMenus メソッドを呼び出すことができます。コンテナーは、ドロップダウンメニュー内のすべての項目に対して、複合メニューに関連付けられた最初のメニューハンドルを使用する必要があります。

実装者への注意

IShellBrowser の実装では、メニュー識別子は FCIDM_BROWSERFIRST から FCIDM_BROWSERLAST の範囲でなければなりません。
vtbl 6 HRESULT SetMenuSB(HMENU hmenuShared, INT_PTR holemenuRes, HWND hwndActiveObject)

複合メニューをビューウィンドウにインストールします。

hmenuSharedHMENUinIShellBrowser::InsertMenusSB および InsertMenu 関数の呼び出しによって構築された複合メニューへのハンドル。
holemenuResINT_PTRin
hwndActiveObjectHWNDinビューのウィンドウハンドル。

戻り値

型: RESULT

成功した場合は S_OK を返し、それ以外の場合は COM で定義されたエラー値を返します。

解説(Remarks)

このメソッドは IOleInPlaceFrame::SetMenu メソッドに似ています。ただし、Windows エクスプローラーはメニュー項目識別子に基づいてメニューのディスパッチを行います。

特定のメニュー項目が利用可能かどうかは、ビューがフォーカスを持っているかどうかに依存します。したがって、ビューウィンドウ(またはその子ウィンドウの 1 つ)がフォーカスを持つたびに、IShellBrowser::OnViewWindowActive メソッドを呼び出す必要があります。

呼び出し側アプリケーションへの注意

オブジェクトは IShellBrowser_SetMenuSB を呼び出して、IShellBrowser::InsertMenusSB の呼び出しによって設定された複合メニュー構造をインストールするようコンテナーに要求します。

実装者への注意

コンテナーによるこのメソッドの実装では、SetMenu 関数を呼び出す必要があります。
vtbl 7 HRESULT RemoveMenusSB(HMENU hmenuShared)

コンテナーが、インプレース複合メニューから自身のメニュー要素を削除し、関連するすべてのリソースを解放できるようにします。

hmenuSharedHMENUinIShellBrowser::InsertMenusSB および InsertMenu 関数の呼び出しによって構築されたインプレース複合メニューへのハンドル。

戻り値

型: HRESULT

成功した場合は S_OK を返し、それ以外の場合は COM で定義されたエラー値を返します。

解説(Remarks)

このメソッドは IOleInPlaceFrame::RemoveMenus メソッドに似ています。

オブジェクトは、共有ユーザーインターフェイスを非アクティブ化する前に、コンテナーが複合メニューから自身のメニュー要素を削除できるよう常に許可する必要があります。

呼び出し側アプリケーションへの注意

このメソッドは、オブジェクトアプリケーションが UI 非アクティブ化されている間に呼び出され、ブラウザーが自身のメニューを削除できるようにします。
vtbl 8 HRESULT SetStatusTextSB(LPWSTR pszStatusText)

コンテナーのフレームウィンドウのステータスバーに、インプレースオブジェクトに関するステータステキストを設定して表示します。

pszStatusTextLPWSTRin表示するメッセージを含む null 終端文字列へのポインター。

戻り値

型: HRESULT

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

解説(Remarks)

IShellBrowser::SendControlMsg メソッドを使用して、ステータスウィンドウに直接メッセージを送信することもできます。

呼び出し側アプリケーションへの注意

ステータスバーの内容を設定するには、このメソッドを使用します。
vtbl 9 HRESULT EnableModelessSB(BOOL fEnable)

Windows エクスプローラーに対して、モードレスダイアログボックスを有効または無効にするよう指示します。

fEnableBOOLinモードレスダイアログボックスを有効にするか無効にするかを指定します。このパラメーターが 0 以外の場合、モードレスダイアログボックスが有効になります。このパラメーターが 0 の場合、モードレスダイアログボックスは無効になります。

戻り値

型: HRESULT

成功した場合は S_OK を返し、それ以外の場合は COM で定義されたエラー値を返します。

解説(Remarks)

このメソッドは IOleInPlaceFrame::EnableModeless メソッドに似ています。現在のバージョンの Windows エクスプローラーにはモードレスダイアログボックスはありませんが、ビューは Windows エクスプローラーウィンドウに関連付けられたモードレスダイアログボックスを無効または有効にしたいときに、このメソッドを呼び出す必要があります。

vtbl 10 HRESULT TranslateAcceleratorSB(MSG* pmsg, WORD wID)

ビューがアクティブな間に、ブラウザーのフレーム宛てのアクセラレーターキーストロークを変換します。

pmsgMSG*inキーストロークメッセージを含む MSG 構造体のアドレス。
wIDWORDinコンテナーが提供するアクセラレーターテーブル内で、キーストロークに対応するコマンド識別子の値。コンテナーは、再度変換するのではなく、この値を使用する必要があります。

戻り値

型: HRESULT

成功した場合は S_OK を返し、それ以外の場合は COM で定義されたエラー値を返します。

解説(Remarks)

このメソッドは IOleInPlaceFrame::TranslateAccelerator メソッドに似ています。

vtbl 11 HRESULT BrowseObject(ITEMIDLIST* pidl, DWORD wFlags)

別のフォルダーへ移動するよう Windows エクスプローラーに指示します。

pidlITEMIDLIST*inオブジェクトの場所を指定する ITEMIDLIST(アイテム識別子リスト)構造体のアドレス。この値は、wFlags パラメーターに設定されたフラグに依存します。
wFlagsDWORDin

移動先のフォルダーを指定するフラグ。0、または次の値の 1 つ以上を指定できます。

これらのフラグは、別のウィンドウを作成するかどうかを指定します。

SBSP_DEFBROWSER (0x0000)

ビューオプション(新しいウィンドウを作成するか、その場で参照するかというユーザー設定)を尊重する既定の動作を使用します。ほとんどの場合、呼び出し側アプリケーションはこのフラグを使用してください。

SBSP_SAMEBROWSER

同じ Windows エクスプローラーウィンドウで別のフォルダーへ移動します。

SBSP_NEWBROWSER

指定したフォルダー用に別のウィンドウを作成します。

次のフラグはモードを指定します。SBSP_SAMEBROWSER が指定されている場合、または SBSP_DEFBROWSER が指定されていてユーザーが その場で参照する を選択している場合、これらの値は無視されます。

SBSP_DEFMODE

現在のウィンドウを使用します。

SBSP_OPENMODE

新しい参照ウィンドウにフォルダーツリーを表示しないよう指定します。現在のブラウザーが参照オブジェクト呼び出しの SBSP_OPENMODE と一致しない場合、新しいウィンドウが開かれます。

SBSP_EXPLOREMODE

新しい参照ウィンドウにフォルダーツリーを表示するよう指定します。現在のブラウザーが参照オブジェクト呼び出しの SBSP_EXPLOREMODE と一致しない場合、新しいウィンドウが開かれます。

SBSP_HELPMODE

サポートされていません。使用しないでください。

SBSP_NOTRANSFERHIST

参照履歴を新しいウィンドウに転送しません。

次のフラグは pidl パラメーターのカテゴリを指定します。

SBSP_ABSOLUTE

デスクトップを基準とする絶対 PIDL。

SBSP_RELATIVE

現在のフォルダーを基準とする相対 PIDL。

SBSP_PARENT

親フォルダーを参照し、PIDL を無視します。

SBSP_NAVIGATEBACK

後方へ移動し、PIDL を無視します。

SBSP_NAVIGATEFORWARD

前方へ移動し、PIDL を無視します。

SBSP_ALLOW_AUTONAVIGATE (0x00010000)

自動ナビゲーションを有効にします。

次のフラグはモードを指定します。

SBSP_KEEPSAMETEMPLATE (0x00020000)

Windows Vista 以降。サポートされていません。使用しないでください。

SBSP_KEEPWORDWHEELTEXT (0x00040000)

Windows Vista 以降。検索入力フィールドをクリアせずに移動します。

SBSP_ACTIVATE_NOFOCUS (0x00080000)

Windows Vista 以降。新しいビューにフォーカスを設定する既定の動作を行わずに移動します。

次のフラグは、ナビゲーションの結果として履歴がどのように操作されるかを制御します。

SBSP_CALLERUNTRUSTED (0x00800000)

Microsoft Internet Explorer 6 Service Pack 2 (SP2) 以降。ナビゲーションは、ローカルシステム上に既に存在するスクリプトコードを持つ Web ページによって開始された可能性があります。

SBSP_TRUSTFIRSTDOWNLOAD (0x01000000)

Microsoft Internet Explorer 6 Service Pack 2 (SP2) 以降。新しいウィンドウはユーザーが開始したアクションの結果です。新しいウィンドウが直ちにコンテンツのダウンロードを試みる場合、そのウィンドウを信頼します。

SBSP_UNTRUSTEDFORDOWNLOAD (0x02000000)

Microsoft Internet Explorer 6 Service Pack 2 (SP2) 以降。ウィンドウは、信頼されていない非 HTML ファイルへ移動しています。ユーザーがファイルのダウンロードを試みても、ダウンロードを許可しないでください。

SBSP_NOAUTOSELECT

履歴ペインでの選択を抑制します。

SBSP_WRITENOHISTORY

このナビゲーションの履歴を、履歴 Shell フォルダーに書き込みません。

SBSP_CREATENOHISTORY (0x00100000)

0x00100000。Windows 7 以降。トラベルログに新しいエントリを追加しません。ユーザーが検索ボックスに検索語を入力し、その後クエリを絞り込むと、ブラウザーは前方へ移動しますが、トラベルログエントリを追加しません。

SBSP_TRUSTEDFORACTIVEX (0x10000000)

Microsoft Internet Explorer 6 Service Pack 2 (SP2) 以降。ナビゲーションで ActiveX のプロンプトを許可します。

SBSP_FEEDNAVIGATION (0x20000000)

Windows Internet Explorer 7 以降。現在のレジストリ設定で許可されている場合、ブラウザーに移動先を与えます。

SBSP_REDIRECT (0x40000000)

別の URL へのリダイレクトを有効にします。

SBSP_INITIATEDBYHLINKFRAME (0x80000000)

SBSP_PLAYNOSOUND (0x00200000)

Windows 7 以降。検索ボックスでのキーストロークごとにナビゲーション完了音を鳴らしません。

戻り値

型: HRESULT

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

解説(Remarks)

ビューはこのメソッドを使用して、名前空間内の特定の場所へ移動するよう Windows エクスプローラーに強制できます。通常、これらはビューに含まれるフォルダーです。

例

IShellBrowser* psb;
hr = IUnknown_QueryService(punkSite, SID_STopLevelBrowser, IID_PPV_ARGS(&psb));

if (SUCCEEDED(hr))
{
    hr = psb->BrowseObject(pidlSearch, SBSP_DEFBROWSER | SBSP_ABSOLUTE);
    psb->Release();
}
vtbl 12 HRESULT GetViewStateStream(DWORD grfMode, IStream** ppStrm)

ビュー固有の状態情報を格納するために使用できる IStream インターフェイスを取得します。

grfModeDWORDin

IStream インターフェイスの読み取り/書き込みアクセス。次のいずれかの値を指定できます。

STGM_READ

読み取りに適した IStream を要求します。

STGM_WRITE

書き込みに適した IStream を要求します。

STGM_READWRITE

読み取りと書き込みに適した IStream を要求します。

ppStrmIStream**outIStream インターフェイスポインターを受け取るアドレス。

戻り値

型: HRESULT

成功した場合は S_OK を返し、それ以外の場合は COM で定義されたエラー値を返します。

解説(Remarks)

このメソッドは、ビューの永続的な状態(たとえば、アイコンの位置、列の幅、現在のスクロール位置など)を保存および復元するために使用されます。

呼び出し側アプリケーションへの注意

ビューが作成されるときに保存されたビュー状態を読み込むため、およびビューが閉じられるときにビュー状態への変更を保存するために、GetViewStateStream を使用します。通常、ビューはビューウィンドウを作成するときに STGM_READ を指定して、また IShellView インターフェイスの SaveViewState メソッドが呼び出されるときに STGM_WRITE を指定して、このメソッドを呼び出します。

実装者への注意

各 Shell ビューは、独自のビューストリームを持つ必要があります。Windows エクスプローラーは、ユーザーごとにレジストリに格納されるビューストリームの最近使用した項目(MRU)リストを実装しています。

IShellBrowser も参照してください。

vtbl 13 HRESULT GetControlWindow(DWORD id, HWND* phwnd)

ブラウザーコントロールへのウィンドウハンドルを取得します。

idDWORDin

要求するコントロールハンドル。このパラメーターには次のいずれかの値を指定できます。

FCW_TOOLBAR

ブラウザーのツールバーへのウィンドウハンドルを取得します。

FCW_STATUS

ブラウザーのステータスバーへのウィンドウハンドルを取得します。

FCW_TREE

ブラウザーのツリービューへのウィンドウハンドルを取得します。

FCW_PROGRESS

ブラウザーのプログレスバーへのウィンドウハンドルを取得します。

phwndHWND*outWindows エクスプローラーコントロールへのウィンドウハンドルのアドレス。

戻り値

型: HRESULT

成功した場合は S_OK を返し、それ以外の場合は COM で定義されたエラー値を返します。

解説(Remarks)

GetControlWindow は、ビューがブラウザーのコントロールを直接操作できるように使用されます。FCW_TREE は、ツリーが存在するかどうかを判定するためだけに使用してください。

呼び出し側アプリケーションへの注意

GetControlWindow は、コントロールウィンドウの状態を操作およびテストするために使用されます。これらのコントロールに直接メッセージを送信しないでください。代わりに IShellBrowser::SendControlMsg を使用してください。このメソッドが NULL を返す場合に備えてください。後のバージョンの Windows エクスプローラーには、ツールバー、ステータスバー、ツリーウィンドウが含まれない可能性があります。

実装者への注意

GetControlWindow は、実装内にこれらのコントロールが存在する場合、それらへのウィンドウハンドルを返します。

IShellBrowser も参照してください。

vtbl 14 HRESULT SendControlMsg(DWORD id, DWORD uMsg, WPARAM wParam, LPARAM lParam, LRESULT* pret)

Windows エクスプローラーウィンドウのツールバーまたはステータスバーに制御メッセージを送信します。

idDWORDinツールバー(FCW_TOOLBAR)またはステータスバーウィンドウ(FCW_STATUS)のいずれかの識別子。
uMsgDWORDinコントロールに送信するメッセージ。
wParamWPARAMin値は uMsg パラメーターで指定されたメッセージに依存します。
lParamLPARAMin値は uMsg パラメーターで指定されたメッセージに依存します。
pretLRESULT*outoptional
                <a href="/windows/desktop/api/winuser/nf-winuser-sendmessage">SendMessage</a> 関数の戻り値のアドレス。

戻り値

型: HRESULT

成功した場合は S_OK を返し、それ以外の場合は COM で定義されたエラー値を返します。

解説(Remarks)

ツールバーまたはステータスバーコントロールに送信できるメッセージの詳細については、コモンコントロール のドキュメントを参照してください。

呼び出し側アプリケーションへの注意

この呼び出しの使用には細心の注意が必要です。ステータスバーまたはツールバーを不適切な状態のままにすると、Windows エクスプローラーのパフォーマンスに影響します。

実装者への注意

お使いの Windows エクスプローラーにこれらのコントロールがない場合は、E_NOTIMPL を返すことができます。
vtbl 15 HRESULT QueryActiveShellView(IShellView** ppshv)

現在アクティブな(表示されている)Shell ビューオブジェクトを取得します。

ppshvIShellView**out現在アクティブな Shell ビューオブジェクトへのポインターのアドレス。

戻り値

型: HRESULT

成功した場合は S_OK を返し、それ以外の場合は COM で定義されたエラー値を返します。

解説(Remarks)

呼び出し側アプリケーションへの注意

IShellBrowser インターフェイスは複数の Shell ビューを同時にホストできるため、このメソッドはアクティブな Shell ビューオブジェクトを判定する簡単な方法を提供します。
vtbl 16 HRESULT OnViewWindowActive(IShellView* pshv)

ビューウィンドウまたはその子ウィンドウの 1 つがフォーカスを取得したとき、またはアクティブになったときに、Shell ビューによって呼び出されます。

pshvIShellView*inビューオブジェクトの IShellView ポインターのアドレス。

戻り値

型: HRESULT

成功した場合は S_OK を返し、それ以外の場合は COM で定義されたエラー値を返します。

解説(Remarks)

現在のバージョンの Windows エクスプローラーはこのパラメーターを使用しませんが、ビューは自身の IShellView 実装をこのルーチンに渡す必要があります。

呼び出し側への注意

Shell ビューオブジェクトは、IShellBrowser::InsertMenusSB メソッドを呼び出す前に、このメソッドを呼び出す必要があります。このメソッドは、ビューがフォーカスを持っているかどうかに応じて、異なるメニュー項目のセットを挿入します。

実装者への注意

このメソッドは、ビューがフォーカスを取得していること(たとえば、ビュー上でマウスがクリックされたとき)をブラウザーに通知します。
vtbl 17 HRESULT SetToolbarItems(TBBUTTON* lpButtons, DWORD nButtons, DWORD uFlags)

Windows エクスプローラーのツールバーにツールバー項目を追加します。

lpButtonsTBBUTTON*inoptionalTBBUTTON 構造体の配列のアドレス。
nButtonsDWORDinlpButtons 配列内の TBBUTTON 構造体の数。
uFlagsDWORDin

ツールバーボタンを配置する場所を指定するフラグ。このパラメーターには次の値の 1 つ以上を指定できます。

FCT_ADDTOEND

ツールバーの右側に追加します。

FCT_CONFIGABLE

実装されていません。

FCT_MERGE

すべてのボタンをビューが提供するものに置き換えるのではなく、ツールバー項目をマージします。これが推奨される選択肢です。

戻り値

型: HRESULT

成功した場合は S_OK を返し、それ以外の場合は COM で定義されたエラー値を返します。

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

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

出力引数: 
#define global IID_IShellBrowser "{000214E2-0000-0000-C000-000000000046}"
#usecom global IShellBrowser IID_IShellBrowser "{}"
#comfunc global IShellBrowser_InsertMenusSB           5 sptr,var
#comfunc global IShellBrowser_SetMenuSB               6 sptr,sptr,sptr
#comfunc global IShellBrowser_RemoveMenusSB           7 sptr
#comfunc global IShellBrowser_SetStatusTextSB         8 wstr
#comfunc global IShellBrowser_EnableModelessSB        9 int
#comfunc global IShellBrowser_TranslateAcceleratorSB  10 var,int
#comfunc global IShellBrowser_BrowseObject            11 var,int
#comfunc global IShellBrowser_GetViewStateStream      12 int,sptr
#comfunc global IShellBrowser_GetControlWindow        13 int,sptr
#comfunc global IShellBrowser_SendControlMsg          14 int,int,sptr,sptr,var
#comfunc global IShellBrowser_QueryActiveShellView    15 sptr
#comfunc global IShellBrowser_OnViewWindowActive      16 sptr
#comfunc global IShellBrowser_SetToolbarItems         17 var,int,int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。