Struktur SHELLEXECUTEINFOA (shellapi.h)

  • Artikel

Berisi informasi yang digunakan oleh ShellExecuteEx.

Sintaks

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;

Anggota

cbSize

Jenis: DWORD

Wajib diisi. Ukuran struktur ini, dalam byte.

fMask

Jenis: ULONG

Kombinasi satu atau beberapa nilai berikut yang menunjukkan konten dan validitas anggota struktur lainnya:

SEE_MASK_DEFAULT (0x00000000) Gunakan nilai default.
SEE_MASK_CLASSNAME (0x00000001) Gunakan nama kelas yang diberikan oleh anggota lpClass . Jika SEE_MASK_CLASSKEY dan SEE_MASK_CLASSNAME diatur, kunci kelas akan digunakan.
SEE_MASK_CLASSKEY (0x00000003) Gunakan kunci kelas yang diberikan oleh anggota hkeyClass . Jika SEE_MASK_CLASSKEY dan SEE_MASK_CLASSNAME diatur, kunci kelas akan digunakan.
SEE_MASK_IDLIST (0x00000004) Gunakan daftar pengidentifikasi item yang diberikan oleh anggota lpIDList . Anggota lpIDList harus menunjuk ke struktur ITEMIDLIST .
SEE_MASK_INVOKEIDLIST (0x0000000C) Gunakan antarmuka IContextMenu dari penangan menu pintasan item yang dipilih. Gunakan lpFile untuk mengidentifikasi item berdasarkan jalur sistem file atau lpIDList untuk mengidentifikasi item dengan PIDL-nya. Bendera ini memungkinkan aplikasi untuk menggunakan ShellExecuteEx untuk memanggil kata kerja dari ekstensi menu pintasan alih-alih kata kerja statis yang tercantum dalam registri.
Catatan: SEE_MASK_INVOKEIDLIST mengambil alih dan menyiratkan SEE_MASK_IDLIST.
SEE_MASK_ICON (0x00000010) Gunakan ikon yang diberikan oleh anggota hIcon . Bendera ini tidak dapat digabungkan dengan SEE_MASK_HMONITOR.
Catatan: Bendera ini hanya digunakan di Windows XP dan yang lebih lama. Ini diabaikan sebagai Windows Vista.
SEE_MASK_HOTKEY (0x00000020) Gunakan pintasan keyboard yang diberikan oleh anggota dwHotKey .
SEE_MASK_NOCLOSEPROCESS (0x00000040) Gunakan untuk menunjukkan bahwa anggota hProcess menerima handel proses. Handel ini biasanya digunakan untuk memungkinkan aplikasi mengetahui kapan proses yang dibuat dengan ShellExecuteEx berakhir. Dalam beberapa kasus, seperti ketika eksekusi terpenuhi melalui percakapan DDE, tidak ada handel yang akan dikembalikan. Aplikasi panggilan bertanggung jawab untuk menutup handel ketika tidak lagi diperlukan.
SEE_MASK_CONNECTNETDRV (0x00000080) Validasi berbagi dan sambungkan ke huruf kandar. Ini memungkinkan koneksi ulang drive jaringan yang terputus. Anggota lpFile adalah jalur UNC dari file di jaringan.
SEE_MASK_NOASYNC (0x00000100) Tunggu hingga operasi eksekusi selesai sebelum kembali. Bendera ini harus digunakan oleh penelepon yang menggunakan formulir ShellExecute yang mungkin mengakibatkan aktivasi asinkron, misalnya DDE, dan membuat proses yang mungkin dijalankan pada utas latar belakang. (Catatan: ShellExecuteEx berjalan pada utas latar belakang secara default jika model utas penelepon bukan Apartemen.) Panggilan ke ShellExecuteEx dari proses yang sudah berjalan pada utas latar belakang harus selalu meneruskan bendera ini. Selain itu, aplikasi yang keluar segera setelah memanggil ShellExecuteEx harus menentukan bendera ini.

Jika operasi eksekusi dilakukan pada utas latar belakang dan pemanggil tidak menentukan bendera SEE_MASK_ASYNCOK, maka utas panggilan menunggu hingga proses baru dimulai sebelum kembali. Ini biasanya berarti bahwa CreateProcess telah dipanggil, komunikasi DDE telah selesai, atau bahwa delegasi eksekusi kustom telah memberi tahu ShellExecuteEx bahwa itu dilakukan. Jika bendera SEE_MASK_WAITFORINPUTIDLE ditentukan, maka ShellExecuteEx memanggil WaitForInputIdle dan menunggu proses baru diam sebelum kembali, dengan batas waktu maksimum 1 menit.

Untuk diskusi lebih lanjut tentang kapan bendera ini diperlukan, lihat bagian Keterangan.
SEE_MASK_FLAG_DDEWAIT (0x00000100) Sama seperti SEE_MASK_NOASYNC, penggunaan opsi tersebut lebih disukai.
SEE_MASK_DOENVSUBST (0x00000200) Perluas variabel lingkungan apa pun yang ditentukan dalam string yang diberikan oleh anggota lpDirectory atau lpFile .
SEE_MASK_FLAG_NO_UI (0x00000400) Jangan tampilkan antarmuka pengguna (UI) termasuk dialog kesalahan, peringatan keamanan, atau antarmuka pengguna lain yang biasanya akan disajikan tanpa opsi ini.
SEE_MASK_UNICODE (0x00004000) Gunakan bendera ini untuk menunjukkan aplikasi Unicode.
SEE_MASK_NO_CONSOLE (0x00008000) Gunakan untuk mewarisi konsol induk untuk proses baru alih-alih membuatnya membuat konsol baru. Ini adalah kebalikan dari menggunakan bendera CREATE_NEW_CONSOLE dengan CreateProcess.
SEE_MASK_ASYNCOK (0x00100000) Eksekusi dapat dilakukan pada utas latar belakang dan panggilan harus segera kembali tanpa menunggu utas latar belakang selesai. Perhatikan bahwa dalam kasus tertentu ShellExecuteEx mengabaikan bendera ini dan menunggu proses selesai sebelum kembali.
SEE_MASK_NOQUERYCLASSSTORE (0x01000000) Tidak digunakan.
SEE_MASK_HMONITOR (0x00200000) Gunakan bendera ini saat menentukan monitor pada sistem multi-monitor. Monitor ditentukan dalam anggota hMonitor . Bendera ini tidak dapat digabungkan dengan SEE_MASK_ICON.
SEE_MASK_NOZONECHECKS (0x00800000) Jangan lakukan pemeriksaan zona. Bendera ini memungkinkan ShellExecuteEx untuk melewati pemeriksaan zona yang diberlakukan oleh IAttachmentExecute.
SEE_MASK_WAITFORINPUTIDLE (0x02000000) Setelah proses baru dibuat, tunggu hingga proses diam sebelum kembali, dengan batas waktu satu menit. Lihat WaitForInputIdle untuk detail selengkapnya.
SEE_MASK_FLAG_LOG_USAGE (0x04000000) Menunjukkan peluncuran yang dimulai pengguna yang memungkinkan pelacakan program yang sering digunakan dan perilaku lainnya.
SEE_MASK_FLAG_HINST_IS_SITE (0x08000000) Anggota hInstApp digunakan untuk menentukan IUnknown objek yang mengimplementasikan IServiceProvider. Objek ini akan digunakan sebagai penunjuk situs. Penunjuk situs digunakan untuk menyediakan layanan ke fungsi ShellExecute , proses pengikatan handler, dan handler kata kerja yang dipanggil.

ICreatingProcess dapat disediakan untuk memungkinkan pemanggil mengubah beberapa parameter proses yang dibuat.

Bendera ini didukung di Windows 8 dan yang lebih baru.

Ketika opsi ini ditentukan, panggilan berjalan secara sinkron pada utas panggilan.

hwnd

Jenis: HWND

Pilihan. Handel ke jendela pemilik, digunakan untuk menampilkan dan memosisikan UI apa pun yang mungkin dihasilkan sistem saat menjalankan fungsi ini.

lpVerb

Jenis: LPCTSTR

String, yang disebut sebagai kata kerja, yang menentukan tindakan yang akan dilakukan. Kumpulan kata kerja yang tersedia tergantung pada file atau folder tertentu. Umumnya, tindakan yang tersedia dari menu pintasan objek tersedia kata kerja. Parameter ini bisa NULL, dalam hal ini kata kerja default digunakan jika tersedia. Jika tidak, kata kerja "buka" digunakan. Jika tidak ada kata kerja yang tersedia, sistem menggunakan kata kerja pertama yang tercantum dalam registri. Kecuali ada alasan untuk membatasi tindakan ke kata kerja tertentu, teruskan NULL untuk menggunakan default komputasi. Ini diperlukan dalam beberapa kasus, misalnya saat menentukan SEE_MASK_FLAG_NO_UI dan niatnya adalah untuk menghasilkan UI "Buka Dengan", jika tidak ada aplikasi yang diinstal.

Kata kerja berikut umumnya digunakan:

  • edit: Meluncurkan editor dan membuka dokumen untuk pengeditan. Jika lpFile bukan file dokumen, fungsi akan gagal.
  • explore: Menjelajahi folder yang ditentukan oleh lpFile.
  • find: Memulai pencarian mulai dari direktori yang ditentukan.
  • open: Membuka file yang ditentukan oleh parameter lpFile . File dapat berupa file yang dapat dieksekusi, file dokumen, atau folder.
  • cetak: Mencetak file dokumen yang ditentukan oleh lpFile. Jika lpFile bukan file dokumen, fungsi akan gagal.
  • properti: Menampilkan properti file atau folder.
  • runas: Meluncurkan aplikasi sebagai Administrator. Kontrol Akun Pengguna (UAC) akan meminta persetujuan kepada pengguna untuk menjalankan aplikasi yang ditinggikan atau memasukkan kredensial akun administrator yang digunakan untuk menjalankan aplikasi.

lpFile

Jenis: LPCTSTR

Alamat string yang dihentikan null yang menentukan nama file atau objek tempat ShellExecuteEx akan melakukan tindakan yang ditentukan oleh parameter lpVerb . Kata kerja registri sistem yang didukung oleh fungsi ShellExecuteEx mencakup "buka" untuk file yang dapat dieksekusi dan file dokumen dan "cetak" untuk file dokumen tempat penangan cetak telah didaftarkan. Aplikasi lain mungkin telah menambahkan kata kerja Shell melalui registri sistem, seperti "putar" untuk file .avi dan .wav. Untuk menentukan objek namespace Shell, berikan nama parse yang sepenuhnya memenuhi syarat dan atur bendera SEE_MASK_INVOKEIDLIST di parameter fMask .

Catatan: Jika bendera SEE_MASK_INVOKEIDLIST diatur, Anda dapat menggunakan lpFile atau lpIDList untuk mengidentifikasi item berdasarkan jalur sistem file atau PIDL-nya masing-masing. Salah satu dari dua nilai—lpFile atau lpIDList—harus diatur.
Catatan: Jika jalur tidak disertakan dengan nama, direktori saat ini diasumsikan.

lpParameters

Jenis: LPCTSTR

Pilihan. Alamat string yang dihentikan null yang berisi parameter aplikasi. Parameter harus dipisahkan oleh spasi. Jika anggota lpFile menentukan file dokumen, lpParameters harus NULL.

lpDirectory

Jenis: LPCTSTR

Pilihan. Alamat string yang dihentikan null yang menentukan nama direktori kerja. Jika anggota ini NULL, direktori saat ini digunakan sebagai direktori kerja.

nShow

Jenis: int

Wajib diisi. Bendera yang menentukan bagaimana aplikasi akan ditampilkan saat dibuka; salah satu nilai SW_ yang tercantum untuk fungsi ShellExecute . Jika lpFile menentukan file dokumen, bendera hanya diteruskan ke aplikasi terkait. Terserah aplikasi untuk memutuskan cara menanganinya.

hInstApp

Jenis: HINSTANCE

[out] Jika SEE_MASK_NOCLOSEPROCESS diatur dan panggilan ShellExecuteEx berhasil, itu menetapkan anggota ini ke nilai yang lebih besar dari 32. Jika fungsi gagal, fungsi diatur ke nilai kesalahan SE_ERR_XXX yang menunjukkan penyebab kegagalan. Meskipun hInstApp dinyatakan sebagai HINSTANCE untuk kompatibilitas dengan aplikasi Windows 16-bit, itu bukan HINSTANCE yang sebenarnya. Ini hanya dapat ditransmisikan ke int dan dibandingkan dengan 32 atau kode kesalahan SE_ERR_XXX berikut.


Kode Kesalahan Alasan
SE_ERR_FNF (2) File tidak ditemukan.
SE_ERR_PNF (3) Jalur tidak ditemukan.
SE_ERR_ACCESSDENIED (5) Akses ditolak.
SE_ERR_OOM (8) Kehabisan memori.
SE_ERR_DLLNOTFOUND (32) Pustaka tautan-dinamis tidak ditemukan.
SE_ERR_SHARE (26) Tidak dapat berbagi file yang terbuka.
SE_ERR_ASSOCINCOMPLETE (27) Informasi asosiasi file tidak lengkap.
SE_ERR_DDETIMEOUT (28) Waktu operasi DDE habis.
SE_ERR_DDEFAIL (29) Operasi DDE gagal.
SE_ERR_DDEBUSY (30) Operasi DDE sibuk.
SE_ERR_NOASSOC (31) Asosiasi file tidak tersedia.

lpIDList

Jenis: LPVOID

Alamat struktur ITEMIDLIST absolut (PCIDLIST_ABSOLUTE) untuk berisi daftar pengidentifikasi item yang secara unik mengidentifikasi file yang akan dijalankan. Anggota ini diabaikan jika anggota fMask tidak menyertakan SEE_MASK_IDLIST atau SEE_MASK_INVOKEIDLIST.

lpClass

Jenis: LPCTSTR

Alamat string yang dihentikan null yang menentukan salah satu hal berikut ini:

  • A ProgId. Misalnya, "Paint.Picture".
  • Skema protokol URI. Misalnya, "http".
  • Ekstensi file. Misalnya, ".txt".
  • Jalur registri di bawah HKEY_CLASSES_ROOT yang menamai subkey yang berisi satu atau beberapa kata kerja Shell. Kunci ini akan memiliki subkunci yang sesuai dengan skema registri kata kerja Shell, sepertinama kata kerjashell\.

Anggota ini diabaikan jika fMask tidak menyertakan SEE_MASK_CLASSNAME.

hkeyClass

Jenis: HKEY

Handel ke kunci registri untuk jenis file. Hak akses untuk kunci registri ini harus diatur ke KEY_READ. Anggota ini diabaikan jika fMask tidak menyertakan SEE_MASK_CLASSKEY.

dwHotKey

Jenis: DWORD

Pintasan keyboard untuk dikaitkan dengan aplikasi. Kata urutan rendah adalah kode kunci virtual, dan kata urutan tinggi adalah bendera pengubah (HOTKEYF_). Untuk daftar bendera pengubah, lihat deskripsi pesan WM_SETHOTKEY . Anggota ini diabaikan jika fMask tidak menyertakan SEE_MASK_HOTKEY.

DUMMYUNIONNAME

DUMMYUNIONNAME.hIcon

Jenis: HANDEL

Handel ke ikon untuk jenis file. Anggota ini diabaikan jika fMask tidak menyertakan SEE_MASK_ICON. Nilai ini hanya digunakan di Windows XP dan yang lebih lama. Ini diabaikan sebagai Windows Vista.

DUMMYUNIONNAME.hMonitor

Jenis: HANDEL

Handel ke monitor tempat dokumen akan ditampilkan. Anggota ini diabaikan jika fMask tidak menyertakan SEE_MASK_HMONITOR.

hProcess

Jenis: HANDEL

Handel ke aplikasi yang baru dimulai. Anggota ini diatur saat kembali dan selalu NULL kecuali fMask diatur ke SEE_MASK_NOCLOSEPROCESS. Bahkan jika fMask diatur ke SEE_MASK_NOCLOSEPROCESS, hProcess akan menjadi NULL jika tidak ada proses yang diluncurkan. Misalnya, jika dokumen yang akan diluncurkan adalah URL dan instans Internet Explorer sudah berjalan, dokumen akan ditampilkan. Tidak ada proses baru yang diluncurkan, dan hProcess akan NULL.

Catatan:ShellExecuteEx tidak selalu mengembalikan hProcess, meskipun proses diluncurkan sebagai hasil dari panggilan. Misalnya, hProcess tidak kembali saat Anda menggunakan SEE_MASK_INVOKEIDLIST untuk memanggil IContextMenu.

Keterangan

Bendera SEE_MASK_NOASYNC harus ditentukan jika utas yang memanggil ShellExecuteEx tidak memiliki perulangan pesan atau jika utas atau proses akan berakhir segera setelah ShellExecuteEx kembali. Dalam kondisi seperti itu, utas panggilan tidak akan tersedia untuk menyelesaikan percakapan DDE, jadi penting bahwa ShellExecuteEx menyelesaikan percakapan sebelum mengembalikan kontrol ke aplikasi panggilan. Kegagalan untuk menyelesaikan percakapan dapat mengakibatkan peluncuran dokumen yang gagal.

Jika utas panggilan memiliki perulangan pesan dan akan ada selama beberapa waktu setelah panggilan ke ShellExecuteEx kembali, bendera SEE_MASK_NOASYNC bersifat opsional. Jika bendera dihilangkan, pompa pesan utas panggilan akan digunakan untuk menyelesaikan percakapan DDE. Aplikasi panggilan mendapatkan kembali kontrol lebih cepat, karena percakapan DDE dapat diselesaikan di latar belakang.

Untuk menyertakan tanda kutip ganda dalam lpParameters, sertakan setiap tanda dalam sepasang tanda kutip, seperti dalam contoh berikut.

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

Dalam hal ini, aplikasi menerima tiga parameter: An, example:, dan "quoted text".

Catatan

Header shellapi.h mendefinisikan SHELLEXECUTEINFO sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta praprosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.

Persyaratan

Persyaratan Nilai
Klien minimum yang didukung Windows XP [hanya aplikasi desktop]
Server minimum yang didukung Windows 2000 Server [hanya aplikasi desktop]
Header shellapi.h