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

Definition of a code analyzer. Typically, a code analyzer is instantiated by a code unit. Clients should not attempt to create such objects. There exists one implementation of this object, provided to clients by the [INativeCodeUnit](INativeCodeUnit). This reference implementation supports partial concurrency: the [#analyze()](#analyze()) method may be called by concurrent threads. 

 An analysis pass consists of several sub\-passes: 
 
- standard analysis \(always\) 
- advanced analysis \(optional \- in settings \-, relies on decompilation\) 
- global analysis \(optional, plugin\-specific, may rely on decompilation\)

## Static Field: FLAG_CALLEE_DIRTY_ANALYSIS
Type: `int`

Constant value: `16`
Description: The analyzer should analyze callee routines with [INativeCodeAnalyzer#PERMISSION_DIRTY](INativeCodeAnalyzer#PERMISSION_DIRTY), whatever the caller's permission is.

## Static Field: FLAG_CALLEE_FORCEFUL_ANALYSIS
Type: `int`

Constant value: `8`
Description: The analyzer should analyze callee routines with [INativeCodeAnalyzer#PERMISSION_FORCEFUL](INativeCodeAnalyzer#PERMISSION_FORCEFUL), whatever the caller's permission is.

## Static Field: FLAG_CALLEE_GENTLE_ANALYSIS
Type: `int`

Constant value: `4`
Description: The analyzer should analyze callee routines with [INativeCodeAnalyzer#PERMISSION_GENTLE](INativeCodeAnalyzer#PERMISSION_GENTLE), whatever the caller's permission is.

## Static Field: FLAG_CODE_CONTIGUOUS
Type: `int`

Constant value: `2`
Description: The analyzer should parse the routine instructions sequentially. The routine is contiguous in memory, there is no instruction gap, and its size is known and stored in the high 24\-bits of the flags.

## Static Field: FLAG_DATA_UNSAFE
Type: `int`

Constant value: `65536`
Description: The analyzer should consider potential data found heuristically which is not safe \(in particular: address can be never reached, size may be unaccurate\)

## Static Field: FLAG_NO_CACHES_CHECK
Type: `int`

Constant value: `32`
Description: The analyzer should not check for previously cached results \(internal use only\).

## Static Field: FLAG_NO_MERGE
Type: `int`

Constant value: `64`
Description: The analyzer will not merge the newly created routine into another routine.

## Static Field: FLAG_NO_ROUTINE
Type: `int`

Constant value: `1`
Description: The analyzer will not create a routine

## Static Field: FLAG_TRANSIENT
Type: `int`

Constant value: `4096`
Description: The analyzer should consider data/routine as meaningless \(no cache, faster\). This can be used for mass data.

## Static Field: PERMISSION_DIRTY
Type: `int`

Constant value: `2`
Description: The analyzer may undefine items as well as pre\-existing routines 

 Note: PERMISSION\_\* values are integers ordered from the least permissive to the most permissive.

## Static Field: PERMISSION_FORCEFUL
Type: `int`

Constant value: `1`
Description: The analyzer may undefine existing overlapping instruction or data items if necessary 

 Note: PERMISSION\_\* values are integers ordered from the least permissive to the most permissive.

## Static Field: PERMISSION_GENTLE
Type: `int`

Constant value: `0`
Description: The analyzer does not undefine existing items. 

 Note: PERMISSION\_\* values are integers ordered from the least permissive to the most permissive.

## Static Field: PERMISSION_GOD_MODE
Type: `int`

Constant value: `3`
Description: The analyzer may undefine items as well as pre\-existing routines. This permission bypasses all analysis safeguards, and should be used with caution: keep this for user\-defined entry\-points. 

 Note: PERMISSION\_\* values are integers ordered from the least permissive to the most permissive.

## Method: analyze

Description: Start an analysis pass. Analyze the entry points that were previously registered, create new routines and data items, etc.

## Method: analyze
- parameter: `preventAdvancedAnalysis`, type: `boolean`
- parameter: `preventSiglibMatch`, type: `boolean`

Description: Start an analysis pass. Analyze the entry points that were previously registered, create new routines and data items, etc.
parameter: preventAdvancedAnalysis: if true, AA will be prevented no matter what
parameter: preventSiglibMatch: if true, siglibs application will not be prevented, no matter what

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

Description: Clear the pending analysis queue.
return: true if the queue was cleared

## Method: defineData
- parameter: `address`, type: `long`
- parameter: `type`, type: `com.pnfsoftware.jeb.core.units.code.asm.type.INativeType`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.items.INativeDataItem`

Description: Define a data item at an address.
parameter: address: data address
parameter: type: data type
return: data item, or null

## Method: defineData
- parameter: `address`, type: `long`
- parameter: `type`, type: `com.pnfsoftware.jeb.core.units.code.asm.type.INativeType`
- parameter: `appliedSize`, type: `int`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.items.INativeDataItem`

Description: Define a data item at an address.
parameter: address: data address
parameter: type: data type
parameter: appliedSize: applied data size
return: data item, or null

## Method: enqueuePointerForAnalysis
- parameter: `pointer`, type: `com.pnfsoftware.jeb.core.units.code.Pointer`
- return type: `boolean`

Description: Register a pointer \(code or data\) for a [gentle analysis](#enqueuePointerForAnalysis(Pointer, int)).
parameter: pointer: code or data pointer; code pointers must be of type            [ICodePointer](ICodePointer)
return: success indicator \(pointer was/not enqueued\)

## Method: enqueuePointerForAnalysis
- parameter: `pointer`, type: `com.pnfsoftware.jeb.core.units.code.Pointer`
- parameter: `permission`, type: `int`
- return type: `boolean`

Description: Register a pointer \(code or data\) for analysis. If the pointer is a code pointer, a routine may be created.
parameter: pointer: code or data pointer; code pointers must be of type            [ICodePointer](ICodePointer)
parameter: permission: analysis permission type, one of [#PERMISSION_GENTLE](#PERMISSION_GENTLE) \(0\),            [#PERMISSION_FORCEFUL](#PERMISSION_FORCEFUL), or [#PERMISSION_DIRTY](#PERMISSION_DIRTY)
return: success indicator \(pointer was/not enqueued\)

## Method: enqueuePointerForAnalysis
- parameter: `pointer`, type: `com.pnfsoftware.jeb.core.units.code.Pointer`
- parameter: `permission`, type: `int`
- parameter: `flags`, type: `int`
- return type: `boolean`

Description: Register a pointer \(code or data\) for analysis.
parameter: pointer: code or data pointer; code pointers must be of type [ICodePointer](ICodePointer)
parameter: permission: analysis permission type, one of [#PERMISSION_GENTLE](#PERMISSION_GENTLE) \(0\),            [#PERMISSION_FORCEFUL](#PERMISSION_FORCEFUL), or [#PERMISSION_DIRTY](#PERMISSION_DIRTY)
parameter: flags: analysis flags, a combination any `FLAG_xxx` entry \(for example:            [#FLAG_NO_ROUTINE](#FLAG_NO_ROUTINE)\)
return: success indicator \(pointer was/not enqueued\)

## Method: enqueueRoutineForReanalysis
- parameter: `routine`, type: `com.pnfsoftware.jeb.core.units.code.asm.items.INativeMethodItem`
- return type: `boolean`

Description: Enqueue an existing routine for reanalysis.
parameter: routine: method to be reanalyzed \(in DIRTY mode\)
return: success indicator \(pointer was/not enqueued\)

## Method: getAdvancedAnalyzer
- return type: `com.pnfsoftware.jeb.core.units.code.asm.analyzer.INativeCodeAdvancedAnalyzer<InsnType>`

Description: Retrieve a reference to the optional advanced analyzer object.
return: may be null

## Method: getAnalysisCount
- return type: `int`

Description: Get the number of times a code analysis was performed.
return: the number of times [#analyze()](#analyze()) was called and has terminated

## Method: getAnalysisRanges
- return type: `com.pnfsoftware.jeb.core.units.code.asm.analyzer.MemoryRanges`

Description: Retrieve a reference to the memory ranges that the analyzer works on.
return: analysis ranges

## Method: getAnalyzerExtensionsManager
- return type: `com.pnfsoftware.jeb.core.units.code.asm.analyzer.INativeCodeAnalyzerExtension<InsnType>`

Description: Retrieve a reference to the analyzer extensions manager. It manages extensions with architecture\-specific or compiler\-specific analysis routines.
return: analyzer extension manager

## Method: getContainer
- return type: `com.pnfsoftware.jeb.core.units.codeobject.ICodeObjectUnit`

Description: Retrieve a reference to the optional code object container that holds the code to be analyzed.
return: code object container, or null

## Method: getDebugInformationPolicy
- return type: `com.pnfsoftware.jeb.core.units.code.asm.analyzer.DebugInformationPolicy`

Description: Retrieve the debug information policy that this code analyzer is using. The analyzer and its extensions, when using debug metadata, should respect this policy.
return: a policy object

## Method: getDetectedCompiler
- return type: `com.pnfsoftware.jeb.core.units.code.asm.analyzer.ICompiler`

Description: Get the compiler detected when analyzing the input file.
return: may be null

## Method: getMemory
- return type: `com.pnfsoftware.jeb.core.units.code.asm.memory.IVirtualMemory`

Description: Retrieve a reference to the virtual memory.
return: virtual memory

## Method: getModel
- return type: `com.pnfsoftware.jeb.core.units.code.asm.analyzer.INativeCodeModel<InsnType>`

Description: Get the memory model managed by this analyzer.
return: the memory model

## Method: getProcessor
- return type: `com.pnfsoftware.jeb.core.units.code.asm.processor.IProcessor<InsnType>`

Description: Retrieve a reference to the machine code processor.
return: processor

## Method: getTypeManager
- return type: `com.pnfsoftware.jeb.core.units.code.asm.type.ITypeManager`

Description: Get a reference to the type manager.
return: type manager

## Method: getUnmanglerService
- return type: `com.pnfsoftware.jeb.core.units.code.asm.mangling.UnmanglerService`

Description: Retrieve the unmangler service \(managing name\-unmanging engines\) used by this analyzer.
return: unmangler service

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

Description: Determine if an analysis is already taking place, possibly in another thread. This method is purely indicative, and can be used by clients to minimize unnecessary blocking. The result offers no guarantee: by the time client code examines the boolean return value, another thread may have finished an existing or started a new analysis.
return: true if analysis is currently running

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

Description: Determine if an analysis pass is required.
return: true if analysis is required

## Method: recordAnalysisComment
- parameter: `address`, type: `long`
- parameter: `comment`, type: `java.lang.String`
- return type: `boolean`

Description: Record a meta\-comment generated during the analysis. The meta\-comment is flagless. This method does not notify.
parameter: address: memory address
parameter: comment: comment string
return: success indicator

## Method: recordDynamicBranchTarget
- parameter: `instructionAddress`, type: `long`
- parameter: `resolved`, type: `boolean`
- parameter: `target`, type: `com.pnfsoftware.jeb.core.units.code.asm.analyzer.IBranchTarget`
- parameter: `prepareAnalysis`, type: `boolean`
- return type: `boolean`

Description: Record branch resolutions for dynamic callsites.
parameter: instructionAddress: the address of a branching instruction making use of a dynamic            callsite
parameter: resolved: true if the target if a true resolution, false if the target is one candidate            among possibly many candidate targets
parameter: target: the target, not null
parameter: prepareAnalysis: if true, the method may decide to enqueue the target for routine            analysis; the decision process depends on whether the instruction is a flow break,            call\-to\-sub, or none, as well as other parameters like whether the added callsite            was already known
return: true if the target was truly added \(no duplicate, no error\), false otherwise

## Method: recordDynamicRegisterValue
- parameter: `instructionAddress`, type: `long`
- parameter: `postExec`, type: `boolean`
- parameter: `register`, type: `long`
- parameter: `value`, type: `long`
- return type: `boolean`

Description: Record a dynamic register value.
parameter: instructionAddress: instruction address
parameter: postExec: true if the value is valid after instruction execution
parameter: register: register id
parameter: value: register value
return: true if the value was recorded

## Method: requestAnalysisInterruption

Description: Request the interruption of the current analysis pass. The interruption may not happen immediately. Client code may use [#isAnalyzing()](#isAnalyzing()) to determine whether the analysis has stopped.

## Method: unrecordDynamicBranchTarget
- parameter: `instructionAddress`, type: `long`
- parameter: `resolved`, type: `boolean`
- parameter: `target`, type: `com.pnfsoftware.jeb.core.units.code.asm.analyzer.IBranchTarget`
- return type: `boolean`

Description: Unrecord a branch resolution. Unlike [#recordDynamicBranchTarget(long, boolean, IBranchTarget, boolean)](#recordDynamicBranchTarget(long, boolean, IBranchTarget, boolean)), this call does not trigger a new analysis pass.
parameter: instructionAddress: branch instruction address
parameter: resolved: true if the target is a true resolution
parameter: target: target to remove
return: true if the target was removed

