IDA SDK

- Main Page
- Header Files
- Classes
- Modules

- File List
- File Members

Classes | Functions | Macros | Typedefs | Variables
lines.hpp File Reference

## Detailed Description

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

This file also contains definitions for the syntax highlighting.

Finally there are functions that deal with anterior/posterior user-defined lines.

## Classes
struct | bgcolors_t
| Structure to keep some background colors configurable in ida.cfg. More...

## Functions
bool | requires_color_esc (char c)
| Is the given char a color escape character?
idaman char *ida_export | tag_on (char *ptr, char *end, color_t tag)
| Append 'turn on color' sequence to a string. More...
idaman char *ida_export | tag_off (char *ptr, char *end, color_t tag)
| Append 'turn off color' sequence to a string. More...
idaman char *ida_export | tag_addchr (char *ptr, char *end, color_t tag, char chr)
| Append a colored character to a string. More...
idaman char *ida_export | tag_addstr (char *ptr, char *end, color_t tag, const char *string)
| Append a colored substring to a string. More...
idaman char *ida_export | tag_addr (char *ptr, char *end, ea_t ea)
| Append an address mark to a string. More...
idaman const char *ida_export | tag_advance (const char *line, int cnt)
| Move pointer to a 'line' to 'cnt' positions right. More...
idaman const char *ida_export | tag_skipcodes (const char *line)
| Move the pointer past all color codes. More...
idaman const char *ida_export | tag_skipcode (const char *line)
| Skip one color code. More...
idaman ssize_t ida_export | tag_strlen (const char *line)
| Calculate length of a colored string. More...
idaman ssize_t ida_export | tag_remove (const char *instr, char *buf, size_t bufsize)
| Remove color escape sequences from a string. More...
idaman color_t ida_export | calc_prefix_color (ea_t ea)
| Get prefix color for line at 'ea'. More...
idaman bgcolor_t ida_export | calc_bg_color (ea_t ea)
| Get background color for line at 'ea'. More...
Source files
IDA can keep information about source files used to create the program. Each source file is represented by a range of addresses. A source file may contain several address ranges.
idaman bool ida_export | add_sourcefile (ea_t ea1, ea_t ea2, const char *filename)
| Mark a range of address as belonging to a source file. More...
idaman const char *ida_export | get_sourcefile (ea_t ea, area_t *bounds=NULL)
| Get name of source file occupying the given address. More...
idaman bool ida_export | del_sourcefile (ea_t ea)
| Delete information about the source file. More...
Generation of disassembled text
idaman void ida_export | set_user_defined_prefix (size_t width, void(idaapi *get_user_defined_prefix)(ea_t ea, int lnnum, int indent, const char *line, char *buf, size_t bufsize))
| User-defined line-prefixes are displayed just after the autogenerated line prefixes. More...
idaman bool ida_export | MakeLine (const char *contents, int indent=-1)
| Generate ONE line of disassembled text. More...
idaman bool ida_export | printf_line_v (int indent, const char *format, va_list va)
| See printf_line()
bool | printf_line (int indent, const char *format,...)
| Generate ONE line of disassembled text. More...
idaman bool ida_export | MakeNull (void)
| Generate empty line. More...
idaman bool ida_export | MakeBorder (void)
| Generate thin border line. More...
idaman bool ida_export | MakeSolidBorder (void)
| Generate solid border line. More...
idaman bool ida_export | gen_colored_cmt_line_v (color_t color, const char *format, va_list va)
| See gen_cmt_line()
bool | gen_cmt_line_v (const char *format, va_list va)
| See gen_cmt_line()
bool | gen_cmt_line (const char *format,...)
| Generate one non-indented comment line, colored with COLOR_AUTOCMT. More...
bool | gen_collapsed_line (const char *format,...)
| Generate one non-indented comment line, colored with COLOR_COLLAPSED. More...
idaman bool ida_export | generate_big_comment (const char *cmt, color_t color)
| Generate big non-indented comment lines. More...
idaman bool ida_export | generate_many_lines (const char *string, color_t color)
| Generate many non-indented lines. More...
Anterior/Posterior lines
idaman void ida_export | describex (ea_t ea, const char *prefix, bool isprev, const char *format, va_list va)
| Add anterior/posterior line(s). More...
void | describe (ea_t ea, bool isprev, const char *format,...)
| Add anterior/posterior line(s). More...
idaman void ida_export | add_long_cmt_v (ea_t ea, bool isprev, const char *format, va_list va)
| See add_long_cmt()
void | add_long_cmt (ea_t ea, bool isprev, const char *format,...)
| Add anterior/posterior comment line(s). More...
void | add_pgm_cmt (const char *format,...)
| Add anterior/posterior comment line(s) at the start of program. More...

## Macros
#define | COLOR_ON '\1'
| Escape character (ON). More...
#define | COLOR_OFF '\2'
| Escape character (OFF). More...
#define | COLOR_ESC '\3'
| Escape character (Quote next character). More...
#define | COLOR_INV '\4'
| Escape character (Inverse foreground and background colors). More...
#define | SCOLOR_ON "\1"
| Escape character (ON)
#define | SCOLOR_OFF "\2"
| Escape character (OFF)
#define | SCOLOR_ESC "\3"
| Escape character (Quote next character)
#define | SCOLOR_INV "\4"
| Escape character (Inverse colors)
#define | COLOR_ADDR_SIZE (sizeof(ea_t)*2)
| Size of a tagged address (see COLOR_ADDR)
#define | SCOLOR_DEFAULT "\x01"
| Default.
#define | SCOLOR_REGCMT "\x02"
| Regular comment.
#define | SCOLOR_RPTCMT "\x03"
| Repeatable comment (defined not here)
#define | SCOLOR_AUTOCMT "\x04"
| Automatic comment.
#define | SCOLOR_INSN "\x05"
| Instruction.
#define | SCOLOR_DATNAME "\x06"
| Dummy Data Name.
#define | SCOLOR_DNAME "\x07"
| Regular Data Name.
#define | SCOLOR_DEMNAME "\x08"
| Demangled Name.
#define | SCOLOR_SYMBOL "\x09"
| Punctuation.
#define | SCOLOR_CHAR "\x0A"
| Char constant in instruction.
#define | SCOLOR_STRING "\x0B"
| String constant in instruction.
#define | SCOLOR_NUMBER "\x0C"
| Numeric constant in instruction.
#define | SCOLOR_VOIDOP "\x0D"
| Void operand.
#define | SCOLOR_CREF "\x0E"
| Code reference.
#define | SCOLOR_DREF "\x0F"
| Data reference.
#define | SCOLOR_CREFTAIL "\x10"
| Code reference to tail byte.
#define | SCOLOR_DREFTAIL "\x11"
| Data reference to tail byte.
#define | SCOLOR_ERROR "\x12"
| Error or problem.
#define | SCOLOR_PREFIX "\x13"
| Line prefix.
#define | SCOLOR_BINPREF "\x14"
| Binary line prefix bytes.
#define | SCOLOR_EXTRA "\x15"
| Extra line.
#define | SCOLOR_ALTOP "\x16"
| Alternative operand.
#define | SCOLOR_HIDNAME "\x17"
| Hidden name.
#define | SCOLOR_LIBNAME "\x18"
| Library function name.
#define | SCOLOR_LOCNAME "\x19"
| Local variable name.
#define | SCOLOR_CODNAME "\x1A"
| Dummy code name.
#define | SCOLOR_ASMDIR "\x1B"
| Assembler directive.
#define | SCOLOR_MACRO "\x1C"
| Macro.
#define | SCOLOR_DSTR "\x1D"
| String constant in data directive.
#define | SCOLOR_DCHAR "\x1E"
| Char constant in data directive.
#define | SCOLOR_DNUM "\x1F"
| Numeric constant in data directive.
#define | SCOLOR_KEYWORD "\x20"
| Keywords.
#define | SCOLOR_REG "\x21"
| Register name.
#define | SCOLOR_IMPNAME "\x22"
| Imported name.
#define | SCOLOR_SEGNAME "\x23"
| Segment name.
#define | SCOLOR_UNKNAME "\x24"
| Dummy unknown name.
#define | SCOLOR_CNAME "\x25"
| Regular code name.
#define | SCOLOR_UNAME "\x26"
| Regular unknown name.
#define | SCOLOR_COLLAPSED "\x27"
| Collapsed line.
#define | SCOLOR_ADDR "\x28"
| Hidden address mark.
#define | SCOLOR_UTF8 "\x32"
| UTF-8 text on/off.
#define | COLSTR(str, tag) SCOLOR_ON tag str SCOLOR_OFF tag
| This macro is used to build colored string constants (e.g. More...
#define | COLOR_DEFAULT 0x01
| Default.
#define | COLOR_SELECTED 0x02
| Selected.
#define | COLOR_LIBFUNC 0x03
| Library function.
#define | COLOR_REGFUNC 0x04
| Regular function.
#define | COLOR_CODE 0x05
| Single instruction.
#define | COLOR_DATA 0x06
| Data bytes.
#define | COLOR_UNKNOWN 0x07
| Unexplored byte.
#define | COLOR_EXTERN 0x08
| External name definition segment.
#define | COLOR_CURITEM 0x09
| Current item.
#define | COLOR_CURLINE 0x0A
| Current line.
#define | COLOR_HIDLINE 0x0B
| Hidden line.
#define | COLOR_BG_MAX 0x0C
| Max color number.
#define | PALETTE_SIZE (COLOR_FG_MAX+COLOR_BG_MAX)

## Typedefs
typedef uchar | color_t
| color tag - see Color tags

## Variables
const color_t | COLOR_DEFAULT = 0x01
| Default.
const color_t | COLOR_REGCMT = 0x02
| Regular comment.
const color_t | COLOR_RPTCMT = 0x03
| Repeatable comment (comment defined somewhere else)
const color_t | COLOR_AUTOCMT = 0x04
| Automatic comment.
const color_t | COLOR_INSN = 0x05
| Instruction.
const color_t | COLOR_DATNAME = 0x06
| Dummy Data Name.
const color_t | COLOR_DNAME = 0x07
| Regular Data Name.
const color_t | COLOR_DEMNAME = 0x08
| Demangled Name.
const color_t | COLOR_SYMBOL = 0x09
| Punctuation.
const color_t | COLOR_CHAR = 0x0A
| Char constant in instruction.
const color_t | COLOR_STRING = 0x0B
| String constant in instruction.
const color_t | COLOR_NUMBER = 0x0C
| Numeric constant in instruction.
const color_t | COLOR_VOIDOP = 0x0D
| Void operand.
const color_t | COLOR_CREF = 0x0E
| Code reference.
const color_t | COLOR_DREF = 0x0F
| Data reference.
const color_t | COLOR_CREFTAIL = 0x10
| Code reference to tail byte.
const color_t | COLOR_DREFTAIL = 0x11
| Data reference to tail byte.
const color_t | COLOR_ERROR = 0x12
| Error or problem.
const color_t | COLOR_PREFIX = 0x13
| Line prefix.
const color_t | COLOR_BINPREF = 0x14
| Binary line prefix bytes.
const color_t | COLOR_EXTRA = 0x15
| Extra line.
const color_t | COLOR_ALTOP = 0x16
| Alternative operand.
const color_t | COLOR_HIDNAME = 0x17
| Hidden name.
const color_t | COLOR_LIBNAME = 0x18
| Library function name.
const color_t | COLOR_LOCNAME = 0x19
| Local variable name.
const color_t | COLOR_CODNAME = 0x1A
| Dummy code name.
const color_t | COLOR_ASMDIR = 0x1B
| Assembler directive.
const color_t | COLOR_MACRO = 0x1C
| Macro.
const color_t | COLOR_DSTR = 0x1D
| String constant in data directive.
const color_t | COLOR_DCHAR = 0x1E
| Char constant in data directive.
const color_t | COLOR_DNUM = 0x1F
| Numeric constant in data directive.
const color_t | COLOR_KEYWORD = 0x20
| Keywords.
const color_t | COLOR_REG = 0x21
| Register name.
const color_t | COLOR_IMPNAME = 0x22
| Imported name.
const color_t | COLOR_SEGNAME = 0x23
| Segment name.
const color_t | COLOR_UNKNAME = 0x24
| Dummy unknown name.
const color_t | COLOR_CNAME = 0x25
| Regular code name.
const color_t | COLOR_UNAME = 0x26
| Regular unknown name.
const color_t | COLOR_COLLAPSED = 0x27
| Collapsed line.
const color_t | COLOR_FG_MAX = 0x28
| Max color number.
const color_t | COLOR_ADDR = COLOR_FG_MAX
| hidden address marks. More...
const color_t | COLOR_OPND1 = COLOR_ADDR+1
| Instruction operand 1.
const color_t | COLOR_OPND2 = COLOR_ADDR+2
| Instruction operand 2.
const color_t | COLOR_OPND3 = COLOR_ADDR+3
| Instruction operand 3.
const color_t | COLOR_OPND4 = COLOR_ADDR+4
| Instruction operand 4.
const color_t | COLOR_OPND5 = COLOR_ADDR+5
| Instruction operand 5.
const color_t | COLOR_OPND6 = COLOR_ADDR+6
| Instruction operand 6.
const color_t | COLOR_UTF8 = COLOR_ADDR+10
| Following text is UTF-8 encoded (until next COLOR_OFF COLOR_UTF8)
const color_t | COLOR_RESERVED1 = COLOR_ADDR+11
| This tag is reserved for internal IDA use.
bgcolors_t | bgcolors
Additional information
The following variables control generation of additional information. Initially they are set to 0, you should set them to 1 when you want additional information generated upon calling MakeLine()
idaman char ida_export_data | gl_comm
| generate comment at the next call to MakeLine()
idaman char ida_export_data | gl_name
| generate name at the next call to MakeLine()
idaman char ida_export_data | gl_xref
| generate xrefs at the next call to MakeLine()
Prefix lengths
The following variables contain lengths of line prefix and binary line prefix accordingly. You can use them IDP modules to calculate necessary indentions and the resulting string length if you need to.
idaman int ida_export_data | gl_psize
| Line prefix width (set by setup_makeline)
idaman int ida_export_data | gl_bpsize
| Binary line prefix width (set by setup_makeline)

## Function Documentation

idaman color_t ida_export calc_prefix_color | ( | ea_t | ea | ) |

Get prefix color for line at 'ea'.

Returns
  Line prefix colors

idaman bgcolor_t ida_export calc_bg_color | ( | ea_t | ea | ) |

Get background color for line at 'ea'.

Returns
  RGB color

idaman bool ida_export add_sourcefile | ( | ea_t | ea1,
|  | ea_t | ea2,
|  | const char * | filename
| ) |  |

Mark a range of address as belonging to a source file.

An address range may belong only to one source file. A source file may be represented by several address ranges.

Parameters

  ea1 | linear address of start of the address range
  ea2 | linear address of end of the address range (excluded)
  filename | name of source file.

Returns
  success

idaman const char* ida_export get_sourcefile | ( | ea_t | ea,
|  | area_t * | bounds = `NULL`
| ) |  |

Get name of source file occupying the given address.

Parameters

  ea | linear address
  bounds | pointer to the output buffer with the address range for the current file. May be NULL.

Returns
  NULL if source file information is not found, otherwise returns pointer to file name

idaman bool ida_export del_sourcefile | ( | ea_t | ea | ) |

Delete information about the source file.

Parameters

  ea | linear address

Returns
  success

idaman void ida_export set_user_defined_prefix | ( | size_t | width,
|  | void(idaapi *)(ea_t ea, int lnnum, int indent, const char *line, char *buf, size_t bufsize) | get_user_defined_prefix
| ) |  |

User-defined line-prefixes are displayed just after the autogenerated line prefixes.

In order to use them, the plugin should call the following function to specify its width and contents.

Parameters

  width | the width of the user-defined prefix
  get_user_defined_prefix | a callback to get the contents of the prefix. Its arguments: ea: linear address indent: indent of the line contents. -1 means the default instruction indent and is used for instruction itself. see explanations for printf_line(). line: the line to be generated. the line usually contains color tags. this argument can be examined to decide whether to generated the prefix. buf: the output buffer bufsize: the size of the output buffer

In order to remove the callback before unloading the plugin, specify the width or the callback == NULL.

idaman bool ida_export MakeLine | ( | const char * | contents,
|  | int | indent = `-1`
| ) |  |

Generate ONE line of disassembled text.

You may call this function from out.cpp as many times as you need to generate all lines for an item (instruction or data).

Parameters

  contents | colored line to generate
  indent | see explanation for printf_line()

Return values

  1 | you've made too many calls to this function, you should stop calling it and return to the caller. The current limit is 500 lines per item.
  0 | ok

bool printf_line | ( | int | indent,
|  | const char * | format,
|  |  | ...
| ) |  |
| inline

Generate ONE line of disassembled text.

You may call this function from out.cpp as many times as you need to generate all lines for an item (instruction or data).

Parameters

  format | printf style colored line to generate
  indent | indention of the line. if indent == -1, the kernel will indent the line at idainfo::indent. if indent < 0, -indent will be used for indention. The first line printed with indent < 0 is considered as the most important line at the current address. Usually it is the line with the instruction itself. This line will be displayed in the cross-reference lists and other places. If you need to output an additional line before the main line then pass idainfo::indent instead of -1. The kernel will know that your line is not the most important one.

Return values

  1 | you've made too many calls to this function, you should stop calling it and return to the caller. The current limit is 500 lines per item.
  0 | ok

idaman bool ida_export MakeNull | ( | void |  | ) |

Generate empty line.

This function does nothing if generation of empty lines is disabled.

Return values

  1 | the limit of lines per item is reached. The current limit is determined by MAX_ITEM_LINES in IDA.CFG
  0 | ok

idaman bool ida_export MakeBorder | ( | void |  | ) |

Generate thin border line.

This function does nothing if generation of border lines is disabled.

Return values

  1 | the limit of lines per item is reached. The current limit is determined by MAX_ITEM_LINES in IDA.CFG
  0 | ok

idaman bool ida_export MakeSolidBorder | ( | void |  | ) |

Generate solid border line.

Return values

  1 | the limit of lines per item is reached. The current limit is determined by MAX_ITEM_LINES in IDA.CFG
  0 | ok

bool gen_cmt_line | ( | const char * | format,
|  |  | ...
| ) |  |
| inline

Generate one non-indented comment line, colored with COLOR_AUTOCMT.

Parameters

  format | printf() style format line. The resulting comment line should not include comment character (;)

Return values

  1 | the limit of lines per item is reached
  0 | ok

bool gen_collapsed_line | ( | const char * | format,
|  |  | ...
| ) |  |
| inline

Generate one non-indented comment line, colored with COLOR_COLLAPSED.

Parameters

  format | printf() style format line. The resulting comment line should not include comment character (;)

Return values

  1 | you've made too many calls to MakeLine(), you should stop calling MakeLine() and return to the caller.
  0 | ok

idaman bool ida_export generate_big_comment | ( | const char * | cmt,
|  | color_t | color
| ) |  |

Generate big non-indented comment lines.

Parameters

  cmt | comment text. may contain \n characters to denote new lines. should not contain comment character (;)
  color | color of comment text (one of Color tags)

Return values

  1 | you've made too many calls to MakeLine(), you should stop calling MakeLine() and return to the caller. The current limit is 500 lines per item.
  0 | ok

idaman bool ida_export generate_many_lines | ( | const char * | string,
|  | color_t | color
| ) |  |

Generate many non-indented lines.

Parameters

  string | text. may contain \n characters to denote new lines.
  color | color of the text (one of Color tags)

Return values

  1 | you've made too many calls to MakeLine(), you should stop calling MakeLine() and return to the caller. The current limit is 500 lines per item.
  0 | ok

idaman void ida_export describex | ( | ea_t | ea,
|  | const char * | prefix,
|  | bool | isprev,
|  | const char * | format,
|  | va_list | va
| ) |  |

Add anterior/posterior line(s).

This is low level function. Use describe() or add_long_cmt() instead.

Parameters

  ea | linear address
  prefix | prefix to use at the start of each line
  isprev | do we add anterior lines? (0-no, posterior)
  format | printf() style format string. may contain \n to denote new lines.
  va | parameters for format

void describe | ( | ea_t | ea,
|  | bool | isprev,
|  | const char * | format,
|  |  | ...
| ) |  |
| inline

Add anterior/posterior line(s).

Parameters

  ea | linear address
  isprev | do we add anterior lines? (0-no, posterior)
  format | printf() style format string. may contain \n to denote new lines.

void add_long_cmt | ( | ea_t | ea,
|  | bool | isprev,
|  | const char * | format,
|  |  | ...
| ) |  |
| inline

Add anterior/posterior comment line(s).

Parameters

  ea | linear address
  isprev | do we add anterior lines? (0-no, posterior)
  format | printf() style format string. may contain \n to denote new lines. The resulting string should not contain comment characters (;), the kernel will add them automatically.

void add_pgm_cmt | ( | const char * | format,
|  |  | ...
| ) |  |
| inline

Add anterior/posterior comment line(s) at the start of program.

Parameters

  format | printf() style format string. may contain \n to denote new lines. The resulting string should not contain comment characters (;), the kernel will add them automatically.