IDA API
Introduction
IDA ICE communicates between instances, and with external programs, by socket communication facilitated by the ZeroMQ framework. On each computer running IDA ICE, the IDA message broker runs (see the IDA message broker chapter), and passes messages between registered clients. Each registered client has a unique (on that computer) id number (which is written in Help/About IDA/API id). This id is used to communicate to that client. The API id is in many cases the same as the Process ID of the client process. Once a session is started (by calling the client with some function), the session is locked, and no other API sessions can talk to that client until the session has been closed.
IDA Message Broker Service
The IDA Message Broker Service is a service with the name IDAMessageBrokerService. It is installed into the c:\ProgramData\equa\ folder. The service can be removed and installed by executing the IDAMessageBrokerService.exe with the flags /install and /remove from a command prompt with elevated rights. It is installed by default during installation of IDA ICE. The service can be started and stopped with the help of the usual Windows service management tool, or by calling sc start(or stop) IDAMessageBrokerService in an elevated command prompt. When started, the ports on which the program is communicating is written to the file ida_ports.txt in c:\ProgramData\equa. Here is also a ida_message_broker_log.txt-file, where some logging is done. If you want to open the message broker for external communication, please place a file named ida_external.txt into the c:\ProgramData\equa folder and restart the service. The content of this file is irrelevant.
The idaapi2.dll
The idaapi2.dll is a .dll (a dynamic-link library), which opens up the IDA API for external programs. Every program language where you can load a Windows .dll-file, and use the ANSI C/C++ function calls, can use the API. In this document, both the technical parts of using the .dll and the API itself will be discussed.
If you want to move the idaapi.dll from the default location, please also copy the libzmq-v100-mt-4_0_4.dll-file to the same location as the idaapi2.dll. There is some logging of the API calls in the file ida_api_dll_log.txt placed in the Windows Temp-folder (usually c:\users\username\appdata\local\temp\). Please check this if you are experiencing problems. To find the correct variable/parameter/object names in IDA ICE, the best way is to first go to Options/Preferences/Developer and check the Do not translate names-checkbox. This makes IDA ICE show the true names in the Outline view. In the outline view, however, not everything is actual objects; entries preceded by a : is a collection, which is just shown for convenience, and does not exist as actual object. Instead, objects listed under the collection, are actually place directly under the parent object for the collection.
Functions in the idaapi2.dll
The functions, except for the connect/disconnect, switch… and get_err and getIDAStatus, are put in a results queue, which you then poll to get the actual result when it is done. These functions immediately return true/false, and then when the real results is done, that result in the pollForQueuedResults call. When a function description say that it returns “A list of child nodes”, it means that pollForQueuedResults returns that after a successful call.
In the idaapi2.dll, the following functions are exposed:
Functions for connecting/disconnecting with IDA:
| Function name | Type | parameter | returns | example |
|---|---|---|---|---|
| connect_to_ida | bool | char *port_c, char *remote_id | True/False | connect_to_ida("5945", "4076") |
| switch_remote_connection | bool | const char *new_remote_id | True/False | switch_remote_connection("4077") |
| switch_api_version | bool | long new_version_number | True/False | switch_api_version(1) |
| call_ida_function | long | char *function, char *values, char *out, int out_len | -1, 0, 1< | call_ida_function("+","[{\"type\": \"integer\", \"value\": 4},{\"type\": \"integer\", \"value\": 5}]", out, 500) |
| ida_disconnect | bool | True/False | ida_disconnect() | |
| get_err | long | char *out, int out_len | -1, 0, 1< | get_err(out, 500) |
DOM api-functions
All functions return -1 if something went wrong, 0 if everything went well, and a positive number if the string buffer sent in is too small. In out, the string representation of a json-structure is located. This can be parsed and used: it is either a structure {"type": type, "value": value}, or a list with such structures. All object values are longs. They are translated back to objects in IDA.
| Function name | Type | parameter | returns |
|---|---|---|---|
| childNodes | long | long node, char * out, int out_len | JSON list of child nodes to node |
| parentNode | long | long node, char * out, int out_len | parent node of node |
| setParentNode | long | long node, long parent, char * out, int out_len | Sets the parent node of node to parent. Returns the parent node |
| hasChildNodes | long | long node, char * out, int out_len | Returns true/false depending on whether node has any child nodes |
| firstChild | long | long node, char * out, int out_len | Returns the first child node of node |
| lastChild | long | long node, char * out, int out_len | Returns the last child node of node |
| nextSibling | long | long node, char * out, int out_len | Returns the next sibling node of node |
| previousSibling | long | long node, char * out, int out_len | Returns the previous sibling node of node |
| childNodesLength | long | long node, char * out, int out_len | Returns the number of child nodes of node |
| cloneNode | long | long node, char * out, int out_len | Clones, and inserts, the node node. Returns the new node |
| createNode | long | long node, char * value, char * out, int out_len | Creates a new node as a child to node, according to the l-form given in the value-parameter. Returns the new node |
| contains | long | long node, long node2, char * out, int out_len | Checks if node is contained within node2. Returns true/false |
| domAncestor | long | long node, long node2, char * out, int out_len | Checks if node is ancestor to node2. Returns true/false |
| item | long | long index, long node, char * out, int out_len | Returns the node with index index in the list of children of node |
| appendChild | long | long child, long parent, char * out, int out_len | Appends child as a child node to parent. Returns the new list of children |
| removeChild | long | long child, long parent, char * out, int out_len | Removes child from parent. Returns the new list of children |
| replaceChild | long | long child, long child_rep, long parent, char * out, int out_len | Replaces child with child_rep. Returns the parent |
| setAttribute | long | char * attribute, long node, char * value, char * out, int out_len | Sets the attribute attribute of node node to value given by the json structure submitted (in text form) in the value parameter. Returns the value of the attribute |
| getAttribute | long | char * attribute, long node, char * out, int out_len | Returns the value of the attribute attribute of node node |
Special IDA api-functions
| Function name | Type | parameter | result | comment/example |
|---|---|---|---|---|
| openDocument | long | char *path, char *out, int out_len | Opens the building specified in path. Returns the building object | |
| openDocByTypeAndName | long | const char * name, const char *type, char * out, int out_len | Returns the building object of type type and name name (without .idm) for an already opened building | |
| saveDocument | long | long building_object, char * new_path, long unpacked, char * out, int out_len | Saves the building object. If new_path is just an empty string, it saves, otherwise, it tries to Save as... | new_path can e.g. be "d:\\temp\\building47.idm" unpacked can be set to 1 if you want unpacked cases, or 0 if you want packed (default behaviour) cases. Returns true/false. |
| runSimulation | long | long building_object, long simulation_type, char * out, int out_len | Acccording to the simulation_type parameter, the building building_object is run as simulation_type: | |
| pollForQueuedResults | long | char * out, int out_len | Returns false if no queued results exists. Returns a list if queued results exist, where first element is true/false depending if calculation is done. If done, the second element in the list contains the result | |
| closeSession | bool | char * out, int out_len | Closes down the current session, so a new one can connect to the child instance | |
| exitSession | bool | char * out, int out_len | Closes down the application, for the current session | |
| getZones | long | long node, char * out, int out_len | If node is a building object, returns a list of the bulding's zones. Otherwise tries to return a list of the node's building's zones (same as above). | |
| getWindows | long | long object, char * out, int out_len | If object is a building object, a list of all windows in the building is returned. If a zone object, a list of all external windows in the zone | |
| getAllSubobjectsOfType | long | long node, char *type, char *out, int out_len | Returns a list of all subobjects of type type recursively for an object | |
| runIDAScript | long | long node, char *script, char *out, int out_len | Executes a general IDA script with node as base object | |
| copyObject | long | long node, char *new_name, char *out, int *out_len | Makes a copy of node node and names it new_name. Returns new node | |
| findObjectsByCriterium | long | long node, char *criterium, char *out, int *out_len | Returns a list of all subobjects (recursively) of node, and returns a list with structures as: (object ("Object name" "Parent name" "Grandparent name.." etc, down to building name))) | Criterium must be an IDA script expression evaluating to true/false. (E.g. "(= (:call name [@]) "Zone name")" "(eq 'SCHEDULE-DATA (:call model-type [@]))" |
| findUseOfResource | long | long resource, char *out, int *out_len | Resource must be a resource object. Returns a list of all objects where the resource is used | |
| printReport | long | long report, char *out_path, long report_type, char *out, int *out_len | Writes a report to out_path. | report must be a report object. report_type specifies what type of report you want 1. .html |
| compareResults | long | char *building_objects, char *out_path, long report_type, char *out, int *out_len | building_objects must be a json-list with building objects: "[{\"type\": "\object\", \"value:\": 1}, {\"type\": "\object\", \"value:\": 1}]" | report_type specifies what type of report you want: 1. .html |
| getIDAStatus | long | char * out, int out_len | Returns a list with the present status of the simulation/IDA, and possible other information. The first element is always the state | Possible normal states: 1) Idle 2) Reading in model 3) Creating math model 4) Simulating (incl. progress) 5) Finished 6) Terminated 7) Saving |
| getChildrenOfType | long | long node, char * type, char * out, int out_len | Returns a list of all the child nodes of node with type type | |
| findNamedChild | long | long node, char * name, char * out, int out_len | Returns one or zero child nodes of node with name name, will try first string version, then symbol version of name | |
| export3dView | long | long building_object, char * output_file, long view, char * out, int out_len | Exports an image of the 3D-view to file output_file given building building_object. Several views are available | 0. Default view (as you looked at the case last) 1. Top view 2. Bottom view 3. Front View 4. Back view 5. Left view 6. Right view |
| exportDiagram | long | long diagram_object, char * output_file, long save_type, char * out, int out_len | Exports an image of the diagram diagram_object to file output_file | Save_type can be: 0. .emf-file 1. .wmf-file 2. .png-file. |
| getNamedObjectFromPath | long | long object, char * path, long save_type, char * out, int out_len | Returns an object from a potentially deep structure. Object is parent object, and in path, you can specify the path down to an object you want to access | The path should be a text representation of a JSON array, with type, value pairs, like this: "[{\"type\":\"string\",\"value\": \"Zone\"}, {\"type\":\"string\",\"value\": \"GROUP\"}]" |
| openIFCFile | long | const char * name, const char *type, char * out, int out_len | Returns the imported building object. | Imports the .ifc file specified by path. The three parameters mergeWindows keepIntersectingSpaces and ignoreRoof can be set to 0 (do not use) or 1 (use). The parameters are from the IFC import options in IDA ICE. |