MsiEnumComponentsExA-Funktion (msi.h)

Artikel
11/20/2024

Die MsiEnumComponentsEx installierten Komponenten aufzählt. Die Funktion ruft den Komponentencode für eine Komponente jedes Mal ab, wenn sie aufgerufen wird. Der Komponentencode ist die Zeichenfolgen-GUID, die für die Komponente, Version und Sprache eindeutig ist.

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

Syntax

UINT MsiEnumComponentsExA(
  [in, optional]  LPCSTR            szUserSid,
  [in]            DWORD             dwContext,
  [in]            DWORD             dwIndex,
  [out, optional] CHAR [39]         szInstalledComponentCode,
  [out, optional] MSIINSTALLCONTEXT *pdwInstalledContext,
  [out, optional] LPSTR             szSid,
  [in, out]       LPDWORD           pcchSid
);

Parameter

[in, optional] szUserSid

Eine mit Null beendete Zeichenfolge, die einen Sicherheitsbezeichner (SID) enthält. Die Aufzählung der installierten Komponenten erstreckt sich auf Benutzer, die von dieser SID identifiziert wurden. Die spezielle SID-Zeichenfolge s-1-1-0 (Jeder) gibt eine Enumeration aller installierten Komponenten für alle Produkte aller Benutzer im System an. Ein anderer SID-Wert als s-1-1-0 gibt eine Benutzer-SID für einen bestimmten Benutzer an und schränkt die Enumeration auf Instanzen von Anwendungen ein, die vom angegebenen Benutzer installiert wurden.

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

Die spezielle SID-Zeichenfolge s-1-5-18 (System) kann nicht zum Aufzählen von Anwendungen verwendet werden, die im Installationskontext pro Computer installiert sind. Durch Festlegen des SID-Werts auf s-1-5-18 wird ERROR_INVALID_PARAMETER zurückgegeben. Wenn dwContext- nur auf MSIINSTALLCONTEXT_MACHINE festgelegt ist, muss szUserSid-NULL-sein.

[in] dwContext

Ein Flag, das die Enumeration der installierten Komponente auf Instanzen von Produkten beschränkt, die im angegebenen Installationskontext installiert sind. Die Enumeration enthält nur Produktinstanzen, die von den von szUserSidangegebenen Benutzern installiert wurden.

Flagge	Bedeutung
MSIINSTALLCONTEXT_USERMANAGED 1	Schließen Sie Produkte ein, die im vom Benutzer verwalteten Installationskontext vorhanden sind.
MSIINSTALLCONTEXT_USERUNMANAGED 2	Schließen Sie Produkte ein, die im Benutzer-nicht verwalteten Installationskontext vorhanden sind.
MSIINSTALLCONTEXT_MACHINE 4	Schließen Sie Produkte ein, die im Installationskontext pro Computer vorhanden sind. Wenn dwInstallContext- nur auf MSIINSTALLCONTEXT_MACHINE festgelegt ist, muss der szUserSID Parameter NULL-sein.

[in] dwIndex

Gibt den Index der abzurufenden Komponente an. Dieser Parameter muss null (0) für den ersten Aufruf von MsiEnumComponentsEx--Funktion 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. Komponenten sind nicht sortiert und können von der Funktion in beliebiger Reihenfolge zurückgegeben werden.

[out, optional] szInstalledComponentCode

Ein Ausgabepuffer, der die Komponentencode-GUID für die installierte Komponente empfängt. Die Länge des Puffers sollte groß genug sein, um einen Null-beendeten Zeichenfolgenwert zu enthalten, der den Komponentencode enthält. Die ersten 38 TCHAR- Zeichen empfangen die GUID für die Komponente, und das 39. Zeichen empfängt ein endendes NULL-Zeichen.

[out, optional] pdwInstalledContext

Ein Flag, das dem Installationskontext die Anwendung gibt, die die Komponente installiert hat.

Flagge	Bedeutung
MSIINSTALLCONTEXT_USERMANAGED 1	Die Anwendung wird im vom Benutzer verwalteten Installationskontext installiert.
MSIINSTALLCONTEXT_USERUNMANAGED 2	Die Anwendung wird im Benutzer-nicht verwalteten Installationskontext installiert.
MSIINSTALLCONTEXT_MACHINE 4	Die Anwendung wird im Installationskontext pro Computer installiert.

[out, optional] szSid

Empfängt die Sicherheits-ID (SID), die den Benutzer identifiziert, der die Anwendung installiert hat, die die Komponente besitzt. Der Speicherort empfängt eine leere Zeichenfolge, wenn diese Instanz der Anwendung in einem Installationskontext pro Computer installiert wird.

Die Länge des Puffers an dieser Position sollte groß genug sein, um einen null-beendeten Zeichenfolgenwert mit der SID zu speichern. Wenn der Puffer zu klein ist, gibt die Funktion ERROR_MORE_DATA zurück und die Position, auf die durch pcchSid verwiesen wird, erhält die Anzahl der TCHAR- in der SID, nicht einschließlich des endenden NULL-Zeichens.

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 die Position empfängt die Anzahl der TCHAR- in der SID, nicht einschließlich des endenden Nullzeichens. Die Funktion kann dann erneut aufgerufen werden, um den Wert abzurufen, wobei die größe des szSid Puffer groß genug ist, um *pcchSid + 1 Zeichen zu enthalten.

SID-Typ	Bedeutung
Leere Zeichenfolge	Die Anwendung wird in einem Installationskontext pro Computer installiert.
Benutzer-SID-	Die SID für den Benutzer im System, das die Anwendung installiert hat.

[in, out] pcchSid

Empfängt die Anzahl der TCHAR- in der SID, nicht einschließlich des endenden Nullzeichens. Wenn die Funktion zurückgegeben wird, 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 beenden kann, auf den szSidverweist. Die Größe wird als Die Anzahl der TCHAR- im angeforderten Wert zurückgegeben, nicht einschließlich des endenden Nullzeichens.

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

Rückgabewert

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

Rückgabecode	Beschreibung
ERROR_ACCESS_DENIED	Administratorrechte müssen Komponenten von Anwendungen aufzählen, die von anderen Benutzern als dem aktuellen Benutzer installiert wurden.
ERROR_BAD_CONFIGURATION	Die Konfigurationsdaten sind beschädigt.
ERROR_INVALID_PARAMETER	An die Funktion wird ein ungültiger Parameter übergeben.
ERROR_NO_MORE_ITEMS	Es gibt keine weiteren Komponenten, die aufgezählt werden sollen.
ERROR_SUCCESS	Die Funktion war erfolgreich.
ERROR_MORE_DATA	Der bereitgestellte Puffer war zu klein, um den gesamten Wert zu halten.
ERROR_FUNCTION_FAILED	Fehler bei der Funktion.

Bemerkungen

Anmerkung

Der msi.h-Header definiert MsiEnumComponentsEx 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 Code, der nicht codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows Installer 5.0 unter Windows Server 2012, Windows 8, Windows Server 2008 R2 oder Windows 7. Informationen zum mindestens von einer Windows Installer-Version erforderlichen Windows-Service Pack finden Sie unter den Windows Installer-Run-Time Anforderungen.
Zielplattform-	Fenster
Header-	msi.h
Library	Msi.lib
DLL-	Msi.dll

Freigeben über