Fungsi MsiEnumClientsExA (msi.h)

Artikel
08/24/2023

Fungsi MsiEnumClientsEx menghitung aplikasi yang diinstal yang menggunakan komponen tertentu. Fungsi ini mengambil kode produk untuk aplikasi setiap kali dipanggil.

Pemasang Windows 4.5 atau yang lebih lama: Tidak didukung. Fungsi ini tersedia dimulai dengan Pemasang Windows 5.0.

Sintaks

UINT MsiEnumClientsExA(
  [in]                LPCSTR            szComponent,
  [in, optional]      LPCSTR            szUserSid,
  [in]                DWORD             dwContext,
  [in]                DWORD             dwProductIndex,
  [out, optional]     CHAR [39]         szProductBuf,
  [out, optional]     MSIINSTALLCONTEXT *pdwInstalledContext,
  [out, optional]     LPSTR             szSid,
  [in, out, optional] LPDWORD           pcchSid
);

Parameter

[in] szComponent

GUID kode komponen yang mengidentifikasi komponen. Fungsi menghitung aplikasi yang menggunakan komponen ini.

[in, optional] szUserSid

Nilai string null-terminated yang berisi pengidentifikasi keamanan (SID.) Enumerasi aplikasi meluas ke pengguna yang diidentifikasi oleh SID ini. String SID khusus s-1-1-0 (Semua Orang) menghitung semua aplikasi untuk semua pengguna dalam sistem. Nilai SID selain s-1-1-0 menentukan SID pengguna untuk pengguna tertentu dan menghitung instans aplikasi yang diinstal oleh pengguna yang ditentukan.

Jenis SID	Makna
NULL	Menentukan pengguna yang saat ini masuk.
Pengidentifikasi keamanan pengguna	Menentukan enumerasi untuk pengguna tertentu. Contoh SID pengguna adalah "S-1-3-64-2415071341-1358098788-3127455600-2561".
s-1-1-0	Menentukan enumerasi untuk semua pengguna dalam sistem.

Catatan String SID khusus s-1-5-18 (Sistem) tidak dapat digunakan untuk menghitung aplikasi yang ada dalam konteks penginstalan per komputer. Mengatur nilai SID ke s-1-5-18 mengembalikan ERROR_INVALID_PARAMETER. Ketika dwContext diatur ke MSIINSTALLCONTEXT_MACHINE saja, nilai szUserSid harus NULL.

[in] dwContext

Bendera yang memperluas enumerasi ke instans aplikasi yang diinstal dalam konteks penginstalan yang ditentukan. Enumerasi hanya mencakup instans aplikasi yang diinstal oleh pengguna yang diidentifikasi oleh szUserSid.

Ini bisa menjadi kombinasi dari nilai berikut.

Konteks	Makna
MSIINSTALLCONTEXT_USERMANAGED 1	Sertakan aplikasi yang diinstal dalam konteks penginstalan yang dikelola per pengguna.
MSIINSTALLCONTEXT_USERUNMANAGED 2	Sertakan aplikasi yang diinstal dalam konteks penginstalan per-pengguna-tidak terkelola.
MSIINSTALLCONTEXT_MACHINE 4	Sertakan aplikasi yang diinstal dalam konteks penginstalan per komputer. Ketika dwInstallContext diatur ke MSIINSTALLCONTEXT_MACHINE saja, nilai parameter szUserSID harus NULL.

[in] dwProductIndex

Menentukan indeks aplikasi yang akan diambil. Nilai parameter ini harus nol (0) dalam panggilan pertama ke fungsi. Untuk setiap panggilan berikutnya, indeks harus bertambah 1. Indeks hanya boleh dinaikkan jika panggilan sebelumnya ke fungsi mengembalikan ERROR_SUCCESS.

[out, optional] szProductBuf

Nilai string yang menerima kode produk untuk aplikasi. Panjang buffer di lokasi ini harus cukup besar untuk menahan nilai string yang dihentikan null yang berisi kode produk. 38 karakter TCHAR pertama menerima GUID untuk komponen, dan karakter ke-39 menerima karakter NULL yang mengakhiri.

[out, optional] pdwInstalledContext

Bendera yang memberikan konteks penginstalan aplikasi.

Ini bisa menjadi kombinasi dari nilai berikut.

Konteks	Makna
MSIINSTALLCONTEXT_USERMANAGED 1	Aplikasi ini diinstal dalam konteks penginstalan yang dikelola per pengguna.
MSIINSTALLCONTEXT_USERUNMANAGED 2	Aplikasi ini diinstal dalam konteks penginstalan per-pengguna-tidak terkelola.
MSIINSTALLCONTEXT_MACHINE 4	Aplikasi ini berada dalam konteks penginstalan penginstalan per mesin.

[out, optional] szSid

Menerima pengidentifikasi keamanan (SID) yang mengidentifikasi pengguna yang menginstal aplikasi. Lokasi menerima nilai string kosong jika instans aplikasi ini ada dalam konteks penginstalan per komputer.

Panjang buffer harus cukup besar untuk menahan nilai string yang dihentikan null yang berisi SID. Jika buffer terlalu kecil, fungsi mengembalikan ERROR_MORE_DATA dan lokasi yang ditujukan oleh pcchSid menerima jumlah TCHAR dalam SID, tidak termasuk karakter NULL yang mengakhiri.

Jika szSid diatur ke NULL dan pcchSid adalah penunjuk yang valid ke lokasi dalam memori, fungsi mengembalikan ERROR_SUCCESS dan lokasi menerima jumlah TCHAR di SID, tidak termasuk karakter null yang mengakhiri. Fungsi ini kemudian dapat dipanggil lagi untuk mengambil nilai, dengan ukuran buffer szSid cukup besar untuk berisi *pcchSid + 1 karakter.

Jenis SID	Makna
String kosong	Aplikasi ini diinstal dalam konteks penginstalan per komputer.
Pengidentifikasi keamanan pengguna	SID untuk pengguna yang menginstal produk.

[in, out, optional] pcchSid

Penunjuk ke lokasi dalam memori yang berisi variabel yang menentukan jumlah TCHAR dalam SID, tidak termasuk karakter null yang mengakhiri. Ketika fungsi kembali, variabel ini diatur ke ukuran SID yang diminta apakah fungsi dapat berhasil menyalin SID dan mengakhiri karakter null ke lokasi buffer yang diacu oleh szSid. Ukuran dikembalikan sebagai jumlah TCHAR dalam nilai yang diminta, tidak termasuk karakter null yang mengakhiri.

Parameter ini dapat diatur ke NULL hanya jika szSid juga NULL, jika tidak, fungsi mengembalikan ERROR_INVALID_PARAMETER. Jika szSid dan pcchSid diatur ke NULL, fungsi mengembalikan ERROR_SUCCESS jika SID ada, tanpa mengambil nilai SID.

Menampilkan nilai

Fungsi MsiEnumClientsEx mengembalikan salah satu nilai berikut.

Menampilkan kode	Deskripsi
ERROR_ACCESS_DENIED	Hak istimewa administrator diperlukan untuk menghitung komponen aplikasi yang diinstal oleh pengguna selain pengguna saat ini.
ERROR_BAD_CONFIGURATION	Data konfigurasi rusak.
ERROR_INVALID_PARAMETER	Parameter yang tidak valid diteruskan ke fungsi.
ERROR_NO_MORE_ITEMS	Tidak ada lagi aplikasi untuk dijumlahkan.
ERROR_SUCCESS	Fungsi berhasil.
ERROR_MORE_DATA	Buffer yang disediakan terlalu kecil untuk menahan seluruh nilai.
ERROR_FUNCTION_FAILED	Fungsi gagal.

Keterangan

Catatan

Header msi.h mendefinisikan MsiEnumClientsEx sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta praprosem 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


Klien minimum yang didukung	Windows Installer 5.0 di Windows Server 2012, Windows 8, Windows Server 2008 R2 atau Windows 7. Lihat Persyaratan Run-Time Penginstal Windows untuk informasi tentang paket layanan Windows minimum yang diperlukan oleh versi Penginstal Windows.
Target Platform	Windows
Header	msi.h
Pustaka	Msi.lib
DLL	Msi.dll

Bagikan melalui