API funkce SHFileOperation - Builder.cz - Informacni server o programovani

10. ledna 2002, 00.00 | Většinou nebývá zvykem věnovat článek jen jediné Win32 API funkci, ale tentokrát uděláme vyjímku. Mimo jiné se naučíte, jak mazat soubory do koše.

Často je v programu potřeba různým způsobem manipulovat se soubory. Teď nemám na mysli čtení/zápis, ale kopírování, přesouvání a mazání. Na tyto věci samozřejmě existují API funkce (CopyFile a spol.). Někdy je ale potřeba, aby tyto funkce uměly víc - třeba zobrazit dialog ukazující průběh prováděné operace nebo provést operaci najednou s více soubory. A v neposlední řadě je někdy potřeba umět mazat soubory nikoliv přímo, ale do koše. Všechny výše uvedené možnosti jsou dostupné v API funkci SHFileOperation, kterou si teď představíme.

Funkce je deklarována v unitě ShellAPI takto:

function SHFileOperation(const lpFileOp: TSHFileOpStruct): Integer; stdcall;

Jejím jediným parametrem je struktura TSHFileOpStruct. V té určujeme, co všechno má funkce provést - jsou v ní tedy "zabaleny" všechny potřebné parametry. Její deklarace se nachází opět u unitě ShellAPI:

type
  TSHFileOpStructA = packed record
    Wnd: HWND;
    wFunc: UINT;
    pFrom: PAnsiChar;
    pTo: PAnsiChar;
    fFlags: FILEOP_FLAGS;
    fAnyOperationsAborted: BOOL;
    hNameMappings: Pointer;
    lpszProgressTitle: PAnsiChar;
  end;
  TSHFileOpStruct = TSHFileOpStructA;

Poznámka pro pokročilejší: Funkce i její parametrová struktura je v dispozici jak v ANSI tak v Unicode variantě (jak už pozorní čtenáři možná usoudili z výpisu). Proto je nejdřív deklarován typ TSHFileOpStructA (a analogicky i TSHFileOpStructW). TSHFileOpStruct je pak defaultně nadefinována jako ekvivalentní s ANSI variantou.

Nyní si popišme jednotlivé parametry.

Wnd

Handle okna, kde se mají zobrazovat informace o průběhu.

wFunc

Hodnota tohoto parametru určuje, jaká operace se má provádět. Lze použít následující čtyři konstanty: FO_COPY, FO_DELETE, FO_MOVE, FO_RENAME. Řekl bych, že názvy konstant mluví samy za sebe.

pFrom

Ukazatel na buffer obsahující názvy souborů, se kterými se má manipulovat. Každý název souboru je ukončen znakem #0. Celý seznam je pak ukončen dvěma znaky #0. Seznam souborů lze také specifikovat pomocí klasické hvězdičkové konvence.

pTo

Ve většině případů je hodnotou tohoto parametru adresář, kam soubory zkopírovat/přemístit. V případě mazání je tento parametr ignorován. Zajímavou možností je použít vlajku FOF_MULTIDESTFILES (viz níže) - pak je hodnotou parametru seznam souborů zapsaný ve stejném formátu jako u pFrom a funkce zkopíruje/přejmenuje soubory z pFrom na soubory na odpovídajících místech seznamu pTo.

fFlags

Vlajky upřesňující provedení operace. Hodnotou je součet libovolných z následujících konstant:

FOF_ALLOWUNDO	V helpu je napsáno, že použití této vlajky zachovává informaci pro undo. Praktický význam je, že použití této vlajky při mazání maže soubory do koše, nikoliv přímo z harddisku.
FOF_FILESONLY	Pokud je v pFrom použita hvězdičková konvence, nezahrnou se do výběru adresáře.
FOF_MULTIDESTFILES	Signalizuje, že v pTo je použit seznam souborů místo adresáře.
FOF_NOCONFIRMATION	Nezobrazuje žádné potvrzovací dialogy (při kolizích jmen souborů apod.), automaticky předpokládá odpověď "Ano".
FOF_NOCONFIRMMKDIR	Nevyžaduje potvrzení vytvoření nového adresáře.
FOF_NOERRORUI	Pokud nastane nějaká chyba, nezobrazí se dialog, který o tom inforuje uživatele.
FOF_RENAMEONCOLLISION	Pokud při kopírování/přesunu dojde ke kolizi jmen (tj. cílový soubor už bude existovat), jméno cílového souboru se upraví (např. v českých Windiws se přidá předpona "Kopie - ").
FOF_SILENT	Naní zobrazován dialog s průběhem operace (defaultně zobrazován vždy je!)
FOF_SIMPLEPROGRESS	Je zobrazena jen zjednodušená verze dialogu s průběhem operace (nejsou zobrazena jména jednotlivých souborů).

Poznámka 1: Nepopisoval jsem vlajky FOF_CONFIRMMOUSE, FOF_NOCOPYSECURITYATTRIBS a FOF_WANTMAPPINGHANDLE, protože je velmi pravděpodobně nevyužijete. Jejich popis zájemci najdou v nápovědě.

Poznámka 2: Typ FILEOP_FLAGS (tedy typ proměnné fFlags) je definován jako Word.

fAnyOperationsAborted

Tato položka je výstupní - po volání funkce je zde hodnota True, pokud uživatel některou z operací přeruší kliknutím na tlačítko Storno. Pokud ne, je zde vrácena hodnota False.

hNameMappings

Pravděpodobně nebudete potřebovat. Funkce zde (pokud použijete vlajku FOF_WANTMAPPINGHANDLE) vrací ve speciálním formátu seznam starých a nových jmen všech souborů

lpszProgressTitle

Nadpis dialogu s průběhem operace. Tento parametr je ignorován, pokud není nastavena vlajka FOF_SIMPLEPROGRESS.

Co dodat? Že když nespecifikujete v pTo nebo pFrom úplnou cestu k souboru (tj. začínající kořenovým adresářem), cesta se považuje za relativní vůči aktuálnímu adresáři. Ještě k návratové hodnotě: Je rovná nule, pokud vše proběhne hladce, nebo různá od nuly, nastane-li při manipulaci se soubory nějaká chyba.

Podle mého názoru je představená funkce poměrně silným nástrojem, který se někdy docela vyplatí používat - tento článek tedy prosím chápejte jako nastínění možností, které SHFileOperation může programátorovi nabídnout.