VerFindFileA-Funktion (winver.h)

Artikel
11/20/2024

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

Syntax

DWORD VerFindFileA(
  [in]           DWORD  uFlags,
  [in]           LPCSTR szFileName,
  [in, optional] LPCSTR szWinDir,
  [in]           LPCSTR szAppDir,
  [out]          LPSTR  szCurDir,
  [in, out]      PUINT  puCurDirLen,
  [out]          LPSTR  szDestDir,
  [in, out]      PUINT  puDestDirLen
);

Parameter

[in] uFlags

Typ: DWORD-

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

Wert	Bedeutung
VFFF_ISSHAREDFILE 0x0001	Die Quelldatei kann von mehreren Anwendungen freigegeben werden. Eine Anwendung kann diese Informationen verwenden, um zu bestimmen, wo die Datei kopiert werden soll.

[in] szFileName

Typ: LPCTSTR-

Der Name der zu installierenden Datei. Fügen Sie nur den Dateinamen und die Erweiterung ein, nicht einen Pfad.

[in, optional] szWinDir

Typ: LPCTSTR-

Das Verzeichnis, in dem Windows ausgeführt wird oder ausgeführt wird. Diese Zeichenfolge wird von der funktion GetWindowsDirectory 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 nicht anders angegeben.

[out] szCurDir

Typ: LPWSTR-

Ein Puffer, der den Pfad zu einer aktuellen Version der installierten Datei empfängt. Der Pfad ist eine leere Zeichenfolge. Wenn keine aktuelle Version installiert ist, enthält der Puffer eine leere Zeichenfolge. 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ückgegeben wird, enthält lpuCurDirLen die Größe der in szCurDirzurückgegebenen Daten, einschließlich des endenden Nullzeichens. Wenn der Puffer zu klein ist, um alle Daten zu enthalten, ist lpuCurDirLen die Größe des Puffers, der zum Speichern des Pfads erforderlich ist.

[out] szDestDir

Typ: LPTSTR-

Ein Puffer, der den Pfad zum Installationsspeicherort empfängt, der von VerFindFile-empfohlen wird. Der Pfad ist eine leere Zeichenfolge. Der Puffer sollte mindestens _MAX_PATH Zeichen lang sein, obwohl dies nicht erforderlich ist.

[in, out] puDestDirLen

Typ: PUINT-

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

Wenn die Funktion zurückgegeben wird, enthält lpuDestDirLen die Größe der in szDestDirzurückgegebenen Daten in Zeichen, einschließlich des endenden Nullzeichens. Wenn der Puffer zu klein ist, um alle Daten zu enthalten, ist lpuDestDirLen die Größe des Puffers, der zum Speichern des Pfads benötigt wird.

Rückgabewert

Typ: DWORD-

Der Rückgabewert ist eine Bitmaske, die den Status der Datei angibt. Dabei kann es sich um einen oder mehrere der folgenden Werte handeln. Alle anderen Werte sind reserviert.

Zurückgeben von Code/Wert	Beschreibung
VFF_CURNEDEST 0x0001	Die aktuell installierte Version der Datei befindet sich nicht im empfohlenen Ziel.
VFF_FILEINUSE 0x0002	Das System verwendet die derzeit installierte Version der Datei; daher kann die Datei nicht überschrieben oder gelöscht werden.
VFF_BUFFTOOSMALL 0x0004	Mindestens ein 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.

Bemerkungen

Diese Funktion funktioniert in 16-, 32- und 64-Bit-Dateibildern.

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 Installation der Datei im Verzeichnis der Anwendung. Andernfalls empfiehlt die Funktion, wenn das System eine freigegebene Kopie des Systems ausführt, die Installation der Datei im Windows-Verzeichnis. Wenn das System eine private Kopie des Systems ausführt, empfiehlt die Funktion die Installation der Datei im Systemverzeichnis.

Anmerkung

Der winver.h-Header definiert VerFindFile als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante 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 2000 Professional [nur Desktop-Apps]
mindestens unterstützte Server-	Windows 2000 Server [nur Desktop-Apps]
Zielplattform-	Fenster
Header-	winver.h (enthalten Windows.h)
Library	Version.lib
DLL-	Api-ms-win-core-version-l1-1-0.dll