Package ghidra.program.util

Class ProgramLocation

java.lang.Object

ghidra.program.util.ProgramLocation

All Implemented Interfaces:

java.lang.Comparable<ProgramLocation>

Direct Known Subclasses:

AssignedVariableLocation, CodeUnitLocation, DecompilerLocation, DividerLocation, FunctionLocation, FunctionPurgeFieldLocation, InstructionMaskValueFieldLocation, ParallelInstructionLocation, PcodeFieldLocation, RegisterFieldLocation, RegisterTransitionFieldLocation, StackDepthFieldLocation

public class ProgramLocation
extends java.lang.Object
implements java.lang.Comparable<ProgramLocation>

ProgramLocation provides information about a location in a program in the most generic way. ProgramLocations refer to a specific location in a program and can be specified down to an address, a field at that address, and within that field, a row, col, and character offset. The field is not recorded directly, but by the subclass of the ProgramLocation. The "cursor position" within a field is specified by three variables: row, col, and character offset. The row is literally the row (line #) the cursor is on within the field, the column represents the display item on that row (For example, in the bytes field the column will represent which "byte" the cursor is on. Most fields only have one column item per row.) And finally, the character offset is the character position within the display item specified by the row and column. Simple fields like the address field and Mnemonic field will always have a row and column of 0.

Field Summary

Fields

Change	Modifier and Type	Field	Description
NEW	protected Address	addr
NEW	protected Program	program
NEW	protected Address	refAddr

Constructor Summary

Constructors

Change	Constructor	Description
ProgramLocation()	Default constructor required for restoring a program location from XML.
ProgramLocation(Program program, Address addr)	Construct a new ProgramLocation for the given address.
ProgramLocation(Program program, Address addr, int[] componentPath, Address refAddr, int row, int col, int charOffset)	Construct a new ProgramLocation for the given address.
ProgramLocation(Program program, Address addr, int row, int col, int charOffset)	Construct a new ProgramLocation for the given address.
ProgramLocation(Program program, Address addr, Address refAddr)	Construct a new ProgramLocation for the given address.
ProgramLocation(Program program, Address addr, Address byteAddr, int[] componentPath, Address refAddr, int row, int col, int charOffset)	Construct a new ProgramLocation.

Method Summary

Change	Modifier and Type	Method	Description
NEW	protected static int	compareAddr(Address addr1, Address addr2)
	int	compareTo(ProgramLocation other)
	boolean	equals(java.lang.Object obj)
	Address	getAddress()	Returns the address associated with this location.
	Address	getByteAddress()	Returns the byte level address associated with this location.
	int	getCharOffset()	Returns the character offset in the display item at the (row,col)
	int	getColumn()	Returns the column index of the display piece represented by this location.
	int[]	getComponentPath()	Returns the componentPath for the codeUnit.
	static ProgramLocation	getLocation(Program program, SaveState saveState)
	Program	getProgram()	Returns program associated with location or null if not specified.
	Address	getRefAddress()	Returns the "referred to" address if the location is over an address in some field.
	int	getRow()	Returns the row within the program location.
	int	hashCode()
	boolean	isValid(Program testProgram)	Returns true if this location represents a valid location in the given program
	void	restoreState(Program program1, SaveState obj)	Restore this program location using the given program and save state object.
	void	saveState(SaveState obj)	Save this program location to the given save state object.
	java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

program NEW

protected Program program

addr NEW

protected Address addr

refAddr NEW

protected Address refAddr

Constructor Detail

ProgramLocation

public ProgramLocation(Program program,
                       Address addr,
                       Address byteAddr,
                       int[] componentPath,
                       Address refAddr,
                       int row,
                       int col,
                       int charOffset)

Construct a new ProgramLocation.
Note: A NullPointerException will be logged if addr is null.

Parameters:

program - the program of the location

addr - address of the location; cannot be null; This could be a code unit minimum address where the byteAddr is within the code unit.

byteAddr - address of the location; cannot be null

groupPath - path associated with the address (an address could appear at more than one group path); may be null

componentPath - array of indexes for each nested data component; the data index is the data component's index within its parent; may be null

refAddr - the "referred to" address if the location is over a reference; may be null

row - the row within the field.

col - - the display item index on the given row. (Note most fields only have one display item per row)

charOffset - - the character offset within the display item.

ProgramLocation

public ProgramLocation(Program program,
                       Address addr,
                       int[] componentPath,
                       Address refAddr,
                       int row,
                       int col,
                       int charOffset)

Construct a new ProgramLocation for the given address. The address will be adjusted to the beginning of the code unit containing that address(if it exists). The original address can be retrieved using the "getByteAddress()" method.
Note: A NullPointerException will be logged if addr is null.

Parameters:

program - the program associated with this program location (also used to obtain a code-unit-aligned address)

addr - address of the location; cannot be null

componentPath - array of indexes for each nested data component; the index is the data component's index within its parent; may be null

refAddr - the "referred to" address if the location is over a reference; may be null

row - the row within the field.

col - - the display item index on the given row. (Note most fields only have one display item per row)

charOffset - - the character offset within the display item.

ProgramLocation

public ProgramLocation(Program program,
                       Address addr)

Construct a new ProgramLocation for the given address. The address will be adjusted to the beginning of the code unit containing that address(if it exists). The original address can be retrieved using the "getByteAddress()" method.

Parameters:

program - the program associated with this program location (also used to obtain a code-unit-aligned address)

addr - address for the location

ProgramLocation

public ProgramLocation(Program program,
                       Address addr,
                       int row,
                       int col,
                       int charOffset)

Construct a new ProgramLocation for the given address. The address will be adjusted to the beginning of the code unit containing that address(if it exists). The original address can be retrieved using the "getByteAddress()" method.

Parameters:

program - the program associated with this program location (also used to obtain a code-unit-aligned address)

addr - address for the location

row - the row within the field.

col - - the display item index on the given row. (Note most fields only have one display item per row)

charOffset - - the character offset within the display item.

ProgramLocation

public ProgramLocation(Program program,
                       Address addr,
                       Address refAddr)

Construct a new ProgramLocation for the given address. The address will be adjusted to the beginning of the code unit containing that address(if it exists). The original address can be retrieved using the "getByteAddress()" method.

Parameters:

program - the program associated with this program location (also used to obtain a code-unit-aligned address)

addr - address for the location

refAddr - the "referred to" address if the location is over a reference

ProgramLocation

public ProgramLocation()

Default constructor required for restoring a program location from XML.

Method Detail

getComponentPath

public int[] getComponentPath()

Returns the componentPath for the codeUnit. Null will be returned if the object is an Instruction or a top-level Data object.

getProgram

public Program getProgram()

Returns program associated with location or null if not specified.

getAddress

public Address getAddress()

Returns the address associated with this location.
Note: this may not be the same as the byte address. For example, in a code unit location this may be the minimum address of the code unit that contains the byte address.

getByteAddress

public Address getByteAddress()

Returns the byte level address associated with this location.

getRefAddress

public Address getRefAddress()

Returns the "referred to" address if the location is over an address in some field.

saveState

public void saveState(SaveState obj)

Save this program location to the given save state object.

Parameters:

obj - the save state object for saving the location

prefix - prefix appended to the names of the save state items to make the entry unique

restoreState

public void restoreState(Program program1,
                         SaveState obj)

Restore this program location using the given program and save state object.

Parameters:

prefix - prefix appended to the names of the save state items to make the entry unique

getLocation

public static ProgramLocation getLocation(Program program,
                                          SaveState saveState)

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

equals

public boolean equals(java.lang.Object obj)

Overrides:

equals in class java.lang.Object

compareTo

public int compareTo(ProgramLocation other)

Specified by:

compareTo in interface java.lang.Comparable<ProgramLocation>

compareAddr NEW

protected static int compareAddr(Address addr1,
                                 Address addr2)

isValid

public boolean isValid(Program testProgram)

Returns true if this location represents a valid location in the given program

Parameters:

testProgram - the program to test if this location is valid.

Returns:

true if this location represents a valid location in the given program

getRow

public int getRow()

Returns the row within the program location.

Returns:

the row within the program location.

getCharOffset

public int getCharOffset()

Returns the character offset in the display item at the (row,col)

Returns:

the character offset in the display item at the (row,col)

getColumn

public int getColumn()

Returns the column index of the display piece represented by this location. For most locations, there is only one display item per row, in which case this value will be 0.