Source code for binaryninja.interaction

# Copyright (c) 2015-2024 Vector 35 Inc
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
# deal in the Software without restriction, including without limitation the
# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
# sell copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
# IN THE SOFTWARE.

import ctypes
import traceback
import webbrowser
from typing import Optional, Callable, List

# Binary Ninja components
from . import _binaryninjacore as core
from .enums import FormInputFieldType, MessageBoxIcon, MessageBoxButtonSet, MessageBoxButtonResult, ReportType
from . import binaryview
from .log import log_error
from . import flowgraph
from . import mainthread



[docs]
class LabelField:
	"""
	``LabelField`` adds a text label to the display.
	"""
	def __init__(self, text: str):
		self._text = text

	def _fill_core_struct(self, value):
		value.type = FormInputFieldType.LabelFormField
		value.hasDefault = False
		value.prompt = self._text

	def _fill_core_result(self, value):
		pass

	def _get_result(self, value):
		pass

	@property
	def text(self) -> str:
		return self._text

	@text.setter
	def text(self, value: str) -> None:
		self._text = value




[docs]
class SeparatorField:
	"""
	``SeparatorField`` adds vertical separation to the display.
	"""
	def _fill_core_struct(self, value):
		value.type = FormInputFieldType.SeparatorFormField
		value.hasDefault = False

	def _fill_core_result(self, value):
		pass

	def _get_result(self, value):
		pass




[docs]
class TextLineField:
	"""
	``TextLineField`` Adds prompt for text string input. Result is stored in self.result as a string on completion.
	"""
	def __init__(self, prompt: str, default: Optional[str] = None):
		self._prompt = prompt
		self._default = default
		self._result = None

	def _fill_core_struct(self, value):
		value.type = FormInputFieldType.TextLineFormField
		value.prompt = self._prompt
		value.hasDefault = self._default is not None
		if self._default is not None:
			value.stringDefault = self._default

	def _fill_core_result(self, value):
		value.stringResult = core.BNAllocString(str(self._result))

	def _get_result(self, value):
		self._result = value.stringResult

	@property
	def prompt(self):
		return self._prompt

	@prompt.setter
	def prompt(self, value):
		self._prompt = value

	@property
	def result(self):
		return self._result

	@result.setter
	def result(self, value):
		self._result = value




[docs]
class MultilineTextField:
	"""
	``MultilineTextField`` add multi-line text string input field. Result is stored in self.result
	as a string. This option is not supported on the command-line.
	"""
	def __init__(self, prompt: str, default: Optional[str] = None):
		self._prompt = prompt
		self._default = default
		self._result = None

	def _fill_core_struct(self, value):
		value.type = FormInputFieldType.MultilineTextFormField
		value.prompt = self._prompt
		value.hasDefault = self._default is not None
		if self._default is not None:
			value.stringDefault = self._default

	def _fill_core_result(self, value):
		value.stringResult = core.BNAllocString(str(self._result))

	def _get_result(self, value):
		self._result = value.stringResult

	@property
	def prompt(self):
		return self._prompt

	@prompt.setter
	def prompt(self, value):
		self._prompt = value

	@property
	def result(self):
		return self._result

	@result.setter
	def result(self, value):
		self._result = value




[docs]
class IntegerField:
	"""
	``IntegerField`` add prompt for integer. Result is stored in self.result as an int.
	"""
	def __init__(self, prompt: str, default: Optional[int] = None):
		self._prompt = prompt
		self._default = default
		self._result = None

	def _fill_core_struct(self, value):
		value.type = FormInputFieldType.IntegerFormField
		value.prompt = self._prompt
		value.hasDefault = self._default is not None
		if self._default is not None:
			value.intDefault = self._default

	def _fill_core_result(self, value):
		value.intResult = self._result

	def _get_result(self, value):
		self._result = value.intResult

	@property
	def prompt(self):
		return self._prompt

	@prompt.setter
	def prompt(self, value):
		self._prompt = value

	@property
	def result(self):
		return self._result

	@result.setter
	def result(self, value):
		self._result = value




[docs]
class AddressField:
	"""
	``AddressField`` prompts the user for an address. By passing the optional view and current_address parameters \
	offsets can be used instead of just an address. The result is stored as in int in self.result.

	.. note:: This API currently functions differently on the command-line, as the view and current_address are \
	disregarded. Additionally where as in the UI the result defaults to hexadecimal on the command-line 0x must be \
	specified.

	"""
	def __init__(self, prompt: str, view: Optional['binaryview.BinaryView'] = None, current_address: int = 0, default: Optional[int] = None):
		self._prompt = prompt
		self._view = view
		self._current_address = current_address
		self._default = default
		self._result = None

	def _fill_core_struct(self, value):
		value.type = FormInputFieldType.AddressFormField
		value.prompt = self._prompt
		value.view = None
		if self._view is not None:
			value.view = self._view.handle
		value.currentAddress = self._current_address
		value.hasDefault = self._default is not None
		if self._default is not None:
			value.addressDefault = self._default

	def _fill_core_result(self, value):
		value.addressResult = self._result

	def _get_result(self, value):
		self._result = value.addressResult

	@property
	def prompt(self):
		"""prompt to be presented to the user"""
		return self._prompt

	@prompt.setter
	def prompt(self, value):
		self._prompt = value

	@property
	def view(self):
		"""BinaryView for the address"""
		return self._view

	@view.setter
	def view(self, value):
		self._view = value

	@property
	def current_address(self):
		"""current address to use as a base for relative calculations"""
		return self._current_address

	@current_address.setter
	def current_address(self, value):
		self._current_address = value

	@property
	def result(self):
		return self._result

	@result.setter
	def result(self, value):
		self._result = value




[docs]
class ChoiceField:
	"""
	``ChoiceField`` prompts the user to choose from the list of strings provided in ``choices``. Result is stored \
	in self.result as an index in to the choices array.

	:attr str prompt: prompt to be presented to the user
	:attr list(str) choices: list of choices to choose from
	"""
	def __init__(self, prompt: str, choices: List[str], default: Optional[str] = None):
		self._prompt = prompt
		self._choices = choices
		self._default = default
		self._result = None

	def _fill_core_struct(self, value):
		value.type = FormInputFieldType.ChoiceFormField
		value.prompt = self._prompt
		choice_buf = (ctypes.c_char_p * len(self._choices))()
		for i in range(0, len(self._choices)):
			choice_buf[i] = self._choices[i].encode('charmap')
		value.choices = choice_buf
		value.count = len(self._choices)
		value.hasDefault = self._default is not None
		if self._default is not None:
			value.indexDefault = self._default

	def _fill_core_result(self, value):
		value.indexResult = self._result

	def _get_result(self, value):
		self._result = value.indexResult

	@property
	def prompt(self):
		return self._prompt

	@prompt.setter
	def prompt(self, value):
		self._prompt = value

	@property
	def choices(self):
		return self._choices

	@choices.setter
	def choices(self, value):
		self._choices = value

	@property
	def result(self):
		return self._result

	@result.setter
	def result(self, value):
		self._result = value




[docs]
class OpenFileNameField:
	"""
	``OpenFileNameField`` prompts the user to specify a file name to open. Result is stored in self.result as a string.
	"""
	def __init__(self, prompt: str, ext: str = "", default: Optional[str] = None):
		self._prompt = prompt
		self._ext = ext
		self._default = default
		self._result = None

	def _fill_core_struct(self, value):
		value.type = FormInputFieldType.OpenFileNameFormField
		value.prompt = self._prompt
		value.ext = self._ext
		value.hasDefault = self._default is not None
		if self._default is not None:
			value.stringDefault = self._default

	def _fill_core_result(self, value):
		value.stringResult = core.BNAllocString(str(self.result))

	def _get_result(self, value):
		self._result = value.stringResult

	@property
	def prompt(self):
		return self._prompt

	@prompt.setter
	def prompt(self, value):
		self._prompt = value

	@property
	def ext(self):
		return self._ext

	@ext.setter
	def ext(self, value):
		self._ext = value

	@property
	def result(self):
		return self._result

	@result.setter
	def result(self, value):
		self._result = value




[docs]
class SaveFileNameField:
	"""
	``SaveFileNameField`` prompts the user to specify a file name to save. Result is stored in self.result as a string.
	"""
	def __init__(self, prompt, ext="", default_name="", default=None):
		self._prompt = prompt
		self._ext = ext
		self._default_name = default_name
		self._default = default
		self._result = None

	def _fill_core_struct(self, value):
		value.type = FormInputFieldType.SaveFileNameFormField
		value.prompt = self._prompt
		value.ext = self._ext
		value.defaultName = self._default_name
		value.hasDefault = self._default is not None
		if self._default is not None:
			value.stringDefault = self._default

	def _fill_core_result(self, value):
		value.stringResult = core.BNAllocString(str(self._result))

	def _get_result(self, value):
		self._result = value.stringResult

	@property
	def prompt(self):
		return self._prompt

	@prompt.setter
	def prompt(self, value):
		self._prompt = value

	@property
	def ext(self):
		return self._ext

	@ext.setter
	def ext(self, value):
		self._ext = value

	@property
	def default_name(self):
		return self._default_name

	@default_name.setter
	def default_name(self, value):
		self._default_name = value

	@property
	def result(self):
		return self._result

	@result.setter
	def result(self, value):
		self._result = value




[docs]
class DirectoryNameField:
	"""
	``DirectoryNameField`` prompts the user to specify a directory name to open. Result is stored in self.result as
	a string.
	"""
	def __init__(self, prompt, default_name="", default=None):
		self._prompt = prompt
		self._default_name = default_name
		self._default = default
		self._result = None

	def _fill_core_struct(self, value):
		value.type = FormInputFieldType.DirectoryNameFormField
		value.prompt = self._prompt
		value.defaultName = self._default_name
		value.hasDefault = self._default is not None
		if self._default is not None:
			value.stringDefault = self._default

	def _fill_core_result(self, value):
		value.stringResult = core.BNAllocString(str(self._result))

	def _get_result(self, value):
		self._result = value.stringResult

	@property
	def prompt(self):
		return self._prompt

	@prompt.setter
	def prompt(self, value):
		self._prompt = value

	@property
	def default_name(self):
		return self._default_name

	@default_name.setter
	def default_name(self, value):
		self._default_name = value

	@property
	def result(self):
		return self._result

	@result.setter
	def result(self, value):
		self._result = value




[docs]
class InteractionHandler:
	_interaction_handler = None

	def __init__(self):
		self._cb = core.BNInteractionHandlerCallbacks()
		self._cb.context = 0
		self._cb.showPlainTextReport = self._cb.showPlainTextReport.__class__(self._show_plain_text_report)
		self._cb.showMarkdownReport = self._cb.showMarkdownReport.__class__(self._show_markdown_report)
		self._cb.showHTMLReport = self._cb.showHTMLReport.__class__(self._show_html_report)
		self._cb.showGraphReport = self._cb.showGraphReport.__class__(self._show_graph_report)
		self._cb.showReportCollection = self._cb.showReportCollection.__class__(self._show_report_collection)
		self._cb.getTextLineInput = self._cb.getTextLineInput.__class__(self._get_text_line_input)
		self._cb.getIntegerInput = self._cb.getIntegerInput.__class__(self._get_int_input)
		self._cb.getAddressInput = self._cb.getAddressInput.__class__(self._get_address_input)
		self._cb.getChoiceInput = self._cb.getChoiceInput.__class__(self._get_choice_input)
		self._cb.getLargeChoiceInput = self._cb.getLargeChoiceInput.__class__(self._get_large_choice_input)
		self._cb.getOpenFileNameInput = self._cb.getOpenFileNameInput.__class__(self._get_open_filename_input)
		self._cb.getSaveFileNameInput = self._cb.getSaveFileNameInput.__class__(self._get_save_filename_input)
		self._cb.getDirectoryNameInput = self._cb.getDirectoryNameInput.__class__(self._get_directory_name_input)
		self._cb.getFormInput = self._cb.getFormInput.__class__(self._get_form_input)
		self._cb.showMessageBox = self._cb.showMessageBox.__class__(self._show_message_box)
		self._cb.openUrl = self._cb.openUrl.__class__(self._open_url)
		self._cb.runProgressDialog = self._cb.runProgressDialog.__class__(self._run_progress_dialog)


[docs]
	def register(self):
		self.__class__._interaction_handler = self
		core.BNRegisterInteractionHandler(self._cb)


	def _show_plain_text_report(self, ctxt, view, title, contents):
		try:
			if view:
				view = binaryview.BinaryView(handle=core.BNNewViewReference(view))
			else:
				view = None
			self.show_plain_text_report(view, title, contents)
		except:
			log_error(traceback.format_exc())

	def _show_markdown_report(self, ctxt, view, title, contents, plaintext):
		try:
			if view:
				view = binaryview.BinaryView(handle=core.BNNewViewReference(view))
			else:
				view = None
			self.show_markdown_report(view, title, contents, plaintext)
		except:
			log_error(traceback.format_exc())

	def _show_html_report(self, ctxt, view, title, contents, plaintext):
		try:
			if view:
				view = binaryview.BinaryView(handle=core.BNNewViewReference(view))
			else:
				view = None
			self.show_html_report(view, title, contents, plaintext)
		except:
			log_error(traceback.format_exc())

	def _show_graph_report(self, ctxt, view, title, graph):
		try:
			if view:
				view = binaryview.BinaryView(handle=core.BNNewViewReference(view))
			else:
				view = None
			self.show_graph_report(view, title, flowgraph.CoreFlowGraph(core.BNNewFlowGraphReference(graph)))
		except:
			log_error(traceback.format_exc())

	def _show_report_collection(self, ctxt, title, reports):
		try:
			self.show_report_collection(title, ReportCollection(core.BNNewReportCollectionReference(reports)))
		except:
			log_error(traceback.format_exc())

	def _get_text_line_input(self, ctxt, result, prompt, title):
		try:
			value = self.get_text_line_input(prompt, title)
			if value is None:
				return False
			result[0] = core.BNAllocString(str(value))
			return True
		except:
			log_error(traceback.format_exc())

	def _get_int_input(self, ctxt, result, prompt, title):
		try:
			value = self.get_int_input(prompt, title)
			if value is None:
				return False
			result[0] = value
			return True
		except:
			log_error(traceback.format_exc())

	def _get_address_input(self, ctxt, result, prompt, title, view, current_address):
		try:
			if view:
				view = binaryview.BinaryView(handle=core.BNNewViewReference(view))
			else:
				view = None
			value = self.get_address_input(prompt, title, view, current_address)
			if value is None:
				return False
			result[0] = value
			return True
		except:
			log_error(traceback.format_exc())

	def _get_choice_input(self, ctxt, result, prompt, title, choice_buf, count):
		try:
			choices = []
			for i in range(0, count):
				choices.append(choice_buf[i])
			value = self.get_choice_input(prompt, title, choices)
			if value is None:
				return False
			result[0] = value
			return True
		except:
			log_error(traceback.format_exc())

	def _get_large_choice_input(self, ctxt, result, prompt, title, choice_buf, count):
		try:
			choices = []
			for i in range(0, count):
				choices.append(choice_buf[i])
			value = self.get_large_choice_input(prompt, title, choices)
			if value is None:
				return False
			result[0] = value
			return True
		except:
			log_error(traceback.format_exc())

	def _get_open_filename_input(self, ctxt, result, prompt, ext):
		try:
			value = self.get_open_filename_input(prompt, ext)
			if value is None:
				return False
			result[0] = core.BNAllocString(str(value))
			return True
		except:
			log_error(traceback.format_exc())

	def _get_save_filename_input(self, ctxt, result, prompt, ext, default_name):
		try:
			value = self.get_save_filename_input(prompt, ext, default_name)
			if value is None:
				return False
			result[0] = core.BNAllocString(str(value))
			return True
		except:
			log_error(traceback.format_exc())

	def _get_directory_name_input(self, ctxt, result, prompt, default_name):
		try:
			value = self.get_directory_name_input(prompt, default_name)
			if value is None:
				return False
			result[0] = core.BNAllocString(str(value))
			return True
		except:
			log_error(traceback.format_exc())

	def _get_form_input(self, ctxt, fields, count, title):
		try:
			field_objs = []
			for i in range(0, count):
				if fields[i].type == FormInputFieldType.LabelFormField:
					field_objs.append(LabelField(fields[i].prompt))
				elif fields[i].type == FormInputFieldType.SeparatorFormField:
					field_objs.append(SeparatorField())
				elif fields[i].type == FormInputFieldType.TextLineFormField:
					field_objs.append(
					    TextLineField(
					        fields[i].prompt, default=fields[i].stringDefault if fields[i].hasDefault else None
					    )
					)
				elif fields[i].type == FormInputFieldType.MultilineTextFormField:
					field_objs.append(
					    MultilineTextField(
					        fields[i].prompt, default=fields[i].stringDefault if fields[i].hasDefault else None
					    )
					)
				elif fields[i].type == FormInputFieldType.IntegerFormField:
					field_objs.append(
					    IntegerField(fields[i].prompt, default=fields[i].intDefault if fields[i].hasDefault else None)
					)
				elif fields[i].type == FormInputFieldType.AddressFormField:
					view = None
					if fields[i].view:
						view = binaryview.BinaryView(handle=core.BNNewViewReference(fields[i].view))
					field_objs.append(
					    AddressField(
					        fields[i].prompt, view, fields[i].currentAddress,
					        default=fields[i].addressDefault if fields[i].hasDefault else None
					    )
					)
				elif fields[i].type == FormInputFieldType.ChoiceFormField:
					choices = []
					for j in range(0, fields[i].count):
						choices.append(fields[i].choices[j])
					field_objs.append(
					    ChoiceField(
					        fields[i].prompt, choices, default=fields[i].choiceDefault if fields[i].hasDefault else None
					    )
					)
				elif fields[i].type == FormInputFieldType.OpenFileNameFormField:
					field_objs.append(
					    OpenFileNameField(
					        fields[i].prompt, fields[i].ext,
					        default=fields[i].stringDefault if fields[i].hasDefault else None
					    )
					)
				elif fields[i].type == FormInputFieldType.SaveFileNameFormField:
					field_objs.append(
					    SaveFileNameField(
					        fields[i].prompt, fields[i].ext, fields[i].defaultName,
					        default=fields[i].stringDefault if fields[i].hasDefault else None
					    )
					)
				elif fields[i].type == FormInputFieldType.DirectoryNameFormField:
					field_objs.append(
					    DirectoryNameField(
					        fields[i].prompt, fields[i].defaultName,
					        default=fields[i].stringDefault if fields[i].hasDefault else None
					    )
					)
				else:
					field_objs.append(LabelField(fields[i].prompt))
			if not self.get_form_input(field_objs, title):
				return False
			for i in range(0, count):
				field_objs[i]._fill_core_result(fields[i])
			return True
		except:
			log_error(traceback.format_exc())

	def _show_message_box(self, ctxt, title, text, buttons, icon):
		try:
			return self.show_message_box(title, text, buttons, icon)
		except:
			log_error(traceback.format_exc())

	def _open_url(self, ctxt, url):
		try:
			return self.open_url(url)
		except:
			log_error(traceback.format_exc())
			return False

	def _run_progress_dialog(self, title, can_cancel, task, task_ctxt):
		try:
			def py_task(progress: Callable[[int, int], bool]):
				progress_c = ctypes.CFUNCTYPE(ctypes.c_bool, ctypes.c_void_p, ctypes.c_size_t, ctypes.c_size_t, lambda ctxt, cur, max: progress(cur, max))
				task(task_ctxt, progress_c, None)

			return self.run_progress_dialog(title, can_cancel, py_task)
		except:
			log_error(traceback.format_exc())
			return False


[docs]
	def show_plain_text_report(self, view, title, contents):
		pass



[docs]
	def show_markdown_report(self, view, title, contents, plaintext):
		self.show_html_report(view, title, markdown_to_html(contents), plaintext)



[docs]
	def show_html_report(self, view, title, contents, plaintext):
		if len(plaintext) != 0:
			self.show_plain_text_report(view, title, plaintext)



[docs]
	def show_graph_report(self, view, title, graph):
		pass



[docs]
	def show_report_collection(self, title, reports):
		pass



[docs]
	def get_text_line_input(self, prompt, title):
		return NotImplemented



[docs]
	def get_int_input(self, prompt, title):
		while True:
			text = self.get_text_line_input(prompt, title)
			if len(text) == 0:
				return False
			try:
				return int(text)
			except:
				continue



[docs]
	def get_address_input(self, prompt, title, view, current_address):
		return get_int_input(prompt, title)



[docs]
	def get_choice_input(self, prompt, title, choices):
		return NotImplemented



[docs]
	def get_large_choice_input(self, prompt, title, choices):
		return NotImplemented



[docs]
	def get_open_filename_input(self, prompt, ext):
		return get_text_line_input(prompt, "Open File")



[docs]
	def get_save_filename_input(self, prompt, ext, default_name):
		return get_text_line_input(prompt, "Save File")



[docs]
	def get_directory_name_input(self, prompt, default_name):
		return get_text_line_input(prompt, "Select Directory")



[docs]
	def get_form_input(self, fields, title):
		return False



[docs]
	def show_message_box(self, title, text, buttons, icon):
		return MessageBoxButtonResult.CancelButton



[docs]
	def open_url(self, url):
		webbrowser.open(url)
		return True



[docs]
	def run_progress_dialog(self, task: Callable[[Callable[[int, int], bool]], None]) -> bool:
		mainthread.execute_on_main_thread_and_wait(lambda: task(lambda cur, max: True))
		return True





[docs]
class PlainTextReport:
	def __init__(self, title, contents, view=None):
		self._view = view
		self._title = title
		self._contents = contents

	def __repr__(self):
		return "<plaintext report: %s>" % self._title

	def __str__(self):
		return self._contents

	@property
	def view(self):
		return self._view

	@view.setter
	def view(self, value):
		self._view = value

	@property
	def title(self):
		return self._title

	@title.setter
	def title(self, value):
		self._title = value

	@property
	def contents(self):
		return self._contents

	@contents.setter
	def contents(self, value):
		self._contents = value




[docs]
class MarkdownReport:
	def __init__(self, title, contents, plaintext="", view=None):
		self._view = view
		self._title = title
		self._contents = contents
		self._plaintext = plaintext

	def __repr__(self):
		return "<markdown report: %s>" % self._title

	def __str__(self):
		return self._contents

	@property
	def view(self):
		return self._view

	@view.setter
	def view(self, value):
		self._view = value

	@property
	def title(self):
		return self._title

	@title.setter
	def title(self, value):
		self._title = value

	@property
	def contents(self):
		return self._contents

	@contents.setter
	def contents(self, value):
		self._contents = value

	@property
	def plaintext(self):
		return self._plaintext

	@plaintext.setter
	def plaintext(self, value):
		self._plaintext = value




[docs]
class HTMLReport:
	def __init__(self, title, contents, plaintext="", view=None):
		self._view = view
		self._title = title
		self._contents = contents
		self._plaintext = plaintext

	def __repr__(self):
		return "<html report: %s>" % self._title

	def __str__(self):
		return self._contents

	@property
	def view(self):
		return self._view

	@view.setter
	def view(self, value):
		self._view = value

	@property
	def title(self):
		return self._title

	@title.setter
	def title(self, value):
		self._title = value

	@property
	def contents(self):
		return self._contents

	@contents.setter
	def contents(self, value):
		self._contents = value

	@property
	def plaintext(self):
		return self._plaintext

	@plaintext.setter
	def plaintext(self, value):
		self._plaintext = value




[docs]
class FlowGraphReport:
	def __init__(self, title, graph, view=None):
		self._view = view
		self._title = title
		self._graph = graph

	def __repr__(self):
		return "<graph report: %s>" % self._title

	@property
	def view(self):
		return self._view

	@view.setter
	def view(self, value):
		self._view = value

	@property
	def title(self):
		return self._title

	@title.setter
	def title(self, value):
		self._title = value

	@property
	def graph(self):
		return self._graph

	@graph.setter
	def graph(self, value):
		self._graph = value




[docs]
class ReportCollection:
	def __init__(self, handle=None):
		if handle is None:
			self.handle = core.BNCreateReportCollection()
		else:
			self.handle = handle

	def __len__(self):
		return core.BNGetReportCollectionCount(self.handle)

	def _report_from_index(self, i):
		report_type = core.BNGetReportType(self.handle, i)
		title = core.BNGetReportTitle(self.handle, i)
		view = core.BNGetReportView(self.handle, i)
		if view:
			view = binaryview.BinaryView(handle=view)
		else:
			view = None
		if report_type == ReportType.PlainTextReportType:
			contents = core.BNGetReportContents(self.handle, i)
			return PlainTextReport(title, contents, view)
		elif report_type == ReportType.MarkdownReportType:
			contents = core.BNGetReportContents(self.handle, i)
			plaintext = core.BNGetReportPlainText(self.handle, i)
			return MarkdownReport(title, contents, plaintext, view)
		elif report_type == ReportType.HTMLReportType:
			contents = core.BNGetReportContents(self.handle, i)
			plaintext = core.BNGetReportPlainText(self.handle, i)
			return HTMLReport(title, contents, plaintext, view)
		elif report_type == ReportType.FlowGraphReportType:
			graph = flowgraph.CoreFlowGraph(core.BNGetReportFlowGraph(self.handle, i))
			return FlowGraphReport(title, graph, view)
		raise TypeError("invalid report type %s" % repr(report_type))

	def __getitem__(self, i):
		if isinstance(i, slice) or isinstance(i, tuple):
			raise IndexError("expected integer report index")
		if (i < 0) or (i >= len(self)):
			raise IndexError("index out of range")
		return self._report_from_index(i)

	def __iter__(self):
		count = len(self)
		for i in range(0, count):
			yield self._report_from_index(i)

	def __repr__(self):
		return "<reports: %s>" % repr(list(self))


[docs]
	def append(self, report):
		if report.view is None:
			view = None
		else:
			view = report.view.handle
		if isinstance(report, PlainTextReport):
			core.BNAddPlainTextReportToCollection(self.handle, view, report.title, report.contents)
		elif isinstance(report, MarkdownReport):
			core.BNAddMarkdownReportToCollection(self.handle, view, report.title, report.contents, report.plaintext)
		elif isinstance(report, HTMLReport):
			core.BNAddHTMLReportToCollection(self.handle, view, report.title, report.contents, report.plaintext)
		elif isinstance(report, FlowGraphReport):
			core.BNAddGraphReportToCollection(self.handle, view, report.title, report.graph.handle)
		else:
			raise TypeError("expected report object")



[docs]
	def update(self, i, report):
		# if isinstance(report, PlainTextReport):
		# 	core.BNUpdatePlainTextReportToCollection(self.handle, i, report.contents)
		# elif isinstance(report, MarkdownReport):
		# 	core.BNUpdateMarkdownReportToCollection(self.handle, i, report.contents, report.plaintext)
		# elif isinstance(report, HTMLReport):
		# 	core.BNUpdateHTMLReportToCollection(self.handle, i, report.contents, report.plaintext)
		if isinstance(report, FlowGraphReport):
			core.BNUpdateReportFlowGraph(self.handle, i, report.graph.handle)
		else:
			raise TypeError("expected report object")





[docs]
def markdown_to_html(contents):
	"""
	``markdown_to_html`` converts the provided markdown to HTML

	:param str contents: Markdown contents to convert to HTML
	:rtype: str
	:Example:
		>>> markdown_to_html("##Yay")
		'<h2>Yay</h2>'
	"""
	return core.BNMarkdownToHTML(contents)




[docs]
def show_plain_text_report(title, contents):
	"""
	``show_plain_text_report`` displays contents to the user in the UI or on the command-line

	.. note:: This API functions differently on the command-line vs the UI. In the UI, a pop-up is used. On the command-line, \
	a simple text prompt is used.

	:param str title: Title to display in the tab
	:param str contents: Plaintext contents to display
	:rtype: None
	:Example:
		>>> show_plain_text_report("title", "contents")
		contents
	"""
	core.BNShowPlainTextReport(None, title, contents)




[docs]
def show_markdown_report(title, contents, plaintext=""):
	"""
	``show_markdown_report`` displays the markdown contents in UI applications and plaintext in command-line \
	applications. This API doesn't support hyperlinking into the BinaryView, use the \
	:py:meth:`BinaryView.show_markdown_report` API if hyperlinking is needed.

	.. note:: This API function differently on the command-line vs the UI. In the UI a pop-up is used. On the command-line \
	a simple text prompt is used.

	:param str title: title to display in the tab
	:param str contents: markdown contents to display
	:param str plaintext: Plain text version to display (used on the command-line)
	:rtype: None
	:Example:
		>>> show_markdown_report("title", "##Contents", "Plain text contents")
		Plain text contents
	"""
	core.BNShowMarkdownReport(None, title, contents, plaintext)




[docs]
def show_html_report(title, contents, plaintext=""):
	"""
	``show_html_report`` displays the HTML contents in UI applications and plaintext in command-line \
	applications. This API doesn't support hyperlinking into the BinaryView, use the :py:meth:`BinaryView.show_html_report` \
	API if hyperlinking is needed.

	:param str title: Title to display in the tab
	:param str contents: HTML contents to display
	:param str plaintext: Plain text version to display (used on the command-line)
	:rtype: None
	:Example:
		>>> show_html_report("title", "<h1>Contents</h1>", "Plain text contents")
		Plain text contents
	"""
	core.BNShowHTMLReport(None, title, contents, plaintext)




[docs]
def show_graph_report(title, graph):
	"""
	``show_graph_report`` displays a flow graph in UI applications and nothing in command-line applications. \
	This API doesn't support clickable references into an existing BinaryView. Use the :py:meth:`BinaryView.show_html_report` \
	API if hyperlinking is needed.

	.. note:: This API function will have no effect outside the UI.

	:param str title: Title to display in the tab
	:param FlowGraph graph: Flow graph to display
	:rtype: None
	"""
	func = graph.function
	if func is None:
		core.BNShowGraphReport(None, title, graph.handle)
	else:
		core.BNShowGraphReport(func.view.handle, title, graph.handle)




[docs]
def show_report_collection(title, reports):
	"""
	``show_report_collection`` displays multiple reports in UI applications

	.. note:: This API function will have no effect outside the UI.

	:param ReportCollection reports: Reports to display
	:rtype: None
	"""
	core.BNShowReportCollection(title, reports.handle)




[docs]
def get_text_line_input(prompt, title):
	"""
	``get_text_line_input`` prompts the user to input a string with the given prompt and title

	.. note:: This API function differently on the command-line vs the UI. In the UI a pop-up is used. On the command-line \
	a simple text prompt is used.

	:param str prompt: String to prompt with
	:param str title: Title of the window when executed in the UI
	:rtype: str containing the input without trailing newline character
	:Example:
		>>> get_text_line_input("PROMPT>", "getinfo")
		PROMPT> Input!
		'Input!'
	"""
	value = ctypes.c_char_p()
	if not core.BNGetTextLineInput(value, prompt, title):
		return None
	result = value.value
	core.free_string(value)
	return result




[docs]
def get_int_input(prompt, title):
	"""
	``get_int_input`` prompts the user to input a integer with the given prompt and title

	.. note:: This API function differently on the command-line vs the UI. In the UI a pop-up is used. On the command-line \
	a simple text prompt is used.

	:param str prompt: String to prompt with
	:param str title: Title of the window when executed in the UI
	:rtype: integer value input by the user
	:Example:
		>>> get_int_input("PROMPT>", "getinfo")
		PROMPT> 10
		10
	"""
	value = ctypes.c_longlong()
	if not core.BNGetIntegerInput(value, prompt, title):
		return None
	return value.value




[docs]
def get_address_input(prompt, title):
	"""
	``get_address_input`` prompts the user for an address with the given prompt and title

	.. note:: This API function differently on the command-line vs the UI. In the UI a pop-up is used. On the command-line \
	a simple text prompt is used.

	:param str prompt: String to prompt with.
	:param str title: Title of the window when executed in the UI.
	:rtype: integer value input by the user.
	:Example:
		>>> get_address_input("PROMPT>", "getinfo")
		PROMPT> 10
		10L
	"""
	value = ctypes.c_ulonglong()
	if not core.BNGetAddressInput(value, prompt, title, None, 0):
		return None
	return value.value




[docs]
def get_choice_input(prompt, title, choices):
	"""
	``get_choice_input`` prompts the user to select the one of the provided choices

	.. note:: This API function differently on the command-line vs the UI. In the UI a pop-up is used. On the command-line \
	a simple text prompt is used. The UI uses a combo box.

	:param str prompt: String to prompt with.
	:param str title: Title of the window when executed in the UI.
	:param choices: A list of strings for the user to choose from.
	:type choices: list(str)
	:rtype: integer array index of the selected option
	:Example:
		>>> get_choice_input("PROMPT>", "choices", ["Yes", "No", "Maybe"])
		choices
		1) Yes
		2) No
		3) Maybe
		PROMPT> 1
		0L
	"""
	choice_buf = (ctypes.c_char_p * len(choices))()
	for i in range(0, len(choices)):
		choice_buf[i] = str(choices[i]).encode('charmap')
	value = ctypes.c_ulonglong()
	if not core.BNGetChoiceInput(value, prompt, title, choice_buf, len(choices)):
		return None
	return value.value




[docs]
def get_large_choice_input(prompt, title, choices):
	"""
	``get_large_choice_input`` prompts the user to select the one of the provided choices from a large pool

	.. note:: This API function differently on the command-line vs the UI. In the UI a pop-up is used. On the command-line \
	a text prompt is used. The UI uses a filterable list of entries

	:param str prompt: Text for the button when executed in the UI. Prompt shown for selection headless.
	:param str title: Title of the window when executed in the UI.
	:param choices: A list of strings for the user to choose from.
	:type choices: list(str)
	:rtype: integer array index of the selected option
	:Example:
		>>> get_large_choice_input("Select Function", "Select a Function", [f.symbol.short_name for f in bv.functions])
	"""
	choice_buf = (ctypes.c_char_p * len(choices))()
	for i in range(0, len(choices)):
		choice_buf[i] = str(choices[i]).encode('charmap')
	value = ctypes.c_ulonglong()
	if not core.BNGetLargeChoiceInput(value, prompt, title, choice_buf, len(choices)):
		return None
	return value.value




[docs]
def get_open_filename_input(prompt: str, ext: str = "") -> Optional[str]:
	"""
	``get_open_filename_input`` prompts the user for a file name to open

	.. note:: This API functions differently on the command-line vs the UI. In the UI a pop-up is used. On the command-line \
	a simple text prompt is used. The UI uses the native window pop-up for file selection.

	Multiple file selection groups can be included if separated by two semicolons. Multiple file wildcards may be specified by using a space within the parenthesis.

	Also, a simple selector of `*.extension` by itself may also be used instead of specifying the description.

	:param str prompt: Prompt to display.
	:param str ext: Optional, file extension
	:Example:
		>>> get_open_filename_input("filename:", "Executables (*.exe *.com);;Python Files (*.py);;All Files (*)")
		'foo.exe'
		>>> get_open_filename_input("filename:", "*.py")
		'test.py'
	"""
	value = ctypes.c_char_p()
	if not core.BNGetOpenFileNameInput(value, prompt, ext):
		return None
	result = value.value
	assert result is not None
	core.free_string(value)
	return result.decode("utf-8")




[docs]
def get_save_filename_input(prompt: str, ext: str = "", default_name: str = "") -> Optional[str]:
	"""
	``get_save_filename_input`` prompts the user for a file name to save as, optionally providing a file extension and \
	default_name

	.. note:: This API function differently on the command-line vs the UI. In the UI a pop-up is used. On the command-line \
	a simple text prompt is used. The UI uses the native window pop-up for file selection.

	:param str prompt: Prompt to display.
	:param str ext: Optional, file extension
	:param str default_name: Optional, default file name.
	:Example:
		>>> get_save_filename_input("filename:", "exe", "foo.exe")
		filename: foo.exe
		'foo.exe'
	"""
	value = ctypes.c_char_p()
	if not core.BNGetSaveFileNameInput(value, prompt, ext, default_name):
		return None
	result = value.value
	assert result is not None
	core.free_string(value)
	return result.decode("utf-8")




[docs]
def get_directory_name_input(prompt: str, default_name: str = ""):
	"""
	``get_directory_name_input`` prompts the user for a directory name to save as, optionally providing a default_name

	.. note:: This API function differently on the command-line vs the UI. In the UI a pop-up is used. On the command-line a simple text prompt is used. The UI uses the native window pop-up for file selection.

	:param str prompt: Prompt to display.
	:param str default_name: Optional, default directory name.
	:rtype: str
	:Example:
		>>> get_directory_name_input("prompt")
		prompt dirname
		'dirname'
	"""
	value = ctypes.c_char_p()
	if not core.BNGetDirectoryNameInput(value, prompt, default_name):
		return None
	result = value.value
	assert result is not None
	core.free_string(value)
	return result.decode("utf-8")




[docs]
def get_form_input(fields, title):
	"""
	``get_from_input`` Prompts the user for a set of inputs specified in ``fields`` with given title. \
	The fields parameter is a list which can contain the following types:

	===================== ===================================================
	FieldType             Description
	===================== ===================================================
	str                   an alias for LabelField
	None                  an alias for SeparatorField
	LabelField            Text output
	SeparatorField        Vertical spacing
	TextLineField         Prompt for a string value
	MultilineTextField    Prompt for multi-line string value
	IntegerField          Prompt for an integer
	AddressField          Prompt for an address
	ChoiceField           Prompt for a choice from provided options
	OpenFileNameField     Prompt for file to open
	SaveFileNameField     Prompt for file to save to
	DirectoryNameField    Prompt for directory name
	===================== ===================================================

	This API is flexible and works both in the UI via a pop-up dialog and on the command-line.

	.. note:: More complicated APIs should consider using the included pyside2 functionality in the `binaryninjaui` module. Returns true or false depending on whether the user submitted responses or cancelled the dialog.

	:param fields: A list containing these classes, strings or None
	:type fields: list(str) or list(None) or list(LabelField) or list(SeparatorField) or list(TextLineField) or list(MultilineTextField) or list(IntegerField) or list(AddressField) or list(ChoiceField) or list(OpenFileNameField) or list(SaveFileNameField) or list(DirectoryNameField)
	:param str title: The title of the pop-up dialog
	:rtype: bool
	:Example:

		>>> int_f = IntegerField("Specify Integer")
		>>> tex_f = TextLineField("Specify name")
		>>> choice_f = ChoiceField("Options", ["Yes", "No", "Maybe"])
		>>> get_form_input(["Get Data", None, int_f, tex_f, choice_f], "The options")
		Get Data
		<empty>
		Specify Integer 1337
		Specify name Peter
		The options
		1) Yes
		2) No
		3) Maybe
		Options 1
		>>> True
		>>> print(tex_f.result, int_f.result, choice_f.result)
		Peter 1337 0
	"""
	value = (core.BNFormInputField * len(fields))()
	for i in range(0, len(fields)):
		if isinstance(fields[i], str):
			LabelField(fields[i])._fill_core_struct(value[i])
		elif fields[i] is None:
			SeparatorField()._fill_core_struct(value[i])
		else:
			fields[i]._fill_core_struct(value[i])
	if not core.BNGetFormInput(value, len(fields), title):
		return False
	for i in range(0, len(fields)):
		if not (isinstance(fields[i], str) or (fields[i] is None)):
			fields[i]._get_result(value[i])
	core.BNFreeFormInputResults(value, len(fields))
	return True




[docs]
def show_message_box(title, text, buttons=MessageBoxButtonSet.OKButtonSet, icon=MessageBoxIcon.InformationIcon):
	"""
	``show_message_box`` Displays a configurable message box in the UI, or prompts on the console as appropriate

	:param str title: Text title for the message box.
	:param str text: Text for the main body of the message box.
	:param MessageBoxButtonSet buttons: One of :py:class:`MessageBoxButtonSet`
	:param MessageBoxIcon icon: One of :py:class:`MessageBoxIcon`
	:return: Which button was selected
	:rtype: MessageBoxButtonResult
	"""
	return core.BNShowMessageBox(title, text, buttons, icon)




[docs]
def open_url(url):
	"""
	``open_url`` Opens a given url in the user's web browser, if available.

	:param str url: Url to open
	:return: True if successful
	:rtype: bool
	"""
	return core.BNOpenUrl(url)




[docs]
def run_progress_dialog(title: str, can_cancel: bool, task: Callable[[Callable[[int, int], bool]], None]) -> bool:
	"""
	``run_progress_dialog`` runs a given task in a background thread, showing an updating
	progress bar which the user can cancel.

	:param title: Dialog title
	:param can_cancel: If the task can be cancelled
	:param task: Function to perform the task, taking as a parameter a function which should be called to report progress updates and check for cancellation. If the progress function returns false, the user has requested to cancel, and the task should handle this appropriately.
	:return: True if not cancelled
	"""

	progress_type = ctypes.CFUNCTYPE(ctypes.c_bool, ctypes.c_void_p, ctypes.c_size_t, ctypes.c_size_t)
	task_type = ctypes.CFUNCTYPE(None, ctypes.c_void_p, progress_type, ctypes.c_void_p)

	def do_task(ctxt: ctypes.c_void_p, progress: progress_type, progress_ctxt: ctypes.c_void_p):
		def py_progress(cur: int, max: int) -> bool:
			return progress(progress_ctxt, cur, max)
		task(py_progress)

	return core.BNRunProgressDialog(title, can_cancel, task_type(do_task), None)