FileMetadata

Detailed Description

Classes
class	BinaryNinja::NavigationHandler
class	BinaryNinja::SaveSettings
class	BinaryNinja::FileMetadata

---

Class Documentation

BinaryNinja::NavigationHandler

class BinaryNinja::NavigationHandler

Public Member Functions
	NavigationHandler ()
virtual	~NavigationHandler ()
BNNavigationHandler *	GetCallbacks ()
virtual std::string	GetCurrentView ()=0
virtual uint64_t	GetCurrentOffset ()=0
virtual bool	Navigate (const std::string &view, uint64_t offset)=0

Constructor & Destructor Documentation

NavigationHandler()

NavigationHandler::NavigationHandler

(

)

~NavigationHandler()

virtual BinaryNinja::NavigationHandler::~NavigationHandler ( )

inlinevirtual

Member Function Documentation

GetCallbacks()

BNNavigationHandler * BinaryNinja::NavigationHandler::GetCallbacks ( )

inline

GetCurrentView()

virtual std::string BinaryNinja::NavigationHandler::GetCurrentView ( )

pure virtual

Implemented in FileContext.

GetCurrentOffset()

virtual uint64_t BinaryNinja::NavigationHandler::GetCurrentOffset ( )

pure virtual

Implemented in FileContext.

Navigate()

virtual bool BinaryNinja::NavigationHandler::Navigate ( const std::string & view, uint64_t offset )

pure virtual

Implemented in FileContext.

BinaryNinja::SaveSettings

class BinaryNinja::SaveSettings

Public Member Functions
	SaveSettings ()
	SaveSettings (BNSaveSettings *settings)
bool	IsOptionSet (BNSaveOption option) const
void	SetOption (BNSaveOption option, bool state=true)
std::string	GetName () const
void	SetName (const std::string &name)
Public Member Functions inherited from BinaryNinja::CoreRefCountObject< BNSaveSettings, BNNewSaveSettingsReference, BNFreeSaveSettings >
	CoreRefCountObject ()
virtual	~CoreRefCountObject ()
BNSaveSettings *	GetObject () const
void	AddRef ()
void	Release ()
void	AddRefForRegistration ()
void	ReleaseForRegistration ()
void	AddRefForCallback ()
void	ReleaseForCallback ()

Additional Inherited Members
Static Public Member Functions inherited from BinaryNinja::CoreRefCountObject< BNSaveSettings, BNNewSaveSettingsReference, BNFreeSaveSettings >
static BNSaveSettings *	GetObject (CoreRefCountObject *obj)
static BNSaveSettings *	GetObject (const CoreRefCountObject *obj)
Public Attributes inherited from BinaryNinja::CoreRefCountObject< BNSaveSettings, BNNewSaveSettingsReference, BNFreeSaveSettings >
std::atomic< int >	m_refs
bool	m_registeredRef
BNSaveSettings *	m_object

Constructor & Destructor Documentation

SaveSettings() [1/2]

SaveSettings::SaveSettings

(

)

SaveSettings() [2/2]

SaveSettings::SaveSettings

(

BNSaveSettings *

settings

)

Member Function Documentation

IsOptionSet()

bool SaveSettings::IsOptionSet

(

BNSaveOption

option

)

const

SetOption()

void SaveSettings::SetOption	(	BNSaveOption	option,
		bool	state = true )

GetName()

std::string SaveSettings::GetName

(

)

const

SetName()

void SaveSettings::SetName

(

const std::string &

name

)

BinaryNinja::FileMetadata

class BinaryNinja::FileMetadata

Public Member Functions
	FileMetadata ()
	FileMetadata (const std::string &filename)
	FileMetadata (Ref< ProjectFile > projectFile)
	FileMetadata (BNFileMetadata *file)
void	Close ()
	Close the underlying file handle.
void	SetNavigationHandler (NavigationHandler *handler)
std::string	GetOriginalFilename () const
	Get the original name of the binary opened if a bndb, otherwise the current filename.
void	SetOriginalFilename (const std::string &name)
	If the filename is not open in a BNDB, sets the filename for the current file.
std::string	GetFilename () const
void	SetFilename (const std::string &name)
	Set the filename for the current BNDB or binary.
bool	IsModified () const
	Whether the file has unsaved modifications.
bool	IsAnalysisChanged () const
	Whether auto-analysis results have changed.
void	MarkFileModified ()
	Mark file as having unsaved changes.
void	MarkFileSaved ()
	Mark file as having been saved (inverse of MarkFileModified)
bool	IsSnapshotDataAppliedWithoutError () const
bool	IsBackedByDatabase (const std::string &binaryViewType="") const
	Whether the FileMetadata is backed by a database, or if specified, a specific BinaryView type.
bool	CreateDatabase (const std::string &name, BinaryView *data, Ref< SaveSettings > settings)
	Writes the current database (.bndb) out to the specified file.
bool	CreateDatabase (const std::string &name, BinaryView *data, const std::function< bool(size_t progress, size_t total)> &progressCallback, Ref< SaveSettings > settings)
	Writes the current database (.bndb) out to the specified file.
Ref< BinaryView >	OpenExistingDatabase (const std::string &path)
	Open an existing database from a given path.
Ref< BinaryView >	OpenExistingDatabase (const std::string &path, const std::function< bool(size_t progress, size_t total)> &progressCallback)
	Open an existing database from a given path with a progress callback.
Ref< BinaryView >	OpenDatabaseForConfiguration (const std::string &path)
bool	SaveAutoSnapshot (BinaryView *data, Ref< SaveSettings > settings)
	Save the current database to the already created file.
bool	SaveAutoSnapshot (BinaryView *data, const std::function< bool(size_t progress, size_t total)> &progressCallback, Ref< SaveSettings > settings)
	Save the current database to the already created file.
void	GetSnapshotData (Ref< KeyValueStore > data, Ref< KeyValueStore > cache, const std::function< bool(size_t, size_t)> &progress)
void	ApplySnapshotData (BinaryView *file, Ref< KeyValueStore > data, Ref< KeyValueStore > cache, const std::function< bool(size_t, size_t)> &progress, bool openForConfiguration=false, bool restoreRawView=true)
Ref< Database >	GetDatabase ()
bool	Rebase (BinaryView *data, uint64_t address)
	Rebase the given BinaryView to a new address.
bool	Rebase (BinaryView *data, uint64_t address, const std::function< bool(size_t progress, size_t total)> &progressCallback)
	Rebase the given BinaryView to a new address.
bool	CreateSnapshotedView (BinaryView *data, const std::string &viewName)
bool	CreateSnapshotedView (BinaryView *data, const std::string &viewName, const std::function< bool(size_t progress, size_t total)> &progressCallback)
bool	RunUndoableTransaction (std::function< bool()> func)
	Run a function in a context in which any changes made to analysis will be added to an undo state.
std::string	BeginUndoActions (bool anonymousAllowed=true)
	Start recording actions taken so they can be undone at some point.
void	CommitUndoActions (const std::string &id)
	Commit the actions taken since a call to BeginUndoActions.
void	RevertUndoActions (const std::string &id)
	Revert the actions taken since a call to BeginUndoActions.
void	ForgetUndoActions (const std::string &id)
	Forget the actions since a call to BeginUndoActions.
bool	CanUndo ()
bool	Undo ()
	Undo the last committed action in the undo database.
bool	CanRedo ()
bool	Redo ()
	Redo the last committed action in the undo database.
std::vector< Ref< User > >	GetUsers ()
std::vector< Ref< UndoEntry > >	GetUndoEntries ()
std::vector< Ref< UndoEntry > >	GetRedoEntries ()
Ref< UndoEntry >	GetLastUndoEntry ()
Ref< UndoEntry >	GetLastRedoEntry ()
std::optional< std::string >	GetLastUndoEntryTitle ()
std::optional< std::string >	GetLastRedoEntryTitle ()
void	ClearUndoEntries ()
std::string	GetCurrentView ()
	Get the current View name, e.g.
uint64_t	GetCurrentOffset ()
	Get the current offset in the current view.
bool	Navigate (const std::string &view, uint64_t offset)
	Navigate to the specified virtual address in the specified view.
BinaryNinja::Ref< BinaryNinja::BinaryView >	GetViewOfType (const std::string &name)
	Get the BinaryView for a specific View type.
std::vector< std::string >	GetExistingViews () const
	List of View names that exist within the current file.
size_t	GetSessionId () const
	Get the current Session ID for this file.
void	UnregisterViewOfType (const std::string &type, BinaryNinja::Ref< BinaryNinja::BinaryView > data)
	Explicitly unregister a binary view of the given type from this file.
Ref< ProjectFile >	GetProjectFile () const
void	SetProjectFile (Ref< ProjectFile > projectFile)
Public Member Functions inherited from BinaryNinja::CoreRefCountObject< BNFileMetadata, BNNewFileReference, BNFreeFileMetadata >
	CoreRefCountObject ()
virtual	~CoreRefCountObject ()
BNFileMetadata *	GetObject () const
void	AddRef ()
void	Release ()
void	AddRefForRegistration ()
void	ReleaseForRegistration ()
void	AddRefForCallback ()
void	ReleaseForCallback ()

Additional Inherited Members
Static Public Member Functions inherited from BinaryNinja::CoreRefCountObject< BNFileMetadata, BNNewFileReference, BNFreeFileMetadata >
static BNFileMetadata *	GetObject (CoreRefCountObject *obj)
static BNFileMetadata *	GetObject (const CoreRefCountObject *obj)
Public Attributes inherited from BinaryNinja::CoreRefCountObject< BNFileMetadata, BNNewFileReference, BNFreeFileMetadata >
std::atomic< int >	m_refs
bool	m_registeredRef
BNFileMetadata *	m_object

Constructor & Destructor Documentation

FileMetadata() [1/4]

FileMetadata::FileMetadata

(

)

FileMetadata() [2/4]

BinaryNinja::FileMetadata::FileMetadata

(

const std::string &

filename

)

FileMetadata() [3/4]

FileMetadata::FileMetadata

(

Ref< ProjectFile >

projectFile

)

FileMetadata() [4/4]

FileMetadata::FileMetadata

(

BNFileMetadata *

file

)

Member Function Documentation

Close()

void FileMetadata::Close

(

)

Close the underlying file handle.

SetNavigationHandler()

void FileMetadata::SetNavigationHandler

(

NavigationHandler *

handler

)

GetOriginalFilename()

string FileMetadata::GetOriginalFilename

(

)

const

Get the original name of the binary opened if a bndb, otherwise the current filename.

Returns

The original name of the binary opened if a bndb, otherwise returns the current filename

SetOriginalFilename()

void FileMetadata::SetOriginalFilename

(

const std::string &

name

)

If the filename is not open in a BNDB, sets the filename for the current file.

Parameters

name

New name

GetFilename()

string FileMetadata::GetFilename

(

)

const

Returns

The name of the open bndb or binary filename

SetFilename()

void FileMetadata::SetFilename

(

const std::string &

name

)

Set the filename for the current BNDB or binary.

Parameters

name	Set the filename for the current BNDB or binary.

IsModified()

bool FileMetadata::IsModified

(

)

const

Whether the file has unsaved modifications.

Returns

Whether the file has unsaved modifications

IsAnalysisChanged()

bool FileMetadata::IsAnalysisChanged

(

)

const

Whether auto-analysis results have changed.

Returns

Whether auto-analysis results have changed.

MarkFileModified()

void FileMetadata::MarkFileModified

(

)

Mark file as having unsaved changes.

MarkFileSaved()

void FileMetadata::MarkFileSaved

(

)

Mark file as having been saved (inverse of MarkFileModified)

IsSnapshotDataAppliedWithoutError()

bool FileMetadata::IsSnapshotDataAppliedWithoutError

(

)

const

IsBackedByDatabase()

bool FileMetadata::IsBackedByDatabase

(

const std::string &

binaryViewType = ""

)

const

Whether the FileMetadata is backed by a database, or if specified, a specific BinaryView type.

Parameters

binaryViewType

Type for the BinaryView

Returns

Whether the FileMetadata is backed by a database

CreateDatabase() [1/2]

bool BinaryNinja::FileMetadata::CreateDatabase	(	const std::string &	name,
		BinaryView *	data,
		Ref< SaveSettings >	settings )

Writes the current database (.bndb) out to the specified file.

Parameters

name	path and filename to write the bndb to. Should have ".bndb" appended to it.
data	BinaryView to save the database from
settings	Special save options

Returns

Whether the save was successful

CreateDatabase() [2/2]

bool BinaryNinja::FileMetadata::CreateDatabase	(	const std::string &	name,
		BinaryView *	data,
		const std::function< bool(size_t progress, size_t total)> &	progressCallback,
		Ref< SaveSettings >	settings )

Writes the current database (.bndb) out to the specified file.

Parameters

name	path and filename to write the bndb to. Should have ".bndb" appended to it.
data	BinaryView to save the database from
progressCallback	callback function to send save progress to.
settings	Special save options

Returns

Whether the save was successful

OpenExistingDatabase() [1/2]

Ref< BinaryView > BinaryNinja::FileMetadata::OpenExistingDatabase

(

const std::string &

path

)

Open an existing database from a given path.

Parameters

path	Path to the existing database

Returns

The resulting BinaryView, if the load was successful

OpenExistingDatabase() [2/2]

Ref< BinaryView > BinaryNinja::FileMetadata::OpenExistingDatabase	(	const std::string &	path,
		const std::function< bool(size_t progress, size_t total)> &	progressCallback )

Open an existing database from a given path with a progress callback.

Parameters

path	Path to the existing database
progressCallback	callback function to send load progress to.

Returns

The resulting BinaryView, if the load was successful

OpenDatabaseForConfiguration()

Ref< BinaryView > FileMetadata::OpenDatabaseForConfiguration

(

const std::string &

path

)

SaveAutoSnapshot() [1/2]

bool FileMetadata::SaveAutoSnapshot	(	BinaryView *	data,
		Ref< SaveSettings >	settings )

Save the current database to the already created file.

Note: CreateDatabase should have been called prior to calling this.

Parameters

data	BinaryView to save the data of
settings	Special save options

Returns

Whether the save was successful

SaveAutoSnapshot() [2/2]

bool BinaryNinja::FileMetadata::SaveAutoSnapshot	(	BinaryView *	data,
		const std::function< bool(size_t progress, size_t total)> &	progressCallback,
		Ref< SaveSettings >	settings )

Save the current database to the already created file.

Note: CreateDatabase should have been called prior to calling this.

Parameters

data	BinaryView to save the data of
settings	Special save options
progressCallback	callback function to send save progress to

Returns

Whether the save was successful

GetSnapshotData()

void FileMetadata::GetSnapshotData	(	Ref< KeyValueStore >	data,
		Ref< KeyValueStore >	cache,
		const std::function< bool(size_t, size_t)> &	progress )

ApplySnapshotData()

void FileMetadata::ApplySnapshotData	(	BinaryView *	file,
		Ref< KeyValueStore >	data,
		Ref< KeyValueStore >	cache,
		const std::function< bool(size_t, size_t)> &	progress,
		bool	openForConfiguration = false,
		bool	restoreRawView = true )

GetDatabase()

Ref< Database > FileMetadata::GetDatabase

(

)

Rebase() [1/2]

bool FileMetadata::Rebase	(	BinaryView *	data,
		uint64_t	address )

Rebase the given BinaryView to a new address.

Parameters

data	BinaryView to rebase
address	Address to rebase to

Returns

Whether the rebase was successful

Rebase() [2/2]

bool BinaryNinja::FileMetadata::Rebase	(	BinaryView *	data,
		uint64_t	address,
		const std::function< bool(size_t progress, size_t total)> &	progressCallback )

Rebase the given BinaryView to a new address.

Parameters

data	BinaryView to rebase
address	Address to rebase to
progressCallback	Callback function to pass rebase progress to

Returns

Whether the rebase was successful

CreateSnapshotedView() [1/2]

bool FileMetadata::CreateSnapshotedView	(	BinaryView *	data,
		const std::string &	viewName )

CreateSnapshotedView() [2/2]

bool BinaryNinja::FileMetadata::CreateSnapshotedView	(	BinaryView *	data,
		const std::string &	viewName,
		const std::function< bool(size_t progress, size_t total)> &	progressCallback )

RunUndoableTransaction()

bool FileMetadata::RunUndoableTransaction

(

std::function< bool()>

func

)

Run a function in a context in which any changes made to analysis will be added to an undo state.

If the function returns false or throws an exception, any changes made within will be reverted.

Parameters

func	Function to run in undo context

Returns

Return status of function

Exceptions

std::exception

If the called function throws an exception

BeginUndoActions()

std::string FileMetadata::BeginUndoActions ( bool anonymousAllowed = true )

nodiscard

Start recording actions taken so they can be undone at some point.

Parameters

anonymousAllowed

Legacy interop: prevent empty calls to CommitUndoActions from affecting this undo state. Specifically for RunUndoableTransaction.

Returns

Id of UndoEntry created, for passing to either CommitUndoActions or RevertUndoActions

CommitUndoActions()

void FileMetadata::CommitUndoActions

(

const std::string &

id

)

Commit the actions taken since a call to BeginUndoActions.

Parameters

id	Id of UndoEntry created by BeginUndoActions

RevertUndoActions()

void FileMetadata::RevertUndoActions

(

const std::string &

id

)

Revert the actions taken since a call to BeginUndoActions.

Parameters

id	Id of UndoEntry created by BeginUndoActions

ForgetUndoActions()

void FileMetadata::ForgetUndoActions

(

const std::string &

id

)

Forget the actions since a call to BeginUndoActions.

Parameters

id	Id of UndoEntry created by BeginUndoActions

CanUndo()

bool FileMetadata::CanUndo

(

)

Returns

Whether it is possible to perform an Undo

Undo()

bool FileMetadata::Undo

(

)

Undo the last committed action in the undo database.

CanRedo()

bool FileMetadata::CanRedo

(

)

Returns

Whether it is possible to perform a Redo

Redo()

bool FileMetadata::Redo

(

)

Redo the last committed action in the undo database.

GetUsers()

vector< Ref< User > > FileMetadata::GetUsers

(

)

GetUndoEntries()

vector< Ref< UndoEntry > > FileMetadata::GetUndoEntries

(

)

GetRedoEntries()

vector< Ref< UndoEntry > > FileMetadata::GetRedoEntries

(

)

GetLastUndoEntry()

Ref< UndoEntry > FileMetadata::GetLastUndoEntry

(

)

GetLastRedoEntry()

Ref< UndoEntry > FileMetadata::GetLastRedoEntry

(

)

GetLastUndoEntryTitle()

std::optional< std::string > FileMetadata::GetLastUndoEntryTitle

(

)

GetLastRedoEntryTitle()

std::optional< std::string > FileMetadata::GetLastRedoEntryTitle

(

)

ClearUndoEntries()

void FileMetadata::ClearUndoEntries

(

)

GetCurrentView()

string FileMetadata::GetCurrentView

(

)

Get the current View name, e.g.

``Linear:ELF``, ``Graph:PE``

Returns

The current view name

GetCurrentOffset()

uint64_t FileMetadata::GetCurrentOffset

(

)

Get the current offset in the current view.

Returns

The current offset

Navigate()

bool FileMetadata::Navigate	(	const std::string &	view,
		uint64_t	offset )

Navigate to the specified virtual address in the specified view.

Parameters

view	View name. e.g. ``Linear:ELF``, ``Graph:PE``
offset	Virtual address to navigate to

Returns

Whether the navigation was successful.

GetViewOfType()

Ref< BinaryView > FileMetadata::GetViewOfType

(

const std::string &

name

)

Get the BinaryView for a specific View type.

Parameters

name	View name. e.g. ``Linear:ELF``, ``Graph:PE``

Returns

The BinaryView, if it exists

GetExistingViews()

std::vector< std::string > FileMetadata::GetExistingViews

(

)

const

List of View names that exist within the current file.

Returns

List of View Names

GetSessionId()

size_t FileMetadata::GetSessionId

(

)

const

Get the current Session ID for this file.

See also

This is used in Logger and LogRegistry to determine what tab logs are sent to.

Returns

Current Session ID

UnregisterViewOfType()

void FileMetadata::UnregisterViewOfType	(	const std::string &	type,
		BinaryNinja::Ref< BinaryNinja::BinaryView >	data )

Explicitly unregister a binary view of the given type from this file.

Note

There is no need to unregister a binary view in ordinary situations. Binary views will be automatically unregistered from the file when the file itself is about to be freed. Also, when a binary view with the same type is created, the old one is automatically unregistered from the file.

Only use this function when you wish to explicitly remove the binary view from the file. For example, in the debugger, this method is used to remove the Debugger view from the file after the target exits.

This also does not necessarily free the binary, because there could be other references to it.

Parameters

type	the type of the view to unregister
data	the binary view to unregister

GetProjectFile()

Ref< ProjectFile > FileMetadata::GetProjectFile

(

)

const

SetProjectFile()

void FileMetadata::SetProjectFile

(

Ref< ProjectFile >

projectFile

)