`libnetdude` Manual
Prev |  | Next

# libnd_trace

## Name

libnd_trace --

## Synopsis

    enum        LND_TraceObserverOp;
    #define     area_space_start
    #define     area_space_end
    #define     area_time_start
    #define     area_time_end
    LND_Trace*  libnd_trace_new                 (const char *filename);
    void        libnd_trace_free                (LND_Trace *trace);
    gboolean    libnd_trace_init                (LND_Trace *trace,
                                                 const char *source_file);
    gboolean    libnd_trace_initialized         (const LND_Trace *trace);
    void        libnd_trace_set_iterator_mode   (LND_Trace *trace,
                                                 LND_PacketIteratorMode mode);
    LND_PacketIteratorMode libnd_trace_get_iterator_mode
                                                (const LND_Trace *trace);
    void        libnd_trace_set_area            (LND_Trace *trace,
                                                 LND_TraceArea *area);
    void        libnd_trace_get_area            (LND_Trace *trace,
                                                 LND_TraceArea *area);
    const char* libnd_trace_get_name            (const LND_Trace *trace);
    LND_Packet* libnd_trace_get_packets         (const LND_Trace *trace);
    gboolean    libnd_trace_save                (LND_Trace *trace);
    gboolean    libnd_trace_save_as             (LND_Trace *trace,
                                                 const char *filename);
    void        libnd_trace_delete_hidden_packets
                                                (LND_Trace *trace);
    void        libnd_trace_set_dirty           (LND_Trace *trace,
                                                 gboolean dirty);
    void        libnd_trace_add_filter          (LND_Trace *trace,
                                                 LND_Filter *filter);
    void        libnd_trace_remove_filter       (LND_Trace *trace,
                                                 LND_Filter *filter);
    void        libnd_trace_clear_filters       (LND_Trace *trace);
    gboolean    libnd_trace_has_filter          (LND_Trace *trace,
                                                 LND_Filter *filter);
    guint64     libnd_trace_apply_filters       (LND_Trace *trace);
    gboolean    libnd_trace_sync                (LND_Trace *trace);
    LND_TraceObserver* libnd_trace_observer_new (void);
    void        libnd_trace_observer_free       (LND_TraceObserver *ob);
    void        libnd_trace_add_observer        (LND_TraceObserver *ob);
    void        libnd_trace_del_observer        (LND_TraceObserver *ob);
    void        libnd_trace_tell_observers      (LND_Trace *trace,
                                                 LND_TraceObserverOp op);
    void        libnd_trace_block_packet_observer_op
                                                (LND_Trace *trace,
                                                 LND_PacketObserverOp op);
    void        libnd_trace_unblock_packet_observer_op
                                                (LND_Trace *trace,
                                                 LND_PacketObserverOp op);
    void        libnd_trace_block_trace_observer_op
                                                (LND_Trace *trace,
                                                 LND_TraceObserverOp op);
    void        libnd_trace_unblock_trace_observer_op
                                                (LND_Trace *trace,
                                                 LND_TraceObserverOp op);
    void        libnd_trace_area_init_time      (LND_TraceArea *area,
                                                 struct bpf_timeval *tv_start,
                                                 struct bpf_timeval *tv_end);
    void        libnd_trace_area_init_space     (LND_TraceArea *area,
                                                 double start,
                                                 double end);

## Description

## Details

### enum LND_TraceObserverOp

    typedef enum {
      LND_TRACE_MODIFIED      = (1 << 0), /* Trace got modified */
      LND_TRACE_CLEANED       = (1 << 1), /* Trace dirty bit got cleared */
      LND_TRACE_JUMPED        = (1 << 2), /* Jump to other location occurred */
      LND_TRACE_RELOAD        = (1 << 3), /* New packets loaded into memory */
      LND_TRACE_CLEAR         = (1 << 4), /* Trace's current part got cleared */
      LND_TRACE_IT_AREA_SET   = (1 << 5)  /* Trace's iterator area got set to new value */
    } LND_TraceObserverOp;

### area_space_start

    #define area_space_start un.space.space_start

### area_space_end

    #define area_space_end   un.space.space_end

### area_time_start

    #define area_time_start  un.time.time_start

### area_time_end

    #define area_time_end    un.time.time_end

### libnd_trace_new ()

    LND_Trace*  libnd_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.

`filename` :

  canonical name of the trace file in the filesystem

Returns :

  new trace.

### libnd_trace_free ()

    void        libnd_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.

### libnd_trace_init ()

    gboolean    libnd_trace_init                (LND_Trace *trace,
                                                 const char *source_file);

You can initialize a trace to a different input file using this function.

`trace` :

  trace to initialize.

`source_file` :

  trace file to initialize to.

Returns :

  TRUE when initializiation was successful, FALSE otherwise.

### libnd_trace_initialized ()

    gboolean    libnd_trace_initialized         (const LND_Trace *trace);

The predicate checks whether a trace has been initialized, i.e. `libnd_trace_init_header()` has been called on this trace and its pcap_file_header is thus initialized.

`trace` :

  trace to check

Returns :

  TRUE when the trace has been initialized, FALSE otherwise.

### libnd_trace_set_iterator_mode ()

    void        libnd_trace_set_iterator_mode   (LND_Trace *trace,
                                                 LND_PacketIteratorMode mode);

The function sets the default packet iteration mode of `trace` to `mode`. The default mode is LND_PACKET_IT_AREA_R.

`trace` :

  trace to update.

`mode` :

  iterator mode to use.

### libnd_trace_get_iterator_mode ()

    LND_PacketIteratorMode libnd_trace_get_iterator_mode
                                                (const LND_Trace *trace);

`trace` :

  trace to query.

Returns :

  the currently active iterator mode of `trace`.

### libnd_trace_set_area ()

    void        libnd_trace_set_area            (LND_Trace *trace,
                                                 LND_TraceArea *area);

The function makes the boundaries defined by `area` the new current trace area of `trace`. The memory pointed to by `area` is not used after the function returns -- all values are copied over. It's therefore safe to pass a pointer to an instance sitting on the local stack.

Using a packet iterator on `area`, in LND_PACKET_IT_AREA_R or LND_PACKET_IT_AREA_RW modes will then iterate over the packets within that region. If `area` is a timeframe and that timeframe falls outside the timeframe covered by the packets of `trace`, the boundaries for `trace`'s new active area are adjusted to fall within the existing range.

`trace` :

  trace to set active area for

`area` :

  `trace`'s new active area.

### libnd_trace_get_area ()

    void        libnd_trace_get_area            (LND_Trace *trace,
                                                 LND_TraceArea *area);

The function reports `trace`'s current trace area in the area structure pointed to by `area`.

`trace` :

  trace to obtain area from.

`area` :

  resulting area.

### libnd_trace_get_name ()

    const char* libnd_trace_get_name            (const LND_Trace *trace);

If the trace contains packets from a tracefile, its filename is returned. Otherwise, a dummy name is generated and returned. In both cases, pointers to local data are returned and should be strdupped if you want to keep them around.

`trace` :

  trace to query

Returns :

  trace name.

### libnd_trace_get_packets ()

    LND_Packet* libnd_trace_get_packets         (const LND_Trace *trace);

For each loaded trace, Netdude only stores a certain number of packets in memory at any one time. Use this function to get to the beginning of the current list of packets. This function returns it.

`trace` :

  trace to look up packets in.

Returns :

  first or NULL if n/a.

### libnd_trace_save ()

    gboolean    libnd_trace_save                (LND_Trace *trace);

The trace is saved to disk. If it doesn't have a name yet, libnd_trace_save_as_dialog is called. If saving was successful, TRUE is returned, FALSE otherwise.

`trace` :

  trace to save.

Returns :

  success status.

### libnd_trace_save_as ()

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

The name of the trace is changed and the trace saved subsequentially. If saving was successful, TRUE is returned, FALSE otherwise.

`trace` :

  trace to save.

`filename` :

  new name of the trace.

Returns :

  success status.

### libnd_trace_delete_hidden_packets ()

    void        libnd_trace_delete_hidden_packets
                                                (LND_Trace *trace);

The function iterates over all packets of the trace in the current iteration mode (ie selection only, all local, or entire trace) and drops every hidden packet. See `libnd_packet_hide()` and the filter API.

`trace` :

  trace to delete packets from.

### libnd_trace_set_dirty ()

    void        libnd_trace_set_dirty           (LND_Trace *trace,
                                                 gboolean dirty);

This function sets the dirty state of `trace` and updates the GUI accordingly. If the trace is marked dirty, you cannot close it without confirmation.

`trace` :

  trace to update.

`dirty` :

  whether we're dirty or not.

### libnd_trace_add_filter ()

    void        libnd_trace_add_filter          (LND_Trace *trace,
                                                 LND_Filter *filter);

The function adds `filter` to `trace`. The filter is hooked into a list that stores the filters that should be applied to this trace -- the filter is not duplicated. Also, no checks are made whether the filter already is added.

`trace` :

  trace to add filter to.

`filter` :

  filter added.

### libnd_trace_remove_filter ()

    void        libnd_trace_remove_filter       (LND_Trace *trace,
                                                 LND_Filter *filter);

The function removes `filter` from the list of filters registered for `trace`.

`trace` :

  trace to remove filter from.

`filter` :

  filter removed.

### libnd_trace_clear_filters ()

    void        libnd_trace_clear_filters       (LND_Trace *trace);

The function removes all filters from `trace`.

`trace` :

  trace to remove filters from.

### libnd_trace_has_filter ()

    gboolean    libnd_trace_has_filter          (LND_Trace *trace,
                                                 LND_Filter *filter);

The function scans the filters registered for `trace` and sees whether `filter` is among them. This is a pure pointer comparison, no semantic equality check. However, there should be no need to duplicate instantiated filters.

`trace` :

  trace to query.

`filter` :

  filter to check for.

Returns :

  TRUE when `trace` is using `filter`, FALSE otherwise.

### libnd_trace_apply_filters ()

    guint64     libnd_trace_apply_filters       (LND_Trace *trace);

The filter applies the filters set for `trace` using the filtering mode currently specified for `trace`. The filters are applied to packets based on the current packet iteration mode of `trace` (i.e., selection, part, or entire trace).

`trace` :

  trace to filter.

Returns :

  the number of packets the filters were applied to.

### libnd_trace_sync ()

    gboolean    libnd_trace_sync                (LND_Trace *trace);

The function saves the entire trace to the current output basename, flattening out all currently existing trace parts. The result is a "clean" version of the trace in that file.

`trace` :

  trace to sync.

Returns :

  TRUE if all went well, FALSE on error.

### libnd_trace_observer_new ()

    LND_TraceObserver* libnd_trace_observer_new (void);

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

Returns :

  new observer.

### libnd_trace_observer_free ()

    void        libnd_trace_observer_free       (LND_TraceObserver *ob);

The function releases all memory associated with `ob`.

`ob` :

  observer to delete.

### libnd_trace_add_observer ()

    void        libnd_trace_add_observer        (LND_TraceObserver *ob);

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

`ob` :

  new observer to register.

### libnd_trace_del_observer ()

    void        libnd_trace_del_observer        (LND_TraceObserver *ob);

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

`ob` :

  observer to drop.

### libnd_trace_tell_observers ()

    void        libnd_trace_tell_observers      (LND_Trace *trace,
                                                 LND_TraceObserverOp op);

`trace` :

`op` :

### libnd_trace_block_packet_observer_op ()

    void        libnd_trace_block_packet_observer_op
                                                (LND_Trace *trace,
                                                 LND_PacketObserverOp op);

This function prevents packet modification events of type `op` from being reported to registered observers.

`trace` :

  trace to block event reporting for.

`op` :

  operation to block from being reported.

### libnd_trace_unblock_packet_observer_op ()

    void        libnd_trace_unblock_packet_observer_op
                                                (LND_Trace *trace,
                                                 LND_PacketObserverOp op);

This function allows packet modification events of type `op` to be reported to registered observers.

`trace` :

  trace for which to allow event reporting.

`op` :

  operation to allow being reported.

### libnd_trace_block_trace_observer_op ()

    void        libnd_trace_block_trace_observer_op
                                                (LND_Trace *trace,
                                                 LND_TraceObserverOp op);

This function prevents trace modification events of type `op` from being reported to registered observers.

`trace` :

  trace to block event reporting for.

`op` :

  operation to block from being reported.

### libnd_trace_unblock_trace_observer_op ()

    void        libnd_trace_unblock_trace_observer_op
                                                (LND_Trace *trace,
                                                 LND_TraceObserverOp op);

This function allows trace modification events of type `op` to be reported to registered observers.

`trace` :

  trace for which to allow event reporting.

`op` :

  operation to allow being reported.

### libnd_trace_area_init_time ()

    void        libnd_trace_area_init_time      (LND_TraceArea *area,
                                                 struct bpf_timeval *tv_start,
                                                 struct bpf_timeval *tv_end);

The function initializes the trace area pointed to by `area` to the timeframe bounded by `tv_start` and `tv_end`.

`area` :

  area to initialize.

`tv_start` :

  start time

`tv_end` :

  end time

### libnd_trace_area_init_space ()

    void        libnd_trace_area_init_space     (LND_TraceArea *area,
                                                 double start,
                                                 double end);

The function initializes the trace area pointed to by `area` to the region of packets between the `start` and `end` fractions of the trace.

`area` :

  area to initialize.

`start` :

  start point

`end` :

  end point

Prev | Home | Next
libnd_tpm | Up | Appendix