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

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

Constructor Summary

Constructors

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

Modifier and Type	Method	Description
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 code unit.
static ProgramLocation	getLocation(Program program, SaveState saveState)	Get the program location for the given program and save state object.
Program	getProgram()	Returns the program associated with this location.
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

protected Program program

addr

protected Address addr

refAddr

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.

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

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.

Throws:

java.lang.NullPointerException - if addr or program is null

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.

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.

Throws:

java.lang.NullPointerException - if addr or program is null

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

Throws:

java.lang.NullPointerException - if addr or program is null

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.

Throws:

java.lang.NullPointerException - if addr or program is null

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

Throws:

java.lang.NullPointerException - if addr or program is null

ProgramLocation

public ProgramLocation()

Default constructor required for restoring a program location from XML.

Method Detail

getComponentPath

public int[] getComponentPath()

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

getProgram

public Program getProgram()

Returns the program associated with this location.

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

restoreState

public void restoreState(Program program1,
                         SaveState obj)

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

Parameters:

program1 - program to restore from

obj - the save state to restore from

getLocation

public static ProgramLocation getLocation(Program program,
                                          SaveState saveState)

Get the program location for the given program and save state object.

Parameters:

program - the program for the location

saveState - the state to restore

Returns:

the restored program location

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

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.