Struktur SHELLEXECUTEINFOA (shellapi.h)
Berisi informasi yang digunakan oleh ShellExecuteEx.
Sintaksis
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
Diperlukan. 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 |
SEE_MASK_CLASSKEY (0x00000003) | Gunakan kunci kelas yang diberikan oleh hkeyClass anggota. 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 |
SEE_MASK_INVOKEIDLIST (0x0000000C) | Gunakan antarmuka IContextMenu dari penangan menu pintasan item yang dipilih. Gunakan lpFile
Catatan: SEE_MASK_INVOKEIDLIST mengambil alih dan menyiratkan SEE_MASK_IDLIST.
|
SEE_MASK_ICON (0x00000010) | Gunakan ikon yang diberikan oleh hIcon anggota. 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 |
SEE_MASK_NOCLOSEPROCESS (0x00000040) | Gunakan untuk menunjukkan bahwa anggota |
SEE_MASK_CONNECTNETDRV (0x00000080) | Validasi berbagi dan sambungkan ke huruf kandar. Ini memungkinkan koneksi ulang drive jaringan yang terputus. Anggota |
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 pemanggil 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 lpDirectory atau anggota lpFile. |
SEE_MASK_FLAG_NO_UI (0x00000400) | Jangan tampilkan dialog kesalahan antarmuka pengguna (UI) yang biasanya akan disajikan tanpa opsi ini. Perintah keamanan dikecualikan dan masih akan ditampilkan. |
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 |
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 menjadi diam sebelum kembali, dengan batas waktu satu menit. Lihat WaitForInputIdle |
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 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
Fakultatif. Handel ke jendela pemilik, digunakan untuk menampilkan dan memosisikan UI apa pun yang mungkin dihasilkan sistem saat menjalankan fungsi ini.
lpVerb
Jenis:
String, 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 dapat 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:
- mengedit: Meluncurkan editor dan membuka dokumen untuk pengeditan. Jika lpFile bukan file dokumen, fungsi akan gagal.
- menjelajahi: Menjelajahi folder yang ditentukan oleh lpFile.
- menemukan: Memulai pencarian mulai dari direktori yang ditentukan.
membuka : Membuka file yang ditentukan oleh parameterlpFile. File dapat berupa file yang dapat dieksekusi, file dokumen, atau folder. - openas: Meluncurkan UI pemilih yang memungkinkan pengguna untuk memilih aplikasi untuk membuka file yang ditentukan oleh parameter lpFile.
- 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:
Alamat string yang dihentikan null yang menentukan nama file atau objek tempat
lpParameters
Jenis:
Fakultatif. Alamat string yang dihentikan null yang berisi parameter aplikasi. Parameter harus dipisahkan oleh spasi. Jika anggota lpFile
lpDirectory
Jenis:
Fakultatif. Alamat string yang dihentikan null yang menentukan nama direktori kerja. Jika anggota ini null, direktori saat ini digunakan sebagai direktori kerja.
nShow
Jenis: int
Diperlukan. Bendera yang menentukan bagaimana aplikasi akan ditampilkan saat dibuka; salah satu nilai SW_ yang tercantum untuk fungsi
hInstApp
Jenis: HINSTANCE
[out] Jika SEE_MASK_NOCLOSEPROCESS diatur dan panggilan ShellExecuteEx berhasil, itu mengatur 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 sejati. Ini hanya dapat ditransmisikan ke int
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:
Alamat struktur ITEMIDLIST
lpClass
Jenis:
Alamat string yang dihentikan null yang menentukan salah satu dari 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 subkuntang yang berisi satu atau beberapa kata kerja Shell. Kunci ini akan memiliki subkunci yang sesuai dengan skema registri kata kerja Shell, seperti shell\nama kata kerja.
Anggota ini diabaikan jika fMask
hkeyClass
Jenis:
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: HANDLE
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: HANDLE
Handel ke monitor tempat dokumen akan ditampilkan. Anggota ini diabaikan jika fMask tidak menyertakan SEE_MASK_HMONITOR.
hProcess
Jenis: HANDLE
Handel ke aplikasi yang baru dimulai. Anggota ini diatur saat kembali dan selalu NULL kecuali fMask diatur ke SEE_MASK_NOCLOSEPROCESS. Bahkan jika
Komentar
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: Contoh, :, dan "teks yang dikutip".
Nota
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
Syarat | Nilai |
---|---|
klien minimum yang didukung | Windows XP [hanya aplikasi desktop] |
server minimum yang didukung |
Windows 2000 Server [hanya aplikasi desktop] |
Header |
shellapi.h |