Sign in to follow this  
Followers 0
wraithdu

Eraser API Library

9 posts in this topic

#1 ·  Posted (edited)

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) -

#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 by wraithdu

Share this post


Link to post
Share on other sites



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.

Share this post


Link to post
Share on other sites

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().

Share this post


Link to post
Share on other sites

Updated, see first post.

Share this post


Link to post
Share on other sites

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.

Share this post


Link to post
Share on other sites

#7 ·  Posted (edited)

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 by wraithdu

Share this post


Link to post
Share on other sites

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!

Share this post


Link to post
Share on other sites

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

Share this post


Link to post
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!


Register a new account

Sign in

Already have an account? Sign in here.


Sign In Now
Sign in to follow this  
Followers 0