Module pychrysalide.glibext
Interface ComparableItem
Interface LineGenerator
Interface SingletonCandidate
Class BinPortion
Class BinaryCursor
Class BufferCache
Class BufferLine
Class ConfigParam
Class ConfigParamIterator
Class GenConfig
Class LineCursor
Class SingletonFactory
Module pychrysalide.glibext
Documentation
This module contains the definition of some objects derived from the GObject structure.
These common objects are used in several places inside Chrysalide and could be seen as extensions to the GLib API.
Interfaces
Classes
- BinPortion
- BinaryCursor
- BufferCache
- BufferLine
- ConfigParam
- ConfigParamIterator
- GenConfig
- LineCursor
- SingletonFactory
Interface ComparableItem
ComparableItem provides an interface to compare objects.
A typical class declaration for a new implementation looks like:
class NewImplem(GObject.Object, ComparableItem):
...
The object can be compared using rich methods (like <= or !=).
Hierarchy
gobject.GInterface ╰── pychrysalide.glibext.ComparableItem
Direct implementation: pychrysalide.analysis.scan.ScanExpression
Constants
RichCmpOperation
Modes for objects comparison.
| 1 | = 1 |
| 2 | = 2 |
| 4 | = 4 |
Interface LineGenerator
LineGenerator gives an interface to all objects which aim to produce content for rendering lines. Such lines can be exported to graphical interfaces or text files.
A typical class declaration for a new implementation looks like:
class NewImplem(GObject.Object, LineGenerator):
...
The following methods have to be defined for new implementations:
Hierarchy
gobject.GInterface ╰── pychrysalide.glibext.LineGenerator
Direct implementations:
- pychrysalide.analysis.db.items.DbComment
- pychrysalide.arch.ArchInstruction
- pychrysalide.format.BinSymbol
- pychrysalide.glibext.BinPortion
Methods
_compute_cursor(self, x, index, repeat)
Abstract method used to create a new cursor for a given location inside displayed lines.
The position on the horizontal axis, the line index and the number of repetitions (only relevant if the generator produces several lines) give indications about the active position.
The result has to be a LineCursor instance.
_contain_cursor(self, index, repeat, cursor)
Abstract method used to check the position of a cursor in relation to rendering lines.
The line index and the number of repetitions (only relevant if the generator produces several lines) give indications about the active position. The cursor is a LineCursor instance.
The result has to be an integer less than, equal to, or greater than zero if the cursor is, respectively, before, inside or after the area covered by the generator.
_count_lines(self)
Abstract method used to count the number of lines produced by the current generator.
_get_flags(self, index, repeat)
Abstract method used to provide flags for a given rendering line.
The line index and the number of repetitions (only relevant if the generator produces several lines) give indications about the active position.
The result has to be a BufferLineFlags value.
_print(self, line, index, repeat, content)
Abstract method used to generate content into a rendering line, which is a provided BufferLine instance.
The line index and the number of repetitions (only relevant if the generator produces several lines) give indications about the current rendering position.
If set, the content is a BinContent instance providing access to the processed binary data.
compute_cursor(self, x, index, repeat)
Create a a new cursor for a given location inside displayed lines.
The position on the horizontal axis, the line index and the number of repetitions (only relevant if the generator produces several lines) give indications about the active position.
The result has to be a LineCursor instance.
contain_cursor(self, index, repeat, cursor)
Check the position of a cursor in relation to rendering lines.
The line index and the number of repetitions (only relevant if the generator produces several lines) give indications about the active position. The cursor is a LineCursor instance.
The result has to be an integer less than, equal to, or greater than zero if the cursor is, respectively, before, inside or after the area covered by the generator.
get_flags(self, index, repeat)
Get the flags of a given position from the generator.
The line index and the number of repetitions (only relevant if the generator produces several lines) give indications about the active position.
The result is a BufferLineFlags value.
print(self, line, index, repeat, content)
Produce output into a rendering line with optional content.
The provided line is a BufferLine instance. The index and the number of repetitions (only relevant if the generator produces several lines) give indications about the current rendering position.
If set, the content is a BinContent instance providing access to the processed binary data.
Attributes
lines_count
Quantity of lines produced by the generator.
This number may vary between calls, if a width has changed for instance.
Interface SingletonCandidate
The SingletonCandidate class is a required interface for objects aiming at becoming singleton instances. All shared singletons are registered within a SingletonFactory object.
The main implemantations come with types derived from DataType.
A typical class declaration for a new implementation looks like:
class NewImplem(GObject.Object, SingletonCandidate):
...
The following methods have to be defined for new implementations:
_list_inner_instances();_update_inner_instances();__hash__();__eq__();_set_read_only();_is_read_only().
The object can be compared using rich methods (like <= or !=).
Hierarchy
gobject.GInterface ╰── pychrysalide.glibext.SingletonCandidate
Direct implementation: pychrysalide.arch.ArchOperand
Methods
__hash__(self)
Abstract method used to produce a hash of the object.
The result must be an integer value up to 64 bits.
Inner instances which are listed through the _list_inner_instances() method do not need to get processed here as they are handled automatically by the interface core.
_is_read_only(self)
Abstract method used to retrieve the status of the data contained by a singleton candidate.
The retured value is True if the candidate is registered inside a SingletonFactory instance as official singleton, False otherwise.
_list_inner_instances(self)
Provide an internal access to the list of optional internal singleton candidate instances.
The result has to be a tuple containing zero or more SingletonCandidate instances.
_set_read_only(self)
Abstract method used to mark the content of a singleton candidate as read-only.
The read-only state is mandatory once the candidate is registered inside a SingletonFactory instance as official singleton.
_update_inner_instances(self, instances)
Update the list of internal singleton candidate instances.
The provided instances are a tuple of SingletonCandidate objets promoted as singletons.
hash(self)
Compute the hash value of the singleton candidate.
The method relies on the interface core to include in the process the optional embedded instances which may become singletons.
The result is an integer value.
Even if the Python hash() method, relying on the __hash__() implementation, provides values up to 64 bits, the final hashes processed by the native GLib hash methods are limited to 32 bits values.
Attributes
inner_instances
List of optional internal singleton candidate instances.
The result has to be a tuple containing zero or more SingletonCandidate instances.
read_only
State of the singleton candidate content.
The result is a boolean: True if the object is registered as singleton, False otherwise.
Once a singleton, the object must not change its content as it is a shared instance.
Class BinPortion
The BinPortion object handles parts of binaries usually formally identified in binary formats, like program segments or sections for ELF files for example.
Instances can be created using the following constructor:
BinPortion(code, addr, size)
Where code is the CSS class style for the rendering color to use, addr is the starting point of the portion in memory, as a vmpa value, and size is the size of the portion.
The object can be compared using rich methods (like <= or !=).
Hierarchy
builtins.object ╰── gi._gi.GObject ╰── pychrysalide.glibext.BinPortion
Implements: pychrysalide.glibext.LineGenerator
Methods
include(self, sub)
Include another binary portion as a child item.
The sub portion has to be a BinPortion instance.
limit_range(self, max)
Ensure the portion range does not cross a boundary size.
An integer value is expected as the maximum size of the portion.
A boolean value indicating the success of the operation is returned.
Attributes
continuation
Tell if the current portion is a continuation of another one.
If a section belongs to several parents, it is cut into several parts when included in the portion tree.
desc
Human description for the binary portion, as a simple string.
range
Area covered by the binary portion.
This property is a mrange instance.
rights
Access rights declared for the binary portion, as a PortionAccessRights value.
Constants
BinaryPortionCode
Selector names for the CSS rendering.
| RAW | = "binportion-raw" |
| CODE | = "binportion-code" |
| DATA | = "binportion-data" |
| DATA_RO | = "binportion-data-ro" |
| DISASS_ERROR | = "binportion-disassembly-error" |
PortionAccessRights
Access rights for binary portions.
| 0 | = 0 |
| 1 | = 1 |
| 2 | = 2 |
| 4 | = 4 |
| 7 | = 7 |
Class BinaryCursor
BinaryCursor handles a position into a disassembly view.
Instances can be created using the following constructor:
BinaryCursor()
Hierarchy
builtins.object ╰── gi._gi.GObject ╰── pychrysalide.glibext.LineCursor ╰── pychrysalide.glibext.BinaryCursor
Methods
retrieve(self)
Retrieve the location of the cursor.
The result is provided as a vmpa instance.
update(self, addr)
Update the location of the cursor.
The addr argument must be able to get converted into a vmpa instance.
Attributes
raw
Type of rendering in the status bar for the binary location.
Class BufferCache
The BufferCache object manages a group of lines intended to get printed onto the screen or into a file.
These lines are cached and rebuilt when needed.
Instances can be created using the following constructor:
BufferCache(content=None)
Where content is a BinContent instance, if defined. This content is provided to lines as argument when the lines get printed, so it may not be always useful and thus can be discarded when creating a new buffer cache.
Hierarchy
builtins.object ╰── gi._gi.GObject ╰── pychrysalide.glibext.BufferCache
Methods
add_line_flag(self, index, flag)
Add one optional flag to those assigned to a given buffer line. The line is located using the index argument.
The index has to be a simple integer, and the flag a BufferLineFlags value.
An write access lock has to be held for the cache; see the lock() function.
append(self, generator, flags=0)
Append a new line at the end of a buffer cache.
The content generator for this new line is a LineGenerator instance. Nominal properties can be set for the line as extra BufferLineFlags values.
An write access lock has to be held for the cache; see the lock() function.
delete_at(self, index)
Delete the line at the index position from a buffer cache.
An write access lock has to be held for the cache; see the lock() function.
delete_type_at(self, index, gtype, before=False, after=False)
Delete the first generator of a given type found inside a line of a buffer cache.
The target type has to be a gobject.GType, usually provided by the __gtype__ attribute of a generator interface. The generator is deleted from the line at, before or after the provided index.
The function returns the deleted generator as a LineGenerator instance, or None if none found.
An write access lock has to be held for the cache; see the lock() function.
extend_with(self, count, generator)
Extend the buffer cache so it will contain count lines.
The count number should be greater than the current line quantity, otherwise the call makes no sense. The generator is a LineGenerator instance used to produce the extra new lines on demand.
An write access lock has to be held for the cache; see the lock() function.
get_line_flags(self, index)
Provide the optional flags assigned to a given buffer line. The line is located using the index argument.
The result is a BufferLineFlags value.
An read access lock has to be held for the cache; see the lock() function.
insert_at(self, index, generator, flags=0, before=False, after=False)
Add an extra content generator to a given line.
The new content generator for the line at, before or after the provided index is a LineGenerator instance. Nominal properties can be set for this line as extra BufferLineFlags values.
An write access lock has to be held for the cache; see the lock() function.
lock(self, write=False)
Lock for access the content of a buffer cache instance.
The write parameter is a boolean value which has to be set if the access to perform will modify the buffer cache.
Each call of this method has to followed by a call to unlock(), with the same write parameter.
look_for_flag(self, index, flag)
Iterate the buffer cache lines from a starting index until a line with flags matching the provided flag is met.
The flag argument has to be a BufferLineFlags value.
The result is an index equal or greater than the starting index or, if no match is found, the number of lines in the buffer cache.
An read access lock has to be held for the cache; see the lock() function.
remove_line_flag(self, index, flag)
Remove one optional flag from those assigned to a given buffer line. The line is located using the index argument.
The index has to be a simple integer, and the flag a BufferLineFlags value.
An write access lock has to be held for the cache; see the lock() function.
truncate(self, max)
Shrink the buffer cache so it will contain at most max lines.
The max number should be lesser than the current line quantity, otherwise no effect will happen.
An write access lock has to be held for the cache; see the lock() function.
unlock(self, write=False)
Unlock the content of a buffer cache instance.
The write parameter is a boolean value which has to be set if the performed access has modified the buffer cache.
Attributes
content
Binary content linked to the buffer cache, as a BinContent instance, or None.
left_margin
Width of the left margin inside of a buffer cache output.
line_height
Height of a line printed from the buffer cache.
lines_count
Count the number of lines contained in a buffer cache.
An read access lock has to be held for the cache; see the lock() function.
text_position
Starting position of the text on the left of a buffer cache output.
Class BufferLine
The BufferLine object is used to display processed data: disassembled instruction, binary content in hexadecimal form, aso.
Instances can be created using the following constructor:
BufferLine()
Such objets aim to be created from the Chrysalide core only, and then get populated on demand. Thus, these lines can be viewed as cached lines and their properties have to be set through the BufferCache instance which contains them.
Hierarchy
builtins.object ╰── gi._gi.GObject ╰── pychrysalide.glibext.BufferLine
Methods
append_text(self, column, text, tag, creator=None)
Append some text to a line at a given column index. The expected rendering for this text is defined by the tag, which must be a RenderingTagType value.
An optional GObject instance may be provided as origin of the creation.
get_text(self, first_col, last_col, markup)
Provide the text of a buffer line.
Attributes
flags
ent flags of the buffer line.
Constants
BufferLineFlags
Optional flags linked to a rendering line.
| 1 | = 0x1 |
| 2 | = 0x2 |
| 4 | = 0x4 |
| 8 | = 0x8 |
| 16 | = 0x10 |
RenderingTagType
Kinds of text rendering.
| 0 | = 0 |
| 1 | = 1 |
| 2 | = 2 |
| 3 | = 3 |
| 4 | = 4 |
| 5 | = 5 |
| 6 | = 6 |
| 7 | = 7 |
| 8 | = 8 |
| 9 | = 9 |
| 10 | = 10 |
| 11 | = 11 |
| 12 | = 12 |
| 13 | = 13 |
| 14 | = 14 |
| 15 | = 15 |
| 16 | = 16 |
| 17 | = 17 |
| 18 | = 18 |
| 19 | = 19 |
| 20 | = 20 |
| 21 | = 21 |
| 22 | = 22 |
| 23 | = 23 |
| 24 | = 24 |
| 25 | = 25 |
| 26 | = 26 |
| 27 | = 27 |
| 28 | = 28 |
Class ConfigParam
ConfigParam holds a configuration parameter with its default and current values.
Parameters are aimed to join a GenConfig instance.
Instances can be created using the following constructor:
ConfigParam(path, type, value=None)
Where path is dot separated string items serving as a parameter key, type is a ConfigParamType value and value is an optional default value if the parameter initial value has not to be empty.
Hierarchy
builtins.object ╰── gi._gi.GObject ╰── pychrysalide.glibext.ConfigParam
Methods
make_empty(self)
Unset the value of the current parameter.
reset(self)
Reset the content of the current parameter.
Attributes
path
Dot separated string items used as key for a configuration parameter.
state
State of a configuration parameter.
The attribute carries a ConfigParamState value.
type
Type of value provided by a configuration parameter.
The attribute carries a ConfigParamType value.
value
Value of a configuration parameter.
The type of the value carried by the attribute depends on type value.
Constants
ConfigParamState
States of a value carried by a configuration parameter.
| 1 | = 1 |
| 2 | = 2 |
| 4 | = 4 |
ConfigParamType
Kind of value available for configuration parameter types.
| 0 | = 0 |
| 1 | = 1 |
| 2 | = 2 |
| 3 | = 3 |
| 4 | = 4 |
| 5 | = 5 |
Class ConfigParamIterator
ConfigParamIterator is an iterator for configuration parameters.
This kind of iterator is provided by the params attribute.
Hierarchy
builtins.object ╰── pychrysalide.glibext.ConfigParamIterator
Methods
__iter__(self)
Implement iter(self).
__next__(self)
Implement next(self).
Class GenConfig
The GenConfig class defines a generic way to load, provide and store configuration items. Each of these items is handled with a ConfigParam object.
Instances can be created using the following constructor:
GenConfig(name=None)
Where name is a suitable storage filename for the configuration. If no name is defined, the configuration is expected to be memory-only resident.
Hierarchy
builtins.object ╰── gi._gi.GObject ╰── pychrysalide.glibext.GenConfig
Methods
add(self, param, lock=True)
Add an existing parameter to a configuration.
The param argument has to be a ConfigParam instance. The lock boolean value is an optional order handling the way configuration parameters are accessed.
The configuration has to be locked while accessing its content. This lock can be managed with the lock argument of this function or thanks to the lock_unlock method().
The returned value is a ConfigParam instance in case of success or None if the parameter already exists in the configuration.
delete(self, path)
Delete an existing parameter from a configuration.
The path argument is a string used as key pointing to the parameter to process.
lock_unlock(self, write, lock)
Lock or unlock access to the configuration internals.
The write argument states if the operation targets read or write accesses, and the lock value defines the state to achieve.
Both arguments are boolean values.
read(self)
Read the configuration from its relative XML file.
The returned value is True if the operation terminated with success, or False in case of failure.
search(self, path, lock=True)
Look for a given configuration parameter.
The path argument is a string used as key pointing to a parameter. The lock boolean value is an optional order handling the way configuration parameters are accessed.
The configuration has to be locked while accessing its content. This lock can be managed with the lock argument of this function or thanks to the lock_unlock method().
The returned value is a ConfigParam instance in case of success or None if the parameter is not found.
write(self)
Write the configuration to its relative XML file.
The returned value is True if the operation terminated with success, or False in case of failure.
Attributes
filename
Path to the file used as storage backend for the configuration.
The result is a string pointing to a file which may not (yet) exist or None if not defined.
params
List of all registered configuration parameters.
The result is a ConfigParamIterator over ConfigParam instances.
Class LineCursor
PyChrysalide line cursor
Hierarchy
builtins.object ╰── gi._gi.GObject ╰── pychrysalide.glibext.LineCursor
Known subclass: pychrysalide.glibext.BinaryCursor
Attributes
label
l for the current state of a line cursor.
valid
dity status of the line cursor.
Class SingletonFactory
The SingletonFactory class reduces the memory footprint by compacting the quantity of running instances of a given GLib type.
Instances can be created using the following constructor:
SingletonFactory()
The first processed instance defines the type handled by the factory.
Hierarchy
builtins.object ╰── gi._gi.GObject ╰── pychrysalide.glibext.SingletonFactory
Methods
get_instance(self, candidate)
Provide the unique instance for a given singleton candidate.
The candidate object and the result of the function belong to the same type: SingletonCandidate.