MsiEnumPatchesExA-Funktion (msi.h)

Artikel
08/24/2023

Die MsiEnumPatchesEx-Funktion listet alle Patches in einem bestimmten Kontext oder in allen Kontexten auf. Patches, die bereits auf Produkte angewendet wurden, werden aufgelistet. Patches, die registriert, aber noch nicht auf Produkte angewendet wurden, werden ebenfalls aufgezählt.

Syntax

UINT MsiEnumPatchesExA(
  [in, optional]      LPCSTR            szProductCode,
  [in, optional]      LPCSTR            szUserSid,
  [in]                DWORD             dwContext,
  [in]                DWORD             dwFilter,
  [in]                DWORD             dwIndex,
  [out, optional]     CHAR [39]         szPatchCode,
  [out, optional]     CHAR [39]         szTargetProductCode,
  [out, optional]     MSIINSTALLCONTEXT *pdwTargetProductContext,
  [out, optional]     LPSTR             szTargetUserSid,
  [in, out, optional] LPDWORD           pcchTargetUserSid
);

Parameter

[in, optional] szProductCode

Eine NULL-Zeichenfolge, die die ProductCode-GUID des Produkts angibt, dessen Patches aufgezählt werden. Wenn nicht NULL, ist die Patchenumeration auf Instanzen dieses Produkts unter dem Benutzer und kontext beschränkt, der durch szUserSid und dwContext angegeben wird. Wenn NULL, werden die Patches für alle Produkte im angegebenen Kontext aufgezählt.

[in, optional] szUserSid

Eine null-endende Zeichenfolge, die eine Sicherheits-ID (SID) angibt, die den Kontext der Enumeration einschränkt. Die spezielle SID-Zeichenfolge "S-1-1-0" (Jeder) gibt die Enumeration für alle Benutzer im System an. Ein anderer SID-Wert als "S-1-1-0" wird als Benutzer-SID betrachtet und beschränkt die Enumeration auf diesen Benutzer. Beim Aufzählen für einen anderen Benutzer als den aktuellen Benutzer werden alle Patches, die in einem benutzerspezifischen nicht verwalteten Kontext mit einer Version angewendet wurden, die kleiner als Windows Installer-Version 3.0 ist, nicht aufgezählt. Dieser Parameter kann auf NULL festgelegt werden, um den aktuellen Benutzer anzugeben.

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

Hinweis Die spezielle SID-Zeichenfolge "S-1-5-18" (System) kann nicht zum Aufzählen von Produkten oder Patches verwendet werden, die pro Computer installiert sind. Durch Festlegen des SID-Werts auf "S-1-5-18" wird ERROR_INVALID_PARAMETER zurückgegeben. Wenn dwContext auf nur MSIINSTALLCONTEXT_MACHINE festgelegt ist, muss szUserSidNULL sein.

[in] dwContext

Beschränkt die Enumeration auf einen oder eine Kombination von Kontexten. Bei diesem Parameter kann es sich um einen beliebigen oder eine Kombination der folgenden Werte handeln.

Kontext	Bedeutung
MSIINSTALLCONTEXT_USERMANAGED	Die Enumeration, die auf alle benutzerspezifischen verwalteten Installationen für die Benutzer erweitert wird, die szUserSid angibt. Eine ungültige SID gibt keine Elemente zurück.
MSIINSTALLCONTEXT_USERUNMANAGED	In diesem Kontext werden nur Patches, die mit Windows Installer Version 3.0 installiert sind, für Benutzer aufgelistet, die nicht der aktuelle Benutzer sind. Für den aktuellen Benutzer listet die Funktion alle installierten und neuen Patches auf. Eine ungültige SID für szUserSid gibt keine Elemente zurück.
MSIINSTALLCONTEXT_MACHINE	Eine Enumeration, die auf alle Computerinstallationen erweitert wird. Wenn dwContext auf nur MSIINSTALLCONTEXT_MACHINE festgelegt ist, muss der szUserSid-ParameterNULL sein.

[in] dwFilter

Der Filter für die Enumeration. Bei diesem Parameter kann es sich um einen oder eine Kombination der folgenden Parameter handelt.

Filter	Bedeutung
MSIPATCHSTATE_APPLIED 1	Die Enumeration enthält angewendete Patches. Die Enumeration enthält keine abgelösten oder veralteten Patches.
MSIPATCHSTATE_SUPERSEDED 2	Die Enumeration enthält Patches, die als abgelöst markiert sind.
MSIPATCHSTATE_OBSOLETED 4	Die Enumeration enthält Patches, die als veraltet markiert sind.
MSIPATCHSTATE_REGISTERED 8	Die Enumeration enthält Patches, die registriert, aber noch nicht angewendet wurden. Die MsiSourceListAddSourceEx-Funktion kann neue Patches registrieren. Hinweis Patches, die für andere Benutzer als den aktuellen Benutzer registriert und im benutzerspezifischen nicht verwalteten Kontext angewendet werden, werden nicht aufgezählt.
MSIPATCHSTATE_ALL 15	Die Enumeration enthält alle angewendeten, veralteten, abgelösten und registrierten Patches.

[in] dwIndex

Der Index des abzurufenden Patches. Dieser Parameter muss für den ersten Aufruf der MsiEnumPatchesEx-Funktion null sein und dann für nachfolgende Aufrufe inkrementiert werden. Der dwIndex-Parameter sollte nur erhöht werden, wenn der vorherige Aufruf ERROR_SUCCESS zurückgegeben wurde.

[out, optional] szPatchCode

Ein Ausgabepuffer, der die GUID des aufgezählten Patches enthält. Der Puffer sollte groß genug sein, um die GUID aufzunehmen. Dieser Parameter kann NULL sein.

[out, optional] szTargetProductCode

Ein Ausgabepuffer, der die ProductCode-GUID des Produkts enthält, das diesen Patch empfängt. Der Puffer sollte groß genug sein, um die GUID aufzunehmen. Dieser Parameter kann NULL sein.

[out, optional] pdwTargetProductContext

Gibt den Kontext des Aufzählungspatches zurück. Der Ausgabewert kann MSIINSTALLCONTEXT_USERMANAGED, MSIINSTALLCONTEXT_USERUNMANAGED oder MSIINSTALLCONTEXT_MACHINE sein. Dieser Parameter kann NULL sein.

[out, optional] szTargetUserSid

Ein Ausgabepuffer, der die Zeichenfolgen-SID des Kontos empfängt, unter dem dieser Patch instance vorhanden ist. Dieser Puffer gibt eine leere Zeichenfolge für einen Computerkontext zurück.

Dieser Puffer sollte groß genug sein, um die SID zu enthalten. Wenn der Puffer zu klein ist, gibt die Funktion ERROR_MORE_DATA zurück und legt *pcchTargetUserSid auf die Anzahl von TCHAR im Wert fest, ohne das abschließende NULL-Zeichen.

Wenn szTargetUserSid auf NULL und pcchTargetUserSid auf einen gültigen Zeiger festgelegt ist, gibt die Funktion ERROR_SUCCESS zurück und legt *pcchTargetUserSid auf die Anzahl von TCHAR im Wert fest, ohne das abschließende NULL-Zeichen . Die Funktion kann dann erneut aufgerufen werden, um den Wert abzurufen, wobei der Puffer szTargetUserSid groß genug ist, um *pcchTargetUserSid + 1 Zeichen zu enthalten.

Wenn szTargetUserSid und pcchTargetUserSid auf NULL festgelegt sind, gibt die Funktion ERROR_SUCCESS zurück, wenn der Wert vorhanden ist, ohne den Wert abzurufen.

[in, out, optional] pcchTargetUserSid

Ein Zeiger auf eine Variable, die die Anzahl von TCHAR im szTargetUserSid-Puffer angibt. Wenn die Funktion zurückgibt, wird dieser Parameter auf die Größe des angeforderten Werts festgelegt, unabhängig davon, ob die Funktion den Wert in den angegebenen Puffer kopiert oder nicht. Die Größe wird als Anzahl von TCHAR im angeforderten Wert zurückgegeben, ohne das abschließende NULL-Zeichen.

Dieser Parameter kann nur auf NULL festgelegt werden, wenn szTargetUserSid ebenfalls NULL ist. Andernfalls gibt die Funktion ERROR_INVALID_PARAMETER zurück.

Rückgabewert

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

Rückgabecode	Beschreibung
ERROR_ACCESS_DENIED	Die Funktion versucht nicht, auf eine Ressource mit unzureichenden Berechtigungen zuzugreifen.
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 Patches, die aufgelistet werden müssen.
ERROR_SUCCESS	Der Patch wurde erfolgreich aufgelistet.
ERROR_UNKNOWN_PRODUCT	Das produkt, das szProduct angibt, wird in den angegebenen Kontexten nicht auf dem Computer installiert.
ERROR_MORE_DATA	Dies wird zurückgegeben, wenn pcchTargetUserSid auf eine Puffergröße verweist, die kleiner ist als zum Kopieren der SID erforderlich ist. In diesem Fall kann der Benutzer den Puffer reparieren und MsiEnumPatchesEx erneut für denselben Indexwert aufrufen.

Hinweise

Nicht-Administratoren können Patches nur innerhalb ihrer Sichtbarkeit auflisten. Administratoren können Patches für andere Benutzerkontexte auflisten.

Hinweis

Der msi.h-Header definiert MsiEnumPatchesEx 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

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Installer 5.0 unter Windows Server 2012, Windows 8, Windows Server 2008 R2 oder Windows 7. Windows Installer 4.0 oder Windows Installer 4.5 unter Windows Server 2008 oder Windows Vista. Informationen zum minimal 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

Weitere Informationen

Installationskontext

MsiSourceListAddSourceEx

In Windows Installer 2.0 und früher nicht unterstützt

ProductCode