You will find here all the public classes and methods that you can use to script Hopper with the Python language.
Before using the scripting capabilities of Hopper, you have to understand how Hopper considers its documents. The main idea is that a document is a set of segments, each of them containing typed bytes. Indeed, let's consider a standard MachO file. It will contains at least one segment of code (usually named TEXT) containing many bytes. Hopper attach some information to each bytes of each segments. At the loading time, all bytes are set to the type TYPE_UNDEFINED. Then, starting from the entry point, Hopper will starts to set the type for some of them to TYPE_CODE, following the program control flow. When an instruction needs more than one byte, Hopper will set the type of the first byte to TYPE_CODE, and the following bytes to the TYPE_NEXT type.
Using Python, you'll be able to manipulate the segments of disassembled files, retrieving information on bytes types, write or read data, change or create name of labels, etc... You'll usually starts at retrieving the current document, using the static method Document.getCurrentDocument().
I tried to name the functions in a way that make it easy to find. Fell free to contact me if something seems difficult to achieve, or if you have any suggestion. My e-mail address is bsr43@hopperapp.com.
Please note that you can use either, the integrated (very) light Python editor, or use a more convenient editor (like the insanely great TextMate editor), but avoid opening the script in both editors at the same time! To use your own editor, simply click on the small gear, underneath the script list. This will open a new Finder. When you add, remove or edit files of this directory, Hopper automatically detects it.
|
Class Procedure
getBasicBlock getBasicBlockCount getEntryPoint getHeapSize Class BasicBlock getEndingAddress getProcedure getStartingAddress getSuccessorAddressAtIndex getSuccessorCount getSuccessorIndexAtIndex Class Instruction getArchitecture getArgumentCount getFormattedArgument getInstructionLength getInstructionString getRawArgument isAConditionalJump isAnInconditionalJump stringForArchitecture Class Segment disassembleWholeSegment getCommentAtAddress getFileOffset getFileOffsetForAddress getInlineCommentAtAddress getInstructionAtAddress getLabelCount getLabelName getLabelsList getLength getName getNameAtAddress getNextAddressWithType getProcedureAtAddress getProcedureAtIndex getProcedureCount getProcedureIndexAtAddress getReferencesOfAddress getStartingAddress getTypeAtAddress isThumbAtAddress labelIterator markAsCode markAsDataByteArray markAsDataIntArray markAsDataShortArray markAsProcedure markAsUndefined markRangeAsUndefined readByte setARMModeAtAddress setCommentAtAddress setInlineCommentAtAddress setNameAtAddress setThumbModeAtAddress setTypeAtAddress stringForType writeByte Class Document ask assemble getAddressForName getCurrentAddress getCurrentColumn getCurrentDocument getCurrentSegment getCurrentSegmentIndex getEntryPoint getHighlightedWord getNameAtAddress getRawSelectedLines getSegment getSegmentAtAddress getSegmentCount getSegmentIndexAtAddress getSegmentsList getSelectionAddressRange is64Bits log message moveCursorAtAddress moveCursorAtEntryPoint moveCursorOneLineDown moveCursorOneLineUp refreshView selectAddressRange setNameAtAddress |
Class Procedure
This class represents a procedure, which is a collection of BasicBlocks. Please note that modifying the document (creating new procedure, or deleting an existing one), will result in a possible inconsistancy of the Python's Procedure object representation.
Class BasicBlock
A BasicBlock is a set of instructions that is guaranteed to be executed in a whole, if the control flow reach the first instruction.
Class Instruction
This class reprents a disassembled instruction. The class defines some constants, like ARCHITECTURE_UNKNOWN, ARCHITECTURE_i386 and ARCHITECTURE_X86_64
stringForArchitecture(t)
[static] Helper method that converts one of the architecture value (ARCHITECTURE_UNKNOWN, ARCHITECTURE_i386, ARCHITECTURE_X86_64, ARCHITECTURE_ARM or ARCHITECTURE_ARM_THUMB) to a string value.
getRawArgument(index)
Returns the instruction argument, identified by an index. The argument is not modified by Hopper, and represents the raw ASM argument.
Class Segment
This class represents a segment of a disassembled file. The class defines some values that are used as the type of bytes of the disassembled file.
TYPE_UNDEFINED : an undefined byte TYPE_NEXT : a byte that is part of a larger data type (ex, the second byte of a 4 bytes integer...) TYPE_BYTE : an integer of a single byte TYPE_SHORT : an integer of 2 bytes TYPE_INT : an integer of 4 bytes TYPE_LONG : an integer of 8 bytes TYPE_ASCII : an ASCII string TYPE_UNICODE : an UNICODE string TYPE_CODE : an instruction TYPE_PROCEDURE : a procedure The class defines the constant BAD_ADDRESS that is returned by some methods when the requested information is incorrect. stringForType(t)
[static] Helper method that converts one of the type value (TYPE_UNDEFINED, TYPE_NEXT, ...) to a string value.
readByte(addr)
Read a byte at a given address. Returns False if the byte is read outside of the segment.
getTypeAtAddress(addr)
Returns the type of the byte at a given address. The type can be TYPE_UNDEFINED, TYPE_NEXT, TYPE_BYTE, TYPE_SHORT, TYPE_INT, TYPE_LONG, TYPE_ASCII, TYPE_CODE or TYPE_PROCEDURE. The method will returns None if the address is outside the segment.
setTypeAtAddress(addr,length,typeValue)
Set the type of a byte range. The type must be TYPE_UNDEFINED, TYPE_BYTE, TYPE_SHORT, TYPE_INT, TYPE_LONG or TYPE_ASCII.
getNextAddressWithType(addr,typeValue)
Returns the next address of a given type. The search begins at the given address, so the returned value can be the given address itself. If no address are found, the returned value is BAD_ADDRESS.
Class Document
This class represents the disassembled document. A document is a set of segments.
ask(msg)
[static] Open a window containing a text field, and wait for the user to give a string value. Returns the string, or returns None if the Cancel button is hit.
message(msg,buttons)
[static] Open a window containing a text field and a set of buttons. The 'Buttons' parameter is a list of strings. The function returns the index of the clicked button.
assemble(instr,address,intel)
Assemble an instruction, and returns the bytes as an array. The instruction is NOT injected in the document: the address given to the function is used to encode the instruction. You wan use the writeByte method to inject an assembled instruction. The first argument is the instruction to be assembled. The second is the address of the instruction. The last parameter is a boolean value indicating if the instruction use the Intel syntax or the AT&T syntax.
getSegment(index)
Returns a segment by index. The returned object is an instance of the Segment class. If the index of not in the range [0;count[, the function returns None.
getCurrentSegmentIndex()
Returns the segment index where the cursor is. Returns -1 if the current segment cannot be located.
getCurrentSegment()
Returns the segment where the cursor is. Returns None if the current segment cannot be located.
getSelectionAddressRange()
Returns a list, containing two addresses. Those address represents the range of bytes covered by the selection.
selectAddressRange(addrRange)
Select a range of byte. The awaited argument is a list containing exactly two address.
moveCursorOneLineDown()
Move the current line down, and remove the multiselection if needed. Returns True if cursor moved.
|