Gcr.Parser¶

Subclasses:: None

Methods¶

Inherited:: GObject.Object (37)
Structs:: GObject.ObjectClass (5)

class	`new` ()
	`add_password` (password)
	`format_disable` (format)
	`format_enable` (format)
	`format_supported` (format)
	`get_filename` ()
	`get_parsed` ()
	`get_parsed_attributes` ()
	`get_parsed_block` ()
	`get_parsed_bytes` ()
	`get_parsed_description` ()
	`get_parsed_format` ()
	`get_parsed_label` ()
	`parse_bytes` (data)
	`parse_data` (data)
	`parse_stream` (input, cancellable)
	`parse_stream_async` (input, cancellable, callback, *user_data)
	`parse_stream_finish` (result)
	`set_filename` (filename)

Virtual Methods¶

Inherited:: GObject.Object (7)

	`do_authenticate` (count)
	`do_parsed` ()

Properties¶

Name	Type	Flags	Short Description
`parsed-attributes`	`Gck.Attributes`	r	Parsed PKCS#11 attributes
`parsed-description`	`str`	r	Parsed item description
`parsed-label`	`str`	r	Parsed item label

Signals¶

Inherited:: GObject.Object (1)

Name	Short Description
`authenticate`	This signal is emitted when an item needs to be unlocked or decrypted before it can be parsed.
`parsed`	This signal is emitted when an item is sucessfully parsed.

Fields¶

Inherited:: GObject.Object (1)

Name	Type	Access	Description
parent	`GObject.Object`	r

Class Details¶

class Gcr.Parser(**kwargs)¶

Bases:: GObject.Object
Abstract:: No
Structure:: Gcr.ParserClass

A parser for parsing various types of files or data.

A GcrParser can parse various certificate and key files such as OpenSSL PEM files, DER encoded certifictes, PKCS#8 keys and so on. Each various format is identified by a value in the [enum`DataFormat`] enumeration.

In order to parse data, a new parser is created with Gcr.Parser.new() and then the [signal`Parser`:py:func:::authenticate<Gcr.Parser.signals.authenticate>] and [signal`Parser`:py:func:::parsed<Gcr.Parser.signals.parsed>] signals should be connected to. Data is then fed to the parser via [method`Parser`.parse_data] or [method`Parser`.parse_stream].

During the [signal`Parser`:py:func:::parsed<Gcr.Parser.signals.parsed>] signal the attributes that make up the currently parsed item can be retrieved using the [method`Parser`.get_parsed_attributes] function.

classmethod new()[source]¶

Returns:: a newly allocated Gcr.Parser
Return type:: Gcr.Parser

Create a new Gcr.Parser

add_password(password)[source]¶

Parameters:: password (str or None) – a password to try

Add a password to the set of passwords to try when parsing locked or encrypted items. This is usually called from the [signal`Parser`:py:func:::authenticate<Gcr.Parser.signals.authenticate>] signal.

format_disable(format)[source]¶

Parameters:: format (Gcr.DataFormat) – The format identifier

Disable parsing of the given format. Use Gcr.DataFormat.ALL to disable all the formats.

format_enable(format)[source]¶

Parameters:: format (Gcr.DataFormat) – The format identifier

Enable parsing of the given format. Use Gcr.DataFormat.ALL to enable all the formats.

format_supported(format)[source]¶

Parameters:: format (Gcr.DataFormat) – The format identifier
Returns:: Whether the format is supported.
Return type:: bool

Check whether the given format is supported by the parser.

get_filename()[source]¶

Returns:: the filename set on the parser, or None
Return type:: str

Get the filename of the parser item.

get_parsed()[source]¶

Returns:: the currently parsed item
Return type:: Gcr.Parsed

Get the currently parsed item

get_parsed_attributes()[source]¶

Returns:: the attributes for the current item, which are owned by the parser and should not be freed
Return type:: Gck.Attributes or None

Get the attributes which make up the currently parsed item. This is generally only valid during the [signal`Parser`:py:func:::parsed<Gcr.Parser.signals.parsed>] signal.

get_parsed_block()[source]¶

Returns:: the raw data block of the currently parsed item; the value is owned by the parser and should not be freed
Return type:: bytes or None

Get the raw data block that represents this parsed object. This is only valid during the [signal`Parser`:py:func:::parsed<Gcr.Parser.signals.parsed>] signal.

get_parsed_bytes()[source]¶

Returns:: the raw data block of the currently parsed item
Return type:: GLib.Bytes

Get the raw data block that represents this parsed object. This is only valid during the [signal`Parser`:py:func:::parsed<Gcr.Parser.signals.parsed>] signal.

get_parsed_description()[source]¶

Returns:: the description for the current item; this is owned by the parser and should not be freed
Return type:: str or None

Get a description for the type of the currently parsed item. This is generally only valid during the [signal`Parser`:py:func:::parsed<Gcr.Parser.signals.parsed>] signal.

get_parsed_format()[source]¶

Returns:: the data format of the currently parsed item
Return type:: Gcr.DataFormat

Get the format of the raw data block that represents this parsed object. This corresponds with the data returned from [method`Parser`.get_parsed_block].

This is only valid during the [signal`Parser`:py:func:::parsed<Gcr.Parser.signals.parsed>] signal.

get_parsed_label()[source]¶

Returns:: the label of the currently parsed item. The value is owned by the parser and should not be freed.
Return type:: str or None

Get the label of the currently parsed item. This is generally only valid during the [signal`Parser`:py:func:::parsed<Gcr.Parser.signals.parsed>] signal.

parse_bytes(data)[source]¶

Parameters:: data (GLib.Bytes) – the data to parse
Raises:: GLib.Error
Returns:: Whether the data was parsed successfully or not.
Return type:: bool

Parse the data. The [signal`Parser`:py:func:::parsed<Gcr.Parser.signals.parsed>] and [signal`Parser`:py:func:::authenticate<Gcr.Parser.signals.authenticate>] signals may fire during the parsing.

parse_data(data)[source]¶

Parameters:: data (bytes) – the data to parse
Raises:: GLib.Error
Returns:: Whether the data was parsed successfully or not.
Return type:: bool

Parse the data. The [signal`Parser`:py:func:::parsed<Gcr.Parser.signals.parsed>] and [signal`Parser`:py:func:::authenticate<Gcr.Parser.signals.authenticate>] signals may fire during the parsing.

A copy of the data will be made. Use [method`Parser`.parse_bytes] to avoid this.

parse_stream(input, cancellable)[source]¶

Parameters:

input (Gio.InputStream) – The input stream
cancellable (Gio.Cancellable or None) – An optional cancellation object

Raises:

GLib.Error

Returns:

Whether the parsing completed successfully or not.

Return type:

bool

Parse items from the data in a Gio.InputStream. This function may block while reading from the input stream. Use [method`Parser`.parse_stream_async] for a non-blocking variant.

The [signal`Parser`:py:func:::parsed<Gcr.Parser.signals.parsed>] and [signal`Parser`:py:func:::authenticate<Gcr.Parser.signals.authenticate>] signals may fire during the parsing.

parse_stream_async(input, cancellable, callback, *user_data)[source]¶

Parameters:

input (Gio.InputStream) – The input stream
cancellable (Gio.Cancellable or None) – An optional cancellation object
callback (Gio.AsyncReadyCallback or None) – Called when the operation result is ready.
user_data (object or None) – Data to pass to callback

Parse items from the data in a Gio.InputStream. This function completes asyncronously and doesn’t block.

The [signal`Parser`:py:func:::parsed<Gcr.Parser.signals.parsed>] and [signal`Parser`:py:func:::authenticate<Gcr.Parser.signals.authenticate>] signals may fire during the parsing.

parse_stream_finish(result)[source]¶

Parameters:: result (Gio.AsyncResult) – The operation result
Raises:: GLib.Error
Returns:: Whether the parsing completed successfully or not.
Return type:: bool

Complete an operation to parse a stream.

set_filename(filename)[source]¶

Parameters:: filename (str or None) – a string of the filename of the parser item

Sets the filename of the parser item.

do_authenticate(count) virtual¶

Parameters:: count (int) –
Return type:: bool

do_parsed() virtual¶

Signal Details¶

Gcr.Parser.signals.authenticate(parser, count)¶

Signal Name:

authenticate

Flags:

RUN_LAST

Parameters:

parser (Gcr.Parser) – The object which received the signal
count (int) – the number of times this item has been authenticated

Returns:

Whether the authentication was handled.

Return type:

bool

This signal is emitted when an item needs to be unlocked or decrypted before it can be parsed. The count argument specifies the number of times the signal has been emitted for a given item. This can be used to display a message saying the previous password was incorrect.

Typically the Gcr.Parser.add_password() function is called in response to this signal.

If False is returned, then the authentication was not handled. If no handlers return True then the item is not parsed and an error with the code Gcr.DataError.CANCELLED will be raised.

Gcr.Parser.signals.parsed(parser)¶

Signal Name:: parsed
Flags:: RUN_FIRST
Parameters:: parser (Gcr.Parser) – The object which received the signal

This signal is emitted when an item is sucessfully parsed. To access the information about the item use the Gcr.Parser.get_parsed_label(), Gcr.Parser.get_parsed_attributes() and Gcr.Parser.get_parsed_description() functions.

Property Details¶

Gcr.Parser.props.parsed_attributes¶

Name:: parsed-attributes
Type:: Gck.Attributes
Default Value:: None
Flags:: READABLE

Get the attributes that make up the currently parsed item. This is generally only valid during a [signal`Parser`:py:func:::parsed<Gcr.Parser.signals.parsed>] signal.

Gcr.Parser.props.parsed_description¶

Name:: parsed-description
Type:: str
Default Value:: ''
Flags:: READABLE

The description of the type of the currently parsed item. This is generally only valid during a [signal`Parser`:py:func:::parsed<Gcr.Parser.signals.parsed>] signal.

Gcr.Parser.props.parsed_label¶

Name:: parsed-label
Type:: str
Default Value:: ''
Flags:: READABLE

The label of the currently parsed item. This is generally only valid during a [signal`Parser`:py:func:::parsed<Gcr.Parser.signals.parsed>] signal.