VerFindFileW-Funktion (winver.h)

Artikel
03/04/2024

Bestimmt, wo eine Datei installiert werden soll, basierend darauf, ob eine andere Version der Datei im System gefunden wird. Die Werte, die VerFindFile in den angegebenen Puffern zurückgibt, werden in einem nachfolgenden Aufruf der VerInstallFile-Funktion verwendet.

Syntax

DWORD VerFindFileW(
  [in]           DWORD   uFlags,
  [in]           LPCWSTR szFileName,
  [in, optional] LPCWSTR szWinDir,
  [in]           LPCWSTR szAppDir,
  [out]          LPWSTR  szCurDir,
  [in, out]      PUINT   puCurDirLen,
  [out]          LPWSTR  szDestDir,
  [in, out]      PUINT   puDestDirLen
);

Parameter

[in] uFlags

Art: DWORD

Dieser Parameter kann der folgende Wert sein. Alle anderen Bits sind reserviert.

Wert	Bedeutung
VFFF_ISSHAREDFILE 0x0001	Die Quelldatei kann von mehreren Anwendungen gemeinsam genutzt werden. Eine Anwendung kann anhand dieser Informationen bestimmen, wohin die Datei kopiert werden soll.

[in] szFileName

Typ: LPCTSTR

Der Name der zu installierenden Datei. Schließen Sie nur den Dateinamen und die Erweiterung ein, keinen Pfad.

[in, optional] szWinDir

Typ: LPCTSTR

Das Verzeichnis, in dem Windows ausgeführt wird oder ausgeführt wird. Diese Zeichenfolge wird von der GetWindowsDirectory-Funktion zurückgegeben.

[in] szAppDir

Typ: LPCTSTR

Das Verzeichnis, in dem das Installationsprogramm eine Reihe verwandter Dateien installiert. Wenn das Installationsprogramm eine Anwendung installiert, ist dies das Verzeichnis, in dem sich die Anwendung befindet. Dieser Parameter verweist auch auf das aktuelle Verzeichnis der Anwendung, sofern nichts anderes angegeben ist.

[out] szCurDir

Typ: LPWSTR

Ein Puffer, der den Pfad zu einer aktuellen Version der zu installierenden Datei empfängt. Der Pfad ist eine Zeichenfolge, die mit Null beendet wird. Wenn keine aktuelle Version installiert ist, enthält der Puffer eine Zeichenfolge der Länge Null. Der Puffer sollte mindestens _MAX_PATH Zeichen lang sein, obwohl dies nicht erforderlich ist.

[in, out] puCurDirLen

Typ: PUINT

Die Länge des szCurDir-Puffers . Dieser Zeiger darf nicht NULL sein.

Wenn die Funktion zurückgibt, enthält lpuCurDirLen die Größe der in szCurDir zurückgegebenen Daten in Zeichen, einschließlich des abschließenden NULL-Zeichens. Wenn der Puffer zu klein ist, um alle Daten zu enthalten, entspricht lpuCurDirLen der Größe des Puffers, der zum Speichern des Pfads erforderlich ist.

[out] szDestDir

Typ: LPTSTR

Ein Puffer, der den Pfad zum von VerFindFile empfohlenen Installationsspeicherort empfängt. Der Pfad ist eine Zeichenfolge, die mit Null beendet wird. Der Puffer sollte mindestens _MAX_PATH Zeichen lang sein, obwohl dies nicht erforderlich ist.

[in, out] puDestDirLen

Typ: PUINT

Ein Zeiger auf eine Variable, die die Länge des szDestDir-Puffers angibt. Dieser Zeiger darf nicht NULL sein.

Wenn die Funktion zurückgibt, enthält lpuDestDirLen die Größe der in szDestDir zurückgegebenen Daten in Zeichen, einschließlich des abschließenden NULL-Zeichens. Wenn der Puffer zu klein ist, um alle Daten zu enthalten, ist lpuDestDirLen die Größe des Puffers, der zum Speichern des Pfads erforderlich ist.

Rückgabewert

Art: DWORD

Der Rückgabewert ist eine Bitmaske, die die status der Datei angibt. Er kann einen der folgenden Werte annehmen. Alle anderen Werte sind reserviert.

Rückgabecode/-wert	BESCHREIBUNG
VFF_CURNEDEST 0x0001	Die aktuell installierte Version der Datei befindet sich nicht im empfohlenen Ziel.
VFF_FILEINUSE 0x0002	Das System verwendet die aktuell installierte Version der Datei. Daher kann die Datei nicht überschrieben oder gelöscht werden.
VFF_BUFFTOOSMALL 0x0004	Mindestens einer der Puffer war zu klein, um die entsprechende Zeichenfolge zu enthalten. Eine Anwendung sollte die Ausgabepuffer überprüfen, um zu ermitteln, welcher Puffer zu klein war.

Hinweise

Diese Funktion funktioniert für 16-, 32- und 64-Bit-Dateibilder.

VerFindFile sucht mithilfe der OpenFile-Funktion nach einer Kopie der angegebenen Datei. Es bestimmt jedoch das Systemverzeichnis aus dem angegebenen Windows-Verzeichnis oder durchsucht den Pfad.

Wenn der dwFlags-Parameter angibt, dass die Datei für diese Anwendung privat ist (nicht VFFF_ISSHAREDFILE), empfiehlt VerFindFile , die Datei im Verzeichnis der Anwendung zu installieren. Andernfalls empfiehlt die Funktion, wenn auf dem System eine freigegebene Kopie des Systems ausgeführt wird, die Datei im Windows-Verzeichnis zu installieren. Wenn auf dem System eine private Kopie des Systems ausgeführt wird, empfiehlt die Funktion, die Datei im Systemverzeichnis zu installieren.

Hinweis

Der winver.h-Header definiert VerFindFile 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
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winver.h (windows.h einschließen)
Bibliothek	Version.lib
DLL	Api-ms-win-core-version-l1-1-0.dll