Netdude Manual
Prev |  | Next

# nd_trace

## Name

nd_trace --

## Synopsis

    enum        ND_TraceLocation;
    void        nd_trace_init                   (void);
    LND_Trace*  nd_trace_new                    (const char *filename);
    void        nd_trace_close                  (LND_Trace *trace);
    void        nd_trace_free                   (LND_Trace *trace);
    ND_Trace*   nd_trace_get                    (const LND_Trace *trace);
    void        nd_trace_add_proto_tab          (LND_Trace *trace,
                                                 LND_Protocol *proto,
                                                 guint nesting);
    void        nd_trace_set_current_proto_selection
                                                (LND_Trace *trace,
                                                 const LND_ProtoInst *pi);
    void        nd_trace_set_current_proto      (LND_Trace *trace,
                                                 const LND_ProtoInst *pi,
                                                 gboolean gui_update);
    LND_ProtoInfo* nd_trace_get_proto_info      (const LND_Trace *trace,
                                                 const LND_Protocol *proto,
                                                 guint nesting);
    LND_ProtoInst* nd_trace_get_current_proto_inst
                                                (const LND_Trace *trace);
    guchar*     nd_trace_get_current_proto_header
                                                (const LND_Trace *trace);
    LND_Packet* nd_trace_get_current_packet     (const LND_Trace *trace);
    void        nd_trace_set_current_packet     (LND_Trace *trace,
                                                 LND_Packet *packet);
    void        nd_trace_load_dialog            (void);
    void        nd_trace_save_as_dialog         (LND_Trace *trace,
                                                 ND_DialogCallback callback_finished,
                                                 void *user_data);
    gboolean    nd_trace_save                   (LND_Trace *trace);
    gboolean    nd_trace_save_as                (LND_Trace *trace,
                                                 const char *filename);
    GtkNotebook* nd_trace_get_notebook          (const LND_Trace *trace);
    void        nd_trace_goto                   (LND_Trace *trace,
                                                 ND_TraceLocation loc);

## Description

## Details

### enum ND_TraceLocation

    typedef enum {
      ND_TRACE_JUMP_TOP,
      ND_TRACE_JUMP_BOTTOM,
      ND_TRACE_JUMP_NEXT,
      ND_TRACE_JUMP_PREV,
      ND_TRACE_JUMP_NEXT_SEL,
      ND_TRACE_JUMP_PREV_SEL,
      ND_TRACE_JUMP_NEXT_PROT,
      ND_TRACE_JUMP_PREV_PROT,
      ND_TRACE_JUMP_NEXT_UNFILTERED,
      ND_TRACE_JUMP_PREV_UNFILTERED,
    } ND_TraceLocation;

### nd_trace_init ()

    void        nd_trace_init                   (void);

### nd_trace_new ()

    LND_Trace*  nd_trace_new                    (const char *filename);

This is the constructor function for new traces. The `filename` is the full name of a trace file. You can pass NULL if you don't want/can provide packet data yet (as in live capture, for example). If a filename is given, the file is checked for existence and readability, if these checks fail, NULL is returned. Otherwise the trace is read into memory and initialized. The trace is NOT automatically added to the trace registry, use `nd_trace_registry_add()` for that purpose.

`filename` :

  canonical name of the trace file in the filesystem

Returns :

  new trace.

### nd_trace_close ()

    void        nd_trace_close                  (LND_Trace *trace);

Safe version of `nd_trace_free()` - if the trace was modified, a dialog is opened that asks for confirmation. Only then the trace is actually removed from the registry and freed.

`trace` :

  trace to close.

### nd_trace_free ()

    void        nd_trace_free                   (LND_Trace *trace);

This function closes the tcpdump connection for this trace and releases the memory it occupies, together with all its packets.

`trace` :

  trace to free.

### nd_trace_get ()

    ND_Trace*   nd_trace_get                    (const LND_Trace *trace);

`trace` :

Returns :

### nd_trace_add_proto_tab ()

    void        nd_trace_add_proto_tab          (LND_Trace *trace,
                                                 LND_Protocol *proto,
                                                 guint nesting);

The function creates the necessary widgets to build a new tab that gets added to the trace's protocols notebook. If there already is a tab for the given protocol/nesting combo, the function does nothing and returns.

`trace` :

  trace to add tab to.

`proto` :

  protocol for which to add a trace.

`nesting` :

  nesting level of protocol.

### nd_trace_set_current_proto_selection ()

    void        nd_trace_set_current_proto_selection
                                                (LND_Trace *trace,
                                                 const LND_ProtoInst *pi);

When browsing through packets in a trace, there is the problem of choosing a protocol to be selected initially (just like you want your cursor to stay in the same column as much as possible in a text editor). Use this function to set that protocol. The protocol instance data is copied internally, so you don't need to allocate `pi`.

`trace` :

  trace to set selection in.

`pi` :

  new protocol instance.

### nd_trace_set_current_proto ()

    void        nd_trace_set_current_proto      (LND_Trace *trace,
                                                 const LND_ProtoInst *pi,
                                                 gboolean gui_update);

This function sets the current protocol in a trace, updating the GUI. It does not influenced the preferred protocol selction which is set using `nd_trace_current_protocol_selection()`. Sometimes it makes sense to not update the GUI immediately, e.g. when you know that another call to this function will follow soon. In this case, set `gui_update` to FALSE. The protocol instance data is copied internally, so you don't need to allocate `pi`.

`trace` :

  trace to set selection in.

`pi` :

  new protocol instance selection.

`gui_update` :

  whether to update the GUI.

### nd_trace_get_proto_info ()

    LND_ProtoInfo* nd_trace_get_proto_info      (const LND_Trace *trace,
                                                 const LND_Protocol *proto,
                                                 guint nesting);

In a trace's protocol notebook, each tab has an associated ND_ProtoInfo structure. This function is used to look up these structures.

`trace` :

  trace to query.

`proto` :

  protocol type to look up.

`nesting` :

  which protocol instance to look up.

Returns :

  protocol info if found, NULL otherwise.

### nd_trace_get_current_proto_inst ()

    LND_ProtoInst* nd_trace_get_current_proto_inst
                                                (const LND_Trace *trace);

This function returns the currently selected protocol of the given trace.

`trace` :

  trace to return current protocol from.

Returns :

  current protocol instance or NULL if n/a.

### nd_trace_get_current_proto_header ()

    guchar*     nd_trace_get_current_proto_header
                                                (const LND_Trace *trace);

This is a convenience function that returns a pointer to the header of the currently selected protocol in the current packet of the given trace. You can then cast this pointer to the appropriate structure. If this function is not applicable, NULL is returned.

`trace` :

  trace to return header from.

Returns :

  pointer to current protocol in current packet.

### nd_trace_get_current_packet ()

    LND_Packet* nd_trace_get_current_packet     (const LND_Trace *trace);

Each trace has a currently selected packet, which may be NULL. This function returns it.

`trace` :

  trace to look up packet in.

Returns :

  current packet or NULL if n/a.

### nd_trace_set_current_packet ()

    void        nd_trace_set_current_packet     (LND_Trace *trace,
                                                 LND_Packet *packet);

This function sets the given packet as the current one in the trace. Normally this could be done with the packet alone (using packet->trace), but this function also allows you to pass NULL as `packet` to unset the current packet. In both cases the GUI is updated accordingly.

`trace` :

  trace to set packet in.

`packet` :

  packet to set as current one.

### nd_trace_load_dialog ()

    void        nd_trace_load_dialog            (void);

### nd_trace_save_as_dialog ()

    void        nd_trace_save_as_dialog         (LND_Trace *trace,
                                                 ND_DialogCallback callback_finished,
                                                 void *user_data);

The function opens a dialog to save `trace`, if the trace got saved after the user closes the dialog, the callback is called with the given `user_data`. This function gets called by `nd_trace_save()` when the trace doesn't yet have a name.

`trace` :

  trace to save.

`callback_finished` :

  callback to call after file is saved.

`user_data` :

  arbitrary data to pass to `callback_finished`.

### nd_trace_save ()

    gboolean    nd_trace_save                   (LND_Trace *trace);

`trace` :

Returns :

### nd_trace_save_as ()

    gboolean    nd_trace_save_as                (LND_Trace *trace,
                                                 const char *filename);

`trace` :

`filename` :

Returns :

### nd_trace_get_notebook ()

    GtkNotebook* nd_trace_get_notebook          (const LND_Trace *trace);

This function provides access to the GTK notebook that contains the protocols for this trace.

`trace` :

  trace to query.

Returns :

  the protocols notebook.

### nd_trace_goto ()

    void        nd_trace_goto                   (LND_Trace *trace,
                                                 ND_TraceLocation loc);

The function selects a new packet in the trace or just scrolls to a different part in the trace, depending on the location specified in `loc`.

`trace` :

  trace to jump around in.

`loc` :

  location to jump to.

Prev | Home | Next
nd_tpm_gui | Up | nd_trace_area_gui