MsiEnumClientsExA-Funktion (msi.h)

Artikel
08/24/2023

Die MsiEnumClientsEx-Funktion listet die installierten Anwendungen auf, die eine angegebene Komponente verwenden. Die Funktion ruft bei jedem Aufruf einen Produktcode für eine Anwendung ab.

Windows Installer 4.5 oder früher: Nicht unterstützt. Diese Funktion ist ab Windows Installer 5.0 verfügbar.

Syntax

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

Die Komponentencode-GUID, die die Komponente identifiziert. Die Funktion listet die Anwendungen auf, die diese Komponente verwenden.

[in, optional] szUserSid

Ein NULL-beendeter Zeichenfolgenwert, der einen Sicherheitsbezeichner (SID) enthält. Die Aufzählung von Anwendungen erstreckt sich auf Benutzer, die von dieser SID identifiziert werden. Die spezielle SID-Zeichenfolge s-1-1-0 (Jeder) listet alle Anwendungen für alle Benutzer im System auf. Ein anderer SID-Wert als s-1-1-0 gibt eine Benutzer-SID für einen bestimmten Benutzer an und listet die Instanzen von Anwendungen auf, die vom angegebenen Benutzer installiert wurden.

SID-Typ	Bedeutung
NULL	Gibt den aktuell angemeldeten Benutzer an.
Benutzer-SID	Gibt eine Enumeration für einen bestimmten Benutzer an. Ein Beispiel für eine Benutzer-SID ist "S-1-3-64-2415071341-1358098788-3127455600-2561".
s-1-1-0	Gibt eine Enumeration für alle Benutzer im System an.

Hinweis Die spezielle SID-Zeichenfolge s-1-5-18 (System) kann nicht verwendet werden, um Anwendungen aufzulisten, die im Installationskontext pro Computer vorhanden sind. Wenn Sie den SID-Wert auf s-1-5-18 festlegen, wird ERROR_INVALID_PARAMETER zurückgegeben. Wenn dwContext nur auf MSIINSTALLCONTEXT_MACHINE festgelegt ist, muss der Wert von szUserSidNULL sein.

[in] dwContext

Ein Flag, das die Enumeration auf Instanzen von Anwendungen erweitert, die im angegebenen Installationskontext installiert sind. Die Enumeration enthält nur Instanzen von Anwendungen, die von den benutzern installiert werden, die durch szUserSid identifiziert werden.

Dies kann eine Kombination der folgenden Werte sein.

Kontext	Bedeutung
MSIINSTALLCONTEXT_USERMANAGED 1	Schließen Sie Anwendungen ein, die im benutzerseitig verwalteten Installationskontext installiert sind.
MSIINSTALLCONTEXT_USERUNMANAGED 2	Schließen Sie Anwendungen ein, die im nicht verwalteten Installationskontext pro Benutzer installiert sind.
MSIINSTALLCONTEXT_MACHINE 4	Schließen Sie Anwendungen ein, die im Installationskontext pro Computer installiert sind. Wenn dwInstallContext nur auf MSIINSTALLCONTEXT_MACHINE festgelegt ist, muss der Wert des parameters szUserSIDNULL sein.

[in] dwProductIndex

Gibt den Index der abzurufenden Anwendung an. Der Wert dieses Parameters muss beim ersten Aufruf der Funktion null (0) sein. Für jeden nachfolgenden Aufruf muss der Index um 1 erhöht werden. Der Index sollte nur erhöht werden, wenn der vorherige Aufruf der Funktion ERROR_SUCCESS zurückgibt.

[out, optional] szProductBuf

Ein Zeichenfolgenwert, der den Produktcode für die Anwendung empfängt. Die Länge des Puffers an diesem Speicherort sollte groß genug sein, um einen NULL-endendierten Zeichenfolgenwert mit dem Produktcode zu enthalten. Die ersten 38 TCHAR-Zeichen empfangen die GUID für die Komponente, und das 39. Zeichen erhält ein beendendes NULL-Zeichen.

[out, optional] pdwInstalledContext

Ein Flag, das den Installationskontext der Anwendung angibt.

Dies kann eine Kombination der folgenden Werte sein.

Kontext	Bedeutung
MSIINSTALLCONTEXT_USERMANAGED 1	Die Anwendung wird im benutzerseitig verwalteten Installationskontext installiert.
MSIINSTALLCONTEXT_USERUNMANAGED 2	Die Anwendung wird im nicht verwalteten Installationskontext pro Benutzer installiert.
MSIINSTALLCONTEXT_MACHINE 4	Die Anwendung befindet sich im Installationskontext pro Computer.

[out, optional] szSid

Empfängt die Sicherheits-ID (SID), die den Benutzer identifiziert, der die Anwendung installiert hat. Der Speicherort empfängt einen leeren Zeichenfolgenwert, wenn dieser instance der Anwendung in einem Installationskontext pro Computer vorhanden ist.

Die Länge des Puffers sollte groß genug sein, um einen null-beendeten Zeichenfolgenwert zu enthalten, der die SID enthält. Wenn der Puffer zu klein ist, gibt die Funktion ERROR_MORE_DATA zurück, und die Position, auf die von pcchSid verwiesen wird, empfängt die Anzahl von TCHAR in der SID, ohne das beendende NULL-Zeichen.

Wenn szSid auf NULL festgelegt ist und pcchSid ein gültiger Zeiger auf einen Speicherort im Arbeitsspeicher ist, gibt die Funktion ERROR_SUCCESS zurück, und der Speicherort empfängt die Anzahl von TCHAR in der SID, ohne das beendende NULL-Zeichen. Die Funktion kann dann erneut aufgerufen werden, um den Wert abzurufen, wobei die Größe des szSid-Puffers so groß ist, dass er *pcchSid + 1 Zeichen enthält.

SID-Typ	Bedeutung
leere Zeichenfolge	Die Anwendung wird in einem Installationskontext pro Computer installiert.
Benutzer-SID	Die SID für den Benutzer, der das Produkt installiert hat.

[in, out, optional] pcchSid

Zeiger auf einen Speicherort im Arbeitsspeicher, der eine Variable enthält, die die Anzahl von TCHAR in der SID angibt, ohne das beendende NULL-Zeichen. Wenn die Funktion zurückgibt, wird diese Variable auf die Größe der angeforderten SID festgelegt, unabhängig davon, ob die Funktion die SID erfolgreich kopieren und das NULL-Zeichen in den Pufferspeicherort kopieren kann, auf den szSid verweist. Die Größe wird als Anzahl von TCHAR im angeforderten Wert zurückgegeben, ohne das beendende NULL-Zeichen.

Dieser Parameter kann nur auf NULL festgelegt werden, wenn szSid ebenfalls NULL ist, andernfalls gibt die Funktion ERROR_INVALID_PARAMETER zurück. Wenn szSid und pcchSid auf NULL festgelegt sind, gibt die Funktion ERROR_SUCCESS zurück, wenn die SID vorhanden ist, ohne den SID-Wert abzurufen.

Rückgabewert

Die MsiEnumClientsEx-Funktion gibt einen der folgenden Werte zurück.

Rückgabecode	Beschreibung
ERROR_ACCESS_DENIED	Administratorrechte sind erforderlich, um Komponenten von Anwendungen aufzulisten, die von anderen Benutzern als dem aktuellen Benutzer installiert werden.
ERROR_BAD_CONFIGURATION	Die Konfigurationsdaten sind beschädigt.
ERROR_INVALID_PARAMETER	Ein ungültiger Parameter wird an die Funktion übergeben.
ERROR_NO_MORE_ITEMS	Es gibt keine weiteren Anwendungen, die aufgelistet werden müssen.
ERROR_SUCCESS	Die Funktion wurde erfolgreich ausgeführt.
ERROR_MORE_DATA	Der bereitgestellte Puffer war zu klein, um den gesamten Wert aufzunehmen.
ERROR_FUNCTION_FAILED	Fehler bei der Funktion.

Hinweise

Hinweis

Der msi.h-Header definiert MsiEnumClientsEx als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit nicht codierungsneutralem Code kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen


Unterstützte Mindestversion (Client)	Windows Installer 5.0 unter Windows Server 2012, Windows 8, Windows Server 2008 R2 oder Windows 7. Informationen zum mindestens erforderlichen Windows Service Pack für eine Windows Installer-Version finden Sie unter Windows Installer – Laufzeitanforderungen.
Zielplattform	Windows
Kopfzeile	msi.h
Bibliothek	Msi.lib
DLL	Msi.dll