[Scamper-dev] skitter/scamper API

[Bradley Huffaker]

Hopefully this will have a more galvanizing effect than David's email did.
I see the code broken down into three objects: FileIO, IpTrace, and IpHop.
I present these as C++ objects for easy, we can always go back to something
else later.

I have added a new field to the Trace object which represents the cycle of the
server.  The cycle counter is a looping counter which when combined with
server and create time should allow traces to be grouped by runs through the
list.  Each server keeps it's own running cycle counter which is increased at
the end of each run though the destination set.  While the cycle counter will
loop I don't see that as a problem since it should be much much larger then
the number of runs a monitor can do in a day.

The trickiest part for me was choosing to go with a STL interface for
IpHop.  Although the number of IpHops will be know, at least for the reader,
using some kind of integer to access them would give the user the impression
that he was accessing the single IpHop that occurred at the integer index.
This simply is not the case.  They can be multiple IpHop objects stored
at the same hop count.
It is also the case that IpHops are stored in the order they were received,
not in the order of increasing TTLs.  While we could sort them it would
not solve the problem of multiple IpHops replying to from the same hop count.

Using a vector interface seems the least likely to present the user with this
false impressions.

FileIO
    boolean Read(istream * readStream);
	This sets the istream that FileIO will search for traces.
    boolean Write(osteam * writeStream);
	This sets the ostream that FileIO will write traces too.

    int ReadTrace(Trace & trace)
	This reads the next Trace in the ostream and returns either:
	    0 - successfully read the trace and updated trace
	    1 - other
	    2 - file error ( corrupted trace found )
	    3 - end of file

    int WriteTrace(const Trace & trace)
	This writes the trace out to the writeStream and returns either: 
	    0 - successfully wrote the trace trace to the ostream
	    1 - other

	For now I will assume that the other case is an error message 
	that the user can get directly from the stream themself.

IpTrace
    static String VersionIDtoString()
	This converts a version ID into a string.

    ------------------------------------------------------------
    -- Duplicate the follow Source operations for Destination --
    ------------------------------------------------------------
    boolean SetSource(const IPv4 source_ip)
    boolean SetSource(const IPv6 source_ip)
	If the AddressFamily passed matches the trace it sets the source and 
	    returns true.
	If the AddressFamily passwd does not match the trace it simply 
	    returns false.

    boolean GetSource(IPv4 & ip);
    boolean GetSource(IPv6 & ip);
	If the AddressFamily passed matches the trace it copy's the source and 
	    returns true.
	If the AddressFamily passwd does not match the trace it simply 
	    returns false.

    ---------------------------------------------------------
    -	Template for remaining access/assignment Functions -
    ---------------------------------------------------------

    void Set<name>(const <type>)
	Sets the <name> of the trace. 
    void Get<name>(<type> & )
	Gets the <name> of the current trace. 
	
    -------------------------------------------------------
    name		type			description
    -------------------------------------------------------
    Version		uint8			the version of IpPath used
						to write the trace.
    AddressFamily	uint8			IPv4 or IPv6 of the trace
    length		uint32			number of bytes needed to
						store the trace.
						although this may not have
						an assignment function

    CreationTime	uint32		the time stamp when the
						source started to prob
						the destination
    DestinationRepliedTime			We currently do not store this
						value.  Do we think we should
						or should creation time be
						close enough?
    DestinationReplied	boolean			true only if a valid
						response was received 
						from the destination
    Rtt			timeval			RTT of the first reply
						from the destination
    HopDistance		uint8			the smallest TTL for which
						a response was received.

    HaltReason		uint8			reason that incremental
						probing was halted
    HaltReasonData	uint8			optional extra data
						that provides more explanation
						of the reason incremental 
						probing was halted
    LoopLength		uint8			length of loop if detected
						  HaltReason = loopDetected
    GapLimit		uint8			the maximum number of 
						non responsive probes used in 
						creation of this trace
						  HaltReason = tllLimitExceeded
    IcmpCode		uint8			ICMP code of packet which
						halted probing
						  HaltReason = icmpUnreachable
						
    -----------------------------------------------------------
    - some possibly useful functions
    -----------------------------------------------------------
    friend ostream & operator << (ostream& os, const & IpTrace);
	This prints a human readable format of the data in the trace.
    
    -----------------------------------------------------------
    - For the reason stated above I choose a vector as the 
    - access interface for the IpHops.
    -----------------------------------------------------------

    inline vector<IpHop> & IpHops()
	Returns the vector for the IpHops stored with this trace.
    void AddHop(const IpHop & IpHop)
	Adds a new IpHop to the end of the vector( or how ever it is storied)

IpHop
    boolean SetIP(const IPv4 ip)
    boolean SetIP(const IPv6 ip)
	If the AddressFamily passed matches the trace it sets the ip and 
	    returns true.
	If the AddressFamily passwd does not match the trace it simply 
	    returns false.


    boolean GetIP(IPv4 & ip);
    boolean GetIP(IPv6 & ip);
	If the AddressFamily passed matches the trace it copy's the ip and 
	    returns true.
	If the AddressFamily passwd does not match the trace it simply 
	    returns false.

    ---------------------------------------------------------
    -	Template for remaining access/assignment Functions -
    ---------------------------------------------------------

    void Set<name>(const <type>)
	Sets the <name> of the trace. 
    void Get<name>(<type> & )
	Gets the <name> of the current trace. 

    -------------------------------------------------------
    name		type			description
    -------------------------------------------------------
    Version		uint8			the version of IpPath used
						to write the trace.
    AddressFamily	uint8			IPv4 or IPv6 of the trace
	    --- not sure if version and AddressFamily are needed,
	    ---	since it should always be the same as IpTrace
    Ttl			uint8			the TTL of the packet
						for which this IP responded
    Rtt			timeval			the RTT of the packet
						that got a response from this
						hop
    -----------------------------------------------------------
    - some possibly useful functions
    -----------------------------------------------------------
    friend ostream & operator << (ostream& os, const & IpTrace);
	This prints a human readable format of the data in the trace.
    
-- 
Bradley Huffaker        Terrorism is the price of Liberty
CAIDA/SDSC/UCSD         Tyranny   is the price of Security