SHFILEOPSTRUCTA-Struktur (shellapi.h)
Enthält Informationen, die die SHFileOperation-Funktion zum Ausführen von Dateivorgängen verwendet.
Syntax
typedef struct _SHFILEOPSTRUCTA {
HWND hwnd;
UINT wFunc;
PCZZSTR pFrom;
PCZZSTR pTo;
FILEOP_FLAGS fFlags;
BOOL fAnyOperationsAborted;
LPVOID hNameMappings;
PCSTR lpszProgressTitle;
} SHFILEOPSTRUCTA, *LPSHFILEOPSTRUCTA;
Member
hwnd
Typ: HWND
Ein Fensterhandle zum Dialogfeld, um Informationen zum status des Dateivorgangs anzuzeigen.
wFunc
Typ: UINT
Ein Wert, der angibt, welcher Vorgang ausgeführt werden soll. Einer der folgenden Werte:
FO_COPY
Kopieren Sie die im pFrom-Element angegebenen Dateien an den speicherort, der im pTo-Element angegeben ist.
FO_DELETE
Löschen Sie die in pFrom angegebenen Dateien.
FO_MOVE
Verschieben Sie die in pFrom angegebenen Dateien an den in pTo angegebenen Speicherort.
FO_RENAME
Benennen Sie die in pFrom angegebene Datei um. Sie können dieses Flag nicht verwenden, um mehrere Dateien mit einem einzigen Funktionsaufruf umzubenennen. Verwenden Sie stattdessen FO_MOVE .
pFrom
Typ: PCZZTSTR
Standardmäßige MS-DOS-Platzhalterzeichen, z. B. "*", sind nur an der Position des Dateinamens zulässig. Die Verwendung eines Feldhalterzeichens an anderer Stelle in der Zeichenfolge führt zu unvorhersehbaren Ergebnissen.
Obwohl dieser Member als einzelne null-beendete Zeichenfolge deklariert wird, ist es tatsächlich ein Puffer, der mehrere Mit NULL-Trennzeichen getrennte Dateinamen enthalten kann. Jeder Dateiname wird durch ein einzelnes NULL-Zeichen beendet. Der letzte Dateiname wird mit einem doppelten NULL-Zeichen ("\0\0") beendet, um das Ende des Puffers anzugeben.
pTo
Typ: PCZZTSTR
Wie pFrom ist auch das pTo-Element eine double-NULL-Zeichenfolge, die auf die gleiche Weise behandelt wird. pTo muss jedoch die folgenden Spezifikationen erfüllen:
- Platzhalterzeichen werden nicht unterstützt.
- Kopier- und Verschiebevorgänge können Zielverzeichnisse angeben, die nicht vorhanden sind. In diesen Fällen versucht das System, sie zu erstellen, und zeigt normalerweise ein Dialogfeld an, um den Benutzer zu fragen, ob er das neue Verzeichnis erstellen möchte. Um dieses Dialogfeld zu unterdrücken und die Verzeichnisse unbeaufsichtigt zu erstellen, legen Sie das FOF_NOCONFIRMMKDIR-Flag in fFlags fest.
- Bei Kopier- und Verschieben-Vorgängen kann der Puffer mehrere Zieldateinamen enthalten, wenn der fFlags-MemberFOF_MULTIDESTFILES angibt.
- Packen Sie mehrere Namen in die pTo-Zeichenfolge auf die gleiche Weise wie für pFrom.
- Verwenden Sie vollqualifizierte Pfade. Die Verwendung relativer Pfade ist nicht verboten, kann aber unvorhersehbare Ergebnisse haben.
fFlags
Typ: FILEOP_FLAGS
Flags, die den Dateivorgang steuern. Dieses Element kann eine Kombination der folgenden Flags verwenden.
FOF_ALLOWUNDO
Behalten Sie nach Möglichkeit Informationen zum Rückgängigmachen bei.
Vor Windows Vista konnten Vorgänge nur aus demselben Prozess rückgängig gemacht werden, der den ursprünglichen Vorgang ausgeführt hat.
In Windows Vista- und höheren Systemen ist der Bereich des Rückgängigmachens eine Benutzersitzung. Jeder Prozess, der in der Benutzersitzung ausgeführt wird, kann einen anderen Vorgang rückgängigmachen. Der Rückgängigzustand wird im Explorer.exe-Prozess gespeichert, und solange dieser Prozess ausgeführt wird, kann er die Rückgängig-Funktionen koordinieren.
Wenn der Quelldateiparameter keine vollqualifizierten Pfad- und Dateinamen enthält, wird dieses Flag ignoriert.
FOF_CONFIRMMOUSE
Wird nicht verwendet.
FOF_FILESONLY
Führen Sie den Vorgang nur für Dateien (nicht für Ordner) aus, wenn ein Feldhalterdateiname (.) angegeben ist.
FOF_MULTIDESTFILES
Das pTo-Element gibt mehrere Zieldateien (eine für jede Quelldatei in pFrom) anstelle eines Verzeichnisses an, in dem alle Quelldateien abgelegt werden sollen.
FOF_NOCONFIRMATION
Antworten Sie mit Ja auf Alle für jedes angezeigte Dialogfeld.
FOF_NOCONFIRMMKDIR
Bitten Sie den Benutzer nicht, die Erstellung eines neuen Verzeichnisses zu bestätigen, wenn für den Vorgang eine Erstellung erforderlich ist.
FOF_NO_CONNECTED_ELEMENTS
Version 5.0. Verschieben Sie verbundene Dateien nicht als Gruppe. Verschieben Sie nur die angegebenen Dateien.
FOF_NOCOPYSECURITYATTRIBS
Version 4.71. Kopieren Sie die Sicherheitsattribute der Datei nicht. Die Zieldatei empfängt die Sicherheitsattribute ihres neuen Ordners.
FOF_NOERRORUI
Zeigen Sie dem Benutzer kein Dialogfeld an, wenn ein Fehler auftritt.
FOF_NORECURSEREPARSE
Wird nicht verwendet.
FOF_NORECURSION
Führen Sie den Vorgang nur im lokalen Verzeichnis aus. Arbeiten Sie nicht rekursiv in Unterverzeichnissen, was das Standardverhalten ist.
FOF_NO_UI
Windows Vista. Führen Sie den Vorgang unbeaufsichtigt aus, wobei dem Benutzer keine Benutzeroberfläche angezeigt wird. Dies entspricht FOF_SILENT | FOF_NOCONFIRMATION | FOF_NOERRORUI | FOF_NOCONFIRMMKDIR.
FOF_RENAMEONCOLLISION
Geben Sie der Datei, die mit einem neuen Namen in einem Verschiebungs-, Kopier- oder Umbenennungsvorgang betrieben wird, wenn am Ziel bereits eine Datei mit dem Zielnamen vorhanden ist.
FOF_SILENT
Zeigt kein Statusdialogfeld an.
FOF_SIMPLEPROGRESS
Zeigen Sie ein Statusdialogfeld an, aber keine einzelnen Dateinamen, während sie ausgeführt werden.
FOF_WANTMAPPINGHANDLE
Wenn FOF_RENAMEONCOLLISION angegeben ist und dateien umbenannt wurden, weisen Sie dem hNameMappings-Element ein Namenszuordnungsobjekt zu, das ihre alten und neuen Namen enthält. Dieses Objekt muss mithilfe von SHFreeNameMappings freigegeben werden, wenn es nicht mehr benötigt wird.
FOF_WANTNUKEWARNING
Version 5.0. Senden Sie eine Warnung, wenn eine Datei während eines Löschvorgangs dauerhaft zerstört wird, anstatt sie zu recyceln. Dieses Flag überschreibt teilweise FOF_NOCONFIRMATION.
fAnyOperationsAborted
Typ: BOOL
Wenn die Funktion zurückgibt, enthält dieser Member TRUE , wenn Dateivorgänge abgebrochen wurden, bevor sie abgeschlossen wurden. andernfalls FALSE. Ein Vorgang kann vom Benutzer manuell über die Benutzeroberfläche abgebrochen oder vom System automatisch abgebrochen werden, wenn die flags FOF_NOERRORUI oder FOF_NOCONFIRMATION festgelegt wurden.
hNameMappings
Typ: LPVOID
Wenn die Funktion zurückgegeben wird, enthält dieses Element ein Handle für ein Namenszuordnungsobjekt, das die alten und neuen Namen der umbenannten Dateien enthält. Dieser Member wird nur verwendet, wenn das fFlags-Element das flag FOF_WANTMAPPINGHANDLE enthält. Weitere Informationen finden Sie unter Hinweise.
lpszProgressTitle
Typ: PCTSTR
Ein Zeiger auf den Titel eines Statusdialogfelds. Dies ist eine NULL-endende Zeichenfolge. Dieses Element wird nur verwendet, wenn fFlags das flag FOF_SIMPLEPROGRESS enthält.
Hinweise
// WRONG
LPTSTR pszSource = L"C:\\Windows\\*";
// RIGHT
LPTSTR pszSource = L"C:\\Windows\\*\0";
Um die beiden endenden NULL-Zeichen zu berücksichtigen, müssen Sie Puffer erstellen, die groß genug sind, um MAX_PATH (die normalerweise das einzelne beendende NULL-Zeichen enthält) plus 1 zu speichern.
Es kann nicht überschätzt werden, dass Ihre Pfade immer vollständige Pfade sein sollten. Wenn die pFrom- oder pTo-Member nicht qualifizierte Namen sind, werden die aktuellen Verzeichnisse aus den globalen aktuellen Laufwerks- und Verzeichniseinstellungen übernommen, die von den Funktionen GetCurrentDirectory und SetCurrentDirectory verwaltet werden.
Wenn Sie keinen vollständigen Pfad angeben, werden die folgenden Fakten relevant:
- Das Fehlen eines Pfads vor einem Dateinamen bedeutet für SHFileOperation nicht, dass sich diese Datei im Stammverzeichnis des aktuellen Verzeichnisses befindet.
- Die PATH-Umgebungsvariable wird von SHFileOperation nicht verwendet, um einen gültigen Pfad zu bestimmen.
- ShFileOperation kann nicht verwendet werden, um das Verzeichnis zu verwenden, das das aktuelle Verzeichnis ist, wenn es mit der Ausführung beginnt. Das Verzeichnis, das als aktuelles Verzeichnis angesehen wird, ist prozessweit und kann von einem anderen Thread geändert werden, während der Vorgang ausgeführt wird. Wenn dies der Fall wäre, wären die Ergebnisse von SHFileOperation unvorhersehbar.
Wenn pFrom auf einen Dateinamen ohne vollständigen Pfad festgelegt ist, wird die Datei beim Löschen mit FO_DELETE nicht in den Papierkorb verschoben, auch wenn das flag FOF_ALLOWUNDO festgelegt ist. Sie müssen einen vollständigen Pfad angeben, um die Datei im Papierkorb zu löschen.
SHFileOperation schlägt für jeden Pfad mit dem Präfix "\?" fehl.
Es gibt zwei Versionen dieser Struktur, eine ANSI-Version (SHFILEOPSTRUCTA) und eine Unicode-Version (SHFILEOPSTRUCTW). Die Unicode-Version ist mit der ANSI-Version identisch, mit der Ausnahme, dass anstelle von ANSI-Zeichenfolgen (LPCSTR) Breitzeichenzeichenfolgen (LPCWSTR) verwendet werden. Unter Windows 98 und früher wird nur die ANSI-Version unterstützt. Unter Microsoft Windows NT 4.0 und höher werden sowohl die ANSI- als auch die Unicode-Versionen dieser Struktur unterstützt. SHFILEOPSTRUCTW und SHFILEOPTSTRUCTA sollten niemals direkt verwendet werden; die entsprechende Struktur wird vom Vorcompiler als SHFILEOPSTRUCT neu definiert, je nachdem, ob die Anwendung für ANSI oder Unicode kompiliert wird.
SHNAMEMAPPING verfügt über ähnliche ANSI- und Unicode-Versionen. Bei ANSI-Anwendungen zeigt hNameMappings auf ein int gefolgt von einem Array von ANSI SHNAMEMAPPING-Strukturen . Bei Unicode-Anwendungen zeigt hNameMappings auf ein int gefolgt von einem Array von Unicode-SHNAMEMAPPING-Strukturen . Unter Microsoft Windows NT 4.0 und höher gibt SHFileOperation jedoch immer ein Handle an einen Unicode-Satz von SHNAMEMAPPING-Strukturen zurück. Wenn Anwendungen mit allen Versionen von Windows funktionsfähig sein sollen, muss die Anwendung bedingten Code verwenden, um Namenszuordnungen zu verarbeiten. Beispiel:
x = SHFileOperation(&shop);
if (fWin9x)
HandleAnsiNameMappings(shop.hNameMappings);
else
HandleUnicodeNameMappings(shop.hNameMappings);
Behandeln Sie hNameMappings als Zeiger auf eine Struktur, deren Member ein UINT-Wert sind, gefolgt von einem Zeiger auf ein Array von SHNAMEMAPPING-Strukturen , wie in der Deklaration zu sehen:
struct HANDLETOMAPPINGS
{
UINT uNumberOfMappings; // Number of mappings in the array.
LPSHNAMEMAPPING lpSHNameMapping; // Pointer to the array of mappings.
};
Der UINT-Wert gibt die Anzahl der SHNAMEMAPPING-Strukturen im Array an. Jede SHNAMEMAPPING-Struktur enthält den alten und neuen Pfad für eine der umbenannten Dateien.
Hinweis
Der Shellapi.h-Header definiert SHFILEOPSTRUCT 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
| Unterstützte Mindestversion (Client) | Windows XP [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows 2000 Server [nur Desktop-Apps] |
| Kopfzeile | shellapi.h |
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für