Metode IDesktopGadget::RunGadget (shobjidl.h)

Artikel
08/26/2023

Menambahkan gadget yang terinstal ke desktop.

Sintaks

HRESULT RunGadget(
  [in] LPCWSTR gadgetPath
);

Parameter

[in] gadgetPath

Jenis: LPCWSTR

Penunjuk ke jalur penuh (absolut) dari folder .gadget. Gadget yang tidak dibungkus dengan Windows hanya dapat dijalankan dari salah satu dari dua lokasi berikut. Penginstalan gadget di lokasi lain akan menyebabkan metode ini gagal dengan kesalahan akses ditolak.

Catatan Jalur ini tidak boleh berisi variabel lingkungan; jalur yang sepenuhnya diperluas harus disediakan. ExpandEnvironmentStrings dapat digunakan untuk memperluas jalur ke formulir yang diperlukan dalam parameter ini.

(%ProgramFiles%\Windows Sidebar\Shared Gadgets)

Ini adalah jalur yang direkomendasikan untuk penginstalan gadget non-Microsoft, tersedia untuk semua pengguna.

(%LOCALAPPDATA%\Microsoft\Windows Sidebar\Gadgets)

Lokasi ini harus digunakan untuk penginstalan pengguna tunggal dari gadget.

Menampilkan nilai

Jenis: HRESULT

Mengembalikan S_OK jika berhasil, atau nilai kesalahan jika tidak, termasuk yang berikut ini:

Menampilkan kode	Deskripsi
SCHED_E_ALREADY_RUNNING	Gadget sudah berjalan.
E_INVALIDARG	Terjadi kesalahan yang melibatkan jalur folder gadget yang diarahkan oleh gadgetPath.

Keterangan

"Menjalankan" gadget di sini berarti bahwa gadget ditambahkan ke desktop.

RunGadget hanya dapat dipanggil pada gadget yang telah diinstal ke sistem. Ini tidak dapat dipanggil pada gadget yang sudah berjalan—hanya satu instans gadget yang dapat dijalankan pada waktu tertentu melalui metode ini.

Karena instalasi gadget tidak memiliki UI sendiri, metode ini sering dijalankan sebagai langkah terakhir dalam proses penginstalan atau sebagai bagian dari peluncuran pertama aplikasi yang terkait dengan gadget. Penginstalan gadget ke %ProgramFiles%\Windows Sidebar\Shared Gadgets memerlukan hak administratif. Oleh karena itu disarankan agar penginstalan gadget dilakukan sebagai bagian dari penginstalan Microsoft Installer (MSI).

Penting Aplikasi tidak boleh memanggil RunGadget tanpa terlebih dahulu meminta izin kepada pengguna. Jika pilihan diberikan kepada pengguna sebagai kotak centang, kotak centang tersebut harus tidak dipilih secara default.

Gadget ditambahkan ke desktop pada posisi yang ditentukan oleh sistem. Pemanggil tidak dapat menentukan lokasi.

Aplikasi per pengguna harus menginstal gadget mereka per pengguna. Aplikasi per mesin harus menginstal gadget per mesin mereka. Ini memastikan pengalaman terpadu kepada pengguna.

Contoh

Contoh berikut menunjukkan IDesktopGadget::RunGadget yang digunakan.

HRESULT RunMyGadget(PCWSTR pszGadgetPath)
{
    IDesktopGadget *pDG;

    HRESULT hr = CoCreateInstance(CLSID_DesktopGadget, 
                                  NULL, 
                                  CLSCTX_INPROC_SERVER, 
                                  IID_PPV_ARGS(&pDG));
    if (SUCCEEDED(hr))
    {
        hr = pDG->RunGadget(pszGadgetPath);
        pDG->Release();
    }

    return hr;
}

Persyaratan


Klien minimum yang didukung	Windows 7 [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2008 R2 [hanya aplikasi desktop]
Target Platform	Windows
Header	shobjidl.h

Bagikan melalui