`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.

`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