SHFILEOPSTRUCTA-Struktur (shellapi.h)

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

Hinweis Ab Windows Vista wird die Verwendung der IFileOperation-Schnittstelle über diese Funktion empfohlen.
 

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 Fensterhandpunkt im Dialogfeld, um Informationen zum Status des Dateivorgangs anzuzeigen.

wFunc

Typ: UINT

Ein Wert, der angibt, welche Operation 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 in den speicherort, der in pTo angegeben ist.

FO_RENAME

Benennen Sie die in pFrom angegebene 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 werden.
 
Ein Zeiger auf einen oder mehrere Quelldateinamen. Diese Namen sollten vollqualifizierte Pfade sein, um unerwartete Ergebnisse zu verhindern.

Standardmäßige MS-DOS-Platzhalterzeichen, z. B. "*", sind nur in der Dateinamenposition zulässig. Die Verwendung eines Ortshalterzeichens 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 werden.
 
Ein Zeiger auf die Zieldatei oder den Verzeichnisnamen. Dieser Parameter muss auf NULL festgelegt werden, wenn er nicht verwendet wird. Freihalterzeichen sind nicht zulässig. Ihre Verwendung führt zu unvorhersehbaren Ergebnissen.

Wie pFrom ist das pTo-Element auch eine doppelt null beendete Zeichenfolge und wird auf ähnliche Weise behandelt. PTo muss jedoch die folgenden Spezifikationen erfüllen:

  • Platzhalterzeichen werden nicht unterstützt.
  • Kopier- und Move-Vorgä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 automatisch erstellt zu haben, legen Sie das FOF_NOCONFIRMMKDIR Flag in fFlags fest.
  • Bei Kopier- und Verschiebungsvorgängen kann der Puffer mehrere Zieldateinamen enthalten, wenn das fFlags-ElementFOF_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 aus den folgenden Flags verwenden.

FOF_ALLOWUNDO

Behalten Sie ggf. Die Informationen rückgängig.

Vor Windows Vista konnten Vorgänge nur aus demselben Prozess rückgängig machen, 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-Status 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 in Ordnern) aus, wenn ein Wildcarddateiname (.) 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 Dialogfeld, das angezeigt wird.

FOF_NOCONFIRMMKDIR

Bitten Sie den Benutzer nicht, die Erstellung eines neuen Verzeichnisses zu bestätigen, wenn der Vorgang eine erstellen 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

Zeigt dem Benutzer kein Dialogfeld an, wenn ein Fehler auftritt.

FOF_NORECURSEREPARSE

Wird nicht verwendet.

FOF_NORECURSION

Führen Sie nur den Vorgang im lokalen Verzeichnis aus. Arbeiten Sie nicht rekursiv in Unterverzeichnissen, was das Standardverhalten ist.

FOF_NO_UI

Windows Vista. Führen Sie den Vorgang im Hintergrund aus, und stellen Sie dem Benutzer keine Benutzeroberfläche vor. Dies entspricht FOF_SILENT | FOF_NOCONFIRMATION | FOF_NOERRORUI | FOF_NOCONFIRMMKDIR.

FOF_RENAMEONCOLLISION

Geben Sie der Datei, die auf einem neuen Namen in einem Verschieben-, Kopieren- oder Umbenennensvorgang ausgeführt 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-Element 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 Kennzeichen ü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 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 null-beendete Zeichenfolge. Dieses Element wird nur verwendet, wenn fFlags das FOF_SIMPLEPROGRESS Flag enthält.

Hinweise

Wichtig Sie müssen sicherstellen, dass die Quell- und Zielpfade doppelt null beendet sind. Eine normale Zeichenfolge endet nur in einem einzelnen NULL-Zeichen. Wenn Sie diesen Wert entweder in den Quell- oder Zielelementen übergeben, wird die Funktion nicht erkennen, wenn sie das Ende der Zeichenfolge erreicht hat und weiterhin im Arbeitsspeicher lesen wird, bis es zu einem zufälligen doppelten Nullwert kommt. Dies kann zumindest zu einem Pufferüberlauf führen und möglicherweise das unbeabsichtigte Löschen nicht verwandter Daten.
 
// WRONG
LPTSTR pszSource = L"C:\\Windows\\*";

// RIGHT
LPTSTR pszSource = L"C:\\Windows\\*\0";

Um die beiden endenden Nullzeichen zu berücksichtigen, müssen Sie Puffer erstellen, die groß genug sind, um MAX_PATH zu halten (die normalerweise das einzelne endende Nullzeichen enthält) plus 1.

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 wie durch die Funktionen GetCurrentDirectory und SetCurrentDirectory verwaltet.

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

  • Der Mangel an Pfaden vor einem Dateinamen weist nicht auf SHFileOperation hin, dass sich diese Datei im Stammverzeichnis des aktuellen Verzeichnisses befindet.
  • Die PATH-Umgebungsvariable wird von SHFileOperation nicht verwendet, um einen gültigen Pfad zu ermitteln.
  • SHFileOperation kann nicht darauf vertrauen, das Verzeichnis zu verwenden, das das aktuelle Verzeichnis ist, wenn es mit der Ausführung beginnt. Das Verzeichnis, das als aktuelles Verzeichnis betrachtet wird, ist prozessweit und kann von einem anderen Thread geändert werden, während der Vorgang ausgeführt wird. Wenn dies geschehen wäre, 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, der mit "\?" präfixiert ist, 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, außer dass breite Zeichenzeichenfolgen (LPCWSTR) anstelle von ANSI-Zeichenzeichenfolgen (LPCSTR) verwendet werden. Unter Windows 98 und früher wird nur die ANSI-Version unterstützt. Auf Microsoft Windows NT 4.0 und höher werden sowohl die ANSI- als auch unicode-Versionen dieser Struktur unterstützt. SHFILEOPSTRUCTW und SHFILEOPTSTRUCTA sollten niemals direkt verwendet werden; die entsprechende Struktur wird vom Vorkompilierer 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 verweist hNameMappings auf ein Int gefolgt von einem Array von ANSI SHNAMEMAPPING-Strukturen . Bei Unicode-Anwendungen verweist hNameMappings auf ein Int gefolgt von einem Array von Unicode SHNAMEMAPPING-Strukturen . In Microsoft Windows NT 4.0 und höher gibt SHFileOperation jedoch immer einen 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. 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 dargestellt:

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 Handle muss mit SHFreeNameMappings freigegeben werden.
 

Hinweis

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 codierungsneutralen Aliase mit Code, der nicht codierungsneutral ist, kann zu Ü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]
Header shellapi.h