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.