DEV IN PROGRESS

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

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:

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:

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.

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.