public interface

IDExpression

implements IDElement
com.pnfsoftware.jeb.core.units.code.android.ir.IDExpression
Known Indirect Subclasses

Class Overview

Base interface for all dexdec IR expressions, such as IR instructions, fields/attributes, immediates, variables/identifiers, operations, etc.

Summary

[Expand]
Inherited Constants
From interface com.pnfsoftware.jeb.core.units.code.android.ir.IDElement
Public Methods
abstract IDArrayElt asArrayElt()
abstract IDCallInfo asCallInfo()
abstract IDReferenceType asClassReference()
This method is deprecated. use asReferenceType() instead
abstract IDImm asImm()
abstract IDInstanceField asInstanceField()
abstract IDInstruction asInstruction()
abstract IDNewArrayInfo asNewArrayInfo()
abstract IDNewInfo asNewInfo()
abstract IDOperation asOperation()
abstract IDPredicate asPredicate()
abstract IDReferenceType asReferenceType()
abstract IDStaticField asStaticField()
abstract IDVar asVar()
abstract boolean canThrow(IDMethodContext ctx)
Determine whether a hypothetical execution of this IR expression could throw.
abstract void collectAllPhysicalOffsets(Collection<Integer> physicalOffsets)
Gather all physical offsets for this element and all its constituents.
abstract void collectSubExpressions(List<IDExpression> sink)
Collect all sub-expressions of this expression, in evaluation order.
abstract void collectVarIds(Set<Integer> sink)
Recursively collect all the variable ids used and defined by this expression.
abstract IDExpression copy(DCopyOptions opt)
Copy this element.
abstract int countIdentifier(IDVar var)
This method is deprecated. use countVariable(IDVar) instead
abstract int countVariable(IDVar var)
Count how many times a given identifier is present in an expression.
abstract IDExpression duplicate()
Duplicate this element.
abstract IDImm evaluate(IDState state)
Evaluate this expression.
abstract IDImm evaluate(IDGlobalContext g, Map<Integer, IDImm> varmap)
Convenience method: evaluate a non-instruction IR expression using the provided set a variable values.
abstract IDImm evaluate(IDMethodContext ctx)
Convenience method: Evaluate this expression within the context of the provided method.
abstract Couple<IDExpressionIDExpression> find(IDExpression elt, int start, int comparisonMethod, IDExpression thisParent)
Find the parent of the the provided child element.
abstract <T extends IDExpression> T findByType(Class<T> clazz, int start)
Find a child element by type.
abstract <T extends IDExpression> T findByType(Class<T> clazz)
Find the first child element by type.
abstract IDExpression findParent(IDExpression elt, int start)
Find the parent of the the provided child element.
abstract IDExpression findParent(IDExpression elt)
Find the parent of the first instance of the provided child element.
abstract IJavaElement generateAST(IDMethodContext ctx, IJavaMethod m)
Generate the Java AST element for this IR expression.
abstract Boolean getCustomCanThrow()
Retrieve the custom override set for canThrow(IDMethodContext).
abstract Object getData(String key)
Retrieve a value from this IR element's data map.
abstract String getOrigin()
Retrieve the origin info string of this IR element, if there is one.
abstract int getPhysicalOffset()
Retrieve the physical offset (dalvik) associated with this IR.
abstract List<IDExpression> getSubExpressions()
Convenience method used to retrieve all the sub-expressions of this IR, in evaluation order.
abstract IJavaType getType()
Get the IR expression type.
abstract Set<Integer> getVarIds()
Recursively collect all the variable ids used and defined by this expression.
abstract boolean hasSideEffects(IDMethodContext ctx, boolean includeCanThrow)
Determine whether a hypothetical execution of this IR expression would change the program internal state.
abstract boolean isArrayElt()
abstract boolean isCallInfo(String wantedMsig)
abstract boolean isCallInfo()
abstract boolean isCastOperation(IJavaType expectedCastType)
abstract boolean isCastOperation()
abstract boolean isClassReference()
This method is deprecated. use isReferenceType() instead
abstract boolean isConstantImm()
abstract boolean isConstantImm(long expectedRawValue)
abstract boolean isImm()
abstract boolean isInstanceField()
abstract boolean isInstruction()
abstract boolean isNewArrayInfo()
abstract boolean isNewInfo()
abstract boolean isOperation(JavaOperatorType expectedOperatorType)
abstract boolean isOperation(JavaOperatorType expectedOperatorType1, JavaOperatorType expectedOperatorType2, JavaOperatorType expectedOperatorType3)
abstract boolean isOperation()
abstract boolean isOperation(JavaOperatorType expectedOperatorType1, JavaOperatorType expectedOperatorType2, JavaOperatorType expectedOperatorType3, JavaOperatorType expectedOperatorType4, JavaOperatorType expectedOperatorType5)
abstract boolean isOperation(JavaOperatorType expectedOperatorType1, JavaOperatorType expectedOperatorType2, JavaOperatorType expectedOperatorType3, JavaOperatorType expectedOperatorType4)
abstract boolean isOperation(JavaOperatorType expectedOperatorType1, JavaOperatorType expectedOperatorType2, JavaOperatorType expectedOperatorType3, JavaOperatorType expectedOperatorType4, JavaOperatorType expectedOperatorType5, JavaOperatorType expectedOperatorType6)
abstract boolean isOperation(JavaOperatorType expectedOperatorType1, JavaOperatorType expectedOperatorType2)
abstract boolean isPredicate()
abstract boolean isReferenceType()
abstract boolean isStaticField()
abstract boolean isStringConstant()
This method is deprecated. use isStringImm()
abstract boolean isStringImm()
abstract boolean isVar()
abstract boolean isVar(int wantedVarId)
abstract void removeData(String key)
Remove an entry from this IR element's data map.
abstract int replaceIdentifier(IDVar var, IDExpression repl)
This method is deprecated. use replaceVariable(IDVar, IDExpression) instead
abstract boolean replaceSubExpression(IDExpression target, IDExpression repl)
Replace an expression of this IR.
abstract int replaceVariable(IDVar var, IDExpression repl)
Deep replace all matching variables by the provided expression.
abstract void setCustomCanThrow(Boolean elemenCanThrow)
Set a custom override for canThrow(IDMethodContext).
abstract void setData(String key, Object value)
Store a key-value pair in this IR element's data map.
abstract void setOrigin(String origin)
Set an optional origin info string for this IR element.
abstract void setPhysicalOffset(int physicalOffset)
Set the main physical offset associated with this IR.
abstract boolean setType(IJavaType newType)
Update the type of an expression.
abstract boolean setType(IJavaType newType, DTypeInfo ti)
Update the type of an expression.
abstract boolean setType(IJavaType newType, DTypeInfo ti, boolean forceUpdate)
Update the type of an expression.
abstract void transferMetadataFrom(IDExpression srcExp)
Transfer (shallow copy) metadata from a source IR to this IR.
abstract void updateAllPhysicalOffsets(int physicalOffset)
Update the physical offset of this element and all its constituents.
abstract void updateTypes(DTypeInfo ti)
Deep update the types of the constituents of this IR expression and update to determine the IR type as well.
abstract boolean visitDepthPost(IDVisitor visitor, IDExpression parent, DVisitResults results)
Visit this expression and its constituents, depth-first post-order.
abstract boolean visitDepthPost(IDVisitor visitor, IDExpression parent)
Visit this expression and its constituents, depth-first post-order.
abstract boolean visitDepthPost(IDVisitor visitor)
Visit this expression and its constituents, depth-first post-order.
abstract boolean visitDepthPre(IDVisitor visitor)
Visit this expression and its constituents, depth-first pre-order.
abstract boolean visitDepthPre(IDVisitor visitor, IDExpression parent, DVisitResults results)
Visit this expression and its constituents, depth-first pre-order.
abstract boolean visitDepthPre(IDVisitor visitor, IDExpression parent)
Visit this expression and its constituents, depth-first pre-order.
[Expand]
Inherited Methods
From interface com.pnfsoftware.jeb.core.units.code.IInstructionOperand
From interface com.pnfsoftware.jeb.core.units.code.android.ir.IDElement

Public Methods

public abstract IDArrayElt asArrayElt ()

Returns

public abstract IDCallInfo asCallInfo ()

Returns

public abstract IDReferenceType asClassReference ()

This method is deprecated.
use asReferenceType() instead

public abstract IDImm asImm ()

Returns

public abstract IDInstanceField asInstanceField ()

Returns

public abstract IDInstruction asInstruction ()

Returns

public abstract IDNewArrayInfo asNewArrayInfo ()

Returns

public abstract IDNewInfo asNewInfo ()

Returns

public abstract IDOperation asOperation ()

Returns

public abstract IDPredicate asPredicate ()

Returns

public abstract IDReferenceType asReferenceType ()

Returns

public abstract IDStaticField asStaticField ()

Returns

public abstract IDVar asVar ()

Returns

public abstract boolean canThrow (IDMethodContext ctx)

Determine whether a hypothetical execution of this IR expression could throw.

This method is not fail-safe, it works on a best-effort basis.

Parameters
ctx mandatory method context

public abstract void collectAllPhysicalOffsets (Collection<Integer> physicalOffsets)

Gather all physical offsets for this element and all its constituents.

Parameters
physicalOffsets sink; it is recommended to provide a Set to avoid the collection of duplicates

public abstract void collectSubExpressions (List<IDExpression> sink)

Collect all sub-expressions of this expression, in evaluation order. If the full expression were to be evaluated at runtime, a sub-expression at index i in the list would be evaluated before a sub-expression at index i+1.

Parameters
sink a list to which all sub-expressions will be added

public abstract void collectVarIds (Set<Integer> sink)

Recursively collect all the variable ids used and defined by this expression.

Parameters
sink collection receiving the variable ids

public abstract IDExpression copy (DCopyOptions opt)

Copy this element. This operation can be seen as a custom duplication; the resulting element may not be of the same type as this element.

Parameters
opt optional; if one is provided, onDup(IDExpression) will be tried first to create a copy
Returns
  • the copied element

public abstract int countIdentifier (IDVar var)

This method is deprecated.
use countVariable(IDVar) instead

public abstract int countVariable (IDVar var)

Count how many times a given identifier is present in an expression. Matching is done using same.

Parameters
var a variable
Returns
  • the number of occurrences of this variable in this IR expression

public abstract IDExpression duplicate ()

Duplicate this element.

Returns
  • a deep copy of this element; the type of the duplicated element should be the same as this element's type

public abstract IDImm evaluate (IDState state)

Evaluate this expression.

Note about evaluating instructions: When evaluating an IDInstruction, a context and frame must be present in the state. The value of PC is not directly updated after the execution of this instruction. Instead, the next expected PC is stored in the current frame, and can be retrieved via getNextPC(). Only the evaluation of ASSIGN, RETURN, INVOKE IR instructions may return a value; else, the method will return null.

To perform emulation of a stub of IR with full controls, use methods in IDState directly.

Parameters
state a machine state
Returns
Throws
DexDecEvaluationException on evaluation error

public abstract IDImm evaluate (IDGlobalContext g, Map<Integer, IDImm> varmap)

Convenience method: evaluate a non-instruction IR expression using the provided set a variable values.

Parameters
g global IR context
varmap a map of variable values to be used when evaluating the expression
Returns

public abstract IDImm evaluate (IDMethodContext ctx)

Convenience method: Evaluate this expression within the context of the provided method.

See important note in evaluate(IDState).

Parameters
ctx method context
Returns
Throws
DexDecEvaluationException on evaluation error

public abstract Couple<IDExpressionIDExpression> find (IDExpression elt, int start, int comparisonMethod, IDExpression thisParent)

Find the parent of the the provided child element.

Parameters
elt an IR element; if the element is this, the method will return null
start count of instances of elt that should be skipped before returning the parent element; this is useful is the element provided may not be unique within the tree (e.g. var)
comparisonMethod 0= identity, 1= equality, 2= type-less equality
thisParent optional parent of this IR element
Returns
  • if found, the pair (parent, element) parent; else, null

public abstract T findByType (Class<T> clazz, int start)

Find a child element by type.

Parameters
clazz type of the element to be found; careful, if the type is the one of this, then this object will be returned
start count of matched elements that should be skipped before returning the element
Returns
  • the element or null

public abstract T findByType (Class<T> clazz)

Find the first child element by type.

Parameters
clazz type of the element to be found; careful, if the type is the one of this, then this object will be returned
Returns
  • the element or null

public abstract IDExpression findParent (IDExpression elt, int start)

Find the parent of the the provided child element. The comparison is done by identity.

Parameters
elt an IR element; if the element is this, the method will return null
start count of instances of elt that should be skipped before returning the parent element; this is useful is the element provided may not be unique within the tree (e.g. var)
Returns
  • the parent or null

public abstract IDExpression findParent (IDExpression elt)

Find the parent of the first instance of the provided child element. The comparison is done by identity.

Parameters
elt an IR element; if the element is this, the method will return null
Returns
  • the parent or null

public abstract IJavaElement generateAST (IDMethodContext ctx, IJavaMethod m)

Generate the Java AST element for this IR expression.

Parameters
ctx IR method context (of which this IR element belongs)
m AST Method context (of which the resulting AST element will belong)
Returns
  • the generated AST element

public abstract Boolean getCustomCanThrow ()

Retrieve the custom override set for canThrow(IDMethodContext). See setCustomCanThrow(Boolean) for details.

Note: Currently, the custom value is only supported by IDArrayElt.

Returns
  • the custom value, or null if none was set

public abstract Object getData (String key)

Retrieve a value from this IR element's data map.

Parameters
key mandatory key
Returns
  • value associated with the key, null if none

public abstract String getOrigin ()

Retrieve the origin info string of this IR element, if there is one.

public abstract int getPhysicalOffset ()

Retrieve the physical offset (dalvik) associated with this IR.

Returns
  • a dalvik method offset (in bytes); -1 if there is no offset associated with the IR

public abstract List<IDExpression> getSubExpressions ()

Convenience method used to retrieve all the sub-expressions of this IR, in evaluation order. Uses collectSubExpressions(List).

Returns
  • a list of sub-expressions

public abstract IJavaType getType ()

Get the IR expression type.

Returns
  • the expression type

public abstract Set<Integer> getVarIds ()

Recursively collect all the variable ids used and defined by this expression.

Returns
  • a set of unique variable ids

public abstract boolean hasSideEffects (IDMethodContext ctx, boolean includeCanThrow)

Determine whether a hypothetical execution of this IR expression would change the program internal state.

This method is not fail-safe, it works on a best-effort basis.

Parameters
ctx method context
includeCanThrow if true, the possibility of this IR to raise exceptions is checked and considered to be a side-effect

public abstract boolean isArrayElt ()

Returns

public abstract boolean isCallInfo (String wantedMsig)

Returns
  • true if this IR is an IDCallInfo or its sub-type IDNewInfo invoking the provided method signature

public abstract boolean isCallInfo ()

Returns

public abstract boolean isCastOperation (IJavaType expectedCastType)

public abstract boolean isCastOperation ()

public abstract boolean isClassReference ()

This method is deprecated.
use isReferenceType() instead

public abstract boolean isConstantImm ()

Returns
  • true if this IR is an IDImm holding a non-reference immediate, that is, a primitive value or a pooled string. (For references, including the null references, this method will return false.)

public abstract boolean isConstantImm (long expectedRawValue)

public abstract boolean isImm ()

Returns
  • true if this IR is an IDImm

public abstract boolean isInstanceField ()

Returns

public abstract boolean isInstruction ()

Returns

public abstract boolean isNewArrayInfo ()

Returns

public abstract boolean isNewInfo ()

Returns

public abstract boolean isOperation (JavaOperatorType expectedOperatorType)

Parameters
expectedOperatorType an operator type
Returns
  • true if this IR is an operation of the provided type

public abstract boolean isOperation (JavaOperatorType expectedOperatorType1, JavaOperatorType expectedOperatorType2, JavaOperatorType expectedOperatorType3)

Parameters
expectedOperatorType1 an operator type
expectedOperatorType2 an operator type
expectedOperatorType3 an operator type
Returns
  • true if this IR is an operation of any of the provided types

public abstract boolean isOperation ()

Returns

public abstract boolean isOperation (JavaOperatorType expectedOperatorType1, JavaOperatorType expectedOperatorType2, JavaOperatorType expectedOperatorType3, JavaOperatorType expectedOperatorType4, JavaOperatorType expectedOperatorType5)

Parameters
expectedOperatorType1 an operator type
expectedOperatorType2 an operator type
expectedOperatorType3 an operator type
expectedOperatorType4 an operator type
expectedOperatorType5 an operator type
Returns
  • true if this IR is an operation of any of the provided types

public abstract boolean isOperation (JavaOperatorType expectedOperatorType1, JavaOperatorType expectedOperatorType2, JavaOperatorType expectedOperatorType3, JavaOperatorType expectedOperatorType4)

Parameters
expectedOperatorType1 an operator type
expectedOperatorType2 an operator type
expectedOperatorType3 an operator type
expectedOperatorType4 an operator type
Returns
  • true if this IR is an operation of any of the provided types

public abstract boolean isOperation (JavaOperatorType expectedOperatorType1, JavaOperatorType expectedOperatorType2, JavaOperatorType expectedOperatorType3, JavaOperatorType expectedOperatorType4, JavaOperatorType expectedOperatorType5, JavaOperatorType expectedOperatorType6)

Parameters
expectedOperatorType1 an operator type
expectedOperatorType2 an operator type
expectedOperatorType3 an operator type
expectedOperatorType4 an operator type
expectedOperatorType5 an operator type
expectedOperatorType6 an operator type
Returns
  • true if this IR is an operation of any of the provided types

public abstract boolean isOperation (JavaOperatorType expectedOperatorType1, JavaOperatorType expectedOperatorType2)

Parameters
expectedOperatorType1 an operator type
expectedOperatorType2 an operator type
Returns
  • true if this IR is an operation of any of the provided types

public abstract boolean isPredicate ()

Returns

public abstract boolean isReferenceType ()

Returns

public abstract boolean isStaticField ()

Returns

public abstract boolean isStringConstant ()

This method is deprecated.
use isStringImm()

public abstract boolean isStringImm ()

Returns
  • true if this IR is an IDImm holding a pooled String constant. (String references are not constants.)

public abstract boolean isVar ()

Returns
  • true if this IR is an IDVar

public abstract boolean isVar (int wantedVarId)

Parameters
wantedVarId a variable id
Returns
  • true if this IR is a variable having the provided id

public abstract void removeData (String key)

Remove an entry from this IR element's data map.

public abstract int replaceIdentifier (IDVar var, IDExpression repl)

This method is deprecated.
use replaceVariable(IDVar, IDExpression) instead

public abstract boolean replaceSubExpression (IDExpression target, IDExpression repl)

Replace an expression of this IR. This method does not perform deep replacement. The target expression is compared by equality.

Parameters
target IR expression to be replaced
repl replacement expression
Returns
  • true if the target was successfully replaced

public abstract int replaceVariable (IDVar var, IDExpression repl)

Deep replace all matching variables by the provided expression. Important notes:
- Matching is done by reference equality (IDVar are factory-created, no two variables created by the same context can have the same id)
- When a replacement is to be performed, a duplication of repl is done and used as the replacement expression to avoid reuse.
- The exploration is recursive: the constituents are explored for replacement.
- If this expression is itself an identifier, it will not be replaced; only the constituents are matched for replacement.

Parameters
var target variable to be replaced
repl expression that will replace the identifier
Returns
  • the number of replacements

public abstract void setCustomCanThrow (Boolean elemenCanThrow)

Set a custom override for canThrow(IDMethodContext). If one is set, canThrow(IDMethodContext) will return the override value instead of performing regular verifications to determine whether the IR element may raise.

Note: Currently, the custom value is only supported by IDArrayElt.

Parameters
elemenCanThrow custom value, null to reset

public abstract void setData (String key, Object value)

Store a key-value pair in this IR element's data map.

Parameters
key mandatory key
value mandatory value

public abstract void setOrigin (String origin)

Set an optional origin info string for this IR element. Note that the origin is stored as an entry in the data map.

public abstract void setPhysicalOffset (int physicalOffset)

Set the main physical offset associated with this IR.

Parameters
physicalOffset an offset, -1 for none

public abstract boolean setType (IJavaType newType)

Update the type of an expression.

Parameters
newType mandatory new type
Returns
  • true if the type was updated, false otherwise

public abstract boolean setType (IJavaType newType, DTypeInfo ti)

Update the type of an expression.

Parameters
newType mandatory new type
ti optional type information object, used to record type update results
Returns
  • true if the type was updated, false otherwise

public abstract boolean setType (IJavaType newType, DTypeInfo ti, boolean forceUpdate)

Update the type of an expression.

Parameters
newType mandatory new type
ti optional type information object, used to record type update results
forceUpdate if true, the new type will always be set (compatibility checks are bypassed)
Returns
  • true if the type was updated, false otherwise

public abstract void transferMetadataFrom (IDExpression srcExp)

Transfer (shallow copy) metadata from a source IR to this IR. Currently, this includes the physical offset and the data map.

Parameters
srcExp source IR expression

public abstract void updateAllPhysicalOffsets (int physicalOffset)

Update the physical offset of this element and all its constituents.

Parameters
physicalOffset new physical offset, -1 to reset (to none)

public abstract void updateTypes (DTypeInfo ti)

Deep update the types of the constituents of this IR expression and update to determine the IR type as well.

Parameters
ti optional type information object, used to record type updates and conflicts

public abstract boolean visitDepthPost (IDVisitor visitor, IDExpression parent, DVisitResults results)

Visit this expression and its constituents, depth-first post-order.

Parameters
visitor visitor object
parent the optional parent of this expression
results an optional result object provided to the visitor, containing flags used to customize the visiting process
Returns
  • success indicator; true unless a different value was specified in DVisitResults when visiting an element

public abstract boolean visitDepthPost (IDVisitor visitor, IDExpression parent)

Visit this expression and its constituents, depth-first post-order.

Parameters
visitor visitor object
parent the optional parent of this expression
Returns
  • success indicator; true unless a different value was specified in DVisitResults when visiting an element

public abstract boolean visitDepthPost (IDVisitor visitor)

Visit this expression and its constituents, depth-first post-order.

Parameters
visitor visitor object
Returns
  • success indicator; true unless a different value was specified in DVisitResults when visiting an element

public abstract boolean visitDepthPre (IDVisitor visitor)

Visit this expression and its constituents, depth-first pre-order.

If the visitor replaces an element, the new element must be specified by calling DVisitResults#setReplacedNode(IDExpression) setReplacedNode().

Parameters
visitor visitor object
Returns
  • success indicator; true unless a different value was specified in DVisitResults when visiting an element

public abstract boolean visitDepthPre (IDVisitor visitor, IDExpression parent, DVisitResults results)

Visit this expression and its constituents, depth-first pre-order.

If the visitor replaces an element, the new element must be specified by calling DVisitResults#setReplacedNode(IDExpression) setReplacedNode().

Parameters
visitor visitor object
parent the optional parent of this expression
results an optional result object provided to the visitor, containing flags used to customize the visiting process
Returns
  • success indicator; true unless a different value was specified in DVisitResults when visiting an element

public abstract boolean visitDepthPre (IDVisitor visitor, IDExpression parent)

Visit this expression and its constituents, depth-first pre-order.

If the visitor replaces an element, the new element must be specified by calling DVisitResults#setReplacedNode(IDExpression) setReplacedNode().

Parameters
visitor visitor object
parent the optional parent of this expression
Returns
  • success indicator; true unless a different value was specified in DVisitResults when visiting an element