Type Containers: API Docs

1 files changed, 109 insertions, 2 deletions

diff --git a/python/typecontainer.py b/python/typecontainer.py
index 3f371213..b25a69f7 100644
--- a/python/typecontainer.py
+++ b/python/typecontainer.py
@@ -34,7 +34,15 @@ ProgressFuncType = Callable[[int, int], bool]
 
 
 class TypeContainer:
+	"""
+	A ``TypeContainer`` is a generic interface to access various Binary Ninja models
+	that contain types. Types are stored with both a unique id and a unique name.
+	"""
 	def __init__(self, handle: core.BNTypeContainerHandle):
+		"""
+		Construct a Type Container, internal use only
+		:param handle: Handle pointer
+		"""
 		binaryninja._init_plugins()
 		self.handle: core.BNTypeContainerHandle = core.handle_of_type(handle, core.BNTypeContainer)
 
@@ -47,27 +55,62 @@ class TypeContainer:
 
 	@property
 	def id(self) -> str:
+		"""
+		Get an id string for the Type Container. This will be unique within a given
+		analysis session, but may not be globally unique.
+		:return: Identifier string
+		"""
 		return core.BNTypeContainerGetId(self.handle)
 
 	@property
 	def name(self) -> str:
+		"""
+		Get a user-friendly name for the Type Container.
+		:return: Display name
+		"""
 		return core.BNTypeContainerGetName(self.handle)
 
 	@property
 	def container_type(self) -> 'enums.TypeContainerType':
+		"""
+		Get the type of underlying model the Type Container is accessing.
+		:return: Container type enum
+		"""
 		return core.BNTypeContainerGetType(self.handle)
 
 	@property
 	def mutable(self) -> bool:
+		"""
+		Test if the Type Container supports mutable operations (add, rename, delete)
+		:return: True if mutable
+		"""
 		return core.BNTypeContainerIsMutable(self.handle)
 
 	@property
 	def platform(self) -> 'platform.Platform':
+		"""
+		Get the Platform object associated with this Type Container. All Type Containers
+		have exactly one associated Platform (as opposed to, e.g. Type Libraries).
+		:return: Associated Platform object
+		"""
 		handle = core.BNTypeContainerGetPlatform(self.handle)
 		assert handle is not None
 		return platform.Platform(handle=handle)
 
 	def add_types(self, types: Mapping['ty_.QualifiedNameType', 'ty_.Type'], progress_func: Optional[ProgressFuncType] = None) -> Optional[Mapping['ty_.QualifiedName', str]]:
+		"""
+		Add or update types to a Type Container. If the Type Container already contains
+		a type with the same name as a type being added, the existing type will be
+		replaced with the definition given to this function, and references will be
+		updated in the source model.
+
+		An optional progress callback is included because adding many types can be a slow operation.
+
+		:param types: Dict from name -> definition of new types to add
+		:param progress_func: Optional function to call for progress updates
+		:return: Dict from name -> id of type in Type Container for all added types if successful,
+		         None otherwise.
+		"""
 		api_names = (core.BNQualifiedName * len(types))()
 		api_types = (ctypes.POINTER(core.BNType) * len(types))()
 		for (i, (key, value)) in enumerate(types.items()):
@@ -101,18 +144,43 @@ class TypeContainer:
 		return result
 
 	def rename_type(self, type_id: str, new_name: 'ty_.QualifiedNameType') -> bool:
+		"""
+		Rename a type in the Type Container. All references to this type will be updated
+		(by id) to use the new name.
+		:param type_id: Id of type to update
+		:param new_name: New name for the type
+		:return: True if successful
+		"""
 		return core.BNTypeContainerRenameType(self.handle, type_id, ty_.QualifiedName(new_name)._to_core_struct())
 
 	def delete_type(self, type_id: str) -> bool:
+		"""
+		Delete a type in the Type Container. Behavior of references to this type is
+		not specified and you may end up with broken references if any still exist.
+		:param type_id: Id of type to delete
+		:return: True if successful
+		"""
 		return core.BNTypeContainerDeleteType(self.handle, type_id)
 
 	def get_type_id(self, type_name: 'ty_.QualifiedNameType') -> Optional[str]:
+		"""
+		Get the unique id of the type in the Type Container with the given name.
+		If no type with that name exists, returns None.
+		:param type_name: Name of type
+		:return: Type id, if exists, else, None
+		"""
 		result = ctypes.c_char_p()
 		if not core.BNTypeContainerGetTypeId(self.handle, ty_.QualifiedName(type_name)._to_core_struct(), result):
 			return None
 		return core.pyNativeStr(result.value)
 
 	def get_type_name(self, type_id: str) -> Optional['ty_.QualifiedName']:
+		"""
+		Get the unique name of the type in the Type Container with the given id.
+		If no type with that id exists, returns None.
+		:param type_id: Id of type
+		:return: Type name, if exists, else, None
+		"""
 		api_result = core.BNQualifiedName()
 		if not core.BNTypeContainerGetTypeName(self.handle, type_id, api_result):
 			return None
@@ -121,6 +189,12 @@ class TypeContainer:
 		return result
 
 	def get_type_by_id(self, type_id: str) -> Optional['ty_.Type']:
+		"""
+		Get the definition of the type in the Type Container with the given id.
+		If no type with that id exists, returns None.
+		:param type_id: Id of type
+		:return: Type object, if exists, else, None
+		"""
 		result = ctypes.POINTER(core.BNType)()
 		if not core.BNTypeContainerGetTypeById(self.handle, type_id, result):
 			return None
@@ -128,6 +202,10 @@ class TypeContainer:
 
 	@property
 	def types(self) -> Optional[Mapping[str, Tuple['ty_.QualifiedName', 'ty_.Type']]]:
+		"""
+		Get a mapping of all types in a Type Container.
+		:return: All types in a dict of type id -> (type name, type definition)
+		"""
 		result_names = ctypes.POINTER(core.BNQualifiedName)()
 		result_ids = ctypes.POINTER(ctypes.c_char_p)()
 		result_types = ctypes.POINTER(ctypes.POINTER(core.BNType))()
@@ -149,6 +227,12 @@ class TypeContainer:
 		return result
 
 	def get_type_by_name(self, type_name: 'ty_.QualifiedNameType') -> Optional['ty_.Type']:
+		"""
+		Get the definition of the type in the Type Container with the given name.
+		If no type with that name exists, returns None.
+		:param type_name: Name of type
+		:return: Type object, if exists, else, None
+		"""
 		result = ctypes.POINTER(core.BNType)()
 		if not core.BNTypeContainerGetTypeByName(self.handle, ty_.QualifiedName(type_name)._to_core_struct(), result):
 			return None
@@ -156,6 +240,10 @@ class TypeContainer:
 
 	@property
 	def type_ids(self) -> Optional[List[str]]:
+		"""
+		Get all type ids in a Type Container.
+		:return: List of all type ids
+		"""
 		result_ids = ctypes.POINTER(ctypes.c_char_p)()
 		result_count = ctypes.c_size_t(0)
 		if not core.BNTypeContainerGetTypeIds(self.handle, result_ids, result_count):
@@ -171,6 +259,10 @@ class TypeContainer:
 
 	@property
 	def type_names(self) -> Optional[List['ty_.QualifiedName']]:
+		"""
+		Get all type names in a Type Container.
+		:return: List of all type names
+		"""
 		result_names = ctypes.POINTER(core.BNQualifiedName)()
 		result_count = ctypes.c_size_t(0)
 		if not core.BNTypeContainerGetTypeNames(self.handle, result_names, result_count):
@@ -186,6 +278,10 @@ class TypeContainer:
 
 	@property
 	def type_names_and_ids(self) -> Optional[Mapping[str, 'ty_.QualifiedName']]:
+		"""
+		Get a mapping of all type ids and type names in a Type Container.
+		:return: Dict of type id -> type name
+		"""
 		result_names = ctypes.POINTER(core.BNQualifiedName)()
 		result_ids = ctypes.POINTER(ctypes.c_char_p)()
 		result_count = ctypes.c_size_t(0)
@@ -202,10 +298,21 @@ class TypeContainer:
 		core.BNFreeStringList(result_ids, result_count.value)
 		return result
 
-	def parse_types_from_source(self, source: str, file_name: str, platform: 'platform.Platform',
+	def parse_types_from_source(self, source: str, file_name: str,
 			options: Optional[List[str]] = None, include_dirs: Optional[List[str]] = None,
 			auto_type_source: str = ""
 	) -> Tuple[Optional['typeparser.TypeParserResult'], List['typeparser.TypeParserError']]:
+		"""
+		Parse an entire block of source into types, variables, and functions, with
+		knowledge of the types in the Type Container.
+
+		:param source: Source code to parse
+		:param file_name: Name of the file containing the source (optional: exists on disk)
+		:param options: Optional string arguments to pass as options, e.g. command line arguments
+		:param include_dirs: Optional list of directories to include in the header search path
+		:param auto_type_source: Optional source of types if used for automatically generated types
+		:return: A tuple of (result, errors) where the result is None if there was a fatal error
+		"""
 		if options is None:
 			options = []
 		if include_dirs is None:
@@ -224,7 +331,7 @@ class TypeContainer:
 		error_count = ctypes.c_size_t()
 
 		success = core.BNTypeContainerParseTypesFromSource(
-			self.handle, source, file_name, platform.handle,
+			self.handle, source, file_name,
 			options_cpp, len(options),
 			include_dirs_cpp, len(include_dirs), auto_type_source,
 			result_cpp, errors_cpp, error_count