Below is the full source code of a sample plugin. It performs a quite useful transformation of the pseudocode: replaces zeroes in pointer contexts with NULLs. A NULL immediately conveys the idea that the current expression is pointer-related. This is especially useful for unknown function arguments.

The plugin is fully automatic. It hooks to the decompiler events and waits for the pseudocode to be ready. At that moment it takes control and modifies the ctree.

The conversion is performed by the convert_zeroes() function. It visits all expressions of the ctree and checks for pointer contexts. If a expression has a pointer type, then the make_null_if_zero() function is called for it. This function checks if the expression is a zero constant and converts it if necessary.

The plugin can be turned on or off by its menu item in the Plugins submenu.

The code is short and straightforward. Use it as a template for your plugins.

\

/*
 *      Hex-Rays Decompiler project
 *      Copyright (c) 2007-2019 by Hex-Rays, support@hex-rays.com
 *      ALL RIGHTS RESERVED.
 *
 *      Sample plugin for Hex-Rays Decompiler.
 *      It automatically replaces zeroes in pointer contexts with NULLs.
 *      For example, expression like
 *
 *              funcptr = 0;
 *
 *      will be displayed as
 *
 *              funcptr = NULL;
 *
 *      Due to highly dynamic nature of the decompier output, we must
 *      use the decompiler events to accomplish the task. The plugin will
 *      wait for the ctree structure to be ready in the memory and will
 *      replace zeroes in pointer contexts with NULLs.
 *
 */

#include <hexrays.hpp>

// Hex-Rays API pointer
hexdsp_t *hexdsp = NULL;

static bool inited = false;

static const char nodename[] = “$ hexrays NULLs”;
static const char null_type[] = “MACRO_NULL”;
//————————————————————————–
// Is the plugin enabled?
// The user can disable it. The plugin will save the on/off switch in the
// current database.
static bool is_enabled(void)
{
  netnode n(nodename); // use a netnode to save the state
  return n.altval(0) == 0; // if the long value is positive, then disabled
}

//————————————————————————–
// If the expression is zero, convert it to NULL
static void make_null_if_zero(cexpr_t *e)
{
  if ( e->is_zero_const() && !e->type.is_ptr() )
  { // this is plain zero, convert it
    number_format_t &nf = e->n->nf;
    nf.flags = enum_flag();
    nf.serial = 0;
    nf.type_name = null_type;
    e->type = tinfo_t::get_stock(STI_PVOID);
  }
}

//————————————————————————–
// Convert zeroes of the ctree to NULLs
static void convert_zeroes(cfunc_t *cfunc)
{
  // To represent NULLs, we will use the MACRO_NULL enumeration
  // Normally it is present in the loaded tils but let’s verify it
  if ( !get_named_type(NULL, null_type, NTF_TYPE) )
  {
    msg(“%s type is missing, cannot convert zeroes to NULLs\n”, null_type);
    return;
  }

  // We derive a helper class from ctree_visitor_t
  // The ctree_visitor_t is a base class to derive
  // ctree walker classes.
  // You have to redefine some virtual functions
  // to do the real job. Here we redefine visit_expr() since we want
  // to examine and modify expressions.
  struct ida_local zero_converter_t : public ctree_visitor_t
  {
    zero_converter_t(void) : ctree_visitor_t(CV_FAST) {}
    int idaapi visit_expr(cexpr_t *e)
    {
      // verify if the current expression has pointer expressions
      // we handle the following patterns:
      //  A. ptr = 0;
      //  B. func(0); where argument is a pointer
      //  C. ptr op 0 where op is a comparison
      switch ( e->op )
      {
        case cot_asg:   // A
          if ( e->x->type.is_ptr() )
            make_null_if_zero(e->y);
          break;

        case cot_call:  // B
          {
            carglist_t &args = *e->a;
            for ( int i=0; i < args.size(); i++ ) // check all arguments
            {
              carg_t &a = args[i];
              if ( a.formal_type.is_ptr_or_array() )
                make_null_if_zero(&a);
            }
          }
          break;

        case cot_eq:    // C
        case cot_ne:
        case cot_sge:
        case cot_uge:
        case cot_sle:
        case cot_ule:
        case cot_sgt:
        case cot_ugt:
        case cot_slt:
        case cot_ult:
          // check both sides for zeroes
          if ( e->y->type.is_ptr() )
            make_null_if_zero(e->x);
          if ( e->x->type.is_ptr() )
            make_null_if_zero(e->y);
          break;

        default:
          break;

      }
      return 0; // continue walking the tree
    }
  };
  zero_converter_t zc;
  // walk the whole function body
  zc.apply_to(&cfunc->body, NULL);
}

//————————————————————————–
// This callback will detect when the ctree is ready to be displayed
// and call convert_zeroes() to create NULLs
static ssize_t idaapi callback(void *, hexrays_event_t event, va_list va)
{
  if ( event == hxe_maturity )
  {
    cfunc_t *cfunc = va_arg(va, cfunc_t*);
    ctree_maturity_t mat = va_argi(va, ctree_maturity_t);
    if ( mat == CMAT_FINAL ) // ctree is ready, time to convert zeroes to NULLs
      convert_zeroes(cfunc);
  }
  return 0;
}

//————————————————————————–
// Initialize the plugin.
int idaapi init(void)
{
  if ( !init_hexrays_plugin() )
    return PLUGIN_SKIP; // no decompiler
  if ( is_enabled() ) // null plugin is enabled?
  {
    install_hexrays_callback(callback, NULL);
    const char *hxver = get_hexrays_version();
    msg(“Hex-rays version %s has been detected, %s ready to use\n”, hxver, PLUGIN.wanted_name);
  }
  inited = true;
  return PLUGIN_KEEP;
}

//————————————————————————–
void idaapi term(void)
{
  if ( inited )
  {
    // clean up
    remove_hexrays_callback(callback, NULL);
    term_hexrays_plugin();
  }
}

//————————————————————————–
bool idaapi run(size_t)
{
  // since all real work is done in the callbacks, use the main plugin entry
  // to turn it on and off.
  // display a message explaining the purpose of the plugin:
  int code = askbuttons(
       “~E~nable”,
       “~D~isable”,
       “~C~lose”,
       –1,
       “AUTOHIDE NONE\n”
       “Sample plugin for Hex-Rays decompiler.\n”
       “\n”
       “This plugin is fully automatic.\n”
       “It detects zeroes in pointer contexts and converts them into NULLs.\n”
       “\n”
       “The current state of the plugin is: %s\n”,
       is_enabled() ? “ENABLED” : “DISABLED”);
  switch ( code )
  {
    case –1:    // close
      break;
    case 0:     // disable
    case 1:     // enable
      netnode n;
      n.create(nodename);
      n.altset(0, code == 0);
      if ( code )
        install_hexrays_callback(callback, NULL);
      else
        remove_hexrays_callback(callback, NULL);
      info(“The %s plugin has been %s.”, PLUGIN.wanted_name, code ? “ENABLED” : “DISABLED”);
      break;
  }
  return true;
}

//————————————————————————–
static char comment[] = “Sample2 plugin for Hex-Rays decompiler”;

//————————————————————————–
//
//      PLUGIN DESCRIPTION BLOCK
//
//————————————————————————–
plugin_t PLUGIN =
{
  IDP_INTERFACE_VERSION,
  0,                    // plugin flags
  init,                 // initialize
  term,                 // terminate. this pointer may be NULL.
  run,                  // invoke plugin
  comment,              // long comment about the plugin
                        // it could appear in the status line
                        // or as a hint
  “”,                   // multiline help about the plugin
  “Hex-Rays NULL converter”, // the preferred short name of the plugin
  “”                    // the preferred hotkey to run the plugin
};

How to create a plugin with C++ SDK?

Intro

The C++ SDK allows developers to create powerful plugins that can extend the IDA Pro capabilities, that enable deeper integration and more control over IDA's core functionality.

This guide will walk you through creating a basic plugin using the C++ SDK, demonstrating the structure and best practices for developing C++ plugins for IDA Pro.

Prerequistes

• Installed the lastest C++ SDK. You can get it from our Download Center in My Hex-Rays portal.

• A working C++ development environment (compiler, debugger, etc.). For the Windows Visual Studio users, a plugin template has been created that can be used to create plugin solutions. It can be found in the C++ SDK with a corresponding README file.

Before you start

1. Check the C++ SDK Reference Documentation for a comprehensive list of classes, functions, and available APIs.

2. Familiarize yourself with the plugin_t class and plugmod_t, that are fundamental for creating plugins using the C++ SDK.

3. Ensure compatibility with the latest version of IDA Pro and refer to the C++ SDK Porting Guide for any recent changes that might affect your plugin.

Overview of the Plugin Structure

An IDA Pro plugin written in C++ typically involves:

• A class that inherits from plugmod_t, this class will implement the actual plugin functionality.

• An init() function that will return a pointer to the above mentioned class.

• Flags that specify when and how the plugin should be loaded and unloaded.

Writing a plugin in C++—basic steps

Create a basic plugin structure

Start by creating a new C++ source file for your plugin. This file will contain the main logic and define the necessary classes and methods for your plugin.

Define base classes

When creating a plugin, it's recommended to create an instace of the class plugin_t with specific flags and a class inheriting from plugmod_t that performs the core functionality.

Example of `implementation:

#include <ida.hpp>
#include <idp.hpp>
#include <loader.hpp>
#include <funcs.hpp>

// Define the class that inherits from plugmod_t
class MyPlugmod : public plugmod_t 
{
public:
	// Constructor
	MyPlugmod() 
	{
		msg("MyPlugmod: Constructor called.\n");
	}

	// Destructor
	virtual ~MyPlugmod() 
	{
		msg("MyPlugmod: Destructor called.\n");
	}

	// Method that gets called when the plugin is activated
	virtual bool idaapi run(size_t arg) override
	{
		msg("MyPlugmod.run() called with arg: %d\n", arg);

		// Iterate through all functions and print their names and addresses
		int n = get_func_qty();
		for (int i = 0; i < n; i++) {
			func_t* pfn = getn_func(i);
			if (pfn == nullptr)
				continue;

			qstring name;
			get_func_name(&name, pfn->start_ea);
			msg("Function %s at address 0x%llX\n", name.length() ? name.c_str(): "-UNK-" , pfn->start_ea);
		}

		return true;
	}
};

static plugmod_t* idaapi init(void)
{
	return new MyPlugmod();
}

plugin_t PLUGIN =
{
  IDP_INTERFACE_VERSION,
  PLUGIN_MULTI,         // plugin flags
  init,                 // initialize
  nullptr,              // terminate. this pointer can be nullptr
  nullptr,              // invoke the plugin
  nullptr,              // long comment about the plugin
  nullptr,              // multiline help about the plugin
  "List functions",		// the preferred short name of the plugin
  ""					// the preferred hotkey to run the plugin
};

In our example:

• MyPlugmod class: This class inherits from plugmod_t and overrides the run() method to perform the plugin's main functionality. The constructor and destructor provide initialization and cleanup messages.

• PLUGIN exported plugin_t instance: This object sets the PLUGIN_MULTI flag to allow the plugin to be loaded multiple times if needed.

• init function: This function is called by the by the kernel in order to initialize the plugin. It returns an instance of MyPlugmod.

Build and install your plugin

1. Compile your plugin. Once your plugin code is ready, Use your C++ development environment to compile the plugin source code into a shared library (.dll on Windows, .so on Linux, or .dylib on macOS).

2. Install your plugin. Copy the compiled plugin binary to the plugins directory in your IDA installation folder.

3. Run your plugin. Execute the plugin via the specified hotkey or by selecting it from the Edit -> Plugins submenu.

Getting started with C++ SDK

IN PROGRESS

Intro

The IDA C++ SDK provides set of tools to interact with IDA Pro's disassembler, allowing you to navigate, analyze, and manipulate various elements such as functions, instructions, and data. This guide is designed to accelerate your learning curve with the IDA C++ SDK and kickstart your development journey, assuming you are already familiar with IDA Pro and its basic usage.

How This Guide is Structured

First, check Basics for core concepts and commonly used variables. Next, explore our Code Snippets to see examples of commonly used functions. Once you're comfortable with these, you can delve into more complex Examples that showcase advanced usage of the SDK.

C++ SDK Installation

You can download the latest C++ SDK Zip file from our Download Center in My Hex-Rays portal. The SDK package includes in the top-level directory a README file with instructions on how to install it on your local machine and additional README files in other directories for processor modules templates, loaders and so on.

Basics

Common Types and Constants

One of the most extensivly used type is ea_t, commonly used to represent an effective address (EA) within a binary.

Common header files and namespaces

The IDA C++ SDK is organized into header files containing various classes and functions. Below is a short desription of commonly used IDA SDK header files:

• pro.h: This is the first header included in the IDA project. It defines the most common types, functions, and data. It also contains compiler- and platform-related definitions.

• ida.hpp: In this file the 'inf' structure is defined: it keeps all parameters of the disassembled file.

• idp.hpp: The 'main' header file for IDP modules. Contains definition of the interface to IDP modules. The interface consists of 2 structures: processor_t - description of processor asm_t - description of assembler Each IDP has one processor_t and several asm_t structures.

• loader.hpp: Definitions of IDP, LDR, and PLUGIN module interfaces. This file also contains:

  • functions to load files into the database

  • functions to generate output files

  • high level functions to work with the database (open, save, close)

• ua.hpp: Functions that deal with the disassembling of program instructions. Disassembly of an instruction is made in three steps:

  • analysis

  • emulation

  • conversion to text

• kernwin.hpp: Defines the interface between the kernel and the UI. Some string processing functions are also kept in this header.

• idd.hpp: Debugger plugin API for debugger module writers. Contains definition of the interface to IDD modules.

• bytes.hpp: Functions and definitions used to describe and manipulate each byte of the disassembled program. Information about the byte includes associated features (comments, names, references, etc), data types (dword, qword, string literal, etc), instruction operands, status (mapped, loaded, patched, etc), among others.

• netnode.hpp: Functions that provide the lowest level public interface to the database. Modules can use this to keep some private information in the database. A description of the concept is available in the header file itself.

• allins.hpp: List of instructions available from all processor modules.

• auto.hpp: Auto-analysis related functions.

• compress.hpp: Data compression functions.

• config.hpp: Functions that deal with configuration options and files.

• dbg.hpp: Contains functions to control the debugging of a process.

• diskio.hpp: File I/O functions for IDA. You should not use standard C file I/O functions in modules. Use functions from this header, pro.h, and fpro.h instead.

• entry.hpp: Functions that deal with entry points to the program being disassembled.

• enum.hpp: Enumeration type management (assembly level types).

• err.h: Thread safe functions that deal with error codes.

• expr.hpp: Functions that deal with C-like expressions, external languages, and the built-in IDC language.

• fixup.hpp: Functions that deal with fixup (relocation) information.

• fpro.h: System independent counterparts of file I/O functions. These functions do check errors but never exit even if an error occurs. They return extended error code in qerrno variable. NOTE: You must use these functions instead of the C standard I/O functions.

• frame.hpp: Routines to manipulate function stack frames, stack variables, register variables and local labels.

• funcs.hpp: Routines for working with functions within the disassembled program. This file also contains routines for working with library signatures (e.g. FLIRT).

• gdl.hpp: Low level graph drawing operations.

• graph.hpp: Graph view management.

• help.h: Help subsystem. This subsystem is not used in IDP files. We put it just in case.

• ieee.h: IEEE floating point functions.

• intel.hpp: Header file from the IBM PC module. For information only. It will not compile because it contains references to internal files!

• lex.hpp: Tools for parsing C-like input.

• lines.hpp: High level functions that deal with the generation of the disassembled text lines.

• nalt.hpp: Definitions of various information kept in netnodes. These functions should not be used directly since they are very low level.

• moves.hpp: Functions and classes related to location history.

• name.hpp: Functions that deal with names (setting, deleting, getting, validating, etc).

• offset.hpp: Functions that deal with offsets.

• problems.hpp: Functions that deal with the list of problems.

• prodir.h: Low level functions to find files in the file system. It is better to use enumerate_files2() from diskio.hpp.

• pronet.h: Network related functions.

• range.hpp: Contains the definition of the 'range_t' class. This is a base class used by many parts of IDA, such as the 'segment_t' and 'segreg_range_t' (segment register) classes.

• registry.hpp: Registry related functions. IDA uses the registry to store global configuration options that must persist after IDA has been closed.

• segment.hpp: Functions that deal with program segmentation.

• segregs.hpp: Functions that deal with the segment registers. If your processor doesn't use segment registers, then you don't need this file.

• strlist.hpp: Functions that deal with the strings list.

• struct.hpp: Structure type management (assembly level types).

• typeinf.hpp: Describes the type information records in IDA.

• xref.hpp: Functions that deal with cross-references.

Here are the most common namespaces to start with:

idc: This namespace provides access to IDC scripting functions via C++ SDK. It is often used for common tasks like setting comments or modifying bytes.

idati: This namespace is used for interacting with type information, such as function signatures and type definitions.

idaapi: This namespace contains core classes and functions for interacting with IDA's API, including functions for handling UI elements, plugins, and database access.

idamisc: This namespace includes utility functions for various tasks, such as working with the address space and disassembly.

Code Snippets

Here are common functions and examples grouped by topics:

Part 1: Addresses and Names

Get the Current Address

ea_t ea = get_screen_ea();  // Get the current address
printf("Current address: %llx\n", ea);

Jump to the address

jumpto(0x401000);  // Jump to address 0x401000

Get the Minimum and Maximum Address in IDB

ea_t min_ea = get_inf_attr(INF_MIN_EA);
ea_t max_ea = get_inf_attr(INF_MAX_EA);

List All Instruction Addresses

for (ea_t ea = get_segm_by_name("CODE"); ea != BADADDR; ea = get_next_head(ea, badaddr)) {
    printf("Instruction address: %llx\n", ea);
}

Get the Name Associated with a Given Address

const char* name = get_name(0x100000da0);
printf("Name: %s\n", name);

Get the Address Associated with a Given Name

ea_t address = get_name_ea(0, "_main");
printf("Address: %llx\n", address);

Part 2: Reading and Writing Data

Reading Bytes and Words

u8 byte_value = get_byte(0x401000);  // Read a byte at address 0x401000
u16 word_value = get_word(0x401002);  // Read a word (2 bytes) at address 0x401002
u32 dword_value = get_dword(0x401004);  // Read a double word (4 bytes) at address 0x401004

printf("Byte: %x, Word: %x, Dword: %x\n", byte_value, word_value, dword_value);

Writing Bytes and Words

patch_byte(0x401000, 0x90);  // Write a byte (0x90) at address 0x401000
patch_word(0x401002, 0x9090);  // Write a word (0x9090) at address 0x401002
patch_dword(0x401004, 0x90909090);  // Write a double word (0x90909090) at address 0x401004

Part 3: Comments

Add a Regular or Repeatable Comment

set_cmt(0x401000, "This is a comment", false);  // Add a regular comment at address 0x401000
set_cmt(0x401000, "This is a repeatable comment", true);  // Add a repeatable comment at address 0x401000

Get a Regular Comment

const char* comment = get_cmt(0x401000, false);  // Get a regular comment at address 0x401000
printf("Comment: %s\n", comment);

Part 4: Segments

Get a Segment Name

const char* seg_name = get_segm_name(ea);
printf("Segment name: %s\n", seg_name);

Iterate Through All Segments

for (seg_t* seg = get_first_seg(); seg != nullptr; seg = get_next_seg(seg)) {
    printf("Segment name: %s\n", get_segm_name(seg->start_ea));
}

Part 5: Functions

Create and Delete Function

add_func(0x401000, 0x401050);  // Create a function starting at 0x401000 and ending at 0x401050
del_func(0x401000);  // Delete the function at 0x401000

Get the Name of the Function

const char* func_name = get_func_name(0x401000);
printf("Function name: %s\n", func_name);

Iterate Through All Functions

for (func_t* func = get_first_func(); func != nullptr; func = get_next_func(func)) {
    printf("Function address: %llx, name: %s\n", func->start_ea, get_func_name(func->start_ea));
}

Part 6: Navigating Cross-References (Xrefs)

List Cross-References to an Address

for (xref_t* xref = get_first_xref_to(0x401000); xref != nullptr; xref = get_next_xref_to(xref)) {
    printf("Xref to 0x401000 from %llx\n", xref->from);
}

List Cross-References from an Address

for (xref_t* xref = get_first_xref_from(0x401000); xref != nullptr; xref = get_next_xref_from(xref)) {
    printf("Xref from 0x401000 to %llx\n", xref->to);
}

Part 7: UI

Set Background Color of a Function

set_color(0x401000, CIC_ITEM, 0x007fff);  // Set background color for the function starting at address 0x401000

Display a Custom Dialog

msg("This is a custom message dialog. Good luck with learning the IDA C++ SDK!\n");

Complex Script Examples

What’s Next?

Our IDA SDK exposes API in the form of C++ libraries and header files, allowing you to create custom processor modules and plugins, automate tasks, or integrate new features directly into IDA. Our IDA API is defined and organized by the contents of the header files, that you can browse in our IDA C++ SDK Reference.

Typical use cases

With IDA SDK, you can develop loaders for unsupported binary formats or custom processors modules to disassemble and analyze non-standard files. What's more, you can write plugins to perform complex, automated tasks and more, allowing you to go far beyong the basic IDC scripting.

What to check next?

SDK Porting Guide

Check out our Porting Guide, which is prepared to help you migrate and adapt your existing modules and plugins from IDA 8.x to IDA 9.0.

Intro

IDAPython API gives you a way to enhance basic IDA capabilities and write your own plugins. These plugins can run directly in IDA as single scripts in the output window or even use complex UI.

IDAPython plugins are faster and easier to develop than C++ SDK plugins (thanks to excluding the build and compilation process) and offer almost the same powerful capabilities as native C++ plugins.

This tutorial will share best practices on how to start writing plugin in IDAPython, acccording to our new plugin framwork and best practises, that will streamline your plugin development.

Before you start

1. Check our for an up-to-date list of all modules, classes, functions, and so on.

2. Familiarize yourself with the ida_idaapi.plugin_t class, a basic and required class that provides the necessary structure for your plugin. It mirrors the C++ SDK plugin_t class.

3. Make sure your plugin will be compatible with the newest version of IDA—check our for recent changes.

Get a sample plugin

For this tutorial, we'll use the simple, exemplary plugin which adapted the new plugin framework that simplifies plugin development. It performs one specific task when called by the user after a database is loaded: it lists all functions and their addresses for the current IDA database and then terminates.

You can download "My First Plugin" from here:

Writing a plugin in IDAPython—basic steps

Create a single .py file to start

The minimum that your plugin should contain is a single Python file that will serve as an entry point. This file should define the main logic and include necessary imports and primary functions that will be executed when the plugin runs.

Define base classes

When creating a plugin, it's recommended to create a class inheriting from plugin_t with specific flags and a class inheriting from plugmod_t that performs the core functionality.

Define a class that inherits from ida_idaapi.plugin_t

While creating a plugin, you should include a class that inherits from plugin_t. This base class will outline the core functionality and lifecycle of your plugin.

Example of plugin_t class implementation:

class MyPlugin(ida_idaapi.plugin_t):
    flags = ida_idaapi.PLUGIN_UNL | ida_idaapi.PLUGIN_MULTI
    comment = "This is my first simple IDA Pro plugin"
    help = "This plugin lists all functions in the current database"
    wanted_name = "My First Plugin"
    wanted_hotkey = "Shift-P"

    def init(self):
        print(">>>MyPlugin: Init called.")
        return MyPlugmod()

Define a subclass that inherits from ida_idaapi.plugmod_t

When creating a plugin in the new framework, it's recommended to subclass plugmod_t, that performs the main task of the plugin.

Example of plugmod_t class implementation:

class MyPlugmod(ida_idaapi.plugmod_t):
    def __del__(self):
        print(">>> MyPlugmod: destructor called.")
    
    def run(self, arg):
        print(">>> MyPlugmod.run() is invoked with argument value: {arg}.")
        for func_ea in idautils.Functions():
            func_name = ida_funcs.get_func_name(func_ea)
            print(f">>>MyPlugmod: Function{func_name} at address {func_ea:x}")

Overview of MyPlugin class attributes

flags attribute

The flags attribute defines the behavior and plugin properties, and what is crucial, describe its lifecycle: how and when it is loaded into IDA.

Your plugin may have no flags (flags = 0). It is usually a good strategy for basic plugins that perform a specific task once and then are no longer needed. Assigning 0 to flags apply a default behavior to your plugin:

• it can be loaded and reloaded at any time;

• it is triggered by the user and does not run constantly in the background;

• it does not modify the database.

Common flags for plugins:

• PLUGIN_MULTI: Recommended for all plugins; this flag enables the plugin to run simultaneously across multiple opened IDBs within the same IDA instance.

• PLUGIN_FIX: The plugin loads when IDA launches and stays loaded until IDA exits.

• PLUGIN_DRAW: The plugin needs to be invoked for every screen refresh.

• PLUGIN_MOD: The plugin modifies the IDA database.

• PLUGIN_PROC: The plugin is a processor module extension.

• PLUGIN_DBG: The plugin will be loaded only when a debugger is active (for debugger-related plugins)

• PLUGIN_UNL: The plugin will be unloaded immediately after calling the run method.

In our example, we used PLUGIN_UNL flag, as after performing a specific task—listing functions in the current database—is no longer needed.

comment attribute The comment attribute allows you to provide a brief description of your plugin.

wanted_name attribute The wanted_name attribute specifies the preferred short name of the plugin, as it apperas under Edit -> Plugins submenu.

wanted_hotkey attribute The wanted_hotkey attribute specifies a preferred shortcut to run the plugin.

Specify your plugin lifecycle

Below we scrutinize the key components for defining your plugin lifecycle.

Define a PLUGIN_ENTRY function Declare a function called PLUGIN_ENTRY that returns a plugin_t instance (or an object containing all attributes of a plugin_t object).

Initialization

The init() method is called when the plugin is loaded into IDA and is responsible for initializing your plugin.

The init() method returns an pointer to a plugmod_t object and indicate that this object run method is going to be used.

In our example, when MyPlugin.init() is called it initalizes the plugin and returns a new instance of MyPlugmod.

    def init(self):
        print(">>>MyPlugin: Init called.")
        return MyPlugmod()

Activation

The run method is executed when the user triggers your plugin activation, whether via hotkey or Edit -> Plugins submenu.

In our example, when the run() method of MyPlugmod is called, it prints function names and addresses in Output window.

    def run(self, arg):
        print(">>> MyPlugmod.run() is invoked with argument value: {arg}.")
        for func_ea in idautils.Functions():
            func_name = ida_funcs.get_func_name(func_ea)
            print(f">>>MyPlugmod: Function{func_name} at address {func_ea:x}")

Unloading

The __del__() is called automatically when the plugin is going to be unloaded (destroyed). The conditions that define the circumstances under which the plugin should be unloaded depend on the flags setting.

Example of plugin lifecycle implementation:

class MyPlugmod(ida_idaapi.plugmod_t):
    def __del__(self):
        print(">>> MyPlugmod: destructor called.")
    
    def run(self, arg):
        print(">>> MyPlugmod.run() is invoked with argument value: {arg}.")
        for func_ea in idautils.Functions():
            func_name = ida_funcs.get_func_name(func_ea)
            print(f">>>MyPlugmod: Function{func_name} at address {func_ea:x}")


class MyPlugin(ida_idaapi.plugin_t):
    flags = ida_idaapi.PLUGIN_UNL | ida_idaapi.PLUGIN_MULTI
    comment = "This is my first simple IDA Pro plugin"
    help = "This plugin lists all functions in the current database"
    wanted_name = "My First Plugin"
    wanted_hotkey = "Shift-P"

    def init(self):
        print(">>>MyPlugin: Init called.")
        return MyPlugmod()


def PLUGIN_ENTRY():
    return MyPlugin()

In our example:

• PLUGIN_ENTRY() returns an instance of the MyPlugin class.

• MyPlugin.init() is called to initialize the plugin and returns an instance of MyPlugmod. MyPlugmod.run() is called when the plugin is activated by the user via the hotkey or the Plugins menu. Then, the run() method of MyPlugmod is called, which prints function names and addresses in the current IDA database.

Include an ida-plugin.json file

It's recommended to add an ida-plugin.json file to your plugin directory with essential metadata to ensure consistency, ease the organization of your plugin files (allows the plugin to be self-contained in its own sub-directory), and smooth the process for accepting your plugin into our official plugin repository, if you decide to share it with Hex-Rays community.

To work properly, the ida-plugin.json file must contain at the very least the IDAMetadataDescriptorVersion field as well as a plugin object containing the name and entryPoint fields.

The name will be used to identify the plugin and also generate a namespace name for it if necessary (e.g. an IDAPython plugin). The namespace name is generated by converting all non alphanumeric characters of the plugin name to underscores (_) and prepending __plugins__ to it. For example "my plugin" would become __plugins__my_plugin.

The entryPoint must be the filename of the "main" file for the plugin. It should be stored in the same directory as its ida-plugin.json file.

If the entryPoint has no file extension, IDA will assume it is a native plugin and append the appropriate file extension for dynamic shared objects for the host platform (.dll, .so, .dylib).

Example of the ida-plugin.json file:

{
  "IDAMetadataDescriptorVersion": 1,
  "plugin": {
    "name": "My First Plugin",
    "entryPoint": "my-first-plugin.py"
  }
}

Install and execute your plugin

1. Copy the plugin directory (in our exemplary case, the folder containing my-first-plugin.py and ida.plugin.json files) or single script to plugins directory in your IDA installation folder. Once it's done, you may need to restart your IDA to see your plugin name under Edit -> Plugins submenu.

2. Run the plugin by pressing the specified hotkey or execute it from Edit -> Plugins -> <your_plugin>.

IDA 9.0 API Changes and porting guide

• Introduction

• struct.hpp

  • Removed classes

  • Removed APIs

• enum.hpp

  • Removed APIs

• bytes.hpp

  • Added APIs

  • Modified APIs

  • Removed APIs

• dirtree.hpp

  • Modified APIs

• diskio.hpp

  • Modified APIs

  • Removed APIs

• err.h

  • Removed APIs

• expr.hpp

  • Modified APIs

• frame.hpp

  • Added APIs

  • Modified PIs

  • Removed APIs

• funcs.hpp

  • Added APIs

  • Removed APIs

• gdl.hpp

  • Added classes/structures

• hexrays.hpp

  • Added classes/structures

  • Added APIs

    • lvar_t

    • lvars_t

    • simple_graph_t

    • fnumber_t

    • minsn_t

    • mba_t

    • codegen_t

    • vd_failure_t

  • Modified APIs

    • stkvar_ref_t

    • mop_t

    • mba_t

    • valrng_t

  • Removed APIs:

    • valrng_t

    • ctree_item_t

    • ctree_parentee_t

    • vdui_t

• graph.hpp

  • Removed classes/structures

  • Modified classes/structures

  • Modified APIs

• idalib.hpp

  • Added APIs

• idd.hpp

  • Added APIs

• idp.hpp

  • Removed APIs:

  • Modified APIs:

  • Added APIs

    • procmod_t

• kernwin.hpp

  • Removed APIs

  • Removed classes/structures

  • Added APIs

    • tagged_line_section_t

    • chooser_base_t

  • Modified APIs

• lex.hpp

  • Modified APIs

• lines.hpp

  • Removed APIs

  • Modified APIs

• nalt.hpp

  • Modified APIs

• parsejson.hpp

  • Added APIs

    • jvalue_t

    • jobj_t

• pro.h

  • Removed APIs

  • Added APIs

    • bytevec_t

    • qlist

  • Added classes/structures

• regex.hpp

  • Removed APIs

• regfinder.hpp

  • Modified APIs

  • Removed APIs

  • Added APIs

• registry.hpp

  • Removed APIs

• search.hpp

  • Removed APIs

• typeinf.hpp

  • Removed APIs

  • Modified APIs

  • Added classes/structures

  • Added APIs

    • til_t

    • callregs_t

    • tinfo_t

    • func_type_data_t

    • enum_type_data_t

    • udm_t

    • udt_type_data_t

• IDB events

Introduction

The largest change is the removal of two headers:

• struct.hpp

• enum.hpp

The functionalities for working with user-defined types are now available in typeinf.hpp (tinfo_t class).

struct.hpp

Removed classes

• class member_t;

• class struc_t;

struc_t is replaced by the notion of "user-defined type" (udt_type_data_t class) and member_t by dt member (udm_t class).

Removed APIs

• get_struc_qty() Rough equivalent is get_ordinal_limit() or get_ordinal_count() but note that it also includes enums and typedefs.

• get_first_struc_idx()

• get_last_struc_idx()

• get_prev_struc_idx()

• get_next_struc_idx()

Local type ordinals always start at 1 (0 is invalid ordinal) and go up to get_ordinal_limit().

• get_struc_idx(tid_t id)

• get_struc_by_idx(uval_t idx)

enum.hpp

Enumerations are now manipulated via:

• tinfo_t class

• enum_type_data_t class

• edm_t class. in typeinf.hpp

Removed APIs

• get_enum_qty(void)

• getn_enum(size_t idx)

• get_enum_idx(enum_t id)

• get_enum(const char *name)

• is_bf(enum_t id)

• is_enum_hidden(enum_t id)

• set_enum_hidden(enum_t id, bool hidden)

• is_enum_fromtil(enum_t id)

• set_enum_fromtil(enum_t id, bool fromtil)

• is_ghost_enum(enum_t id)

• set_enum_ghost(enum_t id, bool ghost)

• get_enum_name(qstring *out, enum_t id)

• get_enum_name2(qstring *out, enum_t id, int flags=0)

• get_enum_name(tid_t id, int flags=0)

• get_enum_width(enum_t id)

• set_enum_width(enum_t id, int width)

• get_enum_cmt(qstring *buf, enum_t id, bool repeatable)

• get_enum_size(enum_t id)

• get_enum_flag(enum_t id)

• get_enum_member_by_name(const char *name)

• get_enum_member_value(const_t id)

• get_enum_member_enum(const_t id)

• get_enum_member_bmask(const_t id)

• get_enum_member(enum_t id, uval_t value, int serial, bmask_t mask)

• get_first_bmask(enum_t enum_id)

• get_last_bmask(enum_t enum_id)

• get_next_bmask(enum_t enum_id, bmask_t bmask\)

• get_prev_bmask(enum_t enum_id, bmask_t bmask)

• get_first_enum_member(enum_t id, bmask_t bmask=DEFMASK)

• get_last_enum_member(enum_t id, bmask_t bmask=DEFMASK)

• get_next_enum_member(enum_t id, uval_t value, bmask_t bmask=DEFMASK)

• get_prev_enum_member(enum_t id, uval_t value, bmask_t bmask=DEFMASK)

• get_enum_member_name(qstring *out, const_t id)

• get_enum_member_cmt(qstring *buf, const_t id, bool repeatable)

• get_first_serial_enum_member(uchar *out_serial, enum_t id, uval_t value, bmask_t bmask)

• get_last_serial_enum_member(uchar *out_serial, enum_t id, uval_t value, bmask_t bmask)

• get_next_serial_enum_member(uchar *in_out_serial, const_t first_cid)

• get_prev_serial_enum_member(uchar *in_out_serial, const_t first_cid)

• for_all_enum_members(enum_t id, enum_member_visitor_t &cv)

• ida_export get_enum_member_serial(const_t cid)

• get_enum_type_ordinal(enum_t id)

• set_enum_type_ordinal(enum_t id, int32 ord)

• add_enum(size_t idx, const char *name, flags64_t flag)

• del_enum(enum_t id)

• set_enum_idx(enum_t id, size_t idx)

• set_enum_bf(enum_t id, bool bf)

• set_enum_name(enum_t id, const char *name)

• set_enum_cmt(enum_t id, const char *cmt, bool repeatable)

• set_enum_flag(enum_t id, flags64_t flag)

• add_enum_member(enum_t id, const char *name, uval_t value, bmask_t bmask=DEFMASK)

• del_enum_member(enum_t id, uval_t value, uchar serial, bmask_t bmask)

• set_enum_member_name(const_t id, const char *name)

• set_enum_member_cmt(const_t id, const char *cmt, bool repeatable)

• is_one_bit_mask(bmask_t mask)

• set_bmask_name(enum_t id, bmask_t bmask, const char *name)

• get_bmask_name(qstring *out, enum_t id, bmask_t bmask)

• set_bmask_cmt(enum_t id, bmask_t bmask, const char *cmt, bool repeatable)

• get_bmask_cmt(qstring *buf, enum_t id, bmask_t bmask, bool repeatable)

bytes.hpp

Added APIs

• idaman ea_t ida_export find_binary(ea_t startea, ea_t endea, const char *ubinstr, int radix, int sflag, int strlits_encoding=0)

Modified APIs

Removed APIs

• bin_search2(ea_t start_ea, ea_t end_ea, const compiled_binpat_vec_t &data, int flags)

• bin_search(ea_t, ea_t, const uchar *, const uchar *, size_t, int, int)

• get_8bit(ea_t *ea, uint32 *v, int *nbit)

• get_octet(ea_t *ea, uint64 *v, int *nbit)

• free_chunk(ea_t bottom, asize_t size, int32 step)

dirtree.hpp

Modified APIs

diskio.hpp

Modified APIs

Removed APIs

• ecreate(const char *file)

• eclose(FILE *fp)

• eread(FILE *fp, void *buf, size_t size)

• ewrite(FILE *fp, const void *buf, size_t size)

• eseek(FILE *fp, qoff64_t pos)

• enumerate_files(char *answer, size_t answer_size, const char *path, const char *fname, int (idaapi*func)(const char *file,void *ud), void *ud=nullptr)

err.h

Removed APIs

• qerrcode(int new_code=-1)

expr.hpp

Modified APIs

frame.hpp

Added APIs

• idaman bool ida_export add_frame_member(const func_t *pfn, const char *name, uval_t offset, const tinfo_t &tif, const struct value_repr_t *repr=nullptr, uint etf_flags=0)

• THREAD_SAFE bool is_anonymous_member_name(const char *name)

• THREAD_SAFE bool is_dummy_member_name(const char *name)

• idaman bool ida_export is_special_frame_member(tid_t tid)

• idaman bool ida_export set_frame_member_type(const func_t *pfn, uval_t offset, const tinfo_t &tif, const struct value_repr_t *repr=nullptr, uint etf_flags=0)

• idaman bool ida_export delete_frame_members(const func_t *pfn, uval_t start_offset, uval_t end_offset)

• idaman sval_t ida_export calc_frame_offset(func_t *pfn, sval_t off, const insn_t *insn = nullptr, const op_t *op = nullptr)

Modified PIs

Removed APIs

• get_frame_member_by_id(qstring *out_mname, struc_t **out_fptr, tid_t mid)

• get_stkvar(sval_t *actval, const insn_t &insn, const op_t &x, sval_t v) See get_stkvar in ida_typeinf.tinfo_t

• get_min_spd_ea(func_t *pfn)

• delete_unreferenced_stkvars(func_t *pfn)

• delete_wrong_stkvar_ops(func_t *pfn)

funcs.hpp

Added APIs

• bool func_item_iterator_t::set_ea(ea_t _ea)

Removed APIs

• save_signatures(void)

• invalidate_sp_analysis(func_t *pfn)

• invalidate_sp_analysis(ea_t ea)

gdl.hpp

Added classes/structures

• struct edge_t

• class node_ordering_t

hexrays.hpp

Added classes/structures

• class control_graph_t

• class edge_mapper_t

• class node_bitset_t

• class array_of_node_bitset_t

• struct ctry_t

• struct cthrow_t

• struct catchexpr_t

• struct ccatch_t

• struct cblock_pos_t

Added APIs

• uvlr_t max_vlr_value(int size)

• uvlr_t min_vlr_svalue(int size)

• uvlr_t max_vlr_svalue(int size)

• bool is_unsigned_cmpop(cmpop_t cmpop)

• bool is_signed_cmpop(cmpop_t cmpop)

• bool is_cmpop_with_eq(cmpop_t cmpop)

• bool is_cmpop_without_eq(cmpop_t cmpop)

lvar_t

• bool was_scattered_arg() const

• void set_scattered_arg()

• void clr_scattered_arg()

lvars_t

• int find_input_reg(int reg, int _size=1)

simple_graph_t

• virtual bool ignore_edge(int /*src*/, int /*dst*/ ) const

• void hexapi compute_dominators(array_of_node_bitset_t &domin, bool post=false) const

• void hexapi compute_immediate_dominators(const array_of_node_bitset_t &domin, intvec_t &idomin, bool post=false) const

• int hexapi depth_first_preorder(node_ordering_t *pre) const

• int hexapi depth_first_postorder(node_ordering_t *post) const

• void depth_first_postorder(node_ordering_t *post, edge_mapper_t *et) const

• void depth_first_postorder_for_all_entries(node_ordering_t *post) const

• intvec_t find_dead_nodes() const

• void find_reaching_nodes(int n, node_bitset_t &reaching) const

• bool path_exists(int m, int n) const

• bool path_back(const array_of_node_bitset_t &domin, int m, int n) const

• bool path_back(const edge_mapper_t &et, int m, int n) const

• iterator begin() const

• iterator end()

• int front()

• void inc(iterator &p, int n=1) const

• virtual int hexapi goup(int node) const

fnumber_t

• int calc_max_exp() const

• bool is_nan() const

minsn_t

• bool was_unpaired() const

mba_t

• mblock_t *hexapi split_block(mblock_t *blk, minsn_t *start_insn)

• merror_t hexapi inline_func(codegen_t &cdg, int blknum, mba_ranges_t &ranges, int decomp_flags=0, int inline_flags=0)

• const stkpnt_t *hexapi locate_stkpnt(ea_t ea) const

codegen_t

• void hexapi clear()

vd_failure_t

• virtual const char *what() const noexcept override

Modified APIs

stkvar_ref_t

mop_t

mba_t

valrng_t

Removed APIs:

• bool hexapi get_member_type(const member_t *mptr, tinfo_t *type)

• bool hexapi checkout_hexrays_license(bool silent)

• bool get_member_type(const member_t *mptr, tinfo_t *type)

valrng_t

• static uvlr_t max_value(int size_)

• static uvlr_t min_svalue(int size_)

• static uvlr_t max_svalue(int size_)

ctree_item_t

• member_t *hexapi get_memptr(struc_t **p_sptr=nullptr) const

ctree_parentee_t

• cblock_t *get_block()

vdui_t

• bool hexapi set_strmem_type(struc_t *sptr, member_t *mptr)

• bool hexapi rename_strmem(struc_t *sptr, member_t *mptr)

graph.hpp

Removed classes/structures

• class node_ordering_t See code

• struct edge_t See code

Modified classes/structures

Modified APIs

idalib.hpp

The new header for the IDA library

Added APIs

• idaman int ida_export init_library(int argc = 0, char *argv[] = nullptr)

• idaman int ida_export open_database(const char *file_path, bool run_auto)

• idaman void ida_export close_database(bool save)

idd.hpp

Added APIs

• idaman int ida_export cpu2ieee(fpvalue_t *ieee_out, const void *cpu_fpval, int size)

• idaman int ida_export ieee2cpu(void *cpu_fpval, const fpvalue_t &ieee_out, int size)

idp.hpp

Removed APIs:

• processor_t::has_realcvt(void) const

Modified APIs:

Added APIs

procmod_t

• const op_t *procmod_t::make_op_reg(op_t *op, int reg, int8 dtype = -1) const

• const op_t *procmod_t::make_op_imm(op_t *op, uval_t val, int8 dtype = -1) const

• const op_t *procmod_t::make_op_displ(op_t *op, int base_reg, uval_t displ, int8 dtype = -1) const

• const op_t *procmod_t::make_op_phrase(op_t *op, int base_reg, int index_reg, int8 dtype = -1) const

See also IDB events for a table providing a list a event replacement and removal.

kernwin.hpp

Removed APIs

• open_enums_window(tid_t const_id=BADADDR)

• open_structs_window(tid_t id=BADADDR, uval_t offset=0)

• choose_struc(const char *title)

• choose_enum_by_value(const char *title, enum_t default_id, uint64 value, int nbytes, uchar *serial)

Removed classes/structures

• class enumplace_t

• class structplace_t

Added APIs

• bool is_ida_library(char *path, size_t pathsize, void** handle)

tagged_line_section_t

• const tagged_line_section_t::tagged_line_section_t *nearest_before(const tagged_line_section_t &range, cpidx_t start, color_t tag=0) const

• const tagged_line_section_t::tagged_line_section_t *nearest_after(const tagged_line_section_t &range, cpidx_t start, color_t tag=0) const

chooser_base_t

• bool chooser_base_t::has_widget_lifecycle() const

Modified APIs

lex.hpp

Modified APIs

lines.hpp

Removed APIs

• set_user_defined_prefix(size_t width, void (idaapi *get_user_defined_prefix)(qstring *buf, ea_t ea, int lnnum, int indent, const char *line))

Modified APIs

nalt.hpp

Modified APIs

parsejson.hpp

Added APIs

jvalue_t

• void jvalue_t::set_str(const char *s)

jobj_t

• void jobj_t::put(const char *key, const jobj_t &value)

pro.h

Removed APIs

• unpack_memory(void *buf, size_t size, const uchar **pptr, const uchar *end)

Added APIs

• idaman THREAD_SAFE bool ida_export get_login_name(qstring *out)

• idaman void *ida_export pipe_process(qhandle_t *read_handle, qhandle_t *write_handle, launch_process_params_t *lpp, qstring *errbuf=nullptr)

bytevec_t

• qstring bytevec_t::tohex(bool upper_case=true) const

qlist

• void qlist::splice(iterator pos, qlist &other, iterator first, iterator last)

Added classes/structures

• struct memory_serializer_t

regex.hpp

Removed APIs

• regcomp(struct regex_t *preg, const char *pattern, int cflags)

• regerror(int errcode, const struct regex_t *preg, char *errbuf, size_t errbuf_size)

• regexec(const struct regex_t *preg, const char *str, size_t nmatch, struct regmatch_t pmatch[], int eflags)

• regfree(struct regex_t *preg)

regfinder.hpp

Modified APIs

Removed APIs

• reg_finder_op_make_rfop(func_t *pfn, const insn_t &insn, const op_t &op)

Added APIs

• void reg_value_info_t::movt(const reg_value_info_t &r, const insn_t &insn)

• static int reg_finder_op_t::get_op_width(const op_t &op)

• static reg_finder_op_t reg_finder_op_t::make_stkoff(sval_t stkoff, int width)

registry.hpp

Removed APIs

• reg_load(void)

• reg_flush(void)

search.hpp

Removed APIs

• user2bin(uchar *, uchar *, ea_t, const char *, int, bool)

• find_binary(ea_t, ea_t, const char *, int, int)

typeinf.hpp

Removed APIs

• set_numbered_type(til_t *ti, uint32 ordinal, int ntf_flags, const char *name, const type_t *type, const p_list *fields=nullptr, const char *cmt=nullptr, const p_list *fldcmts=nullptr, const sclass_t *sclass=nullptr)

• get_ordinal_from_idb_type(const char *name, const type_t *type)

• is_autosync(const char *name, const type_t *type)

• is_autosync(const char *name, const tinfo_t &tif)

• import_type(const til_t *til, int idx, const char *name, int flags=0)

• get_udm_tid(const udm_t *udm, const char *udt_name)

Modified APIs

Added classes/structures

• struct udm_visitor_t

Added APIs

• bool ida_export detach_tinfo_t(tinfo_t *_this)

• bool stroff_as_size(int plen, const tinfo_t &tif, asize_t value)

• int ida_export visit_stroff_udms(udm_visitor_t &sfv, const tid_t *path, int plen, adiff_t *disp, bool appzero)

• bool is_one_bit_mask(uval_t mask)

til_t

• til_t *til_t::find_base(const char *n)

callregs_t

• void callregs_t::set_registers(reg_kind_t kind, int first_reg, int last_reg)

tinfo_t

• bool tinfo_t::get_named_type(const char *name, type_t decl_type=BTF_TYPEDEF, bool resolve=true, bool try_ordinal=true)

• bool tinfo_t::get_numbered_type(uint32 ordinal, type_t decl_type=BTF_TYPEDEF, bool resolve=true)

• bool tinfo_t::detach()

• bool tinfo_t::is_punknown()

• int tinfo_t::find_udm(uint64 offset, int strmem_flags=0) const

• int tinfo_t::find_udm(const char *name, int strmem_flags=0) const

• size_t tinfo_t::get_enum_nmembers() const

• bool tinfo_t::is_empty_enum() const

• tinfo_code_t tinfo_t::get_enum_repr(value_repr_t *repr) const

• int tinfo_t::get_enum_width() const

• uint64 tinfo_t::calc_enum_mask() const

• tid_t tnfo_t::get_edm_tid(size_t idx) const

• tinfo_t tinfo_t::get_innermost_member_type(uint64 bitoffset, uint64 *out_bitoffset=nullptr) const

• bool tinfo_t::is_udm_by_til(size_t idx) const

• tinfo_code_t tinfo_t::set_udm_by_til(size_t idx, bool on=true, uint etf_flags=0)

• tinfo_code_t tinfo_t::set_fixed_struct(bool on=true)

• tinfo_code_t tinfo_t::set_struct_size(size_t new_size)

• bool tinfo_t::is_fixed_struct() const

• bool tinfo_t::get_func_frame(const func_t *pfn)

• bool tinfo_t::is_frame() const

• ea_t tinfo_t::get_frame_func() const

• ssize_t tinfo_t::get_stkvar(sval_t *actval, const insn_t &insn, const op_t *x, sval_t v)

• tinfo_code_t tinfo_t::set_enum_radix(int radix, bool sign, uint etf_flags=0)

• tinfo_code_t tinfo_t::set_funcarg_type(size_t index, const tinfo_t &tif, uint etf_flags=0)

• tinfo_code_t tinfo_t::set_func_rettype(const tinfo_t &tif, uint etf_flags=0)

• tinfo_code_t tinfo_t::del_funcargs(size_t idx1, size_t idx2, uint etf_flags=0)

• tinfo_code_t tinfo_t::del_funcarg(size_t idx, uint etf_flags=0)

• tinfo_code_t tinfo_t::add_funcarg(const funcarg_t &farg, uint etf_flags=0, ssize_t idx=-1)

• tinfo_code_t tinfo_t::set_func_cc(cm_t cc, uint etf_flags=0)

• tinfo_code_t tinfo_t::set_funcarg_loc(size_t index, const argloc_t &argloc, uint etf_flags=0)

• tinfo_code_t tinfo_t::et_func_retloc(const argloc_t &argloc, uint etf_flags=0)

func_type_data_t

• ssize_t func_type_data_t::find_argument(const char *name, size_t from=0, size_t to=size_t(-1)) const

enum_type_data_t

• tinfo_code_t enum_type_data_t::get_value_repr(value_repr_t *repr) const

• uchar enum_type_data_t::get_serial(size_t index) const

• uchar enum_type_data_t::get_max_serial(uint64 value) const

udm_t

• bool udm_t::is_retaddr() const

• bool udm_t::is_savregs() const

• bool udm_t::is_special_member() const

• bool udm_t::is_by_til() const

• void udm_t::set_retaddr(bool on=true)

• void udm_t::set_savregs(bool on=true)

• void udm_t::set_by_til(bool on=true)

udt_type_data_t

• bool udt_type_data_t::is_fixed() const

• void udt_type_data_t::set_fixed(bool on=true)

IDB events

The following table provide a list of IDB events that have been replaced or, in some cases, removed.

Getting started with IDAPython

Intro

The IDAPython API provides you a range of functions to interact with the disassembler, navigate through the output, and manipulate various elements such as functions, instructions, data, and comments.

This guide is is designed to speed up the learning curve in IDAPython API and kickstart your journey with scripting in IDA, assuming that you are already found your way around IDA and got familiar with IDA basics.

How this guide is structured?

First, check basics for the core concepts like common variables, then dive into our simple, reusable code snippets showing examples of commonly used functions. When you feel comfortable with some of the most popular IDAPython API usage, you can delve into our set of more complex examples.

Basics

Common modules

IDAPython API is organized in modules, however their number may be a bit overwhelming for the first sigh. Here's the list of modules that should catch your attention first:

• idautils: This module extracts the most useful and handy functions allowing you to jump right away and interact with the disassembly without the need to scrutinize the whole IDAPython API from the start. You can find here functions to iterate through whole segments, functions (founded by IDA and also user-defined), named locations, etc.

• ida_idaapi: The ida_idaapi module comes handy when you want to create custom plugins or handle events, as it gives you access to more advanced functions and allows interaction with overall system

• idc: This module provides functions that were originally part of native IDA IDC scripting language, wrapped for use in IDAPython API. This is a great starting point if you're already familiar with IDC scripting.

• ida_funcs: This module gives you tools to create and manipulate functions within IDA.

• ida_kernwin: This module provides functionality to interact with IDA UI, so you can create custom dialogs and more.

Common variables and constants

When you start working with IDAPython, you'll realize that one of the most commonly passed variables is ea, which refers to the valid memory address (effective address). On the other hand, the BADADDR is a constant that indicates an invalid address. It is used to indicate that an operation (such as querying a function) has failed or returned an invalid result, or signify that a specific memory location is unusable. Whenever you're working with functions that return memory addresses, it's a best practice to check whether the result equals BADADDR to ensure the operation was successful.

Code snippets

Here you can check the most common functions grouped by topics and short code samples that can serve as building blocks for longer scripts. They are usually focused on performing one specific action and can be easily reusable in more complex scripts, which you can find later under examples.

Part 1: Navigating the disassembly—addresses and names

Get the current address:**

ea = idc.here()  # Get the current address
print(f"Current address: {hex(ea)}")

idc.get_screen_ea()

Set the current address

idc.jumpto(0x401000)  # Jump to address 0x401000

Get the minimum address in IDB

idc.get_inf_attr(INF_MIN_EA)

Get the maximum address in IDB

idc.get_inf_attr(INF_MAX_EA)

List all instruction addresses

for ea in idautils.Heads():
  print(hex(ea))

Get the name associated with a given address

ida_name.get_name(0x100000da0)

Get the address associated with a given name

ida_name.get_name_ea(0, "_main")

Part 2: Reading and Writing Data

Reading Bytes and Words

byte_value = idc.get_wide_byte(0x401000)  # Read a byte at address 0x401000
word_value = idc.get_wide_word(0x401002)  # Read a word (2 bytes) at address 0x401002
dword_value = idc.get_wide_dword(0x401004)  # Read a double word (4 bytes) at address 0x401004

print(f"Byte: {byte_value}, Word: {word_value}, Dword: {dword_value}")

Writing Bytes and Words

idc.patch_byte(0x401000, 0x90)  # Write a byte (0x90) at address 0x401000
idc.patch_word(0x401002, 0x9090)  # Write a word (0x9090) at address 0x401002
idc.patch_dword(0x401004, 0x90909090)  # Write a double word (0x90909090) at address 0x401004

Part 3: Comments

Add a regular (non-repetable) or repeatable comment

idc.set_cmt(0x401000, "This is a comment", 0)  # Add a regular comment at address 0x401000
idc.set_cmt(0x401000, "This is a repeatable comment", 1)  # Add a repeatable comment at address 0x401000

Get a regular comment

comment = idc.get_cmt(0x401000, 0)  # Get a regular comment at address 0x401000
print(f"Comment: {comment}")

Segments

Get a segment name

idc.get_segm_name(ea)

Get the first segment address:

get_first_seg()

Iterate through all segments and return segment names

for seg in idautils.Segments(): print (idc.get_segm_name(seg))

Add segment

Part X: Functions

Create and delete function

idc.add_func(0x401000, 0x401050)  # Create a function starting at 0x401000 and ending at 0x401050
idc.del_func(0x401000)  # Delete the function at 0x401000

Get the name of the function

get_func_name(ea)

Iterate through all functions and print their effective addresses and names

for func_ea in idautils.Functions(): func_name = idc.get_func_name(func_ea); print(hex(func_ea), func_name)

Part: Navigating cross-references (Xrefs)

List cross-references to an address

for xref in idautils.XrefsTo(0x401000):
    print(f"Xref to 0x401000 from {hex(xref.frm)}")

List cross-references from an address:**

for xref in idautils.XrefsFrom(0x401000):
    print(f"Xref from 0x401000 to {hex(xref.to)}")

Iterate through all cross-references to the specific address and print the address from where the reference originates.

for ref in idautils.XrefsTo(ea):
  print(hex(ref.frm))

Part X: UI

Set background color of a function

set_color(0x401000, idc.CIC_ITEM, 0x007fff)  # Set background color for the function starting at address 0x401000

Display a custom dialog

ida_kernwin.info("This is a custom message dialog. Good luck with learning IDAPython API!")

Complex script examples

If you feel more comfortable with IDAPython now, you can delve into more complex and advanced examples shipped with your IDA instance. You can find them in the python/examples folder where your IDA is installed or check them from our docs These collection gathered more advanced code samples, which usually make use of more modules and APIs.

What's next?

Delve into our tutorial on how to create your first custom plugin in IDAPython.

The IDA SDK, which you can get from our Download Center in My Hex-Rays Portal, provides sample code in addition to necessary libraries and headers. These exemplary plugins, processor modules, or file loaders are designed to help you create your own plugins, modules, and more.

Where can I find all the examples?

The IDA SDK is shipped with plenty of samples (including, for example, sample processor modules or loaders) and exemplary plugins that you can find in the IDA SDK folder. To kickstart your journey with the IDA SDK, we encourage you to check out the included samples, compile them, and run them.

Sample plugins

The plugins folder contains sample plugins written in C++. Usually, the subfolders contains at minimum the cpp file(s) and a makefile.

Below, we present only a selection of samples to familiarize yourself with the possibilities of the C++ SDK. All of these samples and their corresponding makefiles can be found in your plugins folder inside the SDK directory.

hello

Simple hello word plugin ideal to get started with IDA SDK.

#include <ida.hpp>
#include <idp.hpp>
#include <loader.hpp>
#include <kernwin.hpp>

//--------------------------------------------------------------------------
struct plugin_ctx_t : public plugmod_t
{
  virtual bool idaapi run(size_t) override;
};

//--------------------------------------------------------------------------
bool idaapi plugin_ctx_t::run(size_t)
{
  msg("Hello, world! (cpp)\n");
  return true;
}

//--------------------------------------------------------------------------
static plugmod_t *idaapi init()
{
  return new plugin_ctx_t;
}

//--------------------------------------------------------------------------
plugin_t PLUGIN =
{
  IDP_INTERFACE_VERSION,
  PLUGIN_UNL            // Unload the plugin immediately after calling 'run'
  | PLUGIN_MULTI,       // The plugin can work with multiple idbs in parallel
  init,                 // initialize
  nullptr,
  nullptr,
  nullptr,              // long comment about the plugin
  nullptr,              // multiline help about the plugin
  "Hello, world",       // the preferred short name of the plugin
  nullptr,              // the preferred hotkey to run the plugin
};

vcsample

Sample plugin, ideal to get familiar with plugins structure.

/*
 *  This is a sample plugin module
 *
 *  It can be compiled by any of the supported compilers:
 *
 *      - Visual C++
 *      - GCC
 *
 */

#include <ida.hpp>
#include <idp.hpp>
#include <expr.hpp>
#include <bytes.hpp>
#include <loader.hpp>
#include <kernwin.hpp>

//#define INSTALL_SAMPLE_CALLBACK
//#define HAS_USER_DEFINED_PREFIX

//--------------------------------------------------------------------------
//lint -e754 struct member not referenced
struct plugin_data_t : public plugmod_t, public event_listener_t
{
  ea_t old_ea = BADADDR;
  int old_lnnum = -1;
  virtual ssize_t idaapi on_event(ssize_t event_id, va_list) override;
  virtual bool idaapi run(size_t arg) override;

  idaapi ~plugin_data_t();
};

//--------------------------------------------------------------------------
// Example of a user-defined IDC function in C++

//#define DEFINE_IDC_FUNC
#ifdef DEFINE_IDC_FUNC
static error_t idaapi myfunc5(idc_value_t *argv, idc_value_t *res)
{
  msg("myfunc is called with arg0=%x and arg1=%s\n", argv[0].num, argv[1].c_str());
  res->num = 5;     // let's return 5
  return eOk;
}
static const char myfunc5_args[] = { VT_LONG, VT_STR, 0 };
static const ext_idcfunc_t myfunc5_desc =
{
  { "MyFunc5", myfunc5, myfunc5_args, nullptr, 0, 0 }
};
#endif // DEFINE_IDC_FUNC

//--------------------------------------------------------------------------
// This callback is called for UI notification events
ssize_t idaapi plugin_data_t::on_event(ssize_t event_id, va_list)
{
  if ( event_id != ui_msg     // avoid recursion
    && event_id != ui_refreshmarked ) // ignore uninteresting events
  {
    msg("ui_callback %" FMT_ZS "\n", event_id);
  }
  return 0; // 0 means "continue processing the event"
            // otherwise the event is considered as processed
}

//--------------------------------------------------------------------------
// A sample how to generate user-defined line prefixes
#ifdef HAS_USER_DEFINED_PREFIX
static const int prefix_width = 8;

struct sample_prefix_t : public user_defined_prefix_t
{
  plugin_data_t *pd;
  sample_prefix_t(plugin_data_t *d) :
    user_defined_prefix_t(prefix_width, d), pd(d) {}
  virtual void idaapi get_user_defined_prefix(
        qstring *out,
        ea_t ea,
        const insn_t & /*insn*/,
        int lnnum,
        int indent,
        const char *line) override
  {
    out->qclear();        // empty prefix by default

    // We want to display the prefix only the lines which
    // contain the instruction itself

    if ( indent != -1 )           // a directive
      return;

    if ( line[0] == '\0' )        // empty line
      return;

    if ( tag_advance(line,1)[-1] == ash.cmnt[0] ) // comment line...
      return;

    // We don't want the prefix to be printed again for other lines of the
    // same instruction/data. For that we remember the line number
    // and compare it before generating the prefix

    if ( pd->old_ea == ea && pd->old_lnnum == lnnum )
      return;

    // Ok, seems that we found an instruction line.

    // Let's display the size of the current item as the user-defined prefix
    asize_t our_size = get_item_size(ea);

    // We don't bother about the width of the prefix
    // because it will be padded with spaces by the kernel

    out->sprnt(" %" FMT_64 "d", our_size);

    // Remember the address and line number we produced the line prefix for:
    pd->old_ea = ea;
    pd->old_lnnum = lnnum;
  }
};
#endif // HAS_USER_DEFINED_PREFIX

//--------------------------------------------------------------------------
static plugmod_t *idaapi init()
{
  if ( inf_get_filetype() == f_ELF )
    return nullptr; // we do not want to work with this idb

  plugin_data_t *pd = new plugin_data_t;

  // notifications
#ifdef INSTALL_SAMPLE_CALLBACK
  hook_event_listener(HT_UI, pd, pd);
#endif // INSTALL_SAMPLE_CALLBACK

  // user-defined prefix. will be automatically uninstalled by the kernel
  // when our plugin gets unloaded.
#ifdef HAS_USER_DEFINED_PREFIX
  new sample_prefix_t(pd);
#endif // HAS_USER_DEFINED_PREFIX

  // custom IDC function
#ifdef DEFINE_IDC_FUNC
  add_idc_func(myfunc5_desc);
#endif // DEFINE_IDC_FUNC

  // an example how to retrieve plugin options
  const char *options = get_plugin_options("vcsample");
  if ( options != nullptr )
    warning("command line options: %s", options);

  return pd;
}

//--------------------------------------------------------------------------
plugin_data_t::~plugin_data_t()
{
#ifdef DEFINE_IDC_FUNC
  del_idc_func(myfunc5_desc.name);
#endif
}

//--------------------------------------------------------------------------
bool idaapi plugin_data_t::run(size_t arg)
{
  warning("vcsample plugin has been called with arg %" FMT_Z, arg);
  // msg("just fyi: the current screen address is: %a\n", get_screen_ea());
  return true;
}

//--------------------------------------------------------------------------
static const char comment[] = "This is a sample plugin. It does nothing useful";

static const char help[] =
  "A sample plugin module\n"
  "\n"
  "This module shows you how to create plugin modules.\n"
  "\n"
  "It does nothing useful - just prints a message that is was called\n"
  "and shows the current address.\n";

//--------------------------------------------------------------------------
// This is the preferred name of the plugin module in the menu system
// The preferred name may be overridden in plugins.cfg file

static const char wanted_name[] = "Sample plugin";


// This is the preferred hotkey for the plugin module
// The preferred hotkey may be overridden in plugins.cfg file

static const char wanted_hotkey[] = "";


//--------------------------------------------------------------------------
//
//      PLUGIN DESCRIPTION BLOCK
//
//--------------------------------------------------------------------------
plugin_t PLUGIN =
{
  IDP_INTERFACE_VERSION,
  PLUGIN_MULTI,         // plugin flags
  init,                 // initialize

  nullptr,              // terminate. this pointer may be nullptr.

  nullptr,              // invoke plugin

  comment,              // long comment about the plugin
                        // it could appear in the status line
                        // or as a hint

  help,                 // multiline help about the plugin

  wanted_name,          // the preferred short name of the plugin
  wanted_hotkey         // the preferred hotkey to run the plugin
};

calle

Sample plugin that allows the user to change the address of the called function.

/*
 *  Change the callee address for constructions like
 *
 *  call esi    ; LocalFree
 *
 */

#include <ida.hpp>
#include <idp.hpp>
#include <loader.hpp>
#include <kernwin.hpp>
#include <bytes.hpp>
#include <auto.hpp>
#include <segregs.hpp>
#define T 20

struct callee_vars_t : public plugmod_t
{
  processor_t &ph;
  callee_vars_t(processor_t &_ph) : ph(_ph) {}
  virtual bool idaapi run(size_t arg) override;
};

//--------------------------------------------------------------------------
static plugmod_t *idaapi init()
{
  processor_t &ph = PH;
  if ( ph.id != PLFM_386 && ph.id != PLFM_MIPS && ph.id != PLFM_ARM )
    return nullptr; // only for x86, MIPS and ARM
  return new callee_vars_t(ph);
}

//--------------------------------------------------------------------------
static const char comment[] = "Change the callee address";
static const char help[] =
  "This plugin allows the user to change the address of the called function\n"
  "in constructs like\n"
  "\n"
  "       call esi\n"
  "\n"
  "You can enter a function name instead of its address\n";

//--------------------------------------------------------------------------
static const char *const form =
  "HELP\n"
  "%s\n"
  "ENDHELP\n"
  "Enter the callee address\n"
  "\n"
  "  <~C~allee:$::40:::>\n"
  "\n"
  "\n";

bool idaapi callee_vars_t::run(size_t)
{
  const char *nname;
  if ( ph.id == PLFM_MIPS )
    nname = "$ mips";
  else if ( ph.id == PLFM_ARM )
    nname = " $arm";
  else
    nname = "$ vmm functions";
  netnode n(nname);
  ea_t ea = get_screen_ea();    // get current address
  if ( !is_code(get_flags(ea)) )
    return false; // not an instruction
  // get the callee address from the database
  ea_t callee = node2ea(n.altval_ea(ea)-1);
  // remove thumb bit for arm
  if ( ph.id == PLFM_ARM )
    callee &= ~1;
  char buf[MAXSTR];
  qsnprintf(buf, sizeof(buf), form, help);
  if ( ask_form(buf, &callee) )
  {
    if ( callee == BADADDR )
    {
      n.altdel_ea(ea);
    }
    else
    {
      if ( ph.id == PLFM_ARM && (callee & 1) == 0 )
      {
        // if we're calling a thumb function, set bit 0
        sel_t tbit = get_sreg(callee, T);
        if ( tbit != 0 && tbit != BADSEL )
          callee |= 1;
      }
      // save the new address
      n.altset_ea(ea, ea2node(callee)+1);
    }
    gen_idb_event(idb_event::callee_addr_changed, ea, callee);
    plan_ea(ea);                 // reanalyze the current instruction
  }
  return true;
}

//--------------------------------------------------------------------------
static const char wanted_name[] = "Change the callee address";
static const char wanted_hotkey[] = "Alt-F11";

//--------------------------------------------------------------------------
//
//      PLUGIN DESCRIPTION BLOCK
//
//--------------------------------------------------------------------------
plugin_t PLUGIN =
{
  IDP_INTERFACE_VERSION,
  PLUGIN_MULTI,         // plugin flags
  init,                 // initialize

  nullptr,              // terminate. this pointer may be nullptr.
  nullptr,              // invoke plugin

  comment,              // long comment about the plugin
                        // it could appear in the status line
                        // or as a hint

  help,                 // multiline help about the plugin

  wanted_name,          // the preferred short name of the plugin
  wanted_hotkey         // the preferred hotkey to run the plugin
};

choose

Sample plugin module that demonstrates the use of the choose() function.

/*
 *  This is a sample plugin module
 *
 *  It demonstrates the use of the choose() function
 *
 */

#include <ida.hpp>
#include <idp.hpp>
#include <loader.hpp>
#include <bytes.hpp>
#include <kernwin.hpp>

struct plugin_ctx_t : public plugmod_t
{
  virtual bool idaapi run(size_t arg) override;
};

//--------------------------------------------------------------------------
static plugmod_t *idaapi init()
{
  return new plugin_ctx_t;
}

//-------------------------------------------------------------------------
// non-modal call instruction chooser
struct calls_chooser_t : public chooser_t
{
protected:
  static const int widths_[];
  static const char *const header_[];

public:
  // remember the call instruction addresses in this qvector
  eavec_t list;

  // this object must be allocated using `new`
  calls_chooser_t(const char *title, bool ok, func_item_iterator_t *fii);

  // function that is used to decide whether a new chooser should be opened
  // or we can use the existing one.
  // The contents of the window are completely determined by its title
  virtual const void *get_obj_id(size_t *len) const override
  {
    *len = strlen(title);
    return title;
  }

  // function that returns number of lines in the list
  virtual size_t idaapi get_count() const override { return list.size(); }

  // function that generates the list line
  virtual void idaapi get_row(
        qstrvec_t *cols,
        int *icon_,
        chooser_item_attrs_t *attrs,
        size_t n) const override;

  // function that is called when the user hits Enter
  virtual cbret_t idaapi enter(size_t n) override
  {
    if ( n < list.size() )
      jumpto(list[n]);
    return cbret_t(); // nothing changed
  }

protected:
  void build_list(bool ok, func_item_iterator_t *fii)
  {
    insn_t insn;
    while ( ok )
    {
      ea_t ea = fii->current();
      if ( decode_insn(&insn, ea) > 0 && is_call_insn(insn) ) // a call instruction is found
        list.push_back(ea);
      ok = fii->next_code();
    }
  }
};

// column widths
const int calls_chooser_t::widths_[] =
{
  CHCOL_HEX | 8,  // Address
  32,             // Instruction
};
// column headers
const char *const calls_chooser_t::header_[] =
{
  "Address",      // 0
  "Instruction",  // 1
};

inline calls_chooser_t::calls_chooser_t(
        const char *title_,
        bool ok,
        func_item_iterator_t *fii)
  : chooser_t(0, qnumber(widths_), widths_, header_, title_),
    list()
{
  CASSERT(qnumber(widths_) == qnumber(header_));

  // build the list of calls
  build_list(ok, fii);
}

void idaapi calls_chooser_t::get_row(
        qstrvec_t *cols_,
        int *,
        chooser_item_attrs_t *,
        size_t n) const
{
  // assert: n < list.size()
  ea_t ea = list[n];

  // generate the line
  qstrvec_t &cols = *cols_;
  cols[0].sprnt("%08a", ea);
  generate_disasm_line(&cols[1], ea, GENDSM_REMOVE_TAGS);
  CASSERT(qnumber(header_) == 2);
}


//--------------------------------------------------------------------------
// The plugin method
// This is the main function of the plugin.
bool idaapi plugin_ctx_t::run(size_t)
{
  qstring title;
  // Let's display the functions called from the current one
  // or from the selected area

  // First we determine the working area
  func_item_iterator_t fii;
  bool ok;
  ea_t ea1, ea2;
  if ( read_range_selection(nullptr, &ea1, &ea2) ) // the selection is present?
  {
    callui(ui_unmarksel);                       // unmark selection
    title.sprnt("Functions called from %08a..%08a", ea1, ea2);
    ok = fii.set_range(ea1, ea2);
  }
  else                                          // nothing is selected
  {
    func_t *pfn = get_func(get_screen_ea());    // try the current function
    if ( pfn == nullptr )
    {
      warning("Please position the cursor on a function or select an area");
      return true;
    }
    ok = fii.set(pfn);
    get_func_name(&title, pfn->start_ea);
    title.insert("Functions called from ");
  }

  // now open the window
  calls_chooser_t *ch = new calls_chooser_t(title.c_str(), ok, &fii);
  ch->choose(); // the default cursor position is 0 (first row)
  return true; //-V773
}

//--------------------------------------------------------------------------
//
//      PLUGIN DESCRIPTION BLOCK
//
//--------------------------------------------------------------------------
plugin_t PLUGIN =
{
  IDP_INTERFACE_VERSION,
  // plugin flags
  PLUGIN_MULTI,
  // initialize
  init,
  nullptr,
  nullptr,
  // long comment about the plugin
  // it could appear in the status line
  // or as a hint
  "This is a sample plugin. It displays the chooser window",
  // multiline help about the plugin
  "A sample plugin module\n"
  "\n"
  "This module shows you how to use choose() function.\n",

  // the preferred short name of the plugin
  "Called functions",
  // the preferred hotkey to run the plugin
  ""
};

custdata

This sample plugin demonstates how to install a custom data type and a custom data format.

custview

This sample plugin demonstates how to create and manipulate a simple custom viewer, that allows you to create a view which displays colored lines.

cvt64_sample

Plugin with CVT64 examples.

dwarf

The source code of the dwarf plugin

ex_debidc

This sample Debugger IDC Helper executes IDC script when the process is launched and allows to hook IDC scripts to various debugger events.

// Debugger IDC Helper
// Executes IDC script when the process is launched
// In fact, this approach can be used to hook IDC scripts to various debugger
// events.

#include <ida.hpp>
#include <idp.hpp>
#include <dbg.hpp>
#include <expr.hpp>
#include <loader.hpp>

int data_id;

//--------------------------------------------------------------------------
// The plugin stores the IDC file name in the database
// It will create a node for this purpose
static const char node_name[] = "$ debugger idc file";


//--------------------------------------------------------------------------
struct plugin_ctx_t;

DECLARE_LISTENER(dbg_listener_t, plugin_ctx_t, ctx);
DECLARE_LISTENER(idp_listener_t, plugin_ctx_t, ctx);

struct plugin_ctx_t : public plugmod_t
{
  dbg_listener_t dbg_listener = dbg_listener_t(*this);
  idp_listener_t idp_listener = idp_listener_t(*this);
  plugin_ctx_t()
  {
    hook_event_listener(HT_DBG, &dbg_listener);
#ifdef ENABLE_MERGE
    hook_event_listener(HT_IDP, &idp_listener);
#endif
    set_module_data(&data_id, this);
  }
  ~plugin_ctx_t()
  {
    clr_module_data(data_id);
    // listeners are uninstalled automatically
    // when the owner module is unloaded
  }

  virtual bool idaapi run(size_t) override;
};

//--------------------------------------------------------------------------
// Get the IDC file name from the database
static bool get_idc_name(char *buf, size_t bufsize)
{
  // access the node
  netnode mynode(node_name);
  // retrieve the value
  return mynode.valstr(buf, bufsize) > 0;
}

//--------------------------------------------------------------------------
// Store the IDC file name in the database
static void set_idc_name(const char *idc)
{
  // access the node
  netnode mynode;
  // if it doesn't exist yet, create it
  // otherwise get its id
  mynode.create(node_name);
  // store the value
  mynode.set(idc, strlen(idc)+1);
}

//--------------------------------------------------------------------------
ssize_t idaapi idp_listener_t::on_event(ssize_t code, va_list va)
{
  return 0;
}

//--------------------------------------------------------------------------
ssize_t idaapi dbg_listener_t::on_event(ssize_t code, va_list /*va*/)
{
  switch ( code )
  {
    case dbg_process_start:
    case dbg_process_attach:
      // it is time to run the script
      char idc[QMAXPATH];
      if ( get_idc_name(idc, sizeof(idc)) )
      {
        qstring errbuf;
        if ( !exec_idc_script(nullptr, idc, "main", nullptr, 0, &errbuf) )
          warning("%s", errbuf.c_str());
      }
      break;
  }
  return 0;
}

//--------------------------------------------------------------------------
bool idaapi plugin_ctx_t::run(size_t)
{
  // retrieve the old IDC name from the database
  char idc[QMAXPATH];
  if ( !get_idc_name(idc, sizeof(idc)) )
    qstrncpy(idc, "*.idc", sizeof(idc));

  char *newidc = ask_file(false, idc, "Specify the script to run upon debugger launch");
  if ( newidc != nullptr )
  {
    // store it back in the database
    set_idc_name(newidc);
    msg("Script %s will be run when the debugger is launched\n", newidc);
  }
  return true;
}

//--------------------------------------------------------------------------
static plugmod_t *idaapi init()
{
  // Our plugin works only for x86 PE executables
  processor_t &ph = PH;
  if ( ph.id != PLFM_386 || inf_get_filetype() != f_PE )
    return nullptr;
  return new plugin_ctx_t;
}

//--------------------------------------------------------------------------
static const char wanted_name[] = "Specify Debugger IDC Script";
static const char wanted_hotkey[] = "";

//--------------------------------------------------------------------------
//
//      PLUGIN DESCRIPTION BLOCK
//
//--------------------------------------------------------------------------
plugin_t PLUGIN =
{
  IDP_INTERFACE_VERSION,
  PLUGIN_MULTI,         // The plugin can work with multiple idbs in parallel
  init,                 // initialize
  nullptr,
  nullptr,
  wanted_name,          // long comment about the plugin
  wanted_name,          // multiline help about the plugin
  wanted_name,          // the preferred short name of the plugin
  wanted_hotkey         // the preferred hotkey to run the plugin
};