Verze 1.14
Copyright © 2001-2002 David Majda
Debordelizátor je program, který vyčistí váš pevný disk od nepotřebných souborů z adresáře Temp, GID souborů nápovědy, zástupců ukazujících na neexistující soubory, apod. Ušetřit můžete až několik desítek MB. Nad celým procesem mazání máte plnou kontrolu, můžete explicitně povolit/zakázat smazání libovolného souboru a zvolit, zda soubory mazat rovnou nebo použít Koš.
Tento dokument se zabývá torbou rozšiřujících modulů (pluginů) pro Debordelizátor verze 1.00 a 1.10. Zeleně psaný text popisuje rozdíly (vylepšení) ve verzi 1.10 oproti verzi 1.00. Pokud tedy chcete vyvíjet pluginy funkční i ve verzi 1.00, tento text ignorujte.
V podstatě jedinou (ale velmi podstatnou) změnou mezi oběma verzemi je možnost mazání adresářů.
Momentálně nejnovější verze Debordelizátoru 1.14 se z hlediska psaní pluginů nijak neodlišuje od verze 1.10.
Pokud spustíte Debordelizátor, můžete si v úvodní obrazovce vybrat, které typy souborů a adresářů chcete smazat. Za vyhledání každého typu souborů na disku je zodpovědný právě jeden plugin. Úkolem pluginu tedy je najít soubory a adresáře daného typu a předat jejich názvy Debordelizátoru, který se postará o jejich smazání.
Po technické stránce je plugin knihovna DLL, která se nachází v podadresáři
Plugins, který je umístěn v hlavním adresáři Debordelizátoru.
Debordelizátor prohledá tento adresář a načte všechny DLL knihovny, které
vyhovují specifikaci pluginu (přesnější popis viz Popis
činnosti algoritmu).
Jak už bylo řečeno, plugin je zodpovědný jen a pouze za vyhledání souborů a adresářů, které považuje za možné smazat. Mazání samotné neprovádí, to má už na starosti Debordelizátor. Díky této koncepci je velice snadné pluginy navrhovat.
Pluginy můžou být napsány v libovolném programovacím nástroji schopném vytvářet DLL knihovny (Delphi, C++ Builder, Visual C++, Visual Basic a další). V tomto manuálu budou všechny části kódu psány v Object Pascalu (tj. jazyk Delphi či Free Pascalu), protože je v něm napsán samotný Debordelizátor a tento programovací jazyk také nejlépe ovládám.
Typický "život" pluginu vypadá takto (detailní popis jednotlivých funkcí viz Popis jednotlivých funkcí):
GetRequiedVersion , GetName,
GetDescription, BeginScanning , GetFileCount, GetFileName a EndScanning. Pokud některou
z nich nenajde, plugin vymaže z paměti a nenabídne jím mazaný typ
souborů uživateli ke zvolení.GetRequiedVersion. Ta vrací verzi Debordelizátoru, pro kterou je plugin určen (důvodem
existence této funkce je případná (ne)kompatibilita budoucích verzí).
Tato funkce musí vrátit hodnotu $00010000 (v C/C++
syntaxi 0x00010000), což znamená, že plugin je určen
pro verzi 1.00. Pokud funkce vrátí jinou hodnotu, plugin se opět
vymaže z paměti a je programem ignorován.
Ve verzi 1.10 může plugin kromě zmiňované hodnoty vrátit i hodnotu
$0001000A (v C/C++ syntaxi 0x0001000A), což
znamená, že plugin je určen pro verzi 1.10.GetName. Ta programu
předá "uživatelsky přívětivý" název typu souborů, které plugin
maže (např. "Soubory GID").GetDescription. Ta
programu předá pro změnu podrobnější popis, co plugin dělá. Ten
se v Debordelizátoru zobrazí jako nápověda při kliknutí na název
pluginu.BeginScanning. Plugin
v ní prohledá oblast disku určenou parametrem a vytvoří seznam
souborů a adresářů jemu příslušejícímu
typu, které je možno smazat.GetFileCount, ve které
plugin vrátí počet nalezených souborů a adresářů.GetFileName
a plugin postupně vrátí jména všech souborů
a adresářů, co nalezl.EndScanning. V té může plugin uvolnit z paměti dříve vytvořený seznam nalezených
souborů a adresářů. Po návratu z této
funkce je plugin vymazán z paměti.Snad je to jasné a pochopitelné, jednodušeji celý proces komunikace plugin-Debordelizátor snad už navrhnout nešlo.
Pro lepší pochopení jsou s vývojovým kitem dodávány zdrojové kódy všech standardních pluginů Debordelizátoru. Můžete je použít jako "odrazový můstek" při psaní vlastních pluginů - klidně vytvářejte pluginy pouhou modifikací již existujících, je to nejjednodušší. Navíc většina pluginů si je velmi podobná.
Pluginy jsou napsány tak, že je lze zkompilovat v Borland Delphi
3.0 a vyšším a kromě pluginu Links.dpr též ve
Free Pascalu 1.00 a vyšším. (Links.dpr nelze
ve Free Pascalu zkompilovat kvůli jeho absenci podpory rozhraní OLE -
ve verzi Free Pascalu 1.2 se to snad změní). Pro kompilaci ve Free Pascalu
můžete využít soubor fpcmake.bat, jehož spuštěním se
automaticky zkompilují všechny pluginy (kromě Links.dpr).
Všechny pluginy využívají na hledání souborů na disku unitu
FindX.pas. Tu doporučuji využívat ve svých "výtvorech" též, dokumentaci
k ní najdete v souboru
http://dmajda.hyperlink.cz/zip/findx-1.10.zip.
Následuje přesný popis jednotlivých povinných funkcí pluginu i s jejich deklaracemi v Pascalu.
function GetRequiedVersion: Integer; stdcall;
Vrací verzi Debordelizátoru, pro kterou je plugin určen. První číslo verze (před desetinnou tečkou) je v horních 16 bitech návratové hodnoty, druhé v dolních 16 bitech. Ve verzi 1.00 musí funkce vracet konstantu
$00010000(v C/C++ syntaxi0x00010000), která představuje číslo verze 1.00.Ve verzi 1.10 může plugin kromě zmiňované hodnoty vrátit i hodnotu$0001000A(v C/C++ syntaxi0x0001000A), což znamená, že plugin je určen pro verzi 1.10.
žádné
číslo verze Debordelizátoru
procedure GetName(Name: PChar); stdcall;
Vrací "uživatelsky přívětivý" popis typu souborů, který daný plugin vyhledává.
NameUkazatel na pole znaků o délce minimálně 1024 znaků. Do tohoto pole musí procedura zkopírovat popis typu souborů, ukončený znakem #0(v Pascalu je možno použít funkciStrCopy).
žádná
procedure GetDescription(Description: PChar); stdcall;
Vrací detailní popis toho, co plugin dělá. Ten se v Debordelizátoru zobrazí jako nápověda při kliknutí na název pluginu.
DescriptionUkazatel na pole znaků o délce minimálně 1024 znaků. Do tohoto pole musí procedura zkopírovat popis pluginu, ukončený znakem #0(v Pascalu je možno použít funkciStrCopy).
žádná
type TScanProgressProc = function(Position, Max: Integer; Msg: PChar); stdcall;
procedure BeginScanning(RootPath: PChar; ScanProgressProc: TScanProgressProc); stdcall;
V této proceduře plugin provede vlastní hledání souborů a adresářů ke smazání. Pokud obecně hledá soubory a adresáře ve všech adresářích disku, musí začít od cesty
RootPath. Pokud hledání trvá déle než několik sekund, musí plugin periodicky volat funkciScanProgressProc.Výsledkem volání procedury
BeginScanningby měl být stav, kdy má plugin vytvořený seznam souborů a adresářů ke smazání. Ten si musí udržovat v paměti až do volání funkceEndScanning(musí být tedy deklarován pomocí globálních proměnných či jiného podobného mechanismu).Poznámka 1: Programem je garantováno, že soubory budou mazány v tom pořadí, v jakém jsou zapsané ve vytvořeném seznamu. Jediné mě známé využití této garance je uvedeno v poznámce č. 2.
Poznámka 2: Při mazání adresářů může nastat situace, že plugin by rád smazal adresář i s obsaženými soubory. V tom případě musí do seznamu nejdříve uložit tyto soubory a teprve za nimi adresář, který je obsahuje (aby se smazal až po souborech). Důvodem nutnosti výpisu jednotlivých souborů v adresáři je především přesnější zobrazení počtu a velikostí mazaných souborů v Debordelizátoru (uživatel vidí, kolik souborů v adresáři je a jaké jsou jejich velikosti) a přehlednější možnost výběru mazaných souborů.
RootPathCesta, odkud má plugin začít vyhledávání souborů a adresářů. Pokud je plugin závislý na konkrétním umístění mazaných souborů a adresářů (např. v adresáři Tempapod.), může tento parametr ignorovat.ScanProgressProcUkazatel na funkci, kterou musí plugin periodicky volat během vyhledávání. Parametr
Positionurčuje už prohledanou část souborů,Maxkonečný stav. Plugin musí funkci volat tak, aby podílPosition/Maxbyl při každém novém volání větší nebo roven hodnotě tohoto podílu při předchozm voláním - jinak řečeno, aby lišta ukazující v Debordelizátoru postup vyhledávání "nesklouzávala" nazpátek. V parametruMsgmůže procedura předat ukazatel na řetězec ukončený znakem#0, který obsahuje hlášení pro uživatele o průběhu vyhledávání (typicky právě prohledávaný adresář).Před voláním funkce
ScanProgressProcje třeba testovat, zda ukazatel na ni nemá hodnotunil- v tom případě samozřjemě plugin nesmí funkci volat. (Ve verzích 1.00 a 1.10 ukazatel hodnotunilsice nikdy nemá, leč o budoucích verzích se to tvrdit nedá. A programátor zájmem samozřejmě je, aby plugin fungoval i v dalších verzích Debordelizátoru).Pokud funkce
ScanProgressProcvrátíTrue, plugin může pokračovat v hledání souborů. Pokud vrátíFalse, znamená to, že uživatel hledání stornoval, a plugin musí okamžitě hledání pozastavit a vrátit se z volání proceduryBeginScanning.
function GetFileCount: Integer; stdcall;
Vrací počat nalezených souborů a adresářů ke smazání. Debordelizátor zaručuje, že tato funkce bude volána po voláním procedury
BeginScanninga před voláním proceduryEndScanning.
žádné
Počet nalezených souborů.
procedure GetFileName(Index: Integer; FileName: PChar); stdcall;
Vrací jméno
Index-tého souboru nebo adresáře ze seznamu souborů a adresářů určených ke mazání. Debordelizátor zaručuje, že tato procedura bude volána po voláním proceduryBeginScanninga před voláním proceduryEndScanning.
IndexUrčuje index souboru nebo adresáře ze seznamu, jehož jméno má funkce vrátit. Může nabývat hodnoty od 0 do hodnoty vrácené funkcí GetFileCountsnížené o 1.FileNameUkazatel na pole znaků o délce minimálně 1024 znaků. Do tohoto pole musí procedura zkopírovat jméno souboru nebo adresáře, ukončené znakem #0(v Pascalu je možno použít funkciStrCopy).
žádná
procedure EndScanning; stdcall;
Procedura je volána po vyzvednutí jmen všech nalezených souborů a adresářů. Měla by zajistit uvolnění seznamu souborů a adresářů z paměti a dealokování všech globálních struktur, které plugin využíval. Po volání
EndScanningje plugin odstraněn z paměti
žádné
žádná
Doufám, že tento stručný manuál vám pomohl či pomůže při tvorbě vlastních pluginů pro Debordelizátor. Pokud jste něčemu neporozuměli, našli jste chybu nebo máte námět na jakékoliv vylepšení (ať už tohoto návodu, pluginů či Debordelizátoru), ozvěte se mi na můj e-mail: david.majda@seznam.cz.