io.pkts.streams

Interface SipStream

All Superinterfaces:

Stream<SipPacket>

All Known Implementing Classes:

BasicSipStream

public interface SipStream
extends Stream<SipPacket>

Represents a stream of related SIP messages.

Author:

jonas@jonasborjesson.com

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	SipStream.CallState Even though SIP can be used for so much more than just establishing "phone calls" (VoIP) it is commonly used for this very purpose.

Method Summary

Modifier and Type	Method and Description
void	addMessage(SipPacket message) Add a SipPacket to this SipStream.
SipStream	createEmptyClone() Create an empty clone of this SipStream.
SDP	get200OkSDP() Convenience method for returning the SDP found on the 200 OK to the first INVITE request.
SipStream.CallState	getCallState() Which SipStream.CallState the call is in.
long	getDuration() The duration for a SipStream is calculated differently depending on what the stream is capturing.
SDP	getInviteSDP() Convenience method for returning the SDP found on the first INVITE request.
List<SipPacket>	getPackets() Get all the SipPackets that belongs to this Stream.
long	getPostDialDelay() Post Dial Delay (PDD) is defined as the time it takes between the INVITE and until some sort of ringing signal is received (18x responses).
StreamId	getStreamIdentifier() Get the identifier used for grouping the SipPackets together.
boolean	handshakeComplete() Indicates whether the INVITE handshake was completed.
boolean	isTerminated() Check whether this SipStream is in the terminated state, which it is if any of the following is true: For INVITE streams: If the initial handshake failed with an error response (which will include CANCEL scenarios) If the call was successfully established and a BYE request and the corresponding final response has been processed
boolean	reTranmitsDetected() Indicates whether there were retransmissions detected.
void	save(OutputStream out) Save this SipStream to the specified OutputStream.
void	save(String filename) Save this SipStream to the specified file.

Methods inherited from interface io.pkts.streams.Stream

getTimeOfFirstPacket, getTimeOfLastPacket, write

Method Detail

getPackets

List<SipPacket> getPackets()

Get all the SipPackets that belongs to this Stream. Get all Packets that belongs to this stream.

Specified by:

getPackets in interface Stream<SipPacket>

Returns:

isTerminated

boolean isTerminated()

Check whether this SipStream is in the terminated state, which it is if any of the following is true: For INVITE streams:

• If the initial handshake failed with an error response (which will include CANCEL scenarios)
• If the call was successfully established and a BYE request and the corresponding final response has been processed

Returns:

getPostDialDelay

long getPostDialDelay()
               throws SipPacketParseException

Post Dial Delay (PDD) is defined as the time it takes between the INVITE and until some sort of ringing signal is received (18x responses). PDD only applies to INVITE scenarios.

Returns:

the PDD in milliseconds or -1 (negative one) in case it hasn't been calculated yet or because this SipStream is not an INVITE scenario.

Throws:

SipPacketParseException - in case anything goes wrong while trying to calculate the PDD.

getInviteSDP

SDP getInviteSDP()
          throws SipPacketParseException

Convenience method for returning the SDP found on the first INVITE request. Note, if you want to find the SDP for a re-invite, then you will have to getPackets() and find the particular INVITE you are looking for.

Returns:

the SDP found in the first INVITE request or null if no INVITE was found in the stream or if that INVITE simply didn't contain an SDP

Throws:

SipPacketParseException

get200OkSDP

SDP get200OkSDP()
         throws SipPacketParseException

Convenience method for returning the SDP found on the 200 OK to the first INVITE request. Note, if you want to find the SDP for 200 OK to a re-invite, then you will have to getPackets() and find the particular response you are looking for.

Returns:

the SDP found in the first INVITE request or null if no INVITE was found in the stream or if that INVITE simply didn't contain an SDP

Throws:

SipPacketParseException

getStreamIdentifier

StreamId getStreamIdentifier()

Get the identifier used for grouping the SipPackets together. Currently, this is the same as the call-id. Note, perhaps this should be a dialog id instead since ideally that is what we should be using for grouping together SipStreams. On the other hand, using the dialog-id as an identifier can make things messy for forked dialogs etc. This works and keeps things simple so we will stick with it for now.

Specified by:

getStreamIdentifier in interface Stream<SipPacket>

Returns:

getDuration

long getDuration()

The duration for a SipStream is calculated differently depending on what the stream is capturing. For dialogs (INVITE, SUBSCRIBE, REFER) the duration is equal to the duration of the dialog. As such, any re-transmissions of the terminating event etc will NOT be taken into consideration when calculating the duration. However, if the underlying sip stream is not a dialog, then the duration will simply be the time between the first and last message that we recorded. Get the duration in microseconds of the stream. Note, see comment on Packet.getArrivalTime() regarding the microsecond precision. Depending on the underlying protocol this can be as simple as the time between the first to the last packet, which is what the RtpStream does. Or, it can be more complicated as with a SipStream that checks the duration of the dialog (if one was established).

Specified by:

getDuration in interface Stream<SipPacket>

Returns:

the duration (in milliseconds) of this Stream. If the duration cannot be calulated for whatever reason (no packets at all? Only one packet?), then -1 (negative one) will be returned.

getCallState

SipStream.CallState getCallState()

Which SipStream.CallState the call is in. NOTE: this only applies to INVITE dialogs.

Returns:

the current SipStream.CallState.

handshakeComplete

boolean handshakeComplete()

Indicates whether the INVITE handshake was completed. I.e., did we see the ACK to the final response to the INVITE. Note, this does not mean that the call was successfully setup, after all, the INVITE setup can be error out for various reasons.

Returns:

reTranmitsDetected

boolean reTranmitsDetected()

Indicates whether there were retransmissions detected. If it was the INVITE that was re-transmitted, or some other request is not conveyed through this method. It just indicates that there were retransmissions in this flow.

Returns:

save

void save(String filename)
   throws FileNotFoundException,
          IOException

Save this SipStream to the specified file.

Parameters:

filename -

Throws:

FileNotFoundException

IOException

save

void save(OutputStream out)
   throws IOException

Save this SipStream to the specified OutputStream. The difference between this method and Stream.write(OutputStream) is that the latter assumes that the pcap headers etc already have been written to the stream. However, this method will write this SipStream as a standalone pcap.

Parameters:

out -

Throws:

IOException

createEmptyClone

SipStream createEmptyClone()

Create an empty clone of this SipStream. What this means is that you get a SipStream with the same StreamId and underlying PcapGlobalHeader (which you really do not need to know) but otherwise it is empty. I.e., it doesn't contain any SipPackets. Use this method when you e.g. have a SipStream that you want to split in two. A typical scenario is if you have a SipStream that went through a SIP Proxy but you want to split this stream in one "left" side and one "right" side. You do so by figuring out which message belongs to each side and then create two empty clones and then drive the traffic from each side through the new SipStreams. This will then give you two separate SipStream but that still will have the stats available.

Returns:

addMessage

void addMessage(SipPacket message)
         throws IllegalArgumentException,
                SipPacketParseException

Add a SipPacket to this SipStream. By doing so you will force the SipStream to move its internal state machine along since it just "received" a new SipPacket.

Parameters:

message -

Throws:

IllegalArgumentException - in case the message you are trying to add does not have the same StreamId.

SipPacketParseException - in case something goes wrong while parsing the SipPacket