Bagikan melalui

Fungsi ShellExecuteA (shellapi.h)

Melakukan operasi pada file tertentu.

Sintaksis

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

Parameter-parameternya

[in, optional] hwnd

Jenis: HWND

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

[in, optional] lpOperation

Jenis: LPCTSTR

Penunjuk ke string yang dihentikan null, yang disebut dalam kasus ini sebagai verb, yang menentukan tindakan yang akan dilakukan. Set yang tersedia verbs tergantung pada file atau folder tertentu. Umumnya, tindakan yang tersedia dari menu pintasan objek tersedia verbs. Berikut ini verbs 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 yang dimulai di direktori yang ditentukan oleh lpDirectory.

open

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

print

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

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.

NOL

Default verb digunakan, jika tersedia. Jika tidak, "open" verb digunakan. Jika tidak verb tersedia, sistem menggunakan yang pertama verb tercantum dalam registri.

[in] lpFile

Jenis: LPCTSTR

Penunjuk ke string yang dihentikan null yang menentukan file atau objek tempat menjalankan verb. Untuk menentukan objek namespace Shell, berikan nama parse yang sepenuhnya memenuhi syarat. Perhatikan bahwa tidak semua verbs didukung pada semua objek. Misalnya, tidak semua jenis dokumen mendukung "print" verb. 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 untainull yang menentukan parameter yang akan diteruskan ke aplikasi. Format string ini ditentukan oleh verb yang akan dipanggil. Jika lpFile menentukan file dokumen, lpParameters harus NULL.

[in, optional] lpDirectory

Jenis: LPCTSTR

Penunjuk ke untai (karakter) nullyang dihentikan 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 akan mengembalikan nilai yang lebih besar dari 32. Jika fungsi gagal, fungsi akan mengembalikan nilai kesalahan yang menunjukkan penyebab kegagalan. Nilai pengembalian 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.

Mengembalikan 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.

Komentar

Karena ShellExecute dapat mendelegasikan eksekusi ke ekstensi Shell (sumber data, penangan menu konteks, verb implementasi) 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 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 lpOperation NULL, fungsi akan membuka file yang ditentukan oleh lpFile. Jika lpOperation adalah "open" atau "explore", fungsi mencoba membuka atau menjelajahi folder.

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

Catatan Jendela folder Luncurkan dalam proses terpisah pengaturan 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.
 

Nota

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

Lihat juga

CoInitializeEx

CreateProcessA

IShellExecuteHook

Meluncurkan Aplikasi (ShellExecute, ShellExecuteEx, SHELLEXECUTEINFO)

ShellExecuteEx

  • Last updated on