BinNavi.API.disassembly.Database Class Reference

Represents a single database configuration. More...

Inherits BinNavi::APIHelpers::ApiObject< IDatabase >.

List of all members.

Public Member Functions
void	addListener (final IDatabaseListener listener)
	Adds a database listener.
void	close ()
void	connect () throws CouldntLoadDriverException, CouldntConnectException, InvalidDatabaseException, CouldntInitializeDatabaseException, InvalidDatabaseFormatException
	Connects to the database.
Project	createProject (final String name) throws CouldntSaveDataException
	Creates a new project.
void	deleteModule (final Module module) throws CouldntDeleteException
	Deletes a module from the database.
void	deleteProject (final Project project) throws CouldntDeleteException
	Deletes a project from the database.
ResultSet	executeQuery (final PreparedStatement statement) throws SQLException
	Query the database with a raw SQL query.
ResultSet	executeQuery (final String query) throws SQLException
	Query the database with a raw SQL query.
DebuggerTemplateManager	getDebuggerTemplateManager ()
	Debugger template manager of the database.
String	getDescription ()
	Description of the database.
String	getDriver ()
	Driver used to connect to the database.
String	getHost ()
	Host of the database.
List< Module >	getModules ()
	Modules in the database.
String	getName ()
	Name of the database.
TagManager	getNodeTagManager ()
	Node tag manager of the database.
String	getPassword ()
	Password used to connect to the database.
List< Project >	getProjects ()
	Projects in the database.
String	getUrl ()
	URL of the database.
String	getUser ()
	User used to connect to the database.
TagManager	getViewTagManager ()
	View tag manager of the database.
void	importIDB (final String idbfile) throws ImportFailedException
	Imports an IDB file to the database.
boolean	isAutoConnect ()
	Checks whether connections to this database are established automatically.
boolean	isConnected ()
	Checks the connection state of the database.
boolean	isLoaded ()
	Checks whether data from this database was already loaded.
boolean	isSavePassword ()
	Checks whether the password to this database is stored in the config file.
void	load () throws CouldntLoadDataException, InvalidDatabaseVersionException
	Loads data from the database.
void	refresh () throws CouldntLoadDataException
	Refreshes the modules list.
void	removeListener (final IDatabaseListener listener)
	Removes a database listener.
void	setAutoConnect (final boolean autoConnect)
	Changes the auto-connect flag of the database.
void	setDescription (final String description)
	Changes the description of the database.
void	setDriver (final String driver)
	Changes the driver string of the database.
void	setHost (final String host)
	Changes the host of the database.
void	setName (final String name)
	Changes the name string of the database.
void	setPassword (final String password)
	Changes password used to connect to the database.
void	setSavePassword (final boolean savePassword)
	Changes the save-password flag of the database.
void	setUser (final String user)
	Changes the database user.
String	toString ()
	Printable representation of the database.

---

Detailed Description

Database objects provide configurations for individual databases and - once loaded - access to the projects, modules, and other objects stored in that database.

To use database objects it is important to understand the lifecycle of database objects. After the creation of a database object you have to connect to the database first. Once the connection is established it is possible to load the data from the database. If loading was successful you have full access to the projects, modules, and other objects stored in the database.

---

Member Function Documentation

void BinNavi.API.disassembly.Database.addListener

(

final IDatabaseListener

listener

)

Adds an object that is notified about changes in the database.

Parameters:

listener

The listener object that is notified about changes in the database.

Exceptions:

	IllegalArgumentException	Thrown if the listener argument is null.
	IllegalStateException	Thrown if the listener object is already listening on the database.

void BinNavi.API.disassembly.Database.close

(

)

Closes the database.

void BinNavi.API.disassembly.Database.connect

(

)

throws CouldntLoadDriverException, CouldntConnectException, InvalidDatabaseException, CouldntInitializeDatabaseException, InvalidDatabaseFormatException

Opens a connection to the database.

Exceptions:

	CouldntLoadDriverException	Thrown if the driver to be used to connect to the database could not be loaded.
	CouldntConnectException	Thrown if no connection to the database could be established.
	InvalidDatabaseException	Thrown if the database is in an inconsistent state and can not be used.
	CouldntInitializeDatabaseException	Thrown if the database could not be initialized for use with BinNavi.
	InvalidDatabaseFormatException	Thrown if the database is not a BinNavi 3.0 database.

Project BinNavi.API.disassembly.Database.createProject

(

final String

name

)

throws CouldntSaveDataException

Creates a new project in the database. The created project is immediately stored in the database. Further save operations are not necessary.

Parameters:

name

The name of the new project

Returns:

The newly created project.

Exceptions:

	IllegalArgumentException	Thrown if the name argument is null.
	IllegalStateException	Thrown if there is no connection to the database or the database is not loaded.
	CouldntSaveDataException	Thrown if the project could not be created.

void BinNavi.API.disassembly.Database.deleteModule

(

final Module

module

)

throws CouldntDeleteException

Deletes a module from the database.

Parameters:

module

The module to delete from the database.

Exceptions:

CouldntDeleteException

Thrown if the module could not be deleted from the database.

void BinNavi.API.disassembly.Database.deleteProject

(

final Project

project

)

throws CouldntDeleteException

Deletes a project from the database.

Parameters:

project

The project to delete from the database.

Exceptions:

CouldntDeleteException

Thrown if the project could not be deleted from the database.

ResultSet BinNavi.API.disassembly.Database.executeQuery

(

final PreparedStatement

statement

)

throws SQLException

Executes a raw SQL query on the database and returns the result set of the query.

Parameters:

statement

The SQL query to issue.

Returns:

The results of the query. Plugins using this method have to close this result set themselves when they are done.

Exceptions:

SQLException

Thrown if the query failed for whatever reason.

ResultSet BinNavi.API.disassembly.Database.executeQuery

(

final String

query

)

throws SQLException

Executes a raw SQL query on the database and returns the result set of the query.

Parameters:

query

The query to issue.

Returns:

The results of the query. Plugins using this method have to close this result set themselves when they are done.

Exceptions:

SQLException

Thrown if the query failed for whatever reason.

DebuggerTemplateManager BinNavi.API.disassembly.Database.getDebuggerTemplateManager

(

)

Returns the debugger template manager of this database. This is the manager that keeps track of all pre-defined debugger templates.

Returns:

The debugger template manager of this database.

String BinNavi.API.disassembly.Database.getDescription

(

)

Returns the description of the database. The description of the database is the text string that is shown in the database node in the project tree.

Returns:

The description of the database.

String BinNavi.API.disassembly.Database.getDriver

(

)

Returns the name of the driver that is used to connect to this database.

Returns:

The driver of the database.

String BinNavi.API.disassembly.Database.getHost

(

)

Returns the host of the database.

Returns:

The host of the database.

List<Module> BinNavi.API.disassembly.Database.getModules

(

)

Returns a list of modules that can be found in the database.

Returns:

A list of modules.

Exceptions:

IllegalStateException

Thrown if the database was not loaded before.

String BinNavi.API.disassembly.Database.getName

(

)

Returns the name of the database as it is known to the database server.

Returns:

The name of the database.

TagManager BinNavi.API.disassembly.Database.getNodeTagManager

(

)

Returns the node tag manager that manages all tags contained in the database.

Returns:

The node tag manager of the database.

String BinNavi.API.disassembly.Database.getPassword

(

)

Returns the password string that is used to connect to the database.

Returns:

The password string.

List<Project> BinNavi.API.disassembly.Database.getProjects

(

)

Returns a list of projects that can be found in the database.

Returns:

A list of projects.

Exceptions:

IllegalStateException

Thrown if the database was not loaded before.

String BinNavi.API.disassembly.Database.getUrl

(

)

Returns the URL that describes the location of the database.

Returns:

The URL of the database.

String BinNavi.API.disassembly.Database.getUser

(

)

Returns the user that is used to connect to the database.

Returns:

The user string.

TagManager BinNavi.API.disassembly.Database.getViewTagManager

(

)

Returns the view tag manager that manages all tags contained in the database.

Returns:

The view tag manager of the database.

void BinNavi.API.disassembly.Database.importIDB

(

final String

idbfile

)

throws ImportFailedException

Imports an IDB file.

Parameters:

idbfile

The location of the IDB file to import.

Exceptions:

ImportFailedException

Thrown if the IDB file could not be imported.

boolean BinNavi.API.disassembly.Database.isAutoConnect

(

)

Returns a flag that indicates whether a connection to the database is established automatically when BinNavi is started.

Returns:

True, if a connection to the database is established automatically. False, otherwise.

boolean BinNavi.API.disassembly.Database.isConnected

(

)

Returns a flag that indicates whether a connection to the database is currently open.

Returns:

True, if a connection to the database is open. False, otherwise.

boolean BinNavi.API.disassembly.Database.isLoaded

(

)

Returns a flag that indicates whether the data has been loaded from the database.

Returns:

True, if the database has been loaded. False, otherwise.

boolean BinNavi.API.disassembly.Database.isSavePassword

(

)

Returns a flag that indicates whether the password of this database configuration is stored in the configuration file when BinNavi exits.

Returns:

True, if the password is saved to configuration file. False, otherwise.

void BinNavi.API.disassembly.Database.load

(

)

throws CouldntLoadDataException, InvalidDatabaseVersionException

Loads the data from the database.

Note that a connection to the database must be open before this function can succeed.

Exceptions:

	IllegalStateException	Thrown if no connection to the database is open.
	CouldntLoadDataException	Thrown if the data could not be loaded from the database.
	InvalidDatabaseVersionException	Thrown if the BinNavi tables in the database are not compatible with the used version of BinNavi.

void BinNavi.API.disassembly.Database.refresh

(

)

throws CouldntLoadDataException

Refreshes the list of modules from the database. This is useful to call if you suspect that the modules stored in the database changed.

Exceptions:

CouldntLoadDataException

Thrown if the modules could not reloaded.

void BinNavi.API.disassembly.Database.removeListener

(

final IDatabaseListener

listener

)

Removes a listener object from the database.

Parameters:

listener

The listener object to remove from the database.

Exceptions:

	IllegalArgumentException	Thrown if the listener argument is null.
	IllegalStateException	Thrown if the listener object was not listening on the database.

void BinNavi.API.disassembly.Database.setAutoConnect

(

final boolean

autoConnect

)

Changes the auto-connect flag of the database that is responsible for loading the content of databases automatically when BinNavi is started.

Parameters:

autoConnect

True, to automatically load this database when BinNavi is started. False, otherwise.

void BinNavi.API.disassembly.Database.setDescription

(

final String

description

)

Changes the description of the database. The description string of a database is the string that is displayed in the database node of the project tree.

Parameters:

description

The new description of the database.

Exceptions:

IllegalArgumentException

Thrown if the description argument is null.

void BinNavi.API.disassembly.Database.setDriver

(

final String

driver

)

Changes the driver string of the database.

Parameters:

driver

The new driver string of the database.

Exceptions:

IllegalArgumentException

Thrown if the driver argument is null.

void BinNavi.API.disassembly.Database.setHost

(

final String

host

)

Changes the host string of the database.

Parameters:

host

The new host string of the database.

Exceptions:

IllegalArgumentException

Thrown if the host argument is null.

void BinNavi.API.disassembly.Database.setName

(

final String

name

)

Changes the name string of the database.

Parameters:

name

The new name string of the database.

Exceptions:

IllegalArgumentException

Thrown if the name argument is null.

void BinNavi.API.disassembly.Database.setPassword

(

final String

password

)

Changes the password that is used to connect to the database.

Parameters:

password

The new password.

Exceptions:

IllegalArgumentException

Thrown if the password argument is null.

void BinNavi.API.disassembly.Database.setSavePassword

(

final boolean

savePassword

)

Changes the save-password flag of the database that is responsible for storing the password to this database in the BinNavi configuration file.

Parameters:

savePassword

True, to store the password. False, otherwise.

void BinNavi.API.disassembly.Database.setUser

(

final String

user

)

Changes the user that is used to connect to the database.

Parameters:

user

The new user string.

Exceptions:

IllegalArgumentException

Thrown if the user argument is null.

String BinNavi.API.disassembly.Database.toString

(

)

Returns the string representation of the database.

Returns:

The string representation of the database.