`libnetdude` Manual
Prev |  | Next

# libnd_packet

## Name

libnd_packet --

## Synopsis

    enum        LND_PacketObserverOp;
    gboolean    (*LND_PacketFunc)               (LND_Packet *packet,
                                                 LND_ProtoData *pd,
                                                 void *user_data);
    LND_Packet* libnd_packet_new                (LND_TracePart *tp,
                                                 guint data_size);
    void        libnd_packet_free               (LND_Packet *packet);
    void        libnd_packet_remove             (LND_Packet *packet);
    LND_Trace*  libnd_packet_get_trace          (const LND_Packet *packet);
    void        libnd_packet_dump               (const LND_Packet *packet,
                                                 pcap_dumper_t *dumper);
    void        libnd_packet_set_data           (LND_Packet *packet,
                                                 const struct pcap_pkthdr *hdr,
                                                 const guchar *data);
    LND_Packet* libnd_packet_duplicate          (LND_Packet *packet);
    void        libnd_packet_set_filtered       (LND_Packet *packet,
                                                 gboolean filtered);
    gboolean    libnd_packet_is_filtered        (LND_Packet *packet);
    void        libnd_packet_init               (LND_Packet *packet);
    void        libnd_packet_init_from_pcap     (LND_Packet *packet,
                                                 pcap_t *pcap);
    gboolean    libnd_packet_is_complete        (const LND_Packet *packet);
    void        libnd_packet_update             (LND_Packet *packet,
                                                 LND_Protocol *proto,
                                                 guint nesting);
    guchar*     libnd_packet_get_data           (const LND_Packet *packet,
                                                 const LND_Protocol *proto,
                                                 guint nesting);
    guchar*     libnd_packet_get_data_end       (const LND_Packet *packet,
                                                 const LND_Protocol *proto,
                                                 guint nesting);
    void        libnd_packet_add_proto_data     (LND_Packet *packet,
                                                 LND_Protocol *proto,
                                                 guchar *data,
                                                 guchar *data_end);
    LND_ProtoData* libnd_packet_get_proto_data  (const LND_Packet *packet,
                                                 const LND_Protocol *proto,
                                                 guint nesting);
    guchar*     libnd_packet_get_end            (const LND_Packet *packet);
    gboolean    libnd_packet_has_complete_header
                                                (const LND_Packet *packet,
                                                 const LND_Protocol *proto,
                                                 guint nesting);
    gboolean    libnd_packet_has_proto          (const LND_Packet *packet,
                                                 const LND_Protocol *proto);
    gboolean    libnd_packet_has_proto_nested   (const LND_Packet *packet,
                                                 const LND_Protocol *proto,
                                                 guint nesting);
    LND_ProtoData* libnd_packet_get_last_nonraw (const LND_Packet *packet);
    void        libnd_packet_update_proto_state (LND_Packet *packet,
                                                 int index);
    void        libnd_packet_foreach_proto      (LND_Packet *packet,
                                                 LND_PacketFunc cb,
                                                 void *user_data);
    void        libnd_packet_foreach_proto_backward
                                                (LND_Packet *packet,
                                                 LND_PacketFunc cb,
                                                 void *user_data);
    void        libnd_packet_modified           (LND_Packet *packet);
    int         libnd_packet_get_index          (const LND_Packet *packet);
    int         libnd_packet_get_proto_nesting  (const LND_Packet *packet,
                                                 const LND_Protocol *proto,
                                                 guchar *data);
    gboolean    libnd_packet_fix                (LND_Packet *packet);
    LND_PacketObserver* libnd_packet_observer_new
                                                (void);
    void        libnd_packet_observer_free      (LND_PacketObserver *ob);
    void        libnd_packet_add_observer       (LND_PacketObserver *ob);
    void        libnd_packet_del_observer       (LND_PacketObserver *ob);
    void        libnd_packet_tell_observers     (LND_Packet *packet,
                                                 LND_PacketObserverOp op,
                                                 void *data);

## Description

## Details

### enum LND_PacketObserverOp

    typedef enum {
      LND_PACKET_INITIALIZED  = (1 << 0),    /* Packet got initialized */
      LND_PACKET_MODIFIED     = (1 << 1),    /* Packet got modified */
      LND_PACKET_DELETE_PRE   = (1 << 2),    /* Packet gets deleted (pre-action) */
      LND_PACKET_DELETE_POST  = (1 << 3),    /* Packet got deleted (post-action) */
      LND_PACKET_INSERT_PRE   = (1 << 4),    /* Packet gets inserted (pre-action) */
      LND_PACKET_INSERT_POST  = (1 << 5),    /* Packet got inserted (post-action) */
      LND_PACKET_DUPLICATED   = (1 << 6),    /* Packet got duplicated */
      LND_PACKET_VISIBILITY   = (1 << 7),    /* Packet visibility changed */
      LND_PACKET_UPDATED      = (1 << 8),    /* Packet got updated (partial initialization) */
      LND_PACKET_FIXED        = (1 << 9),    /* Packet checksums got fixed */
      LND_PACKET_LEN_CHANGED  = (1 << 10),   /* Packet's wire size changed */
      LND_PACKET_CAPLEN_CHANGED = (1 << 11), /* Packet's caplen changed */

      /* If you add something here, also add a callback invocation in
       * libnd_packet_tell_observers().
       */
    } LND_PacketObserverOp;

### LND_PacketFunc ()

    gboolean    (*LND_PacketFunc)               (LND_Packet *packet,
                                                 LND_ProtoData *pd,
                                                 void *user_data);

Functions of this signature are used to iterate over the protocols that are contained in packtes. See `libnd_packet_foreach_proto()` and `libnd_packet_foreach_proto_backward()`.

`packet` :

  the packet over whose protocol data is iterated.

`pd` :

  iterated protocol data.

`user_data` :

  arbitrary data passed through to this callback.

Returns :

  TRUE if the iteration is to continue, FALSE on abort.

### libnd_packet_new ()

    LND_Packet* libnd_packet_new                (LND_TracePart *tp,
                                                 guint data_size);

The function creates a packet and returns it. Each packet must belong to a trace. The function does not register the packet in the trace, because a packet could be inserted anywhere.

`tp` :

  trace part the new packet belongs to.

`data_size` :

  amount of payload the new packet holds.

Returns :

  fresh packet.

### libnd_packet_free ()

    void        libnd_packet_free               (LND_Packet *packet);

This function removes `packet` from its trace's packet lists, then frees `packet`.

`packet` :

  packet to delete.

### libnd_packet_remove ()

    void        libnd_packet_remove             (LND_Packet *packet);

`packet` :

### libnd_packet_get_trace ()

    LND_Trace*  libnd_packet_get_trace          (const LND_Packet *packet);

`packet` :

  packet whose trace to return.

Returns :

  the trace that `packet` belongs to, or NULL if `packet` currently belongs to no trace.

### libnd_packet_dump ()

    void        libnd_packet_dump               (const LND_Packet *packet,
                                                 pcap_dumper_t *dumper);

The function writes `packet` to `dumper`. Always use this function when you want to save some packet's content and don't use the data and ph fields yourself, as the resulting saved packet would contain bogus data.

`packet` :

  packet to write.

`dumper` :

  dumper to write to.

### libnd_packet_set_data ()

    void        libnd_packet_set_data           (LND_Packet *packet,
                                                 const struct pcap_pkthdr *hdr,
                                                 const guchar *data);

The function copies the amount of bytes specified by `hdr` into `packet`, starting at `data`. Less is copied if `packet` was created for fewer bytes.

`packet` :

  packet to set content of.

`hdr` :

  pcap header structure.

`data` :

  packet data copied into packet.

### libnd_packet_duplicate ()

    LND_Packet* libnd_packet_duplicate          (LND_Packet *packet);

Returns a deep copy of a packet, but with the list pointers set to NULL (i.e. the copy does not belong to any packet list). It also doesn't belong to any trace part (i.e., packet->part == NULL).

`packet` :

  packet to copy.

Returns :

  packet copy or NULL when error occured.

### libnd_packet_set_filtered ()

    void        libnd_packet_set_filtered       (LND_Packet *packet,
                                                 gboolean filtered);

The function marks the given packet as filtered (if `filtered` is TRUE) or unfiltered (if `filtered` is FALSE).

`packet` :

  packet to (un)filter.

`filtered` :

  filtering status.

### libnd_packet_is_filtered ()

    gboolean    libnd_packet_is_filtered        (LND_Packet *packet);

`packet` :

  packet to query.

Returns :

  TRUE when the packet is currently filtered, FALSE otherwise.

### libnd_packet_init ()

    void        libnd_packet_init               (LND_Packet *packet);

The function initializes a packet, its data offset pointers, and the protocol types for the protcol stack. It cleans up before adjusting internal settings, so you can call this repeatedly without any cleanups etc.

`packet` :

  packet to initialize.

### libnd_packet_init_from_pcap ()

    void        libnd_packet_init_from_pcap     (LND_Packet *packet,
                                                 pcap_t *pcap);

The function initializes a packet using information provided in the given pcap handle. Use this if you want to initialize a standalone packet that is not part of an LND_Trace. Other than that, it's just like `libnd_packet_init()`.

`packet` :

  packet to initialize.

`pcap` :

  pcap handle.

### libnd_packet_is_complete ()

    gboolean    libnd_packet_is_complete        (const LND_Packet *packet);

The predicate returns TRUE if the packet was captured completely (i.e. pcap's caplen == len) and FALSE otherwise.

`packet` :

  packet to check.

Returns :

  completeness result.

### libnd_packet_update ()

    void        libnd_packet_update             (LND_Packet *packet,
                                                 LND_Protocol *proto,
                                                 guint nesting);

This is `libnd_packet_init()`'s little brother. It doesn't initialize the whole packet, but only the part starting at `proto` with nesting level `nesting`.

`packet` :

  packet to update.

`proto` :

  protocol where to start update.

`nesting` :

  at what nesting of `proto` to update.

### libnd_packet_get_data ()

    guchar*     libnd_packet_get_data           (const LND_Packet *packet,
                                                 const LND_Protocol *proto,
                                                 guint nesting);

The function returns a pointer to the packet data containing the start of `proto`'s data at the given nesting level. If the packet doesn't contain any such data, NULL is returned.

`packet` :

  packet to query.

`proto` :

  protocol to look up.

`nesting` :

  nesting level of `proto` to use.

Returns :

  data pointer.

### libnd_packet_get_data_end ()

    guchar*     libnd_packet_get_data_end       (const LND_Packet *packet,
                                                 const LND_Protocol *proto,
                                                 guint nesting);

The function returns a pointer to the first byte after the data containing the start of `proto`'s data at the given nesting level. If the packet doesn't contain any such data, NULL is returned.

`packet` :

  packet to query.

`proto` :

  protocol to look up.

`nesting` :

  nesting level of `proto` to use.

Returns :

  data pointer.

### libnd_packet_add_proto_data ()

    void        libnd_packet_add_proto_data     (LND_Packet *packet,
                                                 LND_Protocol *proto,
                                                 guchar *data,
                                                 guchar *data_end);

Each packet internally maintains a list of data offsets which store info about the protocol type, nesting etc. This function appends a new chunk information to that list. It is called from `libnd_packet_init()` and `libnd_packet_update()`, chances are you want these functions instead.

`packet` :

  packet to update.

`proto` :

  protocol type of data chunk

`data` :

  start of protocol data.

`data_end` :

  first byte of data after protocol data.

### libnd_packet_get_proto_data ()

    LND_ProtoData* libnd_packet_get_proto_data  (const LND_Packet *packet,
                                                 const LND_Protocol *proto,
                                                 guint nesting);

This function is like libnd_packet_get_data, but does not only return the data pointer but the full LND_ProtoData structure, which yields nesting info, data start end end pointers etc.

`packet` :

  packet to query.

`proto` :

  protocol to look up.

`nesting` :

  nesting level for `proto`.

Returns :

  protocol data or NULL if n/a.

### libnd_packet_get_end ()

    guchar*     libnd_packet_get_end            (const LND_Packet *packet);

The function returns a ponter to the byte following the last byte of the captured data.

`packet` :

  packet to query.

Returns :

  data pointer.

### libnd_packet_has_complete_header ()

    gboolean    libnd_packet_has_complete_header
                                                (const LND_Packet *packet,
                                                 const LND_Protocol *proto,
                                                 guint nesting);

The predicate returns TRUE when a packet contains a complete header of the requested protocol, FALSE otherwise. The implementation of the check itself is up to the implementation of `proto`'s plug-in. If you only need to know whether a protocol is present in the packet at all, use `libnd_packet_has_proto()`, which is faster.

`packet` :

  packet to query.

`proto` :

  protocol to check for.

`nesting` :

  nesting level for `proto`.

Returns :

  check result.

### libnd_packet_has_proto ()

    gboolean    libnd_packet_has_proto          (const LND_Packet *packet,
                                                 const LND_Protocol *proto);

The predicate returns TRUE when a packet contains data of the given protocol. It may contain multiple instances of a protocol, but the function only checks if a protocol is present at all. If you need to find out whether a protocol is present at a given nesting level (e.g. whether a packet contains IP in IP), use `libnd_packet_has_complete_header()` or `libnd_packet_has_proto_nested()`.

`packet` :

  packet to query.

`proto` :

  protocol to check for.

Returns :

  check result.

### libnd_packet_has_proto_nested ()

    gboolean    libnd_packet_has_proto_nested   (const LND_Packet *packet,
                                                 const LND_Protocol *proto,
                                                 guint nesting);

The predicate returns TRUE when a packet contains data of the given protocol at the requested nesting level. If you only need to find out whether a protocol is present at all, use `libnd_packet_has_proto()` instead, which is faster.

`packet` :

  packet to query.

`proto` :

  protocol to check for.

`nesting` :

  nesting level of `proto`.

Returns :

  check result.

### libnd_packet_get_last_nonraw ()

    LND_ProtoData* libnd_packet_get_last_nonraw (const LND_Packet *packet);

The function tries to find the innermost protocol in the packet coming before any uninterpreted raw data.

`packet` :

  packet to query.

Returns :

  the protocol data before raw data, if there is both raw data interpreted data coming before it, or NULL if either is missing.

### libnd_packet_update_proto_state ()

    void        libnd_packet_update_proto_state (LND_Packet *packet,
                                                 int index);

`packet` :

`index` :

### libnd_packet_foreach_proto ()

    void        libnd_packet_foreach_proto      (LND_Packet *packet,
                                                 LND_PacketFunc cb,
                                                 void *user_data);

The function iterates over the protocols in the packet, from outer- to the innermost, and calls `cb` with that the corresponding packet, protocol data and `user_data`.

`packet` :

  packet whose protocols to iterate.

`cb` :

  callback to call.

`user_data` :

  arbitrary data passed to `cb`.

### libnd_packet_foreach_proto_backward ()

    void        libnd_packet_foreach_proto_backward
                                                (LND_Packet *packet,
                                                 LND_PacketFunc cb,
                                                 void *user_data);

The function iterates over the protocols in the packet, from inner- to the outermost, and calls `cb` with that the corresponding packet, protocol data and `user_data`.

`packet` :

  packet whose protocols to iterate.

`cb` :

  callback to call.

`user_data` :

  arbitrary data passed to `cb`.

### libnd_packet_modified ()

    void        libnd_packet_modified           (LND_Packet *packet);

The function marks a packet as modified and updates the GUI accordingly.

`packet` :

  packet to mark.

### libnd_packet_get_index ()

    int         libnd_packet_get_index          (const LND_Packet *packet);

The function returns the index of the packet in it's trace, the first packet has index 0.

`packet` :

  packet to query.

Returns :

  index, or -1 if error occurred.

### libnd_packet_get_proto_nesting ()

    int         libnd_packet_get_proto_nesting  (const LND_Packet *packet,
                                                 const LND_Protocol *proto,
                                                 guchar *data);

The function returns the nesting level of `proto` at the given data offset. The first occurrence of a protocol has nesting level 0. So, if you call this for IP and the data pointer points to somewhere in or after the IP header in an ICMP error message, the nesting level will be 1.

`packet` :

  packet to query.

`proto` :

  protocol whose nesting level to find.

`data` :

  data pointer.

Returns :

  nesting level, or -1 when an error occurred.

### libnd_packet_fix ()

    gboolean    libnd_packet_fix                (LND_Packet *packet);

The function calls the fix_packet callback of every protocol that is contained in `packet`, iterating from the inner- to the outermost protocol.

`packet` :

  packet to fix.

Returns :

  TRUE if `packet` got modified, FALSE otherwise.

### libnd_packet_observer_new ()

    LND_PacketObserver* libnd_packet_observer_new
                                                (void);

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

Returns :

  new packet observer with dummy callbacks.

### libnd_packet_observer_free ()

    void        libnd_packet_observer_free      (LND_PacketObserver *ob);

The function releases all memory associated with `ob`.

`ob` :

  observer to delete.

### libnd_packet_add_observer ()

    void        libnd_packet_add_observer       (LND_PacketObserver *ob);

The function registers the new observer for notifications about future changes to packets.

`ob` :

  new observer to register.

### libnd_packet_del_observer ()

    void        libnd_packet_del_observer       (LND_PacketObserver *ob);

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

`ob` :

  observer to drop.

### libnd_packet_tell_observers ()

    void        libnd_packet_tell_observers     (LND_Packet *packet,
                                                 LND_PacketObserverOp op,
                                                 void *data);

`packet` :

`op` :

`data` :

Prev | Home | Next
libnd_null_protocol | Up | libnd_packet_iterator