SHFILEOPSTRUCTA-Struktur (shellapi.h)

Enthält Informationen, die die SHFileOperation--Funktion zum Ausführen von Dateivorgängen verwendet.

Note As of Windows Vista, the use of the IFileOperation interface is recommended over this function.

 

Syntax

typedef struct _SHFILEOPSTRUCTA {
  HWND         hwnd;
  UINT         wFunc;
  PCZZSTR      pFrom;
  PCZZSTR      pTo;
  FILEOP_FLAGS fFlags;
  BOOL         fAnyOperationsAborted;
  LPVOID       hNameMappings;
  PCSTR        lpszProgressTitle;
} SHFILEOPSTRUCTA, *LPSHFILEOPSTRUCTA;

Angehörige

hwnd

Typ: HWND-

Ein Fensterhandle für das 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 Member angegebenen Dateien an den Speicherort, der im pTo Member angegeben ist.

FO_DELETE

Löschen Sie die in pFromangegebenen Dateien.

FO_MOVE

Verschieben Sie die in pFrom angegebenen Dateien an den speicherort, der in pTo-angegeben ist.

FO_RENAME

Benennen Sie die in pFromangegebene Datei um. Sie können dieses Flag nicht verwenden, um mehrere Dateien mit einem einzelnen Funktionsaufruf umzubenennen. Verwenden Sie stattdessen FO_MOVE.

pFrom

Typ: PCZZTSTR-

Hinweis Diese Zeichenfolge muss doppelt null beendet sein.

 

Ein Zeiger auf einen oder mehrere Quelldateinamen. Diese Namen sollten vollqualifizierte Pfade sein, um unerwartete Ergebnisse zu verhindern.

Standard-MS-DOS Platzhalterzeichen, z. B. "*", sind zulässig, nur an der Position des Dateinamens. Die Verwendung eines Wildcardzeichens an anderer Stelle in der Zeichenfolge führt zu unvorhersehbaren Ergebnissen.

Obwohl dieses Element als einzelne null-beendete Zeichenfolge deklariert wird, handelt es sich tatsächlich um einen Puffer, der mehrere durch Null getrennte Dateinamen enthalten kann. Jeder Dateiname wird durch ein einzelnes NULL- Zeichen beendet. Der Nachname wird mit einem doppelten NULL- Zeichen ("\0\0") beendet, um das Ende des Puffers anzugeben.

pTo

Typ: PCZZTSTR-

Hinweis Diese Zeichenfolge muss doppelt null beendet sein.

 

Ein Zeiger auf die Zieldatei oder den Verzeichnisnamen. Dieser Parameter muss auf NULL- festgelegt werden, wenn er nicht verwendet wird. Wildcardzeichen sind nicht zulässig. Ihre Verwendung führt zu unvorhersehbaren Ergebnissen.

Wie pFromist das pTo Member auch eine Zeichenfolge mit Doppel-Null-Beendigung und wird auf die gleiche Weise behandelt. pTo- müssen jedoch die folgenden Spezifikationen erfüllen:

• Wildcardzeichen 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 im Hintergrund zu erstellen, legen Sie das FOF_NOCONFIRMMKDIR Flag in fFlags-fest.
• Bei Kopier- und Verschiebevorgängen kann der Puffer mehrere Zieldateinamen enthalten, wenn das fFlags-Element Element FOF_MULTIDESTFILESangibt.
• 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

Speichern Sie nach Möglichkeit Rückgängig-Informationen.

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 späteren Systemen ist der Umfang 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ängig-Zustand wird im Explorer.exe Prozess gehalten, und solange dieser Prozess ausgeführt wird, kann er die Rückgängig-Funktionen koordinieren.

Wenn der Quelldateiparameter keinen 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 Wildcarddateiname (.) angegeben ist.

FOF_MULTIDESTFILES

Das pTo Member gibt mehrere Zieldateien an (eine für jede Quelldatei in pFrom) anstelle eines Verzeichnisses, 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 erstellt werden muss.

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 nicht die Sicherheitsattribute der Datei. Die Zieldatei empfängt die Sicherheitsattribute des 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, bei denen es sich um das Standardverhalten handelt.

FOF_NO_UI

Windows Vista. Führen Sie den Vorgang im Hintergrund 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 in einem Verschiebungs-, Kopier- oder Umbenennungsvorgang auf einen neuen Namen angewendet wird, wenn eine Datei mit dem Zielnamen bereits am Ziel vorhanden ist.

FOF_SILENT

Ein Statusdialogfeld wird nicht angezeigt.

FOF_SIMPLEPROGRESS

Zeigt ein Statusdialogfeld an, zeigt jedoch nicht einzelne Dateinamen an, während sie ausgeführt werden.

FOF_WANTMAPPINGHANDLE

Wenn FOF_RENAMEONCOLLISION angegeben ist und alle Dateien umbenannt wurden, weisen Sie dem hNameMappings Member ein Namenszuordnungsobjekt zu, das ihre alten und neuen Namen enthält. Dieses Objekt muss mit 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 wiederverwendet zu werden. Dieses Flag überschreibt teilweise FOF_NOCONFIRMATION.

fAnyOperationsAborted

Typ: BOOL-

Wenn die Funktion zurückgegeben wird, enthält dieses Element TRUE, wenn Dateivorgänge abgebrochen wurden, bevor sie abgeschlossen wurden; andernfalls FALSE. Ein Vorgang kann manuell vom Benutzer über die Benutzeroberfläche abgebrochen werden, oder er kann vom System automatisch abgebrochen werden, wenn die FOF_NOERRORUI oder FOF_NOCONFIRMATION Flags festgelegt wurden.

hNameMappings

Typ: LPVOID-

Wenn die Funktion zurückgegeben wird, enthält dieses Element ein Handle zu einem Namenszuordnungsobjekt, das die alten und neuen Namen der umbenannten Dateien enthält. Dieses Element wird nur verwendet, wenn das fFlags-element das FOF_WANTMAPPINGHANDLE Flag enthält. Weitere Informationen finden Sie in den Hinweisen.

lpszProgressTitle

Typ: PCTSTR-

Ein Zeiger auf den Titel eines Statusdialogfelds. Dies ist eine mit Null beendete Zeichenfolge. Dieses Element wird nur verwendet, wenn fFlags- das FOF_SIMPLEPROGRESS Flag enthält.

Bemerkungen

Wichtig Sie müssen sicherstellen, dass die Quell- und Zielpfade doppelt null beendet sind. Eine normale Zeichenfolge endet nur in einem einzelnen Nullzeichen. Wenn Sie diesen Wert entweder in den Quell- oder Zielmembern übergeben, wird die Funktion nicht erkannt, wenn sie das Ende der Zeichenfolge erreicht hat, und wird im Arbeitsspeicher weiter gelesen, bis es zu einem zufälligen Doppelt null-Wert kommt. Dies kann zumindest zu einem Pufferüberlauf und möglicherweise zum unbeabsichtigten Löschen nicht verknüpfter Daten führen.

 

// 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 endende Nullzeichen enthält) plus 1 zu speichern.

Es kann nicht überstatiert 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, wie sie vom GetCurrentDirectory und SetCurrentDirectory--Funktionen verwaltet werden.

Wenn Sie keinen vollständigen Pfad bereitstellen, sind die folgenden Fakten relevant:

• Das Fehlen eines Pfads vor einem Dateinamen weist nicht darauf hin, SHFileOperation, 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 verwendet wird, ist prozessweit und kann von einem anderen Thread geändert werden, während der Vorgang ausgeführt wird. Wäre dies der Fall, wären die Ergebnisse von SHFileOperation unvorhersehbar.

Wenn pFrom auf einen Dateinamen ohne vollständigen Pfad festgelegt ist, wird die Datei mit FO_DELETE nicht in den Papierkorb verschoben, auch wenn das FOF_ALLOWUNDO Flag festgelegt ist. Sie müssen einen vollständigen Pfad angeben, um die Datei in den Papierkorb zu löschen.

SHFileOperation schlägt bei einem 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 identisch mit der ANSI-Version, mit der Ausnahme, dass breite Zeichenfolgen (LPCWSTR) anstelle von ANSI-Zeichenfolgen verwendet werden (LPCSTR). 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 von der Vorkompilierung abhängig davon, ob die Anwendung für ANSI oder Unicode kompiliert wird, als SHFILEOPSTRUCT neu definiert.

SHNAMEMAPPING hat ähnliche ANSI- und Unicode-Versionen. Bei ANSI-Anwendungen verweist hNameMappings auf eine int gefolgt von einem Array von ANSI SHNAMEMAPPING- Strukturen. Bei Unicode-Anwendungen verweist hNameMappings auf eine int gefolgt von einem Array von Unicode-SHNAMEMAPPING- Strukturen. Unter Microsoft Windows NT 4.0 und höher gibt SHFileOperationjedoch 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 behandeln. Zum 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 SHNAMEMAPPING- Strukturen, wie in der Deklaration dargestellt:

struct HANDLETOMAPPINGS 
{
    UINT              uNumberOfMappings;  // Number of mappings in the array.
    LPSHNAMEMAPPING   lpSHNameMapping;    // Pointer to the array of mappings.
};

Der wert UINT 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.

Note The handle must be freed with SHFreeNameMappings.

 

Anmerkung

Der shellapi.h-Header definiert SHFILEOPSTRUCT 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 XP [nur Desktop-Apps]
mindestens unterstützte Server-	Windows 2000 Server [nur Desktop-Apps]
Header-	shellapi.h