Camel.MimeParser¶

Subclasses:: None

Methods¶

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

class	`new` ()
	`content_type` ()
	`drop_step` ()
	`dup_headers` ()
	`errno` ()
	`filter_add` (mf)
	`filter_remove` (id)
	`from_line` ()
	`header` (name, offset)
	`init_with_bytes` (bytes)
	`init_with_fd` (fd)
	`init_with_input_stream` (input_stream)
	`init_with_stream` (stream)
	`postface` ()
	`preface` ()
	`push_state` (newstate, boundary)
	`read` (len)
	`scan_from` (scan_from)
	`scan_pre_from` (scan_pre_from)
	`seek` (offset, whence)
	`set_header_regex` (matchstr)
	`state` ()
	`step` (databuffer)
	`stream` ()
	`tell` ()
	`tell_start_boundary` ()
	`tell_start_from` ()
	`tell_start_headers` ()
	`unstep` ()

Virtual Methods¶

Inherited:: GObject.Object (7)

	`do_content` ()
	`do_message` (headers)
	`do_part` ()

Properties¶

None

Signals¶

Inherited:: GObject.Object (1)

Fields¶

Inherited:: GObject.Object (1)

Name	Type	Access	Description
parent	`GObject.Object`	r

Class Details¶

class Camel.MimeParser(**kwargs)¶

Bases:: GObject.Object
Abstract:: No
Structure:: Camel.MimeParserClass

classmethod new()¶

Returns:: A new Camel.MimeParser object
Return type:: Camel.MimeParser

Create a new Camel.MimeParser object.

content_type()¶

Returns:: A content_type structure, or None if there is no content-type defined for this Camel.part of state of the parser.
Return type:: Camel.ContentType or None

Get the content type defined in the current Camel.part.

drop_step()¶

Drop the last step call. This should only be used in conjunction with seeking of the stream as the stream may be in an undefined state relative to the state of the parser.

Use this call with care.

dup_headers()¶

Returns:: The headers, or None, if there are no headers defined for the current Camel.part or state. Free it with Camel.NameValueArray.free().
Return type:: Camel.NameValueArray or None

Get the list of the raw headers which are defined for the current state of the parser. These headers are valid until the next call to Camel.MimeParser.step(), or Camel.MimeParser.drop_step().

New in version 3.24.

errno()¶

Return type:: int

filter_add(mf)¶

Parameters:: mf (Camel.MimeFilter) – a Camel.MimeFilter
Returns:: An id that may be passed to Camel.MimeParser.filter_remove() to remove the filter, or -1 if the operation failed.
Return type:: int

Add a filter that will be applied to any body content before it is passed to the caller. Filters may be pipelined to perform multi-pass operations on the content, and are applied in the order they were added.

Note that filters are only applied to the body content of messages, and once a filter has been set, all content returned by a Camel.MimeParser.step() with a state of Camel.MimeParserState.BODY will have passed through the filter.

New in version 2.22.

filter_remove(id)¶

Parameters:: id (int) – id of the filter to remove, as returned from Camel.MimeParser.filter_add()

Remove a processing filter from the pipeline. There is no restriction on the order the filters can be removed.

New in version 2.22.

from_line()¶

Returns:: The From line, or None if called out of context.
Return type:: str or None

Get the last scanned “From “ line, from a recently scanned from. This should only be called in the Camel.MimeParserState.FROM state. The from line will include the closing \n found (if there was one).

The return value will remain valid while in the Camel.MimeParserState.FROM state, or any deeper state.

New in version 2.22.

header(name, offset)¶

Parameters:

name (str) – Name of header.
offset (int) – Pointer that can receive the offset of the header in the stream from the start of parsing.

Returns:

The header value, or None if the header is not defined.

Return type:

str or None

Lookup a header by name.

init_with_bytes(bytes)¶

Parameters:: bytes (GLib.Bytes) – a GLib.Bytes containing the message content

Convenience function creates a Gio.MemoryInputStream from bytes and hands it off to Camel.MimeParser.init_with_input_stream().

New in version 3.12.

init_with_fd(fd)¶

Parameters:: fd (int) – A valid file descriptor.
Returns:: Returns -1 on error.
Return type:: int

Initialise the scanner with an fd. The scanner’s offsets will be relative to the current file position of the file descriptor. As a result, seekable descritors should be seeked using the parser seek functions.

init_with_input_stream(input_stream)¶

Parameters:: input_stream (Gio.InputStream) – a Gio.InputStream

Initialize the scanner with input_stream. The scanner’s offsets will be relative to the current file position of the stream. As a result, seekable streams should only be seeked using the parser seek function.

New in version 3.12.

init_with_stream(stream)¶

Parameters:: stream (Camel.Stream) – a Camel.Stream to init with
Raises:: GLib.Error
Returns:: -1 on error.
Return type:: int

Initialise the scanner with a source stream. The scanner’s offsets will be relative to the current file position of the stream. As a result, seekable streams should only be seeked using the parser seek function.

postface()¶

Returns:: The postface text, or None if there wasn’t any.
Return type:: str or None

Retrieve the postface text for the current multipart. Only returns valid data when the current state if Camel.MimeParserState.MULTIPART_END.

New in version 2.22.

preface()¶

Returns:: The preface text, or None if there wasn’t any.
Return type:: str or None

Retrieve the preface text for the current multipart. Can only be used when the state is Camel.MimeParserState.MULTIPART_END.

New in version 2.22.

push_state(newstate, boundary)¶

Parameters:

newstate (Camel.MimeParserState) – New state
boundary (str) – Boundary marker for state.

Pre-load a new parser state. Used to post-parse multipart content without headers.

read(len)¶

Parameters:

len (int) – The length of data to read

Raises:

GLib.Error

Returns:

The number of bytes available, or -1 on error.

databuffer:: The data buffer

Return type:

(int, databuffer: bytes)

Read at most len bytes from the internal mime parser buffer.

Returns the address of the internal buffer in databuffer, and the length of useful data.

len may be specified as GObject.G_MAXSSIZE, in which case you will get the full remainder of the buffer at each call.

Note that no parsing of the data read through this function occurs, so no state changes occur, but the seek position is updated appropriately.

scan_from(scan_from)¶

Parameters:: scan_from (bool) – True if the scanner should scan From lines.

Tell the scanner if it should scan “^From “ lines or not.

If the scanner is scanning from lines, two additional states Camel.MimeParserState.FROM and Camel.MimeParserState.FROM_END will be returned to the caller during parsing.

This may also be preceeded by an optional Camel.MimeParserState.PRE_FROM state which contains the scanned data found before the From line is encountered. See also Camel.MimeParser.scan_pre_from().

scan_pre_from(scan_pre_from)¶

Parameters:: scan_pre_from (bool) – True if we want to get pre-from data.

Tell the scanner whether we want to know abou the pre-from data during a scan. If we do, then we may get an additional state Camel.MimeParserState.PRE_FROM which returns the specified data.

seek(offset, whence)¶

Parameters:

offset (int) – Number of bytes to offset the seek by.
whence (int) – SEEK_SET, SEEK_CUR, SEEK_END

Returns:

The new seek offset, or -1 on an error (for example, trying to seek on a non-seekable stream or file descriptor).

Return type:

int

Reset the source position to a known value.

Note that if the source stream/descriptor was not positioned at 0 to begin with, and an absolute seek is specified (whence != SEEK_CUR), then the seek position may not match the desired seek position.

New in version 2.22.

set_header_regex(matchstr)¶

Parameters:: matchstr (str) –
Return type:: int

state()¶

Returns:: The current parser state.
Return type:: Camel.MimeParserState

Get the current parser state.

step(databuffer)¶

Parameters:

databuffer (bytes) – Pointer to accept a pointer to the data associated with this step (if any). May be None, in which case datalength is also ingored.

Returns:

The current new state of the parser is returned.

databuffer:: Pointer to accept a pointer to the data associated with this step (if any). May be None, in which case datalength is also ingored.

Return type:

(Camel.MimeParserState, databuffer: bytes)

Parse the next Camel.part of the MIME message. If Camel.MimeParser.unstep() has been called, then continue to return the same state for that many calls.

If the step is Camel.MimeParserState.BODY then the databuffer and datalength pointers will be setup to point to the internal data buffer of the scanner and may be processed as required. Any filters will have already been applied to this data.

Refer to the state diagram elsewhere for a full listing of the states an application is gauranteed to get from the scanner.

stream()¶

Returns:: The stream from Camel.MimeParser.init_with_stream(), or None if the parser is reading from a file descriptor or is uninitialised.
Return type:: Camel.Stream or None

Get the stream, if any, the parser has been initialised with. May be used to setup sub-streams, but should not be read from directly (without saving and restoring the seek position in between).

tell()¶

Returns:: See above.
Return type:: int

Return the current scanning offset. The meaning of this value will depend on the current state of the parser.

An incomplete listing of the states:

Camel.MimeParserState.INITIAL, The start of the current message. Camel.MimeParserState.HEADER, Camel.MimeParserState.MESSAGE, Camel.MimeParserState.MULTIPART, the character position immediately after the end of the header. Camel.MimeParserState.BODY, Position within the message of the start of the current data block. CAMEL_MIME_PARSER_STATE_*_END, The position of the character starting the next section of the scan (the last position + 1 of the respective current state).

New in version 2.22.

tell_start_boundary()¶

Returns:: The start of the boundary, or -1 if there was no boundary encountered yet.
Return type:: int

When parsing a multipart, this returns the start of the last boundary.

New in version 2.22.

tell_start_from()¶

Returns:: The start of the from line, or -1 if there was no From line, or From lines are not being scanned.
Return type:: int

If the parser is scanning From lines, then this returns the position of the start of the From line.

New in version 2.22.

tell_start_headers()¶

Returns:: The header start position, or -1 if no headers were scanned in the current state.
Return type:: int

Find out the position within the file of where the headers started, this is cached by the parser at the time.

New in version 2.22.

unstep()¶

Cause the last step operation to repeat itself. If this is called repeated times, then the same step will be repeated that many times.

Note that it is not possible to scan back using this function, only to have a way of peeking the next state.

do_content() virtual¶

do_message(headers) virtual¶

Parameters:: headers (object or None) –

do_part() virtual¶