Class System

Find the first top-level window in the current desktop to match the given class name and/or window name. If neither are provided any top-level window will match.

Parameters:

• className (str) - (Optional) Class name of the window to find. If None or not used any class name will match the search.
• windowName (str) - (Optional) Caption text of the window to find. If None or not used any caption text will match the search.

Returns: Window or None

A window that matches the request. There may be more matching windows, but this method only returns one. If no matching window is found, the return value is None.

Raises:

• WindowsError - An error occured while processing this request.

Get the window located at the given coordinates in the desktop. If no such window exists an exception is raised.

Parameters:

• x (int) - Horizontal coordinate.
• y (int) - Vertical coordinate.

Returns: Window

Window at the requested position. If no such window exists a WindowsError exception is raised.

Raises:

• WindowsError - An error occured while processing this request.

Returns: Window

Returns the desktop window.

Raises:

• WindowsError - An error occured while processing this request.

Returns: Window

Returns the foreground window.

Raises:

• WindowsError - An error occured while processing this request.

Requests debug privileges.

This may be needed to debug processes running as SYSTEM (such as services) since Windows XP.

Automatically detach from processes when the current thread dies.

Works on the following platforms:

• Microsoft Windows XP and above.
• Wine (Windows Emulator).

Fails on the following platforms:

• Microsoft Windows 2000 and below.
• ReactOS.

Parameters:

• bKillOnExit (bool) - True to automatically kill processes when the debugger thread dies. False to automatically detach from processes when the debugger thread dies.

Returns: bool

True on success, False on error.

Load the dbghelp.dll library shipped with the Debugging Tools for Windows. Essentially this enables symbol server support, since this version is newer than the one pre-installed with Windows, and the symbol server loader library (SymSrv.dll) is present in the same directory.

For this method to have any effect it MUST be called BEFORE any function in dbghelp.dll. It's recommended that you call it right after starting your debug script, or after instancing the Debug object.

Example:

   from winappdbg import Debug

   def simple_debugger( argv ):

       # Instance a Debug object, passing it the event handler callback
       debug = Debug( my_event_handler )
       try:

           # Enable support for symbol downloading
           debug.system.load_dbghelp()

           # Start a new process for debugging
           debug.execv( argv )

           # Wait for the debugee to finish
           debug.loop()

       # Stop the debugger
       finally:
           debug.stop()

Parameters:

• pathname (str) - (Optional) Full pathname to the dbghelp.dll library.

Returns: ctypes.WinDLL

Loaded instance of dbghelp.dll.

Raises:

• NotImplementedError - This feature was not implemented for the current architecture.
• WindowsError - An error occured while processing this request.

Read the contents of the specified MSR (Machine Specific Register).

Parameters:

• address (int) - MSR to read.

Returns: int

Value of the specified MSR.

Raises:

• WindowsError - Raises an exception on error.
• NotImplementedError - Current architecture is not i386 or amd64.

Set the contents of the specified MSR (Machine Specific Register).

Parameters:

• address (int) - MSR to write.
• value (int) - Contents to write on the MSR.

Raises:

• WindowsError - Raises an exception on error.
• NotImplementedError - Current architecture is not i386 or amd64.

When tracing, call this on every single step event for step on branch mode.

Raises:

• WindowsError - Raises ERROR_DEBUGGER_INACTIVE if the debugger is not attached to least one process.
• NotImplementedError - Current architecture is not i386 or amd64.

Returns the source and destination addresses of the last taken branch.

Returns: tuple( int, int )

Source and destination addresses of the last taken branch.

Raises:

• WindowsError - Raises an exception on error.
• NotImplementedError - Current architecture is not i386 or amd64.

arch

Type:

str

Value:

'i386'

bits

Type:

int

Value:

32

os

Type:

str

Value:

'Windows XP'

pageSize

Type:

int

Value:

4096