# Interface: com.pnfsoftware.jeb.core.units.code.asm.analyzer.INativeCodeAnalyzerExtension

Definition of [analyzer](INativeCodeAnalyzer) extensions. A collection of heuristics to improve the generic code analyzer. Clients should inherit from [AbstractAnalyzerExtension](AbstractAnalyzerExtension), which provides default implementations, and implement only the needed methods.

## Method: customizeInstructionItem
- parameter: `item`, type: `com.pnfsoftware.jeb.core.units.code.asm.items.INativeInstructionItem`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.ChainedOperationResult<java.lang.Boolean>`

Description: Customize an instruction item just after its creation by the code analyzer.
parameter: item: instruction item
return: true if the item was customized

## Method: determinePotentialPointers
- parameter: `address`, type: `long`
- parameter: `insn`, type: `InsnType`
- parameter: `values`, type: `java.util.List<com.pnfsoftware.jeb.core.units.code.Pointer>`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.ChainedOperationResult<java.lang.Boolean>`

Description: Determine pointers \(addresses to data or code\) contained in the provided instruction, to let the code analyzer enqueue them for additional analysis. This method is called by the [INativeCodeAnalyzer](INativeCodeAnalyzer) **on non breaking flow instructions** before it tries to determine such additions itself.
parameter: address: address of the instruction
parameter: insn: instruction to be examined
parameter: values: output collection of pointers
return: a Boolean in [ChainedOperationResult#getResult()](ChainedOperationResult#getResult()); false to let the code         analyzer proceed with its own \(generic\) pointer discovery algorithm; true to instruct         it to skip it

## Method: determinePotentialPointersInProtoBlock
- parameter: `blk`, type: `com.pnfsoftware.jeb.core.units.code.IBasicBlockSkeleton<InsnType>`
- parameter: `values`, type: `java.util.List<com.pnfsoftware.jeb.core.units.code.PointerLocation>`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.ChainedOperationResult<java.lang.Boolean>`

Description: Determine additional pointers to be analyzed \(addresses to data or code\) that may be inferred from the analysis of the provided basic block skeleton \(proto\-basic block\). This method is called by the [INativeCodeAnalyzer](INativeCodeAnalyzer) after a basic block is preliminary terminated.
parameter: blk: preliminary basic block to be examined
parameter: values: output collection of pointers
return: N/A

## Method: determineRoutineStackPointerDelta
- parameter: `routine`, type: `com.pnfsoftware.jeb.core.units.code.asm.cfg.CFG<InsnType>`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.ChainedOperationResult<java.lang.Integer>`

Description: Determine \(heuristically\) the stack pointer delta generated by the execution of a routine.
parameter: routine: routine CFG
return: an Integer in [ChainedOperationResult#getResult()](ChainedOperationResult#getResult()), null if the routine failed         to determine the stack pointer delta

## Method: determineSwitchInformation
- parameter: `branchInstructionAddress`, type: `long`
- parameter: `branchInstructionBlock`, type: `com.pnfsoftware.jeb.core.units.code.IBasicBlockSkeleton<InsnType>`
- parameter: `knownBlocks`, type: `java.util.List<com.pnfsoftware.jeb.core.units.code.IBasicBlockSkeleton<InsnType>>`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.ChainedOperationResult<com.pnfsoftware.jeb.core.units.code.asm.analyzer.SwitchInformation>`

Description: Determine \(heuristically\) the information related to a switch\-like statement, i.e. the list of reachable [CodePointer](CodePointer) \(case handlers\) and the jump table addresses \(if any\). 

 This method works on not\-yet\-built routines, i.e. using [IBasicBlockSkeleton](IBasicBlockSkeleton).
parameter: branchInstructionAddress: branch instruction address
parameter: branchInstructionBlock: basic block containing the branch instruction
parameter: knownBlocks: known proto\-basic blocks
return: [SwitchInformation](SwitchInformation) in [ChainedOperationResult#getResult()](ChainedOperationResult#getResult()) \(might be         empty\), null if the routine failed

## Method: getPossiblePaddingSize
- parameter: `address`, type: `long`
- parameter: `addressMax`, type: `long`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.ChainedOperationResult<java.lang.Long>`

Description: Determine if a given memory area *looks like* \(could be\) starting with padding, and provides the size of the padding looking area, if any.
parameter: address: address to be examined \(inclusive\)
parameter: addressMax: end address to be examined \(exclusive\)
return: a Long in [ChainedOperationResult#getResult()](ChainedOperationResult#getResult()); the size of the padding\-like         area from address, 0L if it does not look like padding

## Method: getPreferredAdvancedAnalysisStage
- parameter: `routine`, type: `com.pnfsoftware.jeb.core.units.code.asm.items.INativeMethodItem`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.ChainedOperationResult<com.pnfsoftware.jeb.core.units.code.asm.decompiler.NativeDecompilationStage>`

Description: Determine which [NativeDecompilationStage](NativeDecompilationStage) should be used by [INativeCodeAdvancedAnalyzer](INativeCodeAdvancedAnalyzer) for the given routine. 

 The default implementation returns [NativeDecompilationStage#SIMULATION](NativeDecompilationStage#SIMULATION)
parameter: routine: routine item
return: [NativeDecompilationStage](NativeDecompilationStage) in [ChainedOperationResult#getResult()](ChainedOperationResult#getResult())

## Method: getPreferredBreakingFlow
- parameter: `address`, type: `long`
- parameter: `insn`, type: `InsnType`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.ChainedOperationResult<com.pnfsoftware.jeb.core.units.code.IFlowInformation>`

Description: Provide alternate/custom breaking\-flow information. If no custom information is to be provided, the implementation should return a null object. Upon a null return, it is the responsibility of the caller to retrieve the standard breaking\-flow information \([IInstruction#getBreakingFlow(long)](IInstruction#getBreakingFlow(long))\).
parameter: address: instruction address
parameter: insn: parsed instruction
return: a custom flow\-information object or null

## Method: getPrimitiveSizes
- parameter: `subsystemType`, type: `com.pnfsoftware.jeb.core.units.codeobject.SubsystemType`
- parameter: `compilerType`, type: `com.pnfsoftware.jeb.core.units.codeobject.CompilerType`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.type.IPrimitiveSizes`

Description: This method is called by the code unit to retrieve primitive type information.
parameter: subsystemType: optional hint
parameter: compilerType: optional hint
return: if null is returned, the code unit will attempt to generate the most appropriate         primitive type sizes

## Method: getProbableEntryPoints
- parameter: `address`, type: `long`
- parameter: `addressMax`, type: `long`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.ChainedOperationResult<java.util.List<com.pnfsoftware.jeb.core.units.code.CodePointer>>`

Description: Get the *likely* entry points in the given memory area. It might provide several entry points \(with different modes\) ordered by their likelihood. 

 This method is not guaranteed to give the correct result, and should be considered an heuristic. It is intended to be used before the actual disassembly of code; it may provide a hint on the entry point to disassemble with.
parameter: address: start address, inclusive
parameter: addressMax: end address, exclusive
return: a list of Integer representing entry points in         [ChainedOperationResult#getResult()](ChainedOperationResult#getResult()), ordered from the most probable to the         least probable. The list will be empty if none could be determined

## Method: getPrologueLooking
- parameter: `address`, type: `long`
- parameter: `addressMax`, type: `long`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.ChainedOperationResult<com.pnfsoftware.jeb.core.units.code.CodePointer>`

Description: Determine if a given memory area *looks like* \(could be\) the beginning of a routine.
parameter: address: address to be examined \(inclusive\)
parameter: addressMax: end address to be examined \(exclusive\)
return: an [CodePointer](CodePointer) in [ChainedOperationResult#getResult()](ChainedOperationResult#getResult()) if a prologue         was found, possibly at a different address than address parameter, null if no         prologue was found.

## Method: getTrampolineTarget
- parameter: `routine`, type: `com.pnfsoftware.jeb.core.units.code.asm.cfg.CFG<InsnType>`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.ChainedOperationResult<? extends com.pnfsoftware.jeb.core.units.code.Pointer>`

Description: Get the location targeted by a trampoline routine \-\- a routine that only branches to another location \-\-, if any. 

 Note: the target might be indirectly retrieved \(i.e. through a memory/register indirection\).
parameter: routine: candidate trampoline routine
return: a [Pointer](Pointer) in [ChainedOperationResult#getResult()](ChainedOperationResult#getResult()) for the target, null         if none \(i.e. routine is not a trampoline, or target could not be retrieved\) \(the         return value is not the target itself, but a pointer to the target\)

## Method: getUnit
- return type: `com.pnfsoftware.jeb.core.units.INativeCodeUnit<InsnType>`

Description: Get the code unit managing [INativeCodeAnalyzer](INativeCodeAnalyzer). This method allows extensions to easily retrieve properties of the managing code unit. 

 Important: no guarantee is given on the unit's state; this method should be used preferably to retrieve static features \(eg, unit's properties\).
return: code unit

## Method: initialize
- parameter: `analyzer`, type: `com.pnfsoftware.jeb.core.units.code.asm.analyzer.INativeCodeAnalyzer<InsnType>`

Description: Implementors will receive a reference to the main analyzer. This method is not to be called by third\-party code. It will be called by the GCA when the extension object \(this object\) is being initialized.
parameter: analyzer: analyzer using this extension

## Method: isCandidateSwitchDispatcher
- parameter: `branchInstructionAddress`, type: `long`
- parameter: `branchInstruction`, type: `InsnType`
- parameter: `branchInstructionBlock`, type: `com.pnfsoftware.jeb.core.units.code.IBasicBlockSkeleton<InsnType>`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.ChainedOperationResult<java.lang.Boolean>`

Description: Determine \(heuristically\) if the provided branching instruction \(jump/call/...\) could be the dispatcher of a switch\-like statement. 

 This method is intended to be a fast check, and candidates will then be processed by [#determineSwitchInformation(long, IBasicBlockSkeleton, List)](#determineSwitchInformation(long, IBasicBlockSkeleton, List)).
parameter: branchInstructionAddress: branch instruction address
parameter: branchInstruction: branch instruction
parameter: branchInstructionBlock: basic block containing the branch instruction
return: a boolean in [ChainedOperationResult#getResult()](ChainedOperationResult#getResult()); true if the instruction         might correspond to a switch\-like statement, false otherwise

## Method: isNonReturningRoutine
- parameter: `routine`, type: `com.pnfsoftware.jeb.core.units.code.asm.items.INativeMethodItem`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.ChainedOperationResult<java.lang.Boolean>`

Description: Determine if the given routine is non\-returning.
parameter: routine: routine item
return: a Boolean in [ChainedOperationResult#getResult()](ChainedOperationResult#getResult()); true if the routine does not         return, false otherwise, null when no determination could be made

## Method: postprocessImage
- parameter: `passIndex`, type: `int`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.ChainedOperationResult<java.lang.Boolean>`

Description: This method is called after the standard analysis pass completes \(i.e., before any optional advanced analysis takes place\).
parameter: passIndex: 0\-based analysis pass index
return: true if some processing

## Method: preprocessImage
- parameter: `passIndex`, type: `int`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.ChainedOperationResult<java.lang.Boolean>`

Description: This method is called before an analysis pass is performed.
parameter: passIndex: 0\-based analysis pass index
return: true if some processing

## Method: shouldForceRoutineEnd
- parameter: `address`, type: `long`
- parameter: `insn`, type: `InsnType`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.ChainedOperationResult<java.lang.Boolean>`

Description: Determine if the address is the last instruction of a routine. If true, the basic block containing the provided instruction will be closed, i.e. it will be as if the instruction breaks the flow to nothing. 

 When working with delay slots, this method will indicate routine end for the jump instruction that precedes the delay slot\(s\), not for the delay slot.
parameter: address: instruction address
parameter: insn: parsed instruction at the provided address
return: a Boolean in [ChainedOperationResult#getResult()](ChainedOperationResult#getResult()); true if the address should         be considered a routine termination, false otherwise

## Method: sigMatchingPostProcess
- parameter: `passIndex`, type: `int`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.ChainedOperationResult<java.lang.Boolean>`

Description: This method is called after signatures matching was performed.
parameter: passIndex: 0\-based analysis pass index
return: true if some processing

## Method: skipSymbolProcessing
- return type: `boolean`

Description: This method is called by the code unit to determine whether the symbols provided by the container unit \(e.g. ELF, PE, etc. if there is one\) should be processed. Processing symbols may enqueue code pointers and data pointers for subsequent code analysis.
return: true if symbol processing should be skipped

## Method: typeManagerInitialized
- parameter: `typeman`, type: `com.pnfsoftware.jeb.core.units.code.asm.type.ITypeManager`

Description: This method is called by the code unit right after it created a type manager suitable for processing. This happens before the code analysis starts. Implementors are free to customize the type manager, e.g. by adding types that will be required when further processing takes place.
parameter: typeman: initialized type manager

## Method: verifyGapRoutineCandidate
- parameter: `address`, type: `long`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.ChainedOperationResult<java.lang.Boolean>`

Description: Determine whether a candidate routine in a gap should be considered as valid.
parameter: address: routine start address
return: true or false \(no nulls\)

