IInstruction Class Reference

IInstruction Interface Class Instruction interface More...

#include <MieAPI.h>

List of all members.

Public Member Functions

virtual const EMnemonic GetMnemonic () const =0
  GetMnemonic returns the mnemonics of the instruction
virtual TResult SetMnemonic (const EMnemonic newMnemonic)=0
  SetMnemonic replaces the mnemonics of the instruction
virtual TResult GetOperand (SOperand *pOperand1, SOperand *pOperand2=NULL, SOperand *pOperand3=NULL, SOperand *pOperand4=NULL) const =0
  GetOperand returns the operand(s) of the instruction
virtual TResult SetOperand (SOperand *pOperand1, SOperand *pOperand2=NULL, SOperand *pOperand3=NULL, SOperand *pOperand4=NULL)=0
  SetOperand sets the operand(s) of an instruction
virtual TResult AddBefore (IInstruction **ppInstruction, const EMnemonic newInstMnemonic, const SOperand *pNewInstOperand1=NULL, const SOperand *pNewInstOperand2=NULL, const SOperand *pNewInstOperand3=NULL)=0
  AddBefore inserts a new instruction before the current one
virtual TResult AddAfter (IInstruction **ppInstruction, const EMnemonic newInstMnemonic, const SOperand *pNewInstOperand1=NULL, const SOperand *pNewInstOperand2=NULL, const SOperand *pNewInstOperand3=NULL)=0
  AddAfter inserts a new instruction after the current one
virtual bool IsOriginalInst () const =0
  IsOriginalInst checks if an instruction is part of the original Java byte code or MSIL code of the method
virtual TResult GetOriginalOffset (unsigned int *puiOriginalOffset) const =0
  GetOriginalInstOffset Return the original byte offset from the start of the method
virtual IInstructionGetBranchTarget () const =0
  GetBranchTarget returns the target of a branch instruction
virtual IInstructionSetBranchTarget (IInstruction *pTargetInst)=0
  SetBranchTarget sets the target of a branch instruction


Detailed Description

This interface can be used to retrieve information about a single instruction, change its mnemonics and its operands, and add new instructions before or after the current one. Pseudo instructions associated with try..finally blocks can't be added and their operands can't be set via this interface. Use the IMethod interface function BindTryFinallyBlock to create such blocks.

Member Function Documentation

virtual const EMnemonic GetMnemonic (  )  const [pure virtual]

This API returns the mnemonics of the instruction

Returns:
- EMnemonic - the mnemonics of the instruction.

virtual TResult SetMnemonic ( const EMnemonic  newMnemonic  )  [pure virtual]

This API sets the mnemonics of the instruction to newMnemonic. The caller is responsible for making sure that the operands are valid or to replace it as well via the SetOperand API.

Note: If the number of operands expected for the new mnemonic is different from the number of operands of the current instruction, all operands of the current instruction will be discarded and the caller must set them via the SetOperand API.

Parameters:
newMnemonic [in] - the new mnemonics
Returns:
- MRTE_RESULT_OK success

- MRTE_ERROR_ILLEGAL_ARGUMENT newMnemonic is not valid

- MRTE_ERROR_READ_ONLY instruction was returned from an "inspection-only" iterator and cannot be modified.

virtual TResult GetOperand ( SOperand pOperand1,
SOperand pOperand2 = NULL,
SOperand pOperand3 = NULL,
SOperand pOperand4 = NULL 
) const [pure virtual]

This API returns the operand of the instruction within an SOperand structure.

Parameters:
pOperand1 [out] - the caller allocated SOperand structure, including internal buffers if required, to be filled by the instrumentation engine with the instruction's first operand
pOperand2 [out] - the caller allocated SOperand structure to be filled by the instrumentation engine with the instruction's second operand. This argument is optional and is relevant only for instructions that accept more than one argument. Relevant Java byte code instructions are: wide, iinc, multianewarray and invokeinterface.
pOperand3 [out] - the caller allocated SOperand structure to be filled by the instrumentation engine with the instruction's third operand. This argument is optional and is relevant only for instructions that receive more than two arguments. Relevant Java byte code instructions are: wide and invokeinterface
pOperand4 [out] - the caller allocated SOperand structure to be filled by the instrumentation engine with the instruction's fourth operand. This argument is optional and is relevant only for pseudo instructions.
NOTE: for branch instruction, a pointer to the MARTINI_PSEUDO_TARGET instruction object which is the branch target of the current instruction is returned in pOperand1. An alternative approach for obtaining the branch target of a branch instruction is to call the GetBranchInstruction() method.

Returns:
- MRTE_RESULT_OK success

- MRTE_ERROR_BUFFER_TOO_SHORT the STargetsArray member in the caller's SOperand is not big enough

- MRTE_ERROR_ILLEGAL_ARGUMENT at least one of the instruction operands cannot be filled. The reason can be: its pOperand buffer is NULL, or its internal STargetArray is not allocated (for switch instruction).

- MRTE_RESULT_NO_OPERAND instruction has no operand or not as many operands as the number of arguments

virtual TResult SetOperand ( SOperand pOperand1,
SOperand pOperand2 = NULL,
SOperand pOperand3 = NULL,
SOperand pOperand4 = NULL 
) [pure virtual]

This API sets or replaces the operands of the instruction with new ones. The caller has to make sure the new operand types match the instruction mnemonics or change the mnemonics. SetOperand does not assume that the pointer arguments are valid once it returns (i.e. SetOperand copies all needed info).

Parameters:
pOperand1 [in] - the caller allocated new instruction SOperand structure including internal buffers if required. This is the instruction's first operand
pOperand2 [in] - the caller allocated operand to set as the instruction's second operand. This is an optional argument, and should be used for those instructions that have more than 1 argument. Relevant Java byte code instructions are: wide, iinc, multianewarray and invokeinterface.
pOperand3 [in] - the caller allocated operand to set as the instruction's third operand. This is an optional argument, and should be used for those instructions that have more than 2 arguments. Relevant Java byte code instructions are: wide and invokeinterface
pOperand4 [in] - the caller allocated operand to set as the instruction's fourth operand. This is an optional argument, and should be used only for pseudu-instructions.
NOTE: for branch instruction, pOperand1 must contain a pointer to the IInstruction object which is the branch target. If the target is not a pseudo MARTINI_PSEUDO_TARGET, the pseudo MARTINI_PSEUDO_TARGET is automatically added just before the targeted instruction. An alternative approach for setting a branch target is to use the SetBranchTarget() method. The SetBranchTarget method also returns the pseudo target instruction and is the preferable method for setting branch targets.

Returns:
- MRTE_RESULT_OK success

- MRTE_ERROR_ILLEGAL_ARGUMENT Operand type is invalid

- MRTE_ERROR_ARGUMENT_MISMATCH Operand type and operand value mismatch. e.g. operand type is OT_TARGET or OT_TARGETS_ARRAY and the operand value contains invalid IInstruction pointer(s), operand type is OT_VAR_ID and the value contains an invalid variable id

- MRTE_ERROR_READ_ONLY instruction was returned from an "inspection-only" iterator and cannot be modified.

virtual TResult AddBefore ( IInstruction **  ppInstruction,
const EMnemonic  newInstMnemonic,
const SOperand pNewInstOperand1 = NULL,
const SOperand pNewInstOperand2 = NULL,
const SOperand pNewInstOperand3 = NULL 
) [pure virtual]

This API adds a new instruction, with mnemonics newInstMnemonic and operands pNewInstOperand1-3, immediately before this one. It fails if invoked on the pseudo MARTINI_PSEUDO_START instruction. All three operand arguments are optional, and should be used according to the number of operands the inserted instruction accepts.

Parameters:
ppInstruction [out] - a buffer for the new added instruction interface, in case of success
newInstMnemonic [in] - the mnemonics of the new added instruction
pNewInstOperand1 [in] - the caller allocated new instruction SOperand structure, including internal buffers if required. This operand is optional, and if not NULL, will be used as the inserted instruction first operand
pNewInstOperand2 [in] - the caller allocated new instruction SOperand structure, including internal buffers if required. This operand is optional, and if not NULL, will be used as the inserted instruction second operand
pNewInstOperand3 [in] - the caller allocated new instruction SOperand structure, including internal buffers if required. This operand is optional, and if not NULL, will be used as the inserted instruction third operand
Returns:
- MRTE_RESULT_OK - success

- MRTE_ERROR_OUT_OF_MEMORY - out of memory

- MRTE_ERROR_ILLEGAL_MNEMONIC - illegal mnemonic

- MRTE_ERROR_OPERAND_MISMATCH - there is a mismatch between the mnemonic and its operands

- MRTE_ERROR_ILLEGAL_OPERATION - trying to add an instruction before MARTINI_PSEUDO_START

- MRTE_ERROR_FAIL - internal error

- MRTE_ERROR_READ_ONLY - instruction was returned from an "inspection-only" iterator and cannot be modified.

virtual TResult AddAfter ( IInstruction **  ppInstruction,
const EMnemonic  newInstMnemonic,
const SOperand pNewInstOperand1 = NULL,
const SOperand pNewInstOperand2 = NULL,
const SOperand pNewInstOperand3 = NULL 
) [pure virtual]

This API adds a new instruction, with mnemonics newInstMnemonic and operands pNewInstOperand1-3, immediately after this one. It fails if invoked on the pseudo MARTINI_PSEUDO_END instruction. All three operand arguments are optional, and should be used according to the number of operands the inserted instruction accepts.

Parameters:
ppInstruction [out] - a buffer for the new added instruction interface, in case of success
newInstMnemonic [in] - the mnemonics of the new added instruction
pNewInstOperand1 [in] - the caller allocated new instruction SOperand structure, including internal buffers if required. This operand is optional, and if not NULL, will be used as the inserted instruction first operand
pNewInstOperand2 [in] - the caller allocated new instruction SOperand structure, including internal buffers if required. This operand is optional, and if not NULL, will be used as the inserted instruction second operand
pNewInstOperand3 [in] - the caller allocated new instruction SOperand structure, including internal buffers if required. This operand is optional, and if not NULL, will be used as the inserted instruction third operand
Returns:
- MRTE_RESULT_OK - success

- MRTE_ERROR_OUT_OF_MEMORY - out of memory

- MRTE_ERROR_ILLEGAL_MNEMONIC - illegal mnemonic

- MRTE_ERROR_OPERAND_MISMATCH - there is a mismatch between the mnemonic and its operands

- MRTE_ERROR_ILLEGAL_OPERATION - trying to add an instruction before MARTINI_PSEUDO_END

- MRTE_ERROR_FAIL - internal error

- MRTE_ERROR_READ_ONLY - instruction was returned from an "inspection-only" iterator and cannot be modified.

virtual bool IsOriginalInst (  )  const [pure virtual]

This API returns 'true' if invoked from an instruction that was present in the original method, or 'false' if it was added or modified during instrumentation. For all pseudo instructions false is returned. Instructions for which this flag is 'false' will not change to 'true' as long as the method object containing these instructions is alive (even after ApplyInstrumentation was invoked on the method).

Returns:
- bool - true if original, false if not

virtual TResult GetOriginalOffset ( unsigned int *  puiOriginalOffset  )  const [pure virtual]

This API returns the instruction's original offset from the start of the method

Parameters:
pOriginalOffset [out] - offset in the original Java byte code or MSIL code
Returns:
- MRTE_RESULT_OK - success

- MRTE_RESULT_ADDED_INSTRUCTION - invoked on an added instruction

- MRTE_ERROR_NOT_SUPPORTED - this API is not supported

virtual IInstruction* GetBranchTarget (  )  const [pure virtual]

This API returns the interface of the target instruction of a branch. In most cases this is the pseudo MARTINI_PSEUDO_TARGET instruction that preceeds the actual target instruction. The call to this API will fail if the instruction on which it is invoked is not a branch instruction.

Returns:
- IInstruction* - the interface of the target instruction upon success NULL upon failure

virtual IInstruction* SetBranchTarget ( IInstruction pTargetInst  )  [pure virtual]

This API sets the target of a branch instruction. If the target is not a pseudo MARTINI_PSEUDO_TARGET, the pseudo MARTINI_PSEUDO_TARGET is automatically added just before the targeted instruction The call to this API will fail if the instruction on which it is invoked is not a branch instruction.

Parameters:
pTargetInst [in] - the IInstruction interface of the new branch target
Returns:
- IInstruction* - the interface of the MARTINI_PSEUDO_TARGET target instruction upon success NULL upon failure


The documentation for this class was generated from the following file:


Generated on Thu Mar 6 15:07:57 2008 for Martini by doxygen 1.5.5