`libnetdude` Manual
Prev |  | Next

# libnd_packet_iterator

## Name

libnd_packet_iterator --

## Synopsis

    enum        LND_PacketIteratorMode;
    gboolean    libnd_pit_init                  (LND_PacketIterator *pit,
                                                 LND_Trace *trace);
    gboolean    libnd_pit_init_mode             (LND_PacketIterator *pit,
                                                 LND_Trace *trace,
                                                 LND_PacketIteratorMode mode);
    void        libnd_pit_cleanup               (LND_PacketIterator *pit);
    LND_Packet* libnd_pit_get                   (LND_PacketIterator *pit);
    LND_Packet* libnd_pit_next                  (LND_PacketIterator *pit);
    guint64     libnd_pit_get_count             (LND_PacketIterator *pit);
    void        libnd_pit_skip_filtered         (LND_PacketIterator *pit,
                                                 gboolean skip_filtered);
    void        libnd_pit_drop_current          (LND_PacketIterator *pit);
    LND_PacketIteratorObserver* libnd_pit_observer_new
                                                (void);
    void        libnd_pit_observer_free         (LND_PacketIteratorObserver *ob);
    void        libnd_pit_add_observer          (LND_PacketIteratorObserver *ob);
    void        libnd_pit_del_observer          (LND_PacketIteratorObserver *ob);

## Description

## Details

### enum LND_PacketIteratorMode

    typedef enum {

      /* Iterate over selected packets only, in read-only or
       * read-write mode.
       */
      LND_PACKET_IT_SEL_R,
      LND_PACKET_IT_SEL_RW,

      /* Iterate over all packets in currently loaded
       * trace part, read-only or read-write.
       */
      LND_PACKET_IT_PART_R,
      LND_PACKET_IT_PART_RW,

      /* Iterate over an area in the trace, starting at
       * currently loaded part and going arbitrarily far.
       * Comes in read-only and read-write flavours.
       */
      LND_PACKET_IT_AREA_R,
      LND_PACKET_IT_AREA_RW,

    } LND_PacketIteratorMode;

### libnd_pit_init ()

    gboolean    libnd_pit_init                  (LND_PacketIterator *pit,
                                                 LND_Trace *trace);

Initializes the packet iterator pointed to by `pit` to the iterator mode and possibly the trace area (if the trace's iterator mode is one of the area iterator modes) currently used by `trace`.

`pit` :

  iterator to initialize.

`trace` :

  trace whose packets are to be iterated.

Returns :

  TRUE when iterator initialization was successful, FALSE otherwise.

### libnd_pit_init_mode ()

    gboolean    libnd_pit_init_mode             (LND_PacketIterator *pit,
                                                 LND_Trace *trace,
                                                 LND_PacketIteratorMode mode);

The function prepares `pit` to iterate over `trace` using `mode`. If the mode is a trace area iterator, the trace's current trace area is used.

`pit` :

  packet iterator to initialize.

`trace` :

  the trace that will be iterated over.

`mode` :

  the mode to use for iteration.

Returns :

  TRUE when iterator initialization was successful, FALSE otherwise.

### libnd_pit_cleanup ()

    void        libnd_pit_cleanup               (LND_PacketIterator *pit);

This function releases any state created by `pit`. It does not free `pit` itself, as packet iterators are conveniently used from the function call stack. You *must* call this function if you abort an iteration prematurely, that is, if you don't just break out of a for-loop when `libnd_pit_get()` returns NULL. In this and only in this case is the cleanup performed automatically.

`pit` :

  iterator to clean up.

### libnd_pit_get ()

    LND_Packet* libnd_pit_get                   (LND_PacketIterator *pit);

Accessor function, returns the packet the iterator currently points to. You do *not* need to clean up this packet.

`pit` :

  iterator to retrieve current packet from.

Returns :

  currently iterated packet.

### libnd_pit_next ()

    LND_Packet* libnd_pit_next                  (LND_PacketIterator *pit);

This function advances the iterator, and returns that packet. If there are no more packets, NULL is returned. Upon advancing the iterator, the progressbar and the packet's tcpdump line automatically get updated.

`pit` :

  iterator to advance

Returns :

  next packet.

### libnd_pit_get_count ()

    guint64     libnd_pit_get_count             (LND_PacketIterator *pit);

`pit` :

  iterator to get current count from.

Returns :

  the number of packets iterated using `pit`.

### libnd_pit_skip_filtered ()

    void        libnd_pit_skip_filtered         (LND_PacketIterator *pit,
                                                 gboolean skip_filtered);

The function enables or disables skipping of filtered packets for the given iterator. By default, filtered packets are skipped!

`pit` :

  iterator to adjust.

`skip_filtered` :

  whether to skip or not.

### libnd_pit_drop_current ()

    void        libnd_pit_drop_current          (LND_PacketIterator *pit);

This function only makes sense in iteration mode LND_PACKET_IT_AREA_RW. Calling it during iteration causes the current packet not to be written out. This only applies to the current packet -- the corresponding flag is reset in every iteration.

`pit` :

  packet iterator.

### libnd_pit_observer_new ()

    LND_PacketIteratorObserver* libnd_pit_observer_new
                                                (void);

The function allocates a new, empty iterator observer. You should then fill in callbacks for the events you're interested in, and register it using `libnd_pit_add_observer()`.

Returns :

  new observer.

### libnd_pit_observer_free ()

    void        libnd_pit_observer_free         (LND_PacketIteratorObserver *ob);

The function releases all memory associated with `ob`.

`ob` :

  observer to delete.

### libnd_pit_add_observer ()

    void        libnd_pit_add_observer          (LND_PacketIteratorObserver *ob);

The function registers the new observer for notifications about future iterations.

`ob` :

  new observer to register.

### libnd_pit_del_observer ()

    void        libnd_pit_del_observer          (LND_PacketIteratorObserver *ob);

The function stops iterator operations from being reported to `ob`. It does not release `ob`'s memory, use `libnd_pit_observer_free()` for that.

`ob` :

  observer to drop.

Prev | Home | Next
libnd_packet | Up | libnd_packet_recycler