SetupCopyErrorA-Funktion (setupapi.h)

Artikel
03/04/2024

[Diese Funktion ist für die Verwendung in den betriebssystemen verfügbar, die im Abschnitt "Anforderungen" angegeben sind. Es kann in nachfolgenden Versionen geändert oder entfernt werden. SetupAPI sollte nicht mehr zum Installieren von Anwendungen verwendet werden. Verwenden Sie stattdessen den Windows Installer zum Entwickeln von Installationsprogrammen für Anwendungen. SetupAPI wird weiterhin zum Installieren von Gerätetreibern verwendet.]

Die SetupCopyError-Funktion generiert ein Dialogfeld, um einen Benutzer über einen Kopierdateifehler zu benachrichtigen.

Syntax

WINSETUPAPI UINT SetupCopyErrorA(
  [in]      HWND   hwndParent,
  [in]      PCSTR  DialogTitle,
  [in]      PCSTR  DiskName,
  [in]      PCSTR  PathToSource,
  [in]      PCSTR  SourceFile,
  [in]      PCSTR  TargetPathFile,
  [out]     UINT   Win32ErrorCode,
  [in]      DWORD  Style,
  [in, out] PSTR   PathBuffer,
  [in]      DWORD  PathBufferSize,
  [in, out] PDWORD PathRequiredSize
);

Parameter

[in] hwndParent

Das Handle zum übergeordneten Fenster für dieses Dialogfeld.

[in] DialogTitle

Ein optionaler Zeiger auf eine null-endende Zeichenfolge, die den Dialogfeldtitel angibt.

Dieser Parameter kann NULL sein. Wenn dieser Parameter NULL ist, wird der Standardtitel "Kopierfehler" (lokalisiert in der Systemsprache) verwendet.

[in] DiskName

Ein optionaler Zeiger auf eine NULL-endende Zeichenfolge, die den Namen des einzufügenden Datenträgers angibt.

Dieser Parameter kann NULL sein. Wenn dieser Parameter NULL ist, wird der Standardname "(Unbekannt)" (lokalisiert in der Systemsprache) verwendet.

[in] PathToSource

Ein Zeiger auf die Pfadkomponente der Quelldatei, bei der ein Vorgang fehlschlägt, z. B. F:\x86.

Verwenden Sie eine NULL-endende Zeichenfolge.

[in] SourceFile

Ein Zeiger auf eine NULL-endende Zeichenfolge, die den Dateinamenteil der Datei angibt, bei dem ein Vorgang fehlschlägt.

Verwenden Sie eine NULL-endende Zeichenfolge. Dieser Dateiname wird angezeigt, wenn der Benutzer auf die Schaltflächen Details oder Durchsuchen klickt. Die SetupCopyError-Funktion sucht nach der Datei, die ihre komprimierten Formularnamen verwendet. Daher können Sie cmd.exe übergeben und sich keine Sorgen machen, dass die Datei tatsächlich als cmd.ex_ auf dem Quellmedium vorhanden ist.

[in] TargetPathFile

Ein optionaler Zeiger auf eine NULL-endende Zeichenfolge, die den vollständigen Pfad der Zieldatei für Umbenennungs- und Kopiervorgänge angibt.

Verwenden Sie eine NULL-endende Zeichenfolge. Dieser Parameter kann NULL sein. Wenn TargetPathFile nicht angegeben ist, wird "(Unbekannt)" (lokalisiert in der Systemsprache) verwendet.

[out] Win32ErrorCode

Wenn ein Fehler auftritt, ist dieser Member der Systemfehlercode.

Wenn kein Fehler auftritt, wird er NO_ERROR.

[in] Style

Die Flags, die die Anzeigeformatierung und das Verhalten eines Dialogfelds steuern.

Dieser Parameter kann eines der folgenden Flags sein.

IDF_NOBROWSE

Die Option "Durchsuchen" wird nicht angezeigt.

IDF_NOSKIP

Zeigen Sie die Option Datei überspringen nicht an.

IDF_NODETAILS

Zeigen Sie die Detailoption nicht an.

Wenn dieses Flag festgelegt ist, können die Parameter TargetPathFile und Win32ErrorCode weggelassen werden.

IDF_NOCOMPRESSED

Suchen Sie nicht nach komprimierten Versionen der Quelldatei.

IDF_OEMDISK

Die Vorgangsquelle ist ein Datenträger, den ein Hardwarehersteller bereitstellt.

IDF_NOBEEP

Verhindert, dass das Dialogfeld piept, um die Aufmerksamkeit des Benutzers zu erhalten, wenn es zum ersten Mal angezeigt wird.

IDF_NOFOREGROUND

Verhindert, dass das Dialogfeld zum Vordergrundfenster wird.

IDF_WARNIFSKIP

Warnt den Benutzer, dass sich das Überspringen einer Datei auf die Installation auswirken kann.

[in, out] PathBuffer

Ein optionaler Zeiger auf eine Variable, in der diese Funktion den Pfad (ohne dateinamen) des Speicherorts zurückgibt, den ein Benutzer im Dialogfeld angibt. Sie sollten eine NULL-endende Zeichenfolge verwenden.

Die NULL-Zeichenfolge darf die Größe des Zielpuffers nicht überschreiten. Um unzureichende Pufferfehler zu vermeiden, sollte PathBuffer mindestens MAX_PATH sein. Weitere Informationen finden Sie in diesem Thema im Abschnitt „Hinweise“.

[in] PathBufferSize

Die Größe des Puffers, auf den PathBuffer in Zeichen zeigt.

Die Puffergröße sollte mindestens MAX_PATH Zeichen sein, einschließlich des NULL-Abschlusszeichens .

[in, out] PathRequiredSize

Ein optionaler Zeiger auf eine Variable, in der diese Funktion die erforderliche Puffergröße in Zeichen zurückgibt, einschließlich des NULL-Abschlusszeichens .

Rückgabewert

Die Funktion gibt einen der folgenden Werte zurück.

Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Wenn diese Funktion mit einem PathBuffer von NULL und einem PathBufferSize-Wert von 0 (Null) aufgerufen wird, fügt die Funktion die Puffergröße, die zum Speichern der angegebenen Daten erforderlich ist, in die Variable ein, auf die PathRequiredSize verweist.

Wenn die Funktion erfolgreich ist, wird der Rückgabewert NO_ERROR. Andernfalls ist der Rückgabewert einer der angegebenen Werte.

Um unzureichende Pufferfehler zu vermeiden, sollte ReturnBuffer mindestens MAX_PATH sein.

Hinweis

Der Setupapi.h-Header definiert SetupCopyError 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 XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	setupapi.h
Bibliothek	Setupapi.lib
DLL	Setupapi.dll