Interface IDMethodContext

All Superinterfaces:
ICFGOwnerContext, IVariableInformationProvider

public interface IDMethodContext extends IVariableInformationProvider
dexdec IR method context. A method context holds all intermediate (IR) information relative to the decompilation of a dex method, including factory methods to create IR instructions and IR expressions.
  • Method Details

    • verify

      void verify() throws IllegalStateException
      Self-verification. This method performs several consistency checks on the IR. On failure, the method will throw and an attempt will be made to dump the current IR CFG to a file named "failed.dot".
      Throws:
      IllegalStateException - thrown on verification failure
    • copy

      Create a copy of this context. This method is useful when optimizers need to operate and modify in depth a context and its elements (e.g. the CFG or exception-flow data), while the optimizer's success is not guaranteed. On failure, the copied context may be destroyed. On success, the context may be updated using the copied context, by using load(IDMethodContext)
      Returns:
      a new context, which is a deep duplication of this context
    • load

      void load(IDMethodContext sourceContext)
      Load the constituents of a source context into this context. This method is to be used in conjunction with copy().
      Parameters:
      sourceContext - a source context
    • getWatchdog

      Watchdog getWatchdog()
      Retrieve the optional decompilation watchdog. The watchdog embeds timing information and can be queried by decompilation components: a component can request a self-verification, which will result in an exception being thrown (and decompilation aborted) if the timeout is exceeded.
      Returns:
    • getDecompilationFlags

      int getDecompilationFlags()
      Retrieve the decompilation flags provided by the engine to decompile this method. Refer to IDecompilerUnit#FLAG_xxx constants.
      Returns:
    • isBatchDecompilation

      default boolean isBatchDecompilation()
      Convenience method checking for IDecompilerUnit.FLAG_BATCH_DECOMPILATION.
      Returns:
    • isParseExceptions

      boolean isParseExceptions()
      Determine whether exception information will be parsed and integrated within the initial Intermediate Representation, when the Dalvik code is converted to IR.
      Returns:
    • isParseDebugInfo

      boolean isParseDebugInfo()
      Determine whether debug information (in particular, variable names) will be ported over variables created during the conversion to Intermediate Representation.
      Returns:
    • getGlobalContext

      IDGlobalContext getGlobalContext()
      Retrieve the global IR context, shared by all IR method contexts. The global context (also referred to as 'intermediate context') is managed by the decompiler.
      Returns:
    • getOperatorFactory

      IJavaOperatorFactory getOperatorFactory()
      Retrieve the global high-level operator factory. The type factory can be used to create all operators, including conditionals, string concatenation, and create cast operators.
      Returns:
    • getTypeFactory

      IJavaTypeFactory getTypeFactory()
      Retrieve the global high-level type factory.
      Returns:
    • getTypeInfoProvider

      IDTypeInfoProvider getTypeInfoProvider()
      Retrieve the type information provider. This provider can access additional, user-provided libraries (jar, dex) to retrieve information on types referenced but not defined in the underlying dex unit.
      Returns:
    • getDex

      IDexUnit getDex()
      Retrieve the underlying dex unit.
      Returns:
    • getMethod

      IDexMethod getMethod()
      Retrieve a reference to the dex method being decompiled.
      Returns:
    • getMethodSignature

      String getMethodSignature()
      Retrieve the original signature of the method being decompiled.
      Returns:
    • getParametersTypeMap

      SortedMap<Integer,IJavaType> getParametersTypeMap()
      Retrieve the type map for the decompiled method. The map keys are Dalvik input slot indices. The special index -1 indicates the return value type, if the method returns a value. The first entry is this, if the method is non-static. Although types long and double use two slots, only the first slot number is returned. Other primitives and reference type objects use a single slot.

      - Example: virtual method f() of class A using 10 registers:
      int f(char, double, String) => map= (-1:int, 5:ref_A, 6:char, 7:double, 9:String)

      - Example: static method g() of class B using 20 registers:
      void g(long, long, Object, boolean) => map= (14:long, 16:long, 18:Object, 19:boolean)

      Returns:
    • getCfg

      CFG<IDInstruction> getCfg()
      Get the current IR (intermediate representation) CFG of the decompiled method. As the method advances in the decompilation pipeline, the IR gets refined. When it is fully refined, the final IR is converted to a Java AST.
      Returns:
    • getExceptionData

      IDTryData getExceptionData()
      Retrieve the exception information for the current IR, if the exception information were parsed when the Dalvik method was converted to IR.
      Returns:
      an exception information object, which may be empty if the method is unprotected or if isParseExceptions() was false when this object as built
    • replace

      void replace(CFG<IDInstruction> replCfg, IDTryData replExdata)
      Replace the current IR by a new CFG and exception information.

      This method should be seldom called; most times, modifying the CFG itself is sufficient. However, in some cases, a full replacement may be necessary.

      Parameters:
      replCfg - new CFG
      replExdata - new exception data (may be null)
    • replaceCFG

      void replaceCFG(CFG<IDInstruction> cfg2, Map<Integer,Integer> oldToNewOffsets)
      Replace the current IR by a new CFG and exception information. It is recommended to use replace(CFG, IDTryData) instead.

      This method should be seldom called; most times, modifying the CFG itself is sufficient. However, in some cases, a full replacement may be necessary.

      Parameters:
      cfg2 - new CFG
      oldToNewOffsets - mandatory map map specifying a correspondence "old IR offset to new IR offset" for each instruction of the CFG (this map is currently used to update various internal structures as well as IR exception information)
    • makeSSA

      void makeSSA()
      Convert this CFG to SSA (static single assignment) form. An SSA form should be generated before attempting to apply types. This method is reserved for internal use.
    • isSSA

      boolean isSSA()
      Determine whether the CFG was converted to an SSA form.
      Returns:
      true if the CFG was SSA'ed
    • propagateTypes

      void propagateTypes()
      Perform type determination and propagation on the CFG. The CFG should be in SSA form before doing so. This method is reserved for internal use.
    • getVariableMap

      SortedMap<Integer,IDVar> getVariableMap()
      Retrieve a read-only map of all variables created by this context.
      Returns:
    • isStaticMethod

      boolean isStaticMethod()
      Determine whether the dalvik method in this IR context is static or non-static.
      Returns:
      true if this context is for a static method, false otherwise
    • getParameterVariables

      List<IDVar> getParameterVariables()
      Retrieve the list of variables that hold the method parameters. If the method is non-static, the first entry represents this.
      Returns:
      a list of variables
    • getVar

      IDVar getVar(int id)
      Retrieve a variable by id. This method may return null.
      Parameters:
      id - a variable id (not to be confused with Dalvik register number)
      Returns:
      a variable, or null if no variable with the provided id exists
    • getVar

      IDVar getVar(String name)
      Retrieve a variable by name. This method may return null.
      Parameters:
      name - a variable name (standard name, or custom name)
      Returns:
      a variable, or null if no variable with the provided name exists
    • createVar

      IDVar createVar(int id)
      Create or retrieve a variable.
      Parameters:
      id - variable id (not to be confused with Dalvik register number)
      Returns:
      a variable
    • createVar

      IDVar createVar(int id, IJavaType type)
      Create or retrieve a variable. Caution: if the variable with the provided id already exists, it will be returned by this method without performing type check: the requested type at creation may not be the type of the returned (already existing) variable.
      Parameters:
      id - variable id (not to be confused with Dalvik register number)
      type - mandatory type
      Returns:
      a variable
    • createVar

      IDVar createVar(int id, IJavaType type, boolean performTypeCheckIfExists)
      Create or retrieve a variable.
      Parameters:
      id - variable id (not to be confused with Dalvik register number)
      type - mandatory type
      performTypeCheckIfExists - if false: if the variable with the provided id already exists, it will be returned by this method without performing type check: the requested type may not be the type of the returned (already existing) variable; if true: this method will throw an IllegalArgumentException if an already existing variable does not have the requested type
      Returns:
      a variable
    • createRegisterVar

      IDVar createRegisterVar(int regnum, IJavaType type)
      Create a variable mapping to a physical Dalvik register (or pair of registers). This method is used during the initial decompilation phase when the bytecode is converted to low-level IR.
      Parameters:
      regnum - dalvik register number (first register in the case of a pair)
      type - variable type
      Returns:
      a variable
    • createCopyVar

      IDVar createCopyVar(IDVar srcVar)
      Create a copy-variable. If the source variable has a preferred name, it is copied to the newly-created variable.
      Parameters:
      srcVar - a primary variable, whose id is in [0, 0xFFFF] or [0x10000, 0x1FFFE]
      Returns:
      a variable representing a copy of the provided variable
    • createVirtualVar

      IDVar createVirtualVar(IJavaType type)
      Create a virtual variable. A virtual variable does not map back to physical registers.
      Parameters:
      type - variable type
      Returns:
      the created variable
    • retrievePhysicalRegisterId

      int retrievePhysicalRegisterId(int varid)
      Retrieve the underlying register used by a variable. If the variable uses a long type, the first register of the pair is returned. If the variable is virtual, -1 is returned.
      Parameters:
      varid - a variable id
      Returns:
      a register id in [0, 0xFFFF] if the variable is backed or indirectly backed by a physical register; -1 if the variable is "virtual", not backed by a register
    • retrievePrimaryVariableId

      int retrievePrimaryVariableId(int varid)
      Retrieve the primary variable id from a variable. If the variable directly maps a register or pair of registers, or is virtual, its id is simply returned. If the variable is a copy of another variable, the id of the copied variable is provided.
      Parameters:
      varid - a variable id
      Returns:
      the original (non-copied) variable id, which may be the provided id itself
    • createNop

      IDInstruction createNop()
      Create a no-operation instruction. Opcode: DOpcodeType.IR_NOP.
      Returns:
    • createAssign

      IDInstruction createAssign(IDExpression dst, IDExpression src)
      Create an assignment instruction. Opcode: DOpcodeType.IR_ASSIGN.
      Parameters:
      dst -
      src -
      Returns:
    • createConstruct

      IDInstruction createConstruct(IDNewInfo info)
      Create a new Object(...) instruction. Opcode: DOpcodeType.IR_INVOKE.
      Parameters:
      info -
      Returns:
    • createInvoke

      IDInstruction createInvoke(IDCallInfo info)
      Create an invocation instruction. Opcode: DOpcodeType.IR_INVOKE.
      Parameters:
      info -
      Returns:
    • createNewArray

      IDInstruction createNewArray(IDNewArrayInfo info)
      Create a new array instruction. Opcode: DOpcodeType.IR_INVOKE.
      Parameters:
      info -
      Returns:
    • createJump

      IDInstruction createJump(int irTargetOffset)
      Create a goto (unconditional jump) instruction. Opcode: DOpcodeType.IR_JUMP.
      Parameters:
      irTargetOffset -
      Returns:
    • createJcond

      IDInstruction createJcond(int irTargetOffset, IDExpression cond)
      Create a jcond (conditional jump) instruction. Opcode: DOpcodeType.IR_JCOND.
      Parameters:
      irTargetOffset -
      cond -
      Returns:
    • createSwitch

      IDInstruction createSwitch(IDExpression swexp, IDSwitchData data)
      Create a switch instruction. Opcode: DOpcodeType.IR_SWITCH.
      Parameters:
      swexp -
      data -
      Returns:
    • createReturn

      IDInstruction createReturn(IDExpression exp)
      Create a return instruction. Opcode: DOpcodeType.IR_RETURN.
      Parameters:
      exp -
      Returns:
    • createThrow

      IDInstruction createThrow(IDExpression exp)
      Create a throw instruction. Opcode: DOpcodeType.IR_THROW.
      Parameters:
      exp -
      Returns:
    • createStoreException

      IDInstruction createStoreException(IDVar ident)
      Create an exception-store instruction. Opcode: DOpcodeType.IR_STORE_EXCEPTION.
      Parameters:
      ident -
      Returns:
    • createMonitorEnter

      IDInstruction createMonitorEnter(IDExpression exp)
      Create a monitor-enter instruction. Opcode: DOpcodeType.IR_MONITOR_ENTER.
      Parameters:
      exp -
      Returns:
    • createMonitorExit

      IDInstruction createMonitorExit(IDExpression exp)
      Create a monitor-exit instruction. Opcode: DOpcodeType.IR_MONITOR_EXIT.
      Parameters:
      exp -
      Returns:
    • createImm

      default IDImm createImm(long rawvalue, IJavaType type)
      This convenience IR factory method wraps around IDGlobalContext.createImm(long, IJavaType).
    • createBoolean

      default IDImm createBoolean(boolean value)
      Convenience IR factory method wrapping around getGlobalContext().
    • createByte

      default IDImm createByte(byte value)
      Convenience IR factory method wrapping around getGlobalContext().
    • createChar

      default IDImm createChar(char value)
      Convenience IR factory method wrapping around getGlobalContext().
    • createShort

      default IDImm createShort(short value)
      Convenience IR factory method wrapping around getGlobalContext().
    • createInt

      default IDImm createInt(int value)
      Convenience IR factory method wrapping around getGlobalContext().
    • createLong

      default IDImm createLong(long value)
      Convenience IR factory method wrapping around getGlobalContext().
    • createFloat

      default IDImm createFloat(float value)
      Convenience IR factory method wrapping around getGlobalContext().
    • createDouble

      default IDImm createDouble(double value)
      Convenience IR factory method wrapping around getGlobalContext().
    • createNull

      default IDImm createNull()
      Convenience IR factory method wrapping around getGlobalContext().
    • createString

      default IDImm createString(String value)
      Convenience IR factory method wrapping around getGlobalContext().
    • createString

      default IDImm createString(IDIndex stringIndex)
      Convenience IR factory method wrapping around getGlobalContext().
    • createArrayElt

      default IDArrayElt createArrayElt(IDExpression array, IDExpression index, IJavaType type)
      Convenience IR factory method wrapping around getGlobalContext().
    • createOperation

      default IDOperation createOperation(IJavaType type, JavaOperatorType optype, IDExpression opnd1, IDExpression opnd2)
      Convenience IR factory method wrapping around getGlobalContext().
    • createOperation

      default IDOperation createOperation(IJavaType type, IDExpression left, IJavaOperator operator, IDExpression right)
      Convenience IR factory method wrapping around getGlobalContext().
    • createCast

      default IDOperation createCast(IJavaType casttype, IDExpression e)
      Convenience IR factory method wrapping around getGlobalContext().
    • createConditional

      default IDOperation createConditional(IJavaType type, IDExpression pred, IDExpression expTrue, IDExpression expFalse)
      Convenience IR factory method wrapping around getGlobalContext().
    • createPredicate

      default IDOperation createPredicate(JavaOperatorType optype, IDExpression opnd1, IDExpression opnd2)
      Convenience IR factory method wrapping around getGlobalContext().
    • createPredicate

      default IDOperation createPredicate(IDExpression left, IJavaOperator operator, IDExpression right)
      Convenience IR factory method wrapping around getGlobalContext().
    • createReferenceType

      default IDReferenceType createReferenceType(IDIndex cindex, IJavaType ctype)
      Convenience IR factory method wrapping around getGlobalContext().
    • createReferenceType

      default IDReferenceType createReferenceType(String csig)
      Convenience IR factory method wrapping around getGlobalContext().
    • createIndex

      default IDIndex createIndex(int value)
      Convenience IR factory method wrapping around getGlobalContext().
    • createStaticField

      default IDStaticField createStaticField(IDIndex index, IJavaType fieldtype, String csig, String fieldname)
      Convenience IR factory method wrapping around getGlobalContext().
    • createInstanceField

      default IDInstanceField createInstanceField(IDExpression instance, IDIndex index, IJavaType fieldtype, String fieldname)
      Convenience IR factory method wrapping around getGlobalContext().
    • createClassObject

      default IDStaticField createClassObject(String csig)
      Convenience IR factory method wrapping around getGlobalContext().
    • createArrayLength

      default IDInstanceField createArrayLength(IDExpression instance)
      Convenience IR factory method wrapping around getGlobalContext().
    • createCallInfo

      default IDCallInfo createCallInfo(IDIndex methodindex, IDExpression[] arguments, IJavaType returntype, String methodsig, DInvokeType invoketype)
      Convenience IR factory method wrapping around getGlobalContext().
    • createCallInfo

      default IDCallInfo createCallInfo(IDIndex methodindex, List<IDExpression> arguments, IJavaType returntype, String methodsig, DInvokeType invoketype)
      Convenience IR factory method wrapping around getGlobalContext().
    • createCallInfo

      default IDCallInfo createCallInfo(DInvokeType invoketype, int methodindex, List<IDExpression> arguments)
      Convenience IR factory method wrapping around getGlobalContext().
    • createNewInfo

      default IDNewInfo createNewInfo(String constructorSig, IDExpression... arguments)
      Convenience IR factory method wrapping around getGlobalContext().
    • createNewInfo

      default IDNewInfo createNewInfo(IJavaType objecttype, IJavaType constclasstype, IDIndex constructorindex, IDExpression[] arguments, String methodsig)
      Convenience IR factory method wrapping around getGlobalContext().
    • createNewInfo

      default IDNewInfo createNewInfo(IJavaType objecttype, IJavaType constclasstype, IDIndex constructorindex, List<IDExpression> arguments, String methodsig)
      Convenience IR factory method wrapping around getGlobalContext().
    • createNewArrayInfo

      default IDNewArrayInfo createNewArrayInfo(IJavaType type, IDExpression size, List<IDExpression> initvals)
      Convenience IR factory method wrapping around getGlobalContext().
    • createByteArray

      default IDNewArrayInfo createByteArray(byte[] bytes)
      Convenience IR factory method wrapping around getGlobalContext().
    • createTarget

      default IDTarget createTarget(int offset)
      Convenience IR factory method wrapping around getGlobalContext().
    • createSwitchData

      default IDSwitchData createSwitchData()
    • setData

      Object setData(String key, Object value)
      Store an arbitrary object in this context.
      Parameters:
      key - non-null key
      value - null means remove the entry
      Returns:
      the previous value associated with the key
    • getData

      Object getData(String key)
      Retrieve an arbitrary object in this context.
      Parameters:
      key -
      Returns:
    • getDataKeys

      Set<String> getDataKeys()
      Retrieve the set of objects keys for data elements stored using setData.
      Returns:
      a read-only collection