MsiProvideComponentA-Funktion (msi.h)

Artikel
08/24/2023

Die MsiProvideComponent-Funktion gibt den vollständigen Komponentenpfad zurück und führt jede erforderliche Installation aus. Diese Funktion fordert bei Bedarf zur Quelle auf und erhöht die Nutzungsanzahl für das Feature.

Syntax

UINT MsiProvideComponentA(
  [in]      LPCSTR  szProduct,
  [in]      LPCSTR  szFeature,
  [in]      LPCSTR  szComponent,
  [in]      DWORD   dwInstallMode,
  [out]     LPSTR   lpPathBuf,
  [in, out] LPDWORD pcchPathBuf
);

Parameter

[in] szProduct

Gibt den Produktcode für das Produkt an, das das Feature mit der erforderlichen Komponente enthält.

[in] szFeature

Gibt die Feature-ID des Features mit der erforderlichen Komponente an.

[in] szComponent

Gibt den Komponentencode der erforderlichen Komponente an.

[in] dwInstallMode

Definiert den Installationsmodus. Dieser Parameter kann einen der folgenden Werte annehmen.

Wert	Bedeutung
INSTALLMODE_DEFAULT	Stellt die Komponente bereit und führt alle für die Bereitstellung der Komponente erforderlichen Installationen aus. Wenn die Schlüsseldatei einer Komponente im angeforderten Feature oder einem übergeordneten Feature fehlt, installieren Sie das Feature mithilfe von MsiReinstallFeature mit den folgenden Flagbits neu: REINSTALLMODE_FILEMISSING, REINSTALLMODE_FILEOLDERVERSION, REINSTALLMODE_FILEVERIFY, REINSTALLMODE_MACHINEDATA, REINSTALLMODE_USERDATA und REINSTALLMODE_SHORTCUT.
INSTALLMODE_EXISTING	Stellt die Komponente nur bereit, wenn das Feature vorhanden ist. Andernfalls wird ERROR_FILE_NOT_FOUND zurückgegeben. Mit diesem Modus wird überprüft, ob die Schlüsseldatei der Komponente vorhanden ist.
INSTALLMODE_NODETECTION	Stellt die Komponente nur bereit, wenn das Feature vorhanden ist. Andernfalls wird ERROR_FILE_NOT_FOUND zurückgegeben. Dieser Modus überprüft nur, ob die Komponente registriert ist, und überprüft nicht, ob die Schlüsseldatei der Komponente vorhanden ist.
Kombination der REINSTALLMODE-Flags	Rufen Sie MsiReinstallFeature auf, um das Feature mit diesem Parameter für den dwReinstallMode-Parameter neu zu installieren, und geben Sie dann die Komponente an.
INSTALLMODE_NOSOURCERESOLUTION	Geben Sie die Komponente nur an, wenn der Installationsstatus des Features INSTALLSTATE_LOCAL ist. Wenn der Installationsstatus des Features INSTALLSTATE_SOURCE ist, geben Sie ERROR_INSTALL_SOURCE_ABSENT zurück. Andernfalls wird ERROR_FILE_NOT_FOUND zurückgegeben. Dieser Modus überprüft nur, ob die Komponente registriert ist, und überprüft nicht, ob die Schlüsseldatei vorhanden ist.

[out] lpPathBuf

Zeiger auf eine Variable, die den Pfad zur Komponente empfängt. Dieser Parameter kann NULL sein.

[in, out] pcchPathBuf

Zeiger auf eine Variable, die die Größe des Puffers in Zeichen angibt, auf den der lpPathBuf-Parameter verweist. Bei der Eingabe ist dies die vollständige Größe des Puffers, einschließlich eines Leerzeichens für ein beendendes NULL-Zeichen. Wenn der übergebene Puffer zu klein ist, enthält die zurückgegebene Anzahl nicht das beendende NULL-Zeichen.

Wenn lpPathBuf NULL ist, kann pcchBuf NULL sein.

Rückgabewert

Wert	Bedeutung
ERROR_BAD_CONFIGURATION	Die Konfigurationsdaten sind beschädigt.
ERROR_FILE_NOT_FOUND	Das Feature ist nicht vorhanden oder nicht vorhanden. Dieser Fehler wird für dwInstallMode = INSTALLMODE_EXISTING zurückgegeben.
ERROR_INSTALL_FAILURE	Fehler bei der Installation.
ERROR_INSTALL_NOTUSED	Die angeforderte Komponente ist auf dem Computer deaktiviert.
ERROR_INVALID_PARAMETER	Es wurde ein ungültiger Parameter an die Funktion übergeben.
ERROR_SUCCESS	Die Funktion wurde erfolgreich abgeschlossen.
ERROR_UNKNOWN_FEATURE	Die Feature-ID identifiziert kein bekanntes Feature.
ERROR_UNKNOWN_PRODUCT	Der Produktcode identifiziert kein bekanntes Produkt.
INSTALLSTATE_UNKNOWN	Ein nicht erkanntes Produkt oder ein Featurename wurde an die Funktion übergeben.
ERROR_MORE_DATA	Der Pufferüberlauf wird zurückgegeben.
ERROR_INSTALL_SOURCE_ABSENT	Eine Quelle kann nicht erkannt werden.

Weitere Informationen finden Sie unter Angezeigte Fehlermeldungen.

Hinweise

Nach erfolgreicher Ausführung der MsiProvideComponent-Funktion enthält der pcchPathBuf-Parameter die Länge der Zeichenfolge in lpPathBuf.

Die MsiProvideComponent-Funktion kombiniert die Funktionalität von MsiUseFeature, MsiConfigureFeature und MsiGetComponentPath. Sie können die MsiProvideComponent-Funktion verwenden, um die Aufrufsequenz zu vereinfachen. Da diese Funktion jedoch die Nutzungsanzahl erhöht, verwenden Sie sie mit Vorsicht, um ungenaue Nutzungszahlen zu verhindern. Die MsiProvideComponent-Funktion bietet auch weniger Flexibilität als die Reihe einzelner Aufrufe.

Wenn die Anwendung nach einer unerwarteten Situation wiederhergestellt wird, hat die Anwendung wahrscheinlich bereits MsiUseFeature aufgerufen und die Nutzungsanzahl erhöht. In diesem Fall sollte die Anwendung MsiConfigureFeature anstelle von MsiProvideComponent aufrufen, um zu vermeiden, dass die Anzahl erneut erhöht wird.

Die Option INSTALLMODE_EXISTING kann nicht in Kombination mit dem REINSTALLMODE-Flag verwendet werden.

Features mit Komponenten, die eine beschädigte Datei oder die falsche Version einer Datei enthalten, müssen vom Benutzer oder durch den Aufruf der Anwendung MsiReinstallFeature explizit neu installiert werden.

Hinweis

Der msi.h-Header definiert MsiProvideComponent 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. Windows Installer unter Windows Server 2003 oder Windows XP. 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

Weitere Informationen

Komponentenspezifische Funktionen

Installationen mit mehreren Paketen