Package com.pnfsoftware.jeb.core.units.code.android.ir

Interface IDExpression

All Superinterfaces:
IDElement, IInstructionOperand
All Known Subinterfaces:
IDAllocObjectInfo, IDArrayElt, IDCallInfo, IDField, IDImm, IDInstanceField, IDInstruction, IDInvokeInfo, IDNewArrayInfo, IDNewInfo, IDOperation, IDReferenceType, IDStaticField, IDVar
@Ser public interface IDExpression extends IDElement
Base interface for all dexdec IR expressions, such as IR instructions, fields/attributes, immediates, variables/identifiers, operations, etc.

  • Method Details

    • copy

      IDExpression copy(DCopyOptions opt)
      Description copied from interface: IDElement
      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.
      Specified by:
      copy in interface IDElement
      Parameters:
      opt - optional; if one is provided, DCopyOptions.onDup(IDExpression) will be tried first to create a copy
      Returns:
      the copied element

    • duplicate

      IDExpression duplicate()
      Description copied from interface: IDElement
      Duplicate this element.
      Specified by:
      duplicate in interface IDElement
      Returns:
      a deep copy of this element; the type of the duplicated element should be the same as this element's type

    • transferMetadataFrom

      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

    • setPhysicalMethodIndex

      void setPhysicalMethodIndex(int physicalMethodIndex)
      Set a low-level dex method index mapping to this IR element. This is useful to override the default (owner IDMethodContext's dex method), such as when a method contains inlined code from another method.
      Parameters:
      physicalMethodIndex - a lower-level dex method index, or -1 to signify none or the default

    • getPhysicalMethodIndex

      int getPhysicalMethodIndex()
      Retrieve the low-level dex method index mapping to this IR element.
      Returns:
      a lower-level method index, or -1 to signify the default (which is the IDMethodContext's dex method index)

    • collectAllPhysicalMethodIndices

      void collectAllPhysicalMethodIndices(Collection<Integer> physicalMethodIndices)
      Collect all low-level dex method indices mapped to this IR element and its constituents.
      Parameters:
      physicalMethodIndices - sink for physical method indices

    • updateAllPhysicalMethodIndices

      void updateAllPhysicalMethodIndices(int physicalMethodIndex)
      Update the low-level dex method index mapping for this IR element and its constituents.
      Parameters:
      physicalMethodIndex - new physical method index

    • setPhysicalOffset

      void setPhysicalOffset(int physicalOffset)
      Set the main physical offset associated with this IR.
      Parameters:
      physicalOffset - an offset, -1 for none

    • getPhysicalOffset

      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

    • collectAllPhysicalOffsets

      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

    • updateAllPhysicalOffsets

      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)

    • setData

      Object setData(String key, Object value)
      Store a key-value pair in this IR element's data map.
      Parameters:
      key - mandatory key
      value - mandatory value
      Returns:
      the previous value associated with this key

    • getData

      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

    • removeData

      void removeData(String key)
      Remove an entry from this IR element's data map.
      Parameters:
      key - mandatory key

    • setOrigin

      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.
      Parameters:
      origin - optional origin string

    • getOrigin

      String getOrigin()
      Retrieve the origin info string of this IR element, if there is one.
      Returns:
      origin string, or null

    • updateTypes

      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

    • getType

      IJavaType getType()
      Get the IR expression type.
      Returns:
      the expression type

    • checkType

      boolean checkType(IJavaType wantedType)
      Determine whether the expression type matches an expected type.
      Parameters:
      wantedType - expected type
      Returns:
      true if the type of the expression is as expected

    • setType

      boolean setType(IJavaType newType)
      Update the type of an expression.
      Parameters:
      newType - mandatory new type
      Returns:
      true if the type was updated, false otherwise

    • setType

      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

    • setType

      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

    • replaceVariable

      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

    • collectSubExpressions

      void collectSubExpressions(Collection<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 - collector for the sub-expressions

    • getSubExpressions

      default List<IDExpression> getSubExpressions()
      Convenience method used to retrieve all the sub-expressions of this IR, in evaluation order. Uses collectSubExpressions(Collection).
      Returns:
      a list of sub-expressions

    • replaceSubExpression

      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

    • collectVarIds

      void collectVarIds(Set<Integer> sink)
      Recursively collect all the variable ids used and defined by this expression.
      Parameters:
      sink - collection receiving the variable ids

    • getVarIds

      default Set<Integer> getVarIds()
      Recursively collect all the variable ids used and defined by this expression.
      Returns:
      a set of unique variable ids

    • countVariable

      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

    • setCustomCanThrow

      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

    • getCustomCanThrow

      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

    • canThrow

      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
      Returns:
      true if the expression may have side effects

    • hasSideEffects

      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
      Returns:
      true if the expression may throw

    • evaluate

      IDImm evaluate(IDState state) throws DexDecEvaluationException
      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 IDEmuFrame.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:
      the evaluated expression (be careful, it may be a reference-immediate!)
      Throws:
      DexDecEvaluationException - on evaluation error

    • evaluate

      IDImm evaluate(IDMethodContext ctx) throws DexDecEvaluationException
      Convenience method: Evaluate this expression within the context of the provided method.

      See important note in evaluate(IDState).

      Parameters:
      ctx - method context
      Returns:
      the evaluated expression (be careful, it may be a reference-immediate!)
      Throws:
      DexDecEvaluationException - on evaluation error

    • evaluate

      IDImm evaluate(IDGlobalContext g, Map<Integer,IDImm> varmap) throws DexDecEvaluationException
      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:
      the evaluation result (be careful, it may be a reference-immediate!)
      Throws:
      DexDecEvaluationException - on evaluation error

    • generateAST

      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

    • spawn

      IDImm spawn(long rawvalue)
      Create a new immediate IR with the provided 64-bit raw value, and the type of this IR expression.
      Parameters:
      rawvalue - raw bits
      Returns:
      the new immediate

    • visitDepthPre

      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 setReplacedNode().

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

    • visitDepthPre

      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 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

    • visitDepthPre

      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 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

    • visitDepthPost

      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

    • visitDepthPost

      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

    • visitDepthPost

      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

    • findParent

      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

    • findParent

      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

    • find

      Couple<IDExpression,IDExpression> 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

    • findByType

      <T extends IDExpression> T findByType(Class<T> clazz)
      Find the first child element by type.
      Type Parameters:
      T - expected element 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

    • findByType

      <T extends IDExpression> T findByType(Class<T> clazz, int start)
      Find a child element by type.
      Type Parameters:
      T - expected element 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

    • isInstruction

      default boolean isInstruction()
      Determine whether this IR is an instruction.
      Returns:
      true if this IR is an IDInstruction

    • asInstruction

      default IDInstruction asInstruction()
      Cast this IR to an instruction.
      Returns:
      this IR as an IDInstruction

    • isArrayElt

      default boolean isArrayElt()
      Determine whether this IR is an array element.
      Returns:
      true if this IR is an IDArrayElt

    • asArrayElt

      default IDArrayElt asArrayElt()
      Cast this IR to an array element.
      Returns:
      this IR as an IDArrayElt

    • isReferenceType

      default boolean isReferenceType()
      Determine whether this IR is a reference type expression.
      Returns:
      true if this IR is an IDReferenceType

    • asReferenceType

      default IDReferenceType asReferenceType()
      Cast this IR to a reference type expression.
      Returns:
      this IR as an IDReferenceType

    • isInstanceField

      default boolean isInstanceField()
      Determine whether this IR is an instance field expression.
      Returns:
      true if this IR is an IDInstanceField

    • asInstanceField

      default IDInstanceField asInstanceField()
      Cast this IR to an instance field expression.
      Returns:
      this IR as an IDInstanceField

    • isStaticField

      default boolean isStaticField()
      Determine whether this IR is a static field expression.
      Returns:
      true if this IR is an IDStaticField

    • asStaticField

      default IDStaticField asStaticField()
      Cast this IR to a static field expression.
      Returns:
      this IR as an IDStaticField

    • isOperation

      default boolean isOperation()
      Determine whether this IR is an operation.
      Returns:
      true if this IR is an IDOperation

    • isOperation

      default boolean isOperation(JavaOperatorType expectedOperatorType)
      Determine whether this IR is an operation of the provided type.
      Parameters:
      expectedOperatorType - an operator type
      Returns:
      true if this IR is an operation of the provided type

    • isOperation

      default boolean isOperation(JavaOperatorType expectedOperatorType1, JavaOperatorType expectedOperatorType2)
      Determine whether this IR is an operation of any of the provided types.
      Parameters:
      expectedOperatorType1 - an operator type
      expectedOperatorType2 - an operator type
      Returns:
      true if this IR is an operation of any of the provided types

    • isOperation

      default boolean isOperation(JavaOperatorType expectedOperatorType1, JavaOperatorType expectedOperatorType2, JavaOperatorType expectedOperatorType3)
      Determine whether this IR is an operation of any of the provided types.
      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

    • isOperation

      default boolean isOperation(JavaOperatorType expectedOperatorType1, JavaOperatorType expectedOperatorType2, JavaOperatorType expectedOperatorType3, JavaOperatorType expectedOperatorType4)
      Determine whether this IR is an operation of any of the provided types.
      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

    • isOperation

      default boolean isOperation(JavaOperatorType expectedOperatorType1, JavaOperatorType expectedOperatorType2, JavaOperatorType expectedOperatorType3, JavaOperatorType expectedOperatorType4, JavaOperatorType expectedOperatorType5)
      Determine whether this IR is an operation of any of the provided types.
      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

    • isOperation

      default boolean isOperation(JavaOperatorType expectedOperatorType1, JavaOperatorType expectedOperatorType2, JavaOperatorType expectedOperatorType3, JavaOperatorType expectedOperatorType4, JavaOperatorType expectedOperatorType5, JavaOperatorType expectedOperatorType6)
      Determine whether this IR is an operation of any of the provided types.
      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

    • isCastOperation

      default boolean isCastOperation()
      Determine whether this IR is a cast operation.
      Returns:
      true if this IR is a cast operation

    • isCastOperation

      default boolean isCastOperation(IJavaType expectedCastType)
      Determine whether this IR is a cast operation to an expected type.
      Parameters:
      expectedCastType - wanted cast type
      Returns:
      true if this IR is an operation casting to the wanted type

    • asOperation

      default IDOperation asOperation()
      Cast this IR to an operation.
      Returns:
      this IR as an IDOperation

    • isCallInfo

      default boolean isCallInfo()
      Determine whether this IR is call information.
      Returns:
      true if this IR is an IDCallInfo or its sub-type IDNewInfo

    • isCallInfo

      default boolean isCallInfo(String wantedMsig)
      Determine whether this IR is call information for a method signature.
      Parameters:
      wantedMsig - wanted method signature
      Returns:
      true if this IR is an IDCallInfo or its sub-type IDNewInfo invoking the provided method signature

    • asCallInfo

      default IDCallInfo asCallInfo()
      Cast this IR to call information.
      Returns:
      this IR as an IDCallInfo

    • isNewInfo

      default boolean isNewInfo()
      Determine whether this IR is new-instance information.
      Returns:
      true if this IR is an IDNewInfo

    • asNewInfo

      default IDNewInfo asNewInfo()
      Cast this IR to new-instance information.
      Returns:
      this IR as an IDNewInfo

    • isNewArrayInfo

      default boolean isNewArrayInfo()
      Determine whether this IR is new-array information.
      Returns:
      true if this IR is an IDNewArrayInfo

    • asNewArrayInfo

      default IDNewArrayInfo asNewArrayInfo()
      Cast this IR to new-array information.
      Returns:
      this IR as an IDNewArrayInfo

    • isImm

      default boolean isImm()
      Determine whether this IR is an immediate.
      Returns:
      true if this IR is an IDImm

    • isConstantImm

      default boolean isConstantImm()
      Determine whether this IR is a non-reference immediate.
      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.)

    • isConstantImm

      default boolean isConstantImm(long expectedRawValue)
      Determine whether this IR is a non-reference immediate with an expected raw value.
      Parameters:
      expectedRawValue - wanted value
      Returns:
      true if this IR is an IDImm holding a non-reference immediate with the provided raw value

    • isStringImm

      default boolean isStringImm()
      Determine whether this IR is a pooled string immediate.
      Returns:
      true if this IR is an IDImm holding a pooled String constant. (String references are not constants.)

    • asImm

      default IDImm asImm()
      Cast this IR to an immediate.
      Returns:
      this IR as an IDImm

    • isVar

      default boolean isVar()
      Determine whether this IR is a variable.
      Returns:
      true if this IR is an IDVar

    • isVar

      default boolean isVar(int wantedVarId)
      Determine whether this IR is a variable with an expected id.
      Parameters:
      wantedVarId - a variable id
      Returns:
      true if this IR is a variable having the provided id

    • asVar

      default IDVar asVar()
      Cast this IR to a variable.
      Returns:
      this IR as an IDVar