IMethod Class Reference

IMethod Interface Class Method Interface base class More...

#include <MieAPI.h>

List of all members.

Public Member Functions

virtual TInstructionListIteratorGetInstructionListIterator (const EInstructionIteratorType iteratorType)=0
  GetInstructionListIterator returns an iterator over the method's instructions.
virtual TResult BindTryFinallyBlock (IInstruction *iTry, IInstruction *iEndTry, IInstruction *iFinally, IInstruction *iEndFinally)=0
  BindTryFinallyBlock binds a try..finally block
virtual TResult VerifyCode (SInstrumentationErrorsArray *pErrorsArray=NULL) const =0
  VerifyCode performs simple code validation
virtual TResult ApplyInstrumentation ()=0
  ApplyInstrumentation Generates a Java or MSIL method from the method instruction stream and replaces the original method with the new generated code.
virtual TResult DebugPrint (bool bToResolveNames, char *fileName=NULL)=0
  DebugPrint prints the Java byte code or the MSIL code disassembly of the method to the specified output file


Detailed Description

The IMethod interface provides a base class for low level inspection and instrumentation support for the method it is instantiated for. Once the caller is done with instrumenting the method and is ready to apply the changes, the WriteBack API should be called. While instrumenting the method, intermediate changes to the original Java byte code or MSIL code are either immediately visible or not depending on the type of instruction list iterator interface the client requested. After completing instrumeting a method, the user should call IMethod::WriteBack() in order to apply the instrumentation changes. If the WriteBack method is not called, all instrumentation changes for this method are discarded.

Member Function Documentation

virtual TInstructionListIterator* GetInstructionListIterator ( const EInstructionIteratorType  iteratorType  )  [pure virtual]

This API initializes and returns a new iterator over the method's instructions. The iteratorType argument specifies which type of iterator to create.

The iterator points to objects of type IInstruction*.

* NOTE:when done using the iterator, call its Free method to deallocate the iterator. Do not use the delete operator.

Parameters:
iteratorType [in] - the iterator type to create. tructions are visible.
Returns:
- an iterator over the method's instructions or NULL when no more memory is available.

virtual TResult BindTryFinallyBlock ( IInstruction iTry,
IInstruction iEndTry,
IInstruction iFinally,
IInstruction iEndFinally 
) [pure virtual]

This API is used to bind a try..finally block, i.e. associate between MARTINI_PSEUDO_TRY MARTINI_PSEUDO_ENDTRY MARTINI_PSEUDO_FINALLY MARTINI_PSEUDO_ENDFINALLY instructions, to define a try..finally block. This API is currently supported for all types of exceptions, i.e. any type of exception that is thrown between the MARTINI_PSEUDO_TRY and MARTINI_PSEUDO_ENDTRY block is handled in the MARTINI_PSEUDO_FINALLY block. The caller should ensure that the Java bytecode or MSIL code is correct after adding the try..finally block, and is responsible for maintaining the correct code structure. The code correctness can be verified by calling the VerifyCode API. This API will add the required pseudo instructions, which can't be added in any other way to make sure they are bound correctly.

[Java specific] This API can be used on instance constructors (<init> methods) only when the entire original code is inside the "try .. end_try" block. iTry must point to the first original instruction and iEndTry must point to the last original instruction. This limitation may be removed in the future. [End Java specific]

Parameters:
iTry [in] - the interface of the first instruction in the try block
iEndTry [in] - the interface of the last instruction in the try block
iFinally [in] - the interface of the first instruction in the finally block
iEndFinally [in] - the interface of the last instruction in the finally block
Returns:
- MRTE_RESULT_OK success

- MRTE_ERROR_ILLEGAL_ARGUMENT at least one argument does not point to a valid instruction interface

- MRTE_ERROR_OUT_OF_MEMORY out of memory

- MRTE_ERROR_ILLEGAL_TRY_BLOCK there is a mismatch between the try-endtry or the finally-endfinally blocks

- MRTE_ERROR_NOT_SUPPORTED API is not yet supported

virtual TResult VerifyCode ( SInstrumentationErrorsArray pErrorsArray = NULL  )  const [pure virtual]

This method tries to uncover basic instrumentation errors. It is advised to call it prior to WriteBack() in order to help locating instrumentation errors. The currently checked error is: 1) mismatch between instruction mnemonics and its operand types In the future the following errors will be flagged: 2) 'ret' inside try blocks (.NET only) 3) try block is not ended with a 'leave' instruction (.NET only) 4) error in try blocks nesting

Parameters:
pErrorsArray [out] - a caller allocated buffer to hold uncovered code errors if NULL then the code will be checked up until the first error (if any) and will return success/fail only.
Returns:
- MRTE_RESULT_OK - if no errors discovered MRTE_ERROR_FAIL - otherwise

virtual TResult ApplyInstrumentation (  )  [pure virtual]

This API is used to write back the new instrumented method. It generates a new Java or MSIL method from the current flow graph of instructions, replacing the original method with the new one (in memory) and fixing the line info. When instrumenting Java byte code the client needs to call the WriteBack() class interface function to present the new method as part of the whole class to the JVM.

* IMPORTANT: This API invalidates the method and associated data structures. It should be the last API invoked on the method object. After calling ApplyInstrumentation, the client can no longer inspect and modify the method code. Any references to IInstruction objects will become invalid and using them may cause unexpected results.

Returns:
- MRTE_RESULT_OK success

- MRTE_ERROR_FAIL failure

virtual TResult DebugPrint ( bool  bToResolveNames,
char *  fileName = NULL 
) [pure virtual]

This API is provided as a debug service to the client module developer for printing the disassembly of the instrumented method to verify its correctness

Parameters:
bResolveNames [in] - Determines whether to resolve tokens/indexes to their real value. (Class::Method, strings, etc) If 'false': tokens/indexes are printed in hex
FileName [in] - optional output file name. if NULL or omitted, output is written to stdout
Returns:
- MRTE_RESULT_OK success


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