SHELLEXECUTEINFOA 構造体 (shellapi.h)

  • [アーティクル]

ShellExecuteEx によって使用される情報が含まれます。

構文

typedef struct _SHELLEXECUTEINFOA {
  DWORD     cbSize;
  ULONG     fMask;
  HWND      hwnd;
  LPCSTR    lpVerb;
  LPCSTR    lpFile;
  LPCSTR    lpParameters;
  LPCSTR    lpDirectory;
  int       nShow;
  HINSTANCE hInstApp;
  void      *lpIDList;
  LPCSTR    lpClass;
  HKEY      hkeyClass;
  DWORD     dwHotKey;
  union {
    HANDLE hIcon;
    HANDLE hMonitor;
  } DUMMYUNIONNAME;
  HANDLE    hProcess;
} SHELLEXECUTEINFOA, *LPSHELLEXECUTEINFOA;

メンバー

cbSize

型: DWORD

必須。 この構造体のサイズ (バイト単位)。

fMask

種類: ULONG

他の構造体メンバーの内容と有効性を示す、次の値の 1 つ以上の組み合わせ。

SEE_MASK_DEFAULT (0x00000000) 既定値を使用します。
SEE_MASK_CLASSNAME (0x00000001) lpClass メンバーによって指定されたクラス名を使用します。 SEE_MASK_CLASSKEYとSEE_MASK_CLASSNAMEの両方が設定されている場合は、クラス キーが使用されます。
SEE_MASK_CLASSKEY (0x00000003) hkeyClass メンバーによって指定されたクラス キーを使用します。 SEE_MASK_CLASSKEYとSEE_MASK_CLASSNAMEの両方が設定されている場合は、クラス キーが使用されます。
SEE_MASK_IDLIST (0x00000004) lpIDList メンバーによって指定されたアイテム識別子リストを使用します。 lpIDList メンバーは ITEMIDLIST 構造体を指している必要があります。
SEE_MASK_INVOKEIDLIST (0x0000000C) 選択した項目のショートカット メニュー ハンドラーの IContextMenu インターフェイスを使用します。 lpFile を使用してファイル システム パスで項目を識別するか、lpIDList を使用してその PIDL で項目を識別します。 このフラグを使用すると、アプリケーションは ShellExecuteEx を使用して、レジストリに一覧表示されている静的動詞ではなく、ショートカット メニュー拡張機能から動詞を呼び出すことができます。
メモ： SEE_MASK_INVOKEIDLISTは、 をオーバーライドし、SEE_MASK_IDLISTを意味します。
SEE_MASK_ICON (0x00000010) hIcon メンバーによって指定されたアイコンを使用します。 このフラグをSEE_MASK_HMONITORと組み合わせることはできません。
メモ： このフラグは、Windows XP 以前でのみ使用されます。 Windows Vista では無視されます。
SEE_MASK_HOTKEY (0x00000020) dwHotKey メンバーによって指定されたキーボード ショートカットを使用します。
SEE_MASK_NOCLOSEPROCESS (0x00000040) hProcess メンバーがプロセス ハンドルを受け取っていることを示すには、 を使用します。 通常、このハンドルは、 ShellExecuteEx で作成されたプロセスがいつ終了したかをアプリケーションが確認できるようにするために使用されます。 場合によっては、DDE 会話を介して実行が満たされた場合など、ハンドルは返されません。 呼び出し元のアプリケーションは、不要になったハンドルを閉じる役割を担います。
SEE_MASK_CONNECTNETDRV (0x00000080) 共有を検証し、ドライブ文字に接続します。 これにより、切断されたネットワーク ドライブの再接続が可能になります。 lpFile メンバーは、ネットワーク上のファイルの UNC パスです。
SEE_MASK_NOASYNC (0x00000100) 実行操作が完了するまで待ってから、 を返します。 このフラグは、非同期アクティブ化が発生する可能性がある ShellExecute フォーム (DDE など) を使用している呼び出し元が使用し、バックグラウンド スレッドで実行される可能性のあるプロセスを作成する必要があります。 (注: 呼び出し元のスレッド モデルが Apartment でない場合、 ShellExecuteEx は既定でバックグラウンド スレッドで実行されます)。バックグラウンド スレッドで既に実行されているプロセスから ShellExecuteEx を呼び出す場合は、常にこのフラグを渡す必要があります。 また、 ShellExecuteEx を呼び出した直後に終了するアプリケーションでは、このフラグを指定する必要があります。

実行操作がバックグラウンド スレッドで実行され、呼び出し元が SEE_MASK_ASYNCOK フラグを指定しなかった場合、呼び出し元のスレッドは、新しいプロセスが開始されるまで待機してから、 を返します。 これは通常、 CreateProcess が呼び出されたか、DDE 通信が完了したか、カスタム実行デリゲートが ShellExecuteEx にそれが実行されたことを通知したことを意味します。 SEE_MASK_WAITFORINPUTIDLE フラグが指定されている場合、 ShellExecuteEx は WaitForInputIdle を呼び出し、新しいプロセスがアイドル状態になるまで待機してから、最大タイムアウトは 1 分です。

このフラグが必要な場合の詳細については、「解説」セクションを参照してください。
SEE_MASK_FLAG_DDEWAIT (0x00000100) SEE_MASK_NOASYNCと同じように、そのオプションを使用することをお勧めします。
SEE_MASK_DOENVSUBST (0x00000200) lpDirectory または lpFile メンバーによって指定された文字列で指定された環境変数を展開します。
SEE_MASK_FLAG_NO_UI (0x00000400) エラー ダイアログ、セキュリティ警告、または通常このオプションなしで表示されるその他のユーザー インターフェイスを含むユーザー インターフェイス (UI) を表示しないでください。
SEE_MASK_UNICODE (0x00004000) Unicode アプリケーションを示すには、このフラグを使用します。
SEE_MASK_NO_CONSOLE (0x00008000) を使用して、新しいコンソールを作成するのではなく、新しいプロセスの親のコンソールを継承します。 これは、CreateProcess でCREATE_NEW_CONSOLE フラグを使用するのとは反対です。
SEE_MASK_ASYNCOK (0x00100000) 実行はバックグラウンド スレッドで実行できます。呼び出しは、バックグラウンド スレッドが完了するのを待たずにすぐに返されます。 特定のケースでは、 ShellExecuteEx はこのフラグを無視し、プロセスが終了するまで待機してから、 を返します。
SEE_MASK_NOQUERYCLASSSTORE (0x01000000) 使用されていません。
SEE_MASK_HMONITOR (0x00200000) マルチモニター・システムでモニターを指定する場合は、このフラグを使用します。 モニターは hMonitor メンバーで指定されます。 このフラグをSEE_MASK_ICONと組み合わせることはできません。
SEE_MASK_NOZONECHECKS (0x00800000) ゾーン チェックを実行しないでください。 このフラグを使用すると、 ShellExecuteEx はIAttachmentExecute によって配置されたゾーン チェックをバイパスできます。
SEE_MASK_WAITFORINPUTIDLE (0x02000000) 新しいプロセスが作成されたら、プロセスがアイドル状態になるまで待ってから、1 分のタイムアウトで戻ります。 詳細については、「 WaitForInputIdle 」を参照してください。
SEE_MASK_FLAG_LOG_USAGE (0x04000000) 頻繁に使用されるプログラムやその他の動作の追跡を可能にする、ユーザーが開始した起動を示します。
SEE_MASK_FLAG_HINST_IS_SITE (0x08000000) hInstApp メンバーは、IServiceProvider を実装するオブジェクトの IUnknown を指定するために使用されます。 このオブジェクトは、サイト ポインターとして使用されます。 サイト ポインターは、 ShellExecute 関数、ハンドラー バインド プロセス、および呼び出された動詞ハンドラーにサービスを提供するために使用されます。

ICreatingProcess は 、呼び出し元が作成されるプロセスのパラメーターを変更できるように指定できます。

このフラグは、Windows 8以降でサポートされています。

このオプションを指定すると、呼び出しは呼び出し元スレッドで同期的に実行されます。

hwnd

型: HWND

省略可能。 所有者ウィンドウへのハンドル。この関数の実行中にシステムによって生成される可能性のある UI を表示および配置するために使用されます。

lpVerb

型: LPCTSTR

実行するアクションを指定する、 動詞と呼ばれる文字列。 使用可能な動詞のセットは、特定のファイルまたはフォルダーによって異なります。 一般に、オブジェクトのショートカット メニューから使用できるアクションは動詞として使用できます。 このパラメーターには NULL を指定できます。この場合、既定の動詞が使用可能な場合は使用されます。 そうでない場合は、"open" 動詞が使用されます。 どちらの動詞も使用できない場合、システムはレジストリに一覧表示されている最初の動詞を使用します。 アクションを特定の動詞に制限する理由がない限り、計算された既定値を使用するには NULL を渡します。 これは、アプリがインストールされていない場合に、SEE_MASK_FLAG_NO_UIを指定する場合や、"Open With" UI を生成することを意図している場合など、場合によっては必要になります。

次の動詞が一般的に使用されます。

  • edit: エディターを起動し、編集用にドキュメントを開きます。 lpFile がドキュメント ファイルでない場合、関数は失敗します。
  • explore: lpFile で指定されたフォルダーを探索します。
  • find: 指定したディレクトリから検索を開始します。
  • open: lpFile パラメーターで指定されたファイルを開きます。 ファイルには、実行可能ファイル、ドキュメント ファイル、またはフォルダーを指定できます。
  • print: lpFile で指定されたドキュメント ファイルを印刷します。 lpFile がドキュメント ファイルでない場合、関数は失敗します。
  • properties: ファイルまたはフォルダーのプロパティを表示します。
  • runas: 管理者としてアプリケーションを起動します。 ユーザー アカウント制御 (UAC) は、アプリケーションを管理者特権で実行するか、アプリケーションの実行に使用する管理者アカウントの資格情報を入力する同意をユーザーに求めます。

lpFile

型: LPCTSTR

lpVerb パラメーターで指定されたアクションを ShellExecuteEx が実行するファイルまたはオブジェクトの名前を指定する null で終わる文字列のアドレス。 ShellExecuteEx 関数でサポートされているシステム レジストリ動詞には、実行可能ファイルとドキュメント ファイルの "開く" と、印刷ハンドラーが登録されているドキュメント ファイルの "印刷" が含まれます。 他のアプリケーションでは、.avi ファイルや.wav ファイルの "play" など、システム レジストリを介してシェル動詞が追加されている場合があります。 シェル名前空間オブジェクトを指定するには、完全修飾解析名を渡し、fMask パラメーターに SEE_MASK_INVOKEIDLIST フラグを設定します。

メモ：SEE_MASK_INVOKEIDLIST フラグが設定されている場合は、lpFile または lpIDList を使用して、それぞれファイル システム パスまたはその PIDL によって項目を識別できます。 lpFile または lpIDList という 2 つの値のいずれかを設定する必要があります。
メモ： パスが名前に含まれていない場合は、現在のディレクトリが想定されます。

lpParameters

型: LPCTSTR

省略可能。 アプリケーション パラメーターを含む null で終わる文字列のアドレス。 パラメーターはスペースで区切る必要があります。 lpFile メンバーがドキュメント ファイルを指定する場合、lpParameters は NULL である必要があります。

lpDirectory

型: LPCTSTR

省略可能。 作業ディレクトリの名前を指定する null で終わる文字列のアドレス。 このメンバーが NULL の場合、現在のディレクトリが作業ディレクトリとして使用されます。

nShow

型: int

必須。 アプリケーションを開いたときに表示する方法を指定するフラグ。 ShellExecute 関数に一覧表示されているSW_値の 1 つ。 lpFile でドキュメント ファイルが指定されている場合、フラグは関連付けられたアプリケーションに渡されます。 それを処理する方法は、アプリケーションによって決めることができます。

hInstApp

種類: HINSTANCE

[out]SEE_MASK_NOCLOSEPROCESSが設定され、 ShellExecuteEx 呼び出しが成功した場合、このメンバーは 32 より大きい値に設定されます。 関数が失敗した場合は、エラーの原因を示すSE_ERR_XXXエラー値に設定されます。 hInstApp は、16 ビット Windows アプリケーションとの互換性のために HINSTANCE として宣言されていますが、実際の HINSTANCE ではありません。 int にのみキャストでき、32 または次のSE_ERR_XXXエラー コードと比較できます。


エラー コード 理由
SE_ERR_FNF (2) ファイルが見つかりません。
SE_ERR_PNF (3) パスが見つかりません。
SE_ERR_ACCESSDENIED (5) アクセスが拒否されました。
SE_ERR_OOM (8) メモリが不足しています。
SE_ERR_DLLNOTFOUND (32) ダイナミック リンク ライブラリが見つかりません。
SE_ERR_SHARE (26) 開いているファイルを共有できません。
SE_ERR_ASSOCINCOMPLETE (27) ファイルの関連付け情報が完全ではありません。
SE_ERR_DDETIMEOUT (28) DDE 操作がタイムアウトしました。
SE_ERR_DDEFAIL (29) DDE 操作に失敗しました。
SE_ERR_DDEBUSY (30) DDE 操作がビジー状態です。
SE_ERR_NOASSOC (31) ファイルの関連付けは使用できません。

lpIDList

種類: LPVOID

実行するファイルを一意に識別する項目識別子リストを含む絶対 ITEMIDLIST 構造体 (PCIDLIST_ABSOLUTE) のアドレス。 fMask メンバーにSEE_MASK_IDLISTまたはSEE_MASK_INVOKEIDLISTが含まれていない場合、このメンバーは無視されます。

lpClass

型: LPCTSTR

次のいずれかを指定する null で終わる文字列のアドレス。

  • ProgId。 たとえば、"Paint.Picture" などです。
  • URI プロトコル スキーム。 たとえば、"http" などです。
  • ファイル拡張子。 たとえば、".txt" などです。
  • 1 つ以上のシェル動詞を含むサブキーに名前を付ける、HKEY_CLASSES_ROOTの下のレジストリ パス。 このキーには、シェル動詞のレジストリ スキーマ (シェル動詞名など\) に準拠するサブキーがあります。

fMask にSEE_MASK_CLASSNAMEが含まれていない場合、このメンバーは無視されます。

hkeyClass

種類: HKEY

ファイルの種類のレジストリ キーへのハンドル。 このレジストリ キーのアクセス権は、KEY_READに設定する必要があります。 fMask にSEE_MASK_CLASSKEYが含まれていない場合、このメンバーは無視されます。

dwHotKey

型: DWORD

アプリケーションに関連付けるキーボード ショートカット。 下位ワードは仮想キー コードであり、上位ワードは修飾子フラグ (HOTKEYF_) です。 修飾子フラグの一覧については、 WM_SETHOTKEY メッセージの説明を参照してください。 fMask にSEE_MASK_HOTKEYが含まれていない場合、このメンバーは無視されます。

DUMMYUNIONNAME

DUMMYUNIONNAME.hIcon

型: HANDLE

ファイルの種類のアイコンへのハンドル。 fMask にSEE_MASK_ICONが含まれていない場合、このメンバーは無視されます。 この値は、Windows XP 以前でのみ使用されます。 Windows Vista では無視されます。

DUMMYUNIONNAME.hMonitor

型: HANDLE

ドキュメントを表示するモニターへのハンドル。 fMask にSEE_MASK_HMONITORが含まれていない場合、このメンバーは無視されます。

hProcess

型: HANDLE

新しく開始されたアプリケーションへのハンドル。 fMask が SEE_MASK_NOCLOSEPROCESS に設定されていない限り、このメンバーは戻り値に設定され、常に NULL になります。 fMask が SEE_MASK_NOCLOSEPROCESS に設定されている場合でも、プロセスが起動されなかった場合、hProcess は NULL になります。 たとえば、起動するドキュメントが URL で、インターネット エクスプローラーのインスタンスが既に実行されている場合、ドキュメントが表示されます。 新しいプロセスは起動せず、 hProcess は NULL になります。

注:呼び出しの結果としてプロセスが起動された場合でも、ShellExecuteEx は常に hProcess を返すとは限りません。 たとえば、SEE_MASK_INVOKEIDLISTを使用してIContextMenu を呼び出すと、hProcess は返されません。

注釈

ShellExecuteEx を呼び出すスレッドにメッセージ ループがない場合、または ShellExecuteEx が返された後すぐにスレッドまたはプロセスが終了する場合は、SEE_MASK_NOASYNC フラグを指定する必要があります。 このような状況では、呼び出し元スレッドは DDE 会話を完了するために使用できないため、呼び出し元のアプリケーションに制御を返す前に ShellExecuteEx が 会話を完了することが重要です。 会話を完了しないと、ドキュメントの起動が失敗する可能性があります。

呼び出し元のスレッドにメッセージ ループがあり、 ShellExecuteEx の呼び出しが返された後にしばらく存在する場合、 SEE_MASK_NOASYNC フラグは省略可能です。 フラグを省略すると、呼び出し元スレッドのメッセージ ポンプを使用して DDE 会話が完了します。 DDE 会話をバックグラウンドで完了できるため、呼び出し元のアプリケーションは制御を早く回復します。

lpParameters に二重引用符を含めるには、次の例のように、各マークを引用符のペアで囲みます。

sei.lpParameters = "An example: \"\"\"quoted text\"\"\"";

この場合、アプリケーションは、次の 3 つのパラメーター を受け取ります。例 :、および "引用符で囲まれたテキスト" です。

注意

shellapi.h ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして SHELLEXECUTEINFO を定義します。 encoding-neutral エイリアスの使用を encoding-neutral ではないコードと混在すると、コンパイル エラーまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。

要件

要件 値
サポートされている最小のクライアント Windows XP (デスクトップ アプリのみ)
サポートされている最小のサーバー Windows 2000 Server [デスクトップ アプリのみ]
Header shellapi.h