Fungsi ShellExecuteW (shellapi.h)

Artikel
03/15/2023

Melakukan operasi pada file tertentu.

Sintaks

HINSTANCE ShellExecuteW(
  [in, optional] HWND    hwnd,
  [in, optional] LPCWSTR lpOperation,
  [in]           LPCWSTR lpFile,
  [in, optional] LPCWSTR lpParameters,
  [in, optional] LPCWSTR lpDirectory,
  [in]           INT     nShowCmd
);

Parameter

[in, optional] hwnd

Jenis: HWND

Handel ke jendela induk yang digunakan untuk menampilkan UI atau pesan kesalahan. Nilai ini bisa NULL jika operasi tidak terkait dengan jendela.

[in, optional] lpOperation

Jenis: LPCTSTR

Penunjuk ke string yang dihentikan null, yang disebut dalam hal ini 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. Kata kerja berikut umumnya digunakan:

edit

Meluncurkan editor dan membuka dokumen untuk pengeditan. Jika lpFile bukan file dokumen, fungsi akan gagal.

Menjelajahi

Menjelajahi folder yang ditentukan oleh lpFile.

cari

Memulai pencarian yang dimulai di direktori yang ditentukan oleh lpDirectory.

buka

Membuka item yang ditentukan oleh parameter lpFile . Item dapat berupa file atau folder.

Cetak

Mencetak file yang ditentukan oleh lpFile. Jika lpFile bukan file dokumen, fungsi gagal.

Jalankan Sebagai

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.

NULL

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.

[in] lpFile

Jenis: LPCTSTR

Penunjuk ke string yang dihentikan null yang menentukan file atau objek untuk menjalankan kata kerja yang ditentukan. Untuk menentukan objek namespace Shell, berikan nama parse yang sepenuhnya memenuhi syarat. Perhatikan bahwa tidak semua kata kerja didukung pada semua objek. Misalnya, tidak semua jenis dokumen mendukung kata kerja "cetak". Jika jalur relatif digunakan untuk parameter lpDirectory tidak menggunakan jalur relatif untuk lpFile.

[in, optional] lpParameters

Jenis: LPCTSTR

Jika lpFile menentukan file yang dapat dieksekusi, parameter ini adalah penunjuk ke string yang dihentikan null yang menentukan parameter yang akan diteruskan ke aplikasi. Format string ini ditentukan oleh kata kerja yang akan dipanggil. Jika lpFile menentukan file dokumen, lpParameters harus NULL.

[in, optional] lpDirectory

Jenis: LPCTSTR

Penunjuk ke string yang dihentikan null yang menentukan direktori default (berfungsi) untuk tindakan tersebut. Jika nilai ini NULL, direktori kerja saat ini digunakan. Jika jalur relatif disediakan di lpFile, jangan gunakan jalur relatif untuk lpDirectory.

[in] nShowCmd

Jenis: INT

Bendera yang menentukan bagaimana aplikasi akan ditampilkan saat dibuka. Jika lpFile menentukan file dokumen, bendera hanya diteruskan ke aplikasi terkait. Terserah aplikasi untuk memutuskan cara menanganinya. Ini bisa menjadi salah satu nilai yang dapat ditentukan dalam parameter nCmdShow untuk fungsi ShowWindow .

Mengembalikan nilai

Jenis: HINSTANCE

Jika fungsi berhasil, fungsi mengembalikan nilai yang lebih besar dari 32. Jika fungsi gagal, fungsi mengembalikan nilai kesalahan yang menunjukkan penyebab kegagalan. Nilai yang dikembalikan ditransmisikan sebagai HINSTANCE untuk kompatibilitas mundur dengan aplikasi Windows 16-bit. Namun, ini bukan HINSTANCE sejati. Ini hanya dapat ditransmisikan ke INT_PTR dan dibandingkan dengan 32 atau kode kesalahan berikut di bawah ini.

Menampilkan kode	Deskripsi
0	Sistem operasi kehabisan memori atau sumber daya.
ERROR_FILE_NOT_FOUND	File yang ditentukan tidak ditemukan.
ERROR_PATH_NOT_FOUND	Jalur yang ditentukan tidak ditemukan.
ERROR_BAD_FORMAT	File .exe tidak valid (.exe non-Win32 atau kesalahan dalam gambar .exe).
SE_ERR_ACCESSDENIED	Sistem operasi menolak akses ke file yang ditentukan.
SE_ERR_ASSOCINCOMPLETE	Asosiasi nama file tidak lengkap atau tidak valid.
SE_ERR_DDEBUSY	Transaksi DDE tidak dapat diselesaikan karena transaksi DDE lainnya sedang diproses.
SE_ERR_DDEFAIL	Transaksi DDE gagal.
SE_ERR_DDETIMEOUT	Transaksi DDE tidak dapat diselesaikan karena waktu permintaan habis.
SE_ERR_DLLNOTFOUND	DLL yang ditentukan tidak ditemukan.
SE_ERR_FNF	File yang ditentukan tidak ditemukan.
SE_ERR_NOASSOC	Tidak ada aplikasi yang terkait dengan ekstensi nama file yang diberikan. Kesalahan ini juga akan dikembalikan jika Anda mencoba mencetak file yang tidak dapat dicetak.
SE_ERR_OOM	Memori tidak cukup untuk menyelesaikan operasi.
SE_ERR_PNF	Jalur yang ditentukan tidak ditemukan.
SE_ERR_SHARE	Terjadi pelanggaran berbagi.

Panggil GetLastError untuk informasi kesalahan yang diperluas.

Keterangan

Karena ShellExecute dapat mendelegasikan eksekusi ke ekstensi Shell (sumber data, penangan menu konteks, implementasi kata kerja) yang diaktifkan menggunakan Model Objek Komponen (COM), COM harus diinisialisasi sebelum ShellExecute dipanggil. Beberapa ekstensi Shell memerlukan jenis COM single-threaded apartment (STA). Dalam hal ini, COM harus diinisialisasi seperti yang ditunjukkan di sini:

CoInitializeEx(NULL, COINIT_APARTMENTTHREADED | COINIT_DISABLE_OLE1DDE)

Tentu saja ada instans di mana ShellExecute tidak menggunakan salah satu jenis ekstensi Shell ini dan instans tersebut tidak akan mengharuskan COM untuk diinisialisasi sama sekali. Meskipun demikian, ada baiknya untuk selalu menginisialisasi COM sebelum menggunakan fungsi ini.

Metode ini memungkinkan Anda untuk menjalankan perintah apa pun di menu pintasan folder atau disimpan di registri.

Untuk membuka folder, gunakan salah satu panggilan berikut:

ShellExecute(handle, NULL, <fully_qualified_path_to_folder>, NULL, NULL, SW_SHOWNORMAL);

atau

ShellExecute(handle, "open", <fully_qualified_path_to_folder>, NULL, NULL, SW_SHOWNORMAL);

Untuk menjelajahi folder, gunakan panggilan berikut:

ShellExecute(handle, "explore", <fully_qualified_path_to_folder>, NULL, NULL, SW_SHOWNORMAL);

Untuk meluncurkan utilitas Temukan Shell untuk direktori, gunakan panggilan berikut.

ShellExecute(handle, "find", <fully_qualified_path_to_folder>, NULL, NULL, 0);

Jika lpOperationADALAH NULL, fungsi akan membuka file yang ditentukan oleh lpFile. Jika lpOperation "terbuka" atau "jelajahi", fungsi mencoba membuka atau menjelajahi folder.

Untuk mendapatkan informasi tentang aplikasi yang diluncurkan sebagai akibat dari panggilan ShellExecute, gunakan ShellExecuteEx.

Catatan Jendela Luncurkan folder dalam pengaturan proses terpisah di Opsi Folder memengaruhi ShellExecute. Jika opsi tersebut dinonaktifkan (pengaturan default), ShellExecute menggunakan jendela Explorer yang terbuka daripada meluncurkan yang baru. Jika tidak ada jendela Explorer yang terbuka, ShellExecute meluncurkan yang baru.

Catatan

Header shellapi.h mendefinisikan ShellExecute 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]
Target Platform	Windows
Header	shellapi.h
Pustaka	Shell32.lib
DLL	Shell32.dll (versi 3.51 atau yang lebih baru)