A potentially confusing point about netnodes is that declaring a netnode variable within one of your modules does not necessarily create an internal representation of that netnode within the database. A netnode is not created internally until one of the following events takes place:

There are three constructors available for declaring netnodes within your modules. The prototypes for each, extracted from netnode.hpp, and examples of their use are shown in Example 16-1.

#ifdef __EA64__
  typedef ulonglong nodeidx_t;
  #else
  typedef ulong nodeidx_t;
  #endif
  class netnode {
    netnode();
    netnode(nodeidx_t num);
    netnode(const char *name, size_t namlen=0, bool do_create=false);
    bool create(const char *name, size_t namlen=0);
    bool create();
     //... remainder of netnode class follows
  };
  netnode n0;                       //uses
  netnode n1(0x00401110);           //uses
  netnode n2("$ node 2");           //uses
  netnode n3("$ node 3", 0, true);  //uses

In this example, only one netnode (n3) is guaranteed to exist within the database after the code has executed. Netnodes n1 and n2 may exist if they had been previously created and populated with data. Whether it previously existed or not, n1 is capable of receiving new data at this point. If n2 did not exist, meaning that no netnode named $ node 2 could be found in the database, then n2 must be explicitly created ( or ) before data can be stored into it. If we want to guarantee that we can store data into n2, we need to add the following safety check:

if (BADNODE == (nodeidx_t)n2) {
   n2.create("$ node 2");
}

The preceding example demonstrates the use of the nodeidx_t operator, which allows a netnode to be cast to a nodeidx_t. The nodeidx_t operator simply returns the netnodenumber data member of the associated netnode and allows netnode variables to be easily converted into integers.

An important point to understand about netnodes is that a netnode must have a valid netnodenumber before you can store data into the netnode. A netnodenumber may be explicitly assigned, as with n1 via a constructor shown at in the previous example. Alternatively, a netnodenumber may be internally generated when a netnode is created using the create flag in a constructor (as with n3 via a constructor shown in ) or via the create function (as with n2). Internally assigned netnodenumbers begin with 0xFF000000 and increment with each newly created netnode.

We have thus far neglected netnode n0 in our example. As things currently stand, n0 has neither a number nor a name. We could create n0 by name using the create function in a manner similar to n2. Or we could use the alternate form of create to create an unnamed netnode with a valid, internally generated netnodenumber, as shown here:

n0.create();  //assign an internally generated netnodenumber to n0

At this point it is possible to store data into n0, though we have no way to retrieve that data in the future unless we record the assigned netnodenumber somewhere or assign n0 a name. This demonstrates the fact that netnodes are easy to access when they are associated with a virtual address (similar to n1 in our example). For all other netnodes, assigning a name makes it possible to perform a named lookup for all future references to the netnode (as with n2 and n3 in our example).

Note that for our named netnodes, we have chosen to use names prefixed with “$ ”, which is in keeping with the practice, recommended in netnode.hpp, for avoiding conflicts with names IDA uses internally.

Now that you understand how to create a netnode that you can store data into, let’s return to the discussion of the internal array storage capability of net-nodes. To store a value into an array within a netnode, we need to specify five pieces of information: an index value, an index size (8 or 32 bits), a value to store, the number of bytes the value contains, and an array (one of 256 available for each category of array) in which to store the value. The index size parameter is specified implicitly by the function that we use to store or retrieve the data. The remaining values are passed into that function as parameters. The parameter that selects which of the 256 possible arrays a value is stored in is usually called a tag, and it is often specified (though it need not be) using a character. The netnode documentation distinguishes among a few special types of values termed altvals, supvals, and hashvals. By default, each of these values is typically associated with a specific array tag: 'A' for altvals, 'S' for supvals, and 'H' for hashvals. A fourth type of value, called a charval, is not associated with any specific array tag.

It is important to understand that these value types are associated more with a specific way of storing data into a netnode than with a specific array within a netnode. It is possible to store any type of value in any array simply by specifying an alternate array tag when storing data. In all cases, it is up to you to remember what type of data you stored into a particular array location so that you can use retrieval methods appropriate to the type of the stored data.

Altvals provide a simple interface for storing and retrieving integer data in netnodes. Altvals may be stored into any array within a netnode but default to the 'A' array. Regardless of which array you wish to store integers into, using the altval-related functions greatly simplifies matters. The code in Example 16-2 demonstrates data storage and retrieval using altvals.

netnode n("$ idabook", 0, true);  //create the netnode if it doesn't exist
sval_t index = 1000;  //sval_t is a 32 bit type, this example uses 32-bit indexes
ulong value = 0x12345678;
n.altset(index, value);   //store value into the 'A' array at index
value = n.altval(index);  //retrieve value from the 'A' array at index
n.altset(index, value, (char)3);  //store into array 3
value = n.altval(index, (char)3); //read from array 3

In this example, you see a pattern that will be repeated for other types of netnode values, namely, the use of an XXXset function (in this case, altset) to store a value into a netnode and an XXXval function (in this case, altval) to retrieve a value from a netnode. If we want to store integers into arrays using 8-bit index values, we need to use slightly different functions, as shown in the next example.

netnode n("$ idabook", 0, true);
uchar index = 80;      //this example uses 8-bit index values
ulong value = 0x87654321;
n.altset_idx8(index, value, 'A'),  //store, no default tags with xxx_idx8 functions
value = n.altval_idx8(index, 'A'), //retrieve value from the 'A' array at index
n.altset_idx8(index, value, (char)3);  //store into array 3
value = n.altval_idx8(index, (char)3); //read from array 3

Here you see that the general rule of thumb for the use of 8-bit index values is to use a function with an _idx8 suffix. Also note that none of the _idx8 functions provide default values for the array tag parameter.

Supvals represent the most versatile means of storing and retrieving data in netnodes. Supvals represent data of arbitrary size, from 1 byte to a maximum of 1,024 bytes. When using 32-bit index values, the default array for storing and retrieving supvals is the 'S' array. Again, however, supvals can be stored into any of the 256 available arrays by specifying an appropriate array tag value. Strings are a common form of arbitrary length data and as such are afforded special handling in supval manipulation functions. The code in Example 16-3 provides examples of storing supvals into a netnode.

netnode n("$ idabook", 0, true);  //create the netnode if it doesn't exist

char *string_data = "example supval string data";
char binary_data[] = {0xfe, 0xdc, 0x4e, 0xc7, 0x90, 0x00, 0x13, 0x8a,
                      0x33, 0x19, 0x21, 0xe5, 0xaa, 0x3d, 0xa1, 0x95};

//store binary_data into the 'S' array at index 1000, we must supply a
//pointer to data and the size of the data
n.supset(1000, binary_data, sizeof(binary_data));

//store string_data into the 'S' array at index 1001.  If no size is supplied,
//or size is zero, the data size is computed as: strlen(data) + 1
n.supset(1001, string_data);
//store into an array other than 'S' (200 in this case) at index 500
n.supset(500, binary_data, sizeof(binary_data), (char)200);

The supset function requires an array index, a pointer to some data, the length of the data (in bytes), and an array tag that defaults to 'S' if omitted. If the length parameter is omitted, it defaults to zero. When the length is specified as zero, supset assumes that the data being stored is a string, computes the length of the data as strlen(data) + 1, and stores a null termination character along with the string data.

Retrieving data from a supval takes a little care, as you may not know the amount of data contained within the supval before you attempt to retrieve it. When you retrieve data from a supval, bytes are copied out of the netnode into a user-supplied output buffer. How do you ensure that your output buffer is of sufficient size to receive the supval data? The first method is to retrieve all supval data into a buffer that is at least 1,024 bytes. The second method is to preset the size of your output buffers by querying the size of the supval. Two functions are available for retrieving supvals. The supval function is used to retrieve arbitrary data, while the supstr function is specialized for retrieving string data. Each of these functions expects a pointer to your output buffer along with the size of the buffer. The return value for supval is the number of bytes copied into the output buffer, while the return value for supstr is the length of the string copied to the output buffer not including the null terminator, even though the null terminator is copied to the buffer. Each of these functions recognizes the special case in which a NULL pointer is supplied in place of an output buffer pointer. In such cases, supval and supstr return the number of bytes of storage (including any null terminator) required to hold the supval data. Example 16-4 demonstrates retrieval of supval data using the supval and supstr functions.

//determine size of element 1000 in 'S' array.  The NULL pointer indicates
//that we are not supplying an output buffer
int len = n.supval(1000, NULL, 0);

char *outbuf = new char[len];  //allocate a buffer of sufficient size
n.supval(1000, outbuf, len);   //extract data from the supval

//determine size of element 1001 in 'S' array.  The NULL pointer indicates
//that we are not supplying an output buffer.
len = n.supstr(1001, NULL, 0);

char *outstr = new char[len];  //allocate a buffer of sufficient size
n.supval(1001, outstr, len);   //extract data from the supval

//retrieve a supval from array 200, index 500
char buf[1024];
len = n.supval(500, buf, sizeof(buf), (char)200);

Using supvals, it is possible to access any data stored in any array within a netnode. For example, supval functions can be used to store and retrieve altval data by limiting the supset and supval operations to the size of an altval. Reading through netnode.hpp, you will see that this is in fact the case by observing the inlined implementation of the altset function, as shown here:

bool altset(sval_t alt, nodeidx_t value, char tag=atag) {
   return supset(alt, &value, sizeof(value), tag);
}

Hashvals offer yet another interface to netnodes. Rather than being associated with integer indexes, hashvals are associated with key strings. Overloaded versions of the hashset function make it easy to associate integer data or array data with a hash key, while the hashval, hashstr, and hashval_long functions allow retrieval of hashvals when provided with the appropriate hash key. Tag values associated with the hashXXX functions actually choose one of 256 hash tables, with the default table being 'H'. Alternate tables are selected by specifying a tag other than 'H'.

The last interface to netnodes that we will mention is the charval interface. The charval and charset functions offer a simple means to store single-byte data into a netnode array. There is no default array associated with charval storage and retrieval, so you must specify an array tag for every charval operation. Charvals are stored into the same arrays as altvals and supvals, and the charval functions are simply wrappers around 1-byte supvals.

Another capability provided by the netnode class is the ability to iterate over the contents of a netnode array (or hash table). Iteration is performed using XXX1st, XXXnxt, XXXlast, and XXXprev functions that are available for altvals, supvals, hashvals, and charvals. The example in Example 16-5 illustrates iteration across the default altvals array ('A').

Iteration over supvals, charvals, and hashvals is performed in a very similar manner; however, you will find that the syntax varies depending on the type of values being accessed. For example, iteration over hashvals returns hashkeys rather than array indexes, which must then be used to retrieve hashvals.

netnode n("$ idabook", 0, true);
//Iterate altvals first to last
for (nodeidx_t idx = n.alt1st(); idx != BADNODE; idx = n.altnxt(idx)) {
   ulong val = n.altval(idx);
   msg("Found altval['A'][%d] = %d
", idx, val);
}

//Iterate altvals last to first
for (nodeidx_t idx = n.altlast(); idx != BADNODE; idx = n.altprev(idx)) {
   ulong val = n.altval(idx);
   msg("Found altval['A'][%d] = %d
", idx, val);
}

The netnode class also provides functions for deleting individual array elements, the entire contents of an array, or the entire contents of a netnode. Removing an entire netnode is fairly straightforward.

netnode n("$ idabook", 0, true);
n.kill();                        //entire contents of n are deleted

When deleting individual array elements, or entire array contents, you must take care to choose the proper deletion function because the names of the functions are very similar and choosing the wrong form may result in significant loss of data. Commented examples demonstrating deletion of altvals follow:

netnode n("$ idabook", 0, true);
 n.altdel(100);       //delete item 100 from the default altval array ('A')
  n.altdel(100, (char)3); //delete item 100 from altval array 3
 n.altdel();          //delete the entire contents of the default altval array
  n.altdel_all('A'),      //alternative to delete default altval array contents
  n.altdel_all((char)3);  //delete the entire contents of altval array 3;

Note the similarity in the syntax to delete the entire contents of the default altval array and the syntax to delete a single element from the default altval array . If for some reason you fail to specify an index when you want to delete a single element, you may end up deleting an entire array. Similar functions exist to delete supval, charval, and hashval data.

The following functions, declared in bytes.hpp, provide access to individual bytes, words, and dwords within a database.

Additional functions exist for accessing alternative data sizes. Note that the get_original_XXX functions get the very first original value, which is not necessarily the value at an address prior to a patch. Consider the case when a byte value is patched twice; over time this byte has held three different values. After the second patch, both the current value and the original value are accessible, but there is no way to obtain the second value (which was set with the first patch).

Interaction with the IDA user interface is handled by a single dispatcher function named callui. Requests for various user interface services are made by passing a user interface request (one of the enumerated ui_notification_t constants) to callui along with any additional parameters required by the request. Parameters required for each request type are specified in kernwin.hpp. Fortunately, a number of convenience functions that hide many of the details of using callui directly are also defined in kernwin.hpp. Several common convenience functions are described here:

Many more user interface capabilities are available using the API than are available with IDC scripting, including the ability to create customized single- and multicolumn list selection dialogs. Users interested in these capabilities should consult kernwin.hpp and the choose and choose2 functions in particular.

The following functions are available for working with named locations within a database:

The API functions for accessing information about disassembled functions are declared in funcs.hpp. Functions for accessing stack frame information are declared in frame.hpp. Some of the more commonly used functions are described here:

The struc_t class is used to access function stack frames as well as structured datatypes defined within type libraries. Some of the basic functions for interacting with structures and their associated members are described here. Many of these functions make use of a type ID (tid_t) datatype. The API includes functions for mapping a struc_t to an associated tid_t and vice versa. Note that both the struc_t and member_t classes contain a tid_t data member, so obtaining type ID information is simple if you already have a pointer to a valid struc_t or member_t object.

The segment_t class stores information related to the different segments within a database (such as .text and .data) as listed in the View ▸ Open Subviews ▸ Segments window. Recall that what IDA terms segments are often referred to as sections by various executable file formats such as PE and ELF. The following functions provide basic access to segment_t objects. Additional functions dealing with the segment_t class are declared in segment.hpp.

One of the add_segm functions must be used to actually create a segment. Simply declaring and initializing a segment_t object does not actually create a segment within the database. This is true with all of the wrapper classes such as func_t and struc_t. These classes merely provide a convenient means to access attributes of an underlying database entity. The appropriate functions to create, modify, or delete actual database objects must be utilized in order to make persistent changes to the database.

A number of functions and enumerated constants are defined in xref.hpp for use with code cross-references. Some of these are described here:

The functions for accessing data cross-reference information (also declared in xref.hpp) are very similar to the functions used to access code cross-reference information. These functions are described here:

The SDK contains no equivalent to IDC’s XrefType function. A variable named lastXR is declared in xref.hpp; however, it is not exported. If you need to determine the exact type of a cross-reference, you must iterate cross-references using an xrefblk_t structure. The xrefblk_t is described in “Enumerating Cross-References

The first technique for iterating through the functions within a database mimics the manner in which we performed the same task using IDC:

for (func_t *f = get_next_func(0); f != NULL; f = get_next_func(f->startEA)) {
   char fname[1024];
   get_func_name(f->startEA, fname, sizeof(fname));
   msg("%08x: %s
", f->startEA, fname);
}

Alternatively, we can simply iterate through functions by index numbers, as shown in the next example:

for (int idx = 0; idx < get_func_qty(); idx++) {
   char fname[1024];
   func_t *f = getn_func(idx);
   get_func_name(f->startEA, fname, sizeof(fname));
   msg("%08x: %s
", f->startEA, fname);
}

Finally, we can work at a somewhat lower level and make use of a data structure called an areacb_t, also known as an area control block, defined in area.hpp. Area control blocks are used to maintain lists of related area_t objects. A global areacb_t named funcs is exported (in funcs.hpp) as part of the IDA API. Using the areacb_t class, the previous example can be rewritten as follows:

 int a = funcs.get_next_area(0);
  while (a != −1) {
     char fname[1024];
    func_t *f = (func_t*)funcs.getn_area(a);  // getn_area returns an area_t
     get_func_name(f->startEA, fname, sizeof(fname));
     msg("%08x: %s
", f->startEA, fname);
    a = funcs.get_next_area(f->startEA);
  }

In this example, the get_next_area member function and is used repeatedly to obtain the index values for each area in the funcs control block. A pointer to each related func_t area is obtained by supplying each index value to the getn_area member function . Several global areacb_t variables are declared within the SDK, including the segs global, which is an area control block containing segment_t pointers for each section in the binary.

Within the SDK, stack frames are modeled using the capabilities of the struc_t class. The example in Example 16-6 utilizes structure member iteration as a means of printing the contents of a stack frame.

func_t *func = get_func(get_screen_ea());  //get function at cursor location
msg("Local variable size is %d
", func->frsize);
msg("Saved regs size is %d
", func->frregs);
struc_t *frame = get_frame(func);          //get pointer to stack frame
if (frame) {
   size_t ret_addr = func->frsize + func->frregs;  //offset to return address
   for (size_t m = 0; m < frame->memqty; m++) {    //loop through members
      char fname[1024];
      get_member_name(frame->members[m].id, fname, sizeof(fname));
      if (frame->members[m].soff < func->frsize) {
         msg("Local variable ");
      }
      else if (frame->members[m].soff > ret_addr) {
         msg("Parameter ");
      }
      msg("%s is at frame offset %x
", fname, frame->members[m].soff);
      if (frame->members[m].soff == ret_addr) {
         msg("%s is the saved return address
", fname);
      }
   }
}

This example summarizes a function’s stack frame using information from the function’s func_t object and the associated struc_t representing the function’s stack frame. The frsize and and frregs fields specify the size of the local variable portion of the stack frame and the number of bytes dedicated to saved registers, respectively. The saved return address can be found within the frame following the local variables and the saved registers. Within the frame itself, the memqty field specifies the number of defined members contained in the frame structure, which also corresponds to the size of the members array. A loop is used to retrieve the name of each member and determine whether the member is a local variable or an argument based on its starting offset (soff) within the frame structure.

In Chapter 15 we saw that it is possible to enumerate cross-references from IDC scripts. The same capabilities exist within the SDK, though in a some-what different form. As an example, let’s revisit the idea of listing all calls of a particular function (see Example 15-4 in Enumerating Exported Functions). The following function almost works.

void list_callers(char *bad_func) {
   char name_buf[MAXNAMELEN];
   ea_t func = get_name_ea(BADADDR, bad_func);
   if (func == BADADDR) {
      warning("Sorry, %s not found in database", bad_func);
   }
   else {
      for (ea_t addr = get_first_cref_to(func); addr != BADADDR;
           addr = get_next_cref_to(func, addr)) {
         char *name = get_func_name(addr, name_buf, sizeof(name_buf));
         if (name) {
            msg("%s is called from 0x%x in %s
", bad_func, addr, name);
         }
         else {
            msg("%s is called from 0x%x
", bad_func, addr);
         }
      }
   }
}

The reason this function almost works is that there is no way to determine the type of cross-reference returned for each iteration of the loop (recall that there is no SDK equivalent for IDC’s XrefType). In this case we should verify that each cross-reference to the given function is in fact a call type (fl_CN or fl_CF) cross-reference.

When you need to determine the type of a cross-reference within the SDK, you must use an alternative form of cross-reference iteration facilitated by the xrefblk_t structure, which is described in xref.hpp. The basic layout of an xrefblk_t is shown in the following listing. (For full details, please see xref.hpp.)

struct xrefblk_t {
    ea_t from;     // the referencing address - filled by first_to(),next_to()
    ea_t to;       // the referenced address - filled by first_from(), next_from()
    uchar iscode;  // 1-is code reference; 0-is data reference
    uchar type;    // type of the last returned reference
    uchar user;    // 1-is user defined xref, 0-defined by ida

    //fill the "to" field with the first address to which "from" refers.
   bool first_from(ea_t from, int flags);

    //fill the "to" field with the next address to which "from" refers.
    //This function assumes a previous call to first_from.
   bool next_from(void);

    //fill the "from" field with the first address that refers to "to".
   bool first_to(ea_t to,int flags);

    //fill the "from" field with the next address that refers to "to".
    //This function assumes a previous call to first_to.
   bool next_to(void);
  };

The member functions of xrefblk_t are used to initialize the structure and and perform the iteration and , while the data members are used to access information about the last cross-reference that was retrieved. The flags value required by the first_from and first_to functions dictates which type of cross-references should be returned. Legal values for the flags parameter include the following (from xref.hpp):

#define XREF_ALL        0x00            // return all references
#define XREF_FAR        0x01            // don't return ordinary flow xrefs
#define XREF_DATA       0x02            // return data references only

Note that no flag value restricts the returned references to code only. If you are interested in code cross-references, you must either compare the xrefblk_t type field to specific cross-reference types (such as fl_JN) or test the iscode field to determine if the last returned cross-reference was a code cross-reference.

The following modified version of the list_callers function demonstrates the use of an xrefblk_t iteration structure.

void list_callers(char *bad_func) {
     char name_buf[MAXNAMELEN];
     ea_t func = get_name_ea(BADADDR, bad_func);
     if (func == BADADDR) {
        warning("Sorry, %s not found in database", bad_func);
     }
     else {
        xrefblk_t xr;
        for (bool ok = xr.first_to(func, XREF_ALL); ok; ok = xr.next_to()) {
          if (xr.type != fl_CN && xr.type != fl_CF) continue;
           char *name = get_func_name(xr.from, name_buf, sizeof(name_buf));
           if (name) {
              msg("%s is called from 0x%x in %s
", bad_func, xr.from, name);
           }
           else {
              msg("%s is called from 0x%x
", bad_func, xr.from);
           }
        }
     }
  }

Through the use of an xrefblk_t, we now have the opportunity to examine the type of each cross-reference returned by the iterator and decide whether it is interesting to us or not. In this example we simply ignore any cross-reference that is not related to a function call. We did not use the iscode member of xrefblk_t because iscode is true for jump and ordinary flow cross-references in addition to call cross-references. Thus, iscode alone does not guarantee that the current cross-reference is related to a function call.