Module pywraps

Get the specified number of bytes of the program into the buffer.

Parameters:

• ea - program address
• size - number of bytes to return

Returns:

None or the string buffer

Registers a custom data type.

Parameters:

• dt - an instance of the data_type_t class

Returns:

< 0 if failed to register > 0 data type id

Unregisters a custom data type.

Parameters:

• dtid - the data type id

Returns:

Boolean

Registers a custom data format with a given data type.

Parameters:

• dtid - data type id
• df - an instance of data_format_t

Returns:

< 0 if failed to register > 0 data format id

Unregisters a custom data format

Parameters:

• dtid - data type id
• dfid - data format id

Returns:

Boolean

Returns a dictionary populated with the data format values or None on failure.

Parameters:

• dtid - data type id
• dfid - data format id

Returns a dictionary populated with the data type values or None on failure.

Parameters:

• dtid - data type id

Registers multiple data types and formats at once.
To register one type/format at a time use register_custom_data_type/register_custom_data_format
It employs a special table of types and formats described below:
The 'formats' is a list of tuples. If a tuple has one element then it is the format to be registered with dtid=0
If the tuple has more than one element, then tuple[0] is the data type and tuple[1:] are the data formats. For example:
many_formats = [
  (pascal_data_type(), pascal_data_format()),
  (simplevm_data_type(), simplevm_data_format()),
  (makedword_data_format(),),
  (simplevm_data_format(),)
]
The first two tuples describe data types and their associated formats.
The last two tuples describe two data formats to be used with built-in data types.

Returns the manual memory regions

Returns:

list(startEA, endEA, name, sclass, sbase, bitness, perm)

Checks if a debugger is loaded

Returns:

Boolean

Refreshes the debugger memory

Returns:

Nothing

Enumerate files in the specified directory while the callback returns 0.

Parameters:

• path - directory to enumerate files in
• fname - mask of file names to enumerate
• callback - a callable object that takes the filename as its first argument and it returns 0 to continue enumeration or non-zero to stop enumeration.

Returns:

None in case of script errors tuple(code, fname) : If the callback returns non-zero

Returns a C str from the passed value. The passed value can be of type refclass (returned by a call to buffer() or byref()) It scans for the first and returns the string value up to that point.

Returns a number as signed. The number of bits are specified by the user. The MSB holds the sign.

Copy bits from a value

Parameters:

• v - the value
• s - starting bit
• e - ending bit

Unpack a buffer given its length and offset using struct.unpack_from(). This function will know how to unpack the given buffer by using the lookup table '__struct_unpack_table' If the buffer is of unknown length then None is returned. Otherwise the unpacked value is returned.

Run the specified script. It also addresses http://code.google.com/p/idapython/issues/detail?id=42 This function is used by the low-level plugin code.

Parses a space separated string (quotes and escape character are supported)

Parameters:

• cmdline - The command line to parse

Returns:

A list of strings or None on failure

Changes the script timeout value.

Parameters:

• timeout - This value is in seconds. If this value is set to zero then the script will never timeout.

Returns:

returns the old timeout value

Enables or disables Python extlang. When enabled, all expressions will be evaluated by Python.

Parameters:

• enable - Set to True to enable, False otherwise

This is an IDC function exported from the Python plugin. It is used to evaluate Python statements from IDC.

Parameters:

• stmt - The statement to evaluate

Returns:

0 - on success otherwise a string containing the error

Register a callback that will be called when an event happens.
@param when: one of NW_XXXX constants
@param callback: This callback prototype varies depending on the 'when' parameter:
                 The general callback format:
                     def notify_when_callback(nw_code)
                 In the case of NW_OPENIDB:
                     def notify_when_callback(nw_code, is_old_database)
@return: Boolean

This function returns the register definition from the currently loaded debugger. Basically, it returns an array of structure similar to to idd.hpp / register_info_t

Returns:

None if no debugger is loaded tuple(name, flags, class, dtyp, bit_strings, bit_strings_default_mask) The bit_strings can be a tuple of strings or None (if the register does not have bit_strings)

Returns the segment register base value

Parameters:

• tid - thread id
• sreg_value - segment register (selector) value

Returns:

• The base as an 'ea'
• Or None on failure

Reads from the debugee's memory at the specified ea

Returns:

• The read buffer (as a string)
• Or None on failure

Writes a buffer to the debugee's memory

Returns:

Boolean

This function returns the current debugger's name.

Returns:

Debugger name or None if no debugger is active

This function returns the memory configuration of a debugged process.

Returns:

None if no debugger is active tuple(startEA, endEA, name, sclass, sbase, bitness, perm)

This function can be used to check if the debugger can be queried:

• debugger is loaded
• process is suspended
• process is not suspended but can take requests. In this case some requests like memory read/write, bpt management succeed and register querying will fail. Check if idaapi.get_process_state() < 0 to tell if the process is suspended

Returns:

Boolean

Assemble an instruction to a buffer (display a warning if an error is found)

Parameters:

• ea - linear address of instruction
• cs - cs of instruction
• ip - ip of instruction
• use32 - is 32bit segment
• line - line to assemble

Returns:

• None on failure
• or a string containing the assembled instruction

Returns the currently highlighted identifier

Parameters:

• flags - reserved (pass 0)

Returns:

None or the highlighted identifier

Asks for a long text

Parameters:

• max_text - Maximum text length
• defval - The default value
• prompt - The prompt value

Returns:

None or the entered string

Converts a string express to EA. The expression evaluator may be called as well.

Returns:

BADADDR or address value

Deletes a menu item previously added with add_menu_item()

Parameters:

• menu_ctx - value returned by add_menu_item()

Returns:

Boolean

Adds a menu item
@param menupath: path to the menu item after or before which the insertion will take place
@param name: name of the menu item (~x~ is used to denote Alt-x hot letter)
@param hotkey: hotkey for the menu item (may be empty)
@param flags: one of SETMENU_... consts
@param callback: function which gets called when the user selects the menu item.
           The function callback is of the form:
           def callback(*args):
              pass
@param args: tuple containing the arguments
@return: None or a menu context (to be used by del_menu_item())

Sets the dock orientation of a window relatively to another window.
@param src: Source docking control
@param dest: Destination docking control
@param orient: One of DOR_XXXX constants
@param left, top, right, bottom: These parameter if DOR_FLOATING is used, or if you want to specify the width of docked windows
@return: Boolean
Example:
    set_dock_pos('Structures', 'Enums', DOR_RIGHT) <- docks the Structures window to the right of Enums window

User-defined line-prefixes are displayed just after the autogenerated
line prefixes. In order to use them, the plugin should call the
following function to specify its width and contents.
@param width: the width of the user-defined prefix
@param callback: a get_user_defined_prefix callback to get the contents of the prefix.
    Its arguments:
      ea     - linear address
      lnnum  - line number
      indent - indent of the line contents (-1 means the default instruction)
               indent and is used for instruction itself. see explanations for printf_line()
      line   - the line to be generated. the line usually contains color tags this argument
               can be examined to decide whether to generated the prefix
      bufsize- the maximum allowed size of the output buffer
    It returns a buffer of size < bufsize
In order to remove the callback before unloading the plugin, specify the width = 0 or the callback = None

Remove color escape sequences from a string

Parameters:

• colstr - the colored string with embedded tags

Returns:

None on failure or a new string w/o the tags

Generate disassembly lines (many lines) and put them into a buffer

Parameters:

• ea - address to generate disassembly for
• max_lines - how many lines max to generate
• as_stack - Display undefined items as 2/4/8 bytes

Returns:

• None on failure
• tuple(most_important_line_number, tuple(lines)) : Returns a tuple containing the most important line number and a tuple of generated lines

Checks if the given character requires escaping

Parameters:

• c - character (string of one char)

Returns:

Boolean

Utility function to create a colored line

Parameters:

• str - The string
• tag - Color tag constant. One of SCOLOR_XXXX

Load database from the memory.

Parameters:

• mem - the buffer
• ea - start linear addresses
• fpos - position in the input file the data is taken from. if == -1, then no file position correspond to the data.

Returns:

• Returns zero if the passed buffer was not a string
• Otherwise 1 is returned

Loads a plugin

Returns:

• None if plugin could not be loaded
• An opaque object representing the loaded plugin

Runs a plugin

Parameters:

• plg - A plugin object (returned by load_plugin())

Returns:

Boolean

Returns the name of an imported module given its index

Returns:

None or the module name

Returns the a switch_info_ex_t structure containing the information about the switch. Please refer to the SDK sample 'uiswitch'

Returns:

None or switch_info_ex_t instance

This function creates xrefs from the indirect jump. Usually there is no need to call this function directly because the kernel will call it for switch tables Note: Custom switch information are not supported yet.

Parameters:

• insn_ea - address of the 'indirect jump' instruction
• si - switch information

Returns:

Boolean

Create switch table from the switch information

Parameters:

• insn_ea - address of the 'indirect jump' instruction
• si - switch information

Returns:

Boolean

Saves the switch information in the database Please refer to the SDK sample 'uiswitch'

Returns:

Boolean

Enumerate imports from a specific module. Please refer to ex_imports.py example.

Parameters:

• mod_index - The module index
• callback - A callable object that will be invoked with an ea, name (could be None) and ordinal.

Returns:

1-finished ok, -1 on error, otherwise callback return value (<=0)

Returns the size of a type

Parameters:

• ti - Type info. 'idaapi.cvar.idati' can be passed.
• tp - type string

Returns:

• None on failure
• The size of the type

Returns the type of an item

Returns:

• None on failure
• The type string with a semicolon. Can be used directly with idc.SetType()

Unpacks from the database at 'ea' to an object. Please refer to unpack_object_from_bv()

Unpacks a buffer into an object. Returns the error_t returned by idaapi.pack_object_to_idb

Parameters:

• ti - Type info. 'idaapi.cvar.idati' can be passed.
• tp - type string
• fields - type fields
• bytes - the bytes to unpack
• pio_flags - flags used while unpacking

Returns:

• tuple(0, err) on failure
• tuple(1, obj) on success

Write a typed object to the database. Raises an exception if wrong parameters were passed or conversion fails Returns the error_t returned by idaapi.pack_object_to_idb

Parameters:

• ti - Type info. 'idaapi.cvar.idati' can be passed.
• tp - type string
• fields - type fields
• ea - ea to be used while packing
• pio_flags - flags used while unpacking

Packs a typed object to a string

Parameters:

• ti - Type info. 'idaapi.cvar.idati' can be passed.
• tp - type string
• fields - type fields
• base_ea - base ea used to relocate the pointers in the packed object
• pio_flags - flags used while unpacking

Returns:

tuple(0, err_code) on failure tuple(1, packed_buf) on success

This function initialize an output buffer with the given size. It should be called before using any out_xxxx() functions.

Returns:

It returns a string. This string should then be passed to MakeLine(). This function could return None if it failed to create a buffer with the given size.

Decodes the preceding instruction. Please check ua.hpp / decode_preceding_insn()

Parameters:

• ea - current ea

Returns:

tuple(preceeding_ea or BADADDR, farref = Boolean)

Output immediate value

Parameters:

• op - operand (of type op_t)

Returns:

flags of the output value -1: value is output with COLOR_ERROR 0: value is output as a number or character or segment

Get pointer to stack variable

Parameters:

• op - reference to instruction operand
• v - immediate value in the operand (usually op.addr)

Returns:

• None on failure
• tuple(member_t, actval) where actval: actual value used to fetch stack variable

Automatically add stack variable if doesn't exist Processor modules should use ua_stkvar2()

Parameters:

• op - reference to instruction operand
• v - immediate value in the operand (usually op.addr)
• flags - combination of STKVAR_... constants

Returns:

Boolean

Apply type information to a stack variable

Parameters:

• op - reference to instruction operand
• v - immediate value in the operand (usually op.addr)
• type - type string. Retrieve from idc.ParseType("type string", flags)[1]
• name - stack variable name

Returns:

Boolean

Output operand value as a commented character constant

Parameters:

• op - operand (of type op_t)

Returns:

None

Create or modify a stack variable in the function frame. Please check ua.hpp / ua_stkvar2()

Parameters:

• op - operand (of type op_t)

Returns:

None

Add xrefs for offset operand of the current instruction Please check ua.hpp / ua_add_off_drefs()

Parameters:

• op - operand (of type op_t)

Returns:

None

Add xrefs for offset operand of the current instruction Please check ua.hpp / ua_add_off_drefs2()

Returns:

ea_t

Output a name expression

Parameters:

• op - operand (of type op_t)
• ea - address of expression
• off - the value of name expression. this parameter is used only to check that the name expression will have the wanted value. You may pass BADADDR for this parameter.

Returns:

true if the name expression has been produced

NW_OPENIDB

Notify when the database is opened. Its callback is of the form: def notify_when_callback(nw_code, is_old_database)

Value:

0x0001

NW_CLOSEIDB

Notify when the database is closed. Its callback is of the form: def notify_when_callback(nw_code)

Value:

0x0002

NW_INITIDA

Notify when the IDA starts. Its callback is of the form: def notify_when_callback(nw_code)

Value:

0x0004

NW_TERMIDA

Notify when the IDA terminates. Its callback is of the form: def notify_when_callback(nw_code)

Value:

0x0008

COLOR_ADDR_SIZE

Value:

16 if _idaapi.BADADDR== 0xFFFFFFFFFFFFFFFFL else 8

SWI_CUSTOM

custom jump table - ph.create_switch_xrefs will be called to create code xrefs for the table. it must return 2. custom jump table must be created by the module

Value:

0x4000

cmd

cmd is a global variable of type insn_t. It is contains information about the last decoded instruction. This variable is also filled by processor modules when they decode instructions.

Value:

insn_t(_idaapi.py_get_global_cmd_link())