libnd_trace 3 LIBNETDUDE Library libnd_trace 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); LND_TraceObserverOptypedef 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_newLND_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_freevoid 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_initgboolean 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_initializedgboolean 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_modevoid 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_modeLND_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_areavoid 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_areavoid 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_nameconst 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_packetsLND_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_savegboolean 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_asgboolean 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_packetsvoid 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_dirtyvoid 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_filtervoid 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_filtervoid 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_filtersvoid libnd_trace_clear_filters (LND_Trace *trace); The function removes all filters from trace. trace : trace to remove filters from. libnd_trace_has_filtergboolean 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_filtersguint64 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_syncgboolean 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_newLND_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_freevoid libnd_trace_observer_free (LND_TraceObserver *ob); The function releases all memory associated with ob. ob : observer to delete. libnd_trace_add_observervoid 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_observervoid 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_observersvoid libnd_trace_tell_observers (LND_Trace *trace, LND_TraceObserverOp op); trace : op : libnd_trace_block_packet_observer_opvoid 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_opvoid 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_opvoid 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_opvoid 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_timevoid 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_spacevoid 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