Function sequoia_ffi::openpgp::parse::pgp_packet_parser_next [−][src]
#[no_mangle]
pub extern "C" fn pgp_packet_parser_next<'a>(
errp: Option<&mut *mut Error>,
pp: *mut PacketParser<'a>,
old_packet: Option<&mut *mut Packet>,
ppr: Option<&mut *mut PacketParserResult<'a>>
) -> Status
Expand description
Finishes parsing the current packet and starts parsing the
C Declaration
pgp_status_t
pgp_packet_parser_next (pgp_error_t *errp,
pgp_packet_parser_t pp,
pgp_packet_t *old_packet,
pgp_packet_parser_result_t *ppr);
following one.
This function finishes parsing the current packet. By
default, any unread content is dropped. (See
PacketParsererBuilder
for how to configure this.) It then
creates a new packet parser for the following packet. If the
current packet is a container, this function does not
recurse into the container, but skips any packets it contains.
To recurse into the container, use the recurse()
method.
The return value is a tuple containing:
-
A
Packet
holding the fully processed old packet; -
The old packet’s recursion depth;
-
A
PacketParser
holding the new packet; -
And, the recursion depth of the new packet.
A recursion depth of 0 means that the packet is a top-level packet, a recursion depth of 1 means that the packet is an immediate child of a top-level-packet, etc.
Since the packets are serialized in depth-first order and all interior nodes are visited, we know that if the recursion depth is the same, then the packets are siblings (they have a common parent) and not, e.g., cousins (they have a common grandparent). This is because, if we move up the tree, the only way to move back down is to first visit a new container (e.g., an aunt).
Using the two positions, we can compute the change in depth as new_depth - old_depth. Thus, if the change in depth is 0, the two packets are siblings. If the value is 1, the old packet is a container, and the new packet is its first child. And, if the value is -1, the new packet is contained in the old packet’s grandparent. The idea is illustrated below:
ancestor
| \
... -n
|
grandparent
| \
parent -1
| \
packet 0
|
1
Note: since this function does not automatically recurse into a container, the change in depth will always be non-positive. If the current container is empty, this function DOES pop that container off the container stack, and returns the following packet in the parent container.
The items of the tuple are returned in out-parameters. If you do
not wish to receive the value, pass NULL
as the parameter.
Consumes the given packet parser.