Eraser API Library

[wraithdu]

UPDATE: 2008-09-18

Updated API with better error returns. Now sets @error on function failures.

UPDATE: 2008-09-17

Added the rest of the progress functions. Updated the example showing all Eraser window messages - BEGIN, UPDATE, DONE.

UPDATE: 2008-06-19

Added more functions, and corrected the datatypes. Updated the example to show new stuff.

I finally decided I really wanted to do this, so I didn't have to rely on EraserL. It's mostly complete of the useful functions. I have yet to do the Progress and Statistics functions, but the library is usable as is. I will be adding those as I need them (which will be soon). The current Library is based off the DLL from the portable version of Eraser 5.87.1, found here -

http://bbs.heidi.ie/viewtopic.php?f=14&t=4470

Here's an example for usage (documentation is not done but this gives the general idea) -

expandcollapse popup

#include <_EraserAPI.au3>
#include <GUIConstantsEx.au3>
#include <WinAPI.au3>
#include <Date.au3>

; $ERASER_OK = 0

Global $context, $iUpdate = 1
Global Const $SHCNE_RMDIR = 0x10
Global Const $SHCNF_PATHW = 0x5
Global Const $SHCNF_PATH = $SHCNF_PATHW

$nGUI = GUICreate("dummy")
$eMsg = _WinAPI_RegisterWindowMessage("ThisIsMyMessage")

GUIRegisterMsg($eMsg, "_ERASER_NOTIFY")

ConsoleWrite("Init: " & _EraserInit() & @CRLF)
$context = _EraserCreateContextEx($DOD_METHOD_ID)
ConsoleWrite("Context: " & $context & @CRLF)
ConsoleWrite("Set type: " & _EraserSetDataType($context, $ERASER_DATA_FILES) & @CRLF)

ConsoleWrite("Set window: " & _EraserSetWindow($context, $nGUI) & @CRLF)
ConsoleWrite("Set msg: " & _EraserSetWindowMessage($context, $eMsg) & @CRLF)

ConsoleWrite("Add item 1: " & _EraserAddItem($context, @ScriptDir & "\test\test\test.zip") & @CRLF)
ConsoleWrite("Add item 2: " & _EraserAddItem($context, @ScriptDir & "\test\test\test2.zip") & @CRLF)

ConsoleWrite("Start: " & _EraserStart($context) & @CRLF)

While 1
    Sleep(1000)
WEnd

Func _ERASER_NOTIFY($hwnd, $msg, $wparam, $lparam)
    Switch $wparam
        Case $ERASER_WIPE_BEGIN
            ; BEGIN message sent before each file in the context
            _EraserBegin()
        Case $ERASER_WIPE_UPDATE
            _EraserUpdate()
        Case $ERASER_WIPE_DONE
            _EraserDoneWipe()
    EndSwitch
EndFunc

Func _EraserBegin()
    ConsoleWrite("+>=== Eraser Wipe Starting ===" & @CRLF)
EndFunc

Func _EraserUpdate()
    Local $iFlags = _EraserDispFlags($context)
    
    ConsoleWrite("-> === Update #" & $iUpdate & " ===" & @CRLF)
    ConsoleWrite("iFlags: " & $iFlags & @CRLF)
    ; Eraser errors are negative integers
    If $iFlags >= 0 Then
        ConsoleWrite("Current File Percent: " & _EraserProgGetPercent($context) & " %" & @CRLF)
        ConsoleWrite("Total Job Percent: " & _EraserProgGetTotalPercent($context) & " %" & @CRLF)
        
        If BitAND($iFlags, $eraserDispPass) Then
            ConsoleWrite("Pass: " & _EraserProgGetCurrentPass($context) & "  of  " & _EraserProgGetPasses($context) & @CRLF)
        EndIf
        If BitAND($iFlags, $eraserDispTime) Then
            ConsoleWrite("Time Left: " & _EraserProgGetTimeLeft($context) & " seconds" & @CRLF)
        EndIf
        
        ConsoleWrite("Message: " & _EraserProgGetMessage($context) & @CRLF)
        ConsoleWrite("Current File: " & _EraserProgGetCurrentDataString($context) & @CRLF)
    EndIf
    
    $iUpdate += 1
EndFunc

Func _EraserDoneWipe()
    Local $result, $h, $m, $s
    
    ConsoleWrite(">=== Finished Wipe Files ===" & @CRLF & "Is running: " & _EraserIsRunning($context) & @CRLF & "+>=== Start Wipe Folders ===" & @CRLF)
    $result = _EraserRemoveFolder(@ScriptDir & "\test\test")
    ConsoleWrite("Remove folder: " & $result & @CRLF)
    If _EraserOK($result) Then
        ConsoleWrite("Sending SHChangeNotify()" & @CRLF)
        _SHChangeNotifyFolder(@ScriptDir & "\test\test")
    EndIf
    ConsoleWrite("Completed: " & _EraserCompleted($context) & @CRLF)
    ConsoleWrite("Failed: " & _EraserFailed($context) & @CRLF)
    _TicksToTime(_EraserStatGetTime($context), $h, $m, $s)
    ConsoleWrite("Time: " & StringFormat("%02i:%02i:%02i", $h, $m, $s) & " hh:mm:ss" & @CRLF)
    ConsoleWrite("Area wiped: " & Round(_EraserStatGetArea($context) / 1024, 2) & " KB" & @CRLF)
    ConsoleWrite("Total written: " & Round(_EraserStatGetWiped($context) / 1024, 2) & " KB" & @CRLF)
    ConsoleWrite("Error count: " & _EraserErrorStringCount($context) & @CRLF)
    ConsoleWrite("First error: " & _EraserErrorString($context, 0) & @CRLF)
    ConsoleWrite("Failed count: " & _EraserFailedCount($context) & @CRLF)
    ConsoleWrite("First failed: " & _EraserFailedString($context, 0) & @CRLF)
    ConsoleWrite("Report: " & _EraserShowReport($context, $nGUI) & @CRLF)
    ConsoleWrite("Destroy context: " & _EraserDestroyContext($context) & @CRLF)
    ConsoleWrite("End: " & _EraserEnd() & @CRLF)
    ConsoleWrite(">=== Eraser Wipe Finished ===" & @CRLF)
    GUIRegisterMsg($eMsg, "")
    Exit
EndFunc

Func _SHChangeNotifyFolder($folder)
    DllCall("shell32.dll", "int", "SHChangeNotify", _
                            "long", $SHCNE_RMDIR, _
                            "uint", $SHCNF_PATH, _
                            "str", $folder, _
                            "str", Chr(0) _
                            )
EndFunc

General Usage -

1. Call _EraserInit()

2. Create a context (_EraserCreateContextEx())

2b. Set the DATA_TYPE - is set for FILES by default. Change to DRIVES if erasing drive free space.

3. Optionally register the Window and WindowMessage for the created context

4. Add files to the context (_EraserAddItem())

5. Start Eraser (_EraserStart())

6. Check the context is finished with _EraserIsRunning() or wait for the window message

7. Remove folders (_EraserRemoveFolder())

7b. Send SHChangeNotify() with the SHCNE_RMDIR flag

NOTE: Folder removal will fail if there are files in them. So the correct usage is to parse a folder and subfolders, then erase all files FIRST, then remove the folder.

8. Destroy the context (_EraserDestroyContext())

9. Shutdown, call _EraserEnd()

I know, not the best instructions, but I had to get everything from the Eraser source code. Eventually I'll do some better docs. See the source for EraserL to get the big picture.

Erasing the Recycle Bin consists of parsing the correct Recycle Bin hidden directories, erasing files, removing folders (including sending SHChangeNotify() as above), emptying the bin (SHEmptyRecycleBin()).

Here is a link to my EraserDropTarget application from PortableApps.com, which is a full implementation of the API. It should be a pretty good example of everything possible.

EraserDropTarget (link)

_EraserAPI.au3

Edited September 19, 2008 by wraithdu

[WeMartiansAreFriendly]

I think this is pretty good.

Except AutoIt crashes if the DLL is missing, kind of odd.

[wraithdu]

Thanks!

I guess AutoIt crashes if the dll in a DllCall() equals -1, which is what it's set to if the DllOpen() fails. I could code around it. Better would be to test the success of the _EraserInit() -

If Not _EraserOK(_EraserInit()) then Exit

Anyway, the _EraserInit() function has the Eraser.dll path default to the script directory. You can pass an alternate path to the function as a parameter though if the DLL is somewhere else.

[wraithdu]

Small update to the Usage - must send SHChangeNotify() with the SHCNE_RMDIR flag after each folder removal, including when removing folders from the Recycle Bin directories. It is not necessary to send this message after calling SHEmptyRecycleBin().

[wraithdu]

Updated, see first post.

[plastix]

hi there. just stumbled over this... have been using eraserl.exe with commandline parameters to securely delete files - noticed your API using the dll directly. Have you managed to get a callback for progress of erasing procedure?? Eraserl.exe appears to be a 'console' win32 app that parses the command line parameters and then calls the DLL... if there is a means of getting feedback of process that would be perfect... (could then also consider embedding the DLL etc).

Any 'pointers' appreciated. Nice work.

[wraithdu]

Yes there is. The best way to see it all is to look at the eraserl source. I'd have to dig through myself, but if I remember correctly, the DLL sends a window message to the window designated in the Eraser "Context". It sends messages for start, end, and update. Then there's a function to extract the progress. Really though, the eraserl source has the best example of it. I'll see if I can't pull some pieces of it later.

Hmm, just noticed I haven't done all the functions yet either...there might be some more for stats / progress.

Edited September 17, 2008 by wraithdu

[wraithdu]

Ok, I updated the API with the rest of the progress functions, and updated the example to show them. Adjust the file and folder paths to work for your test setup. This is pretty much everything that Eraserl.exe uses. I also added a link to my EraserDropTarget application, which is a full implementation of the API. Enjoy!

[wraithdu]

Small update to API to add better error returns. Now @error is set with the error returned from failed functions.