org.echarts.test.sip
Interface SIPAgent

All Known Implementing Classes:

SIPAgentImpl

public interface SIPAgent

SIPAgent serves as the user interface for SIP endpoints in a KitCAT test case. An instance of SIPAgent is created using createAgent factory method in CATTestCase. Once an agent is created, the test writer can perform operations on an agent using the API below. Example operations on an agent are - make a call to another endpoint, answer a call from another endpoint, send DTMF key sequence, etc. The internal implementation of this interface in KitCAT uses a state machine to drive the SIP interaction. Assertions can be performed on agents using the assertThat JUnit primitive that takes in as argument a KitCAT matcher object (see CATMatchers). A SIPAgent is not thread-safe. Only one thread (the main test case runner thread) should access the SIPAgent methods.

Field Summary

static java.lang.String

rcsid

Method Summary

void	addMessageModifier(MessageModifier modifier) Adds a message modifier.
CommandId	answer() Send a 200 OK response to the peer endpoint
CommandId	call(SIPAgent callee) Sends an INVITE with the request URI containing the SipURI of the agent specified in callee
CommandId	call(SIPAgent callee, java.util.Map<java.lang.String,java.util.List<java.lang.String>> headerMap) Sends an INVITE with the request URI containing the SipURI of the agent specified in callee and with the additional headers specified
CommandId	call(SIPAgent callee, java.lang.String fromUri) Sends an INVITE with the request URI containing the SipURI of the agent specified in callee and From header containing the value specified in fromUri.
CommandId	call(java.lang.String calleeUri) Sends an INVITE with the request URI containing the value specified in calleeUri
CommandId	call(java.lang.String sipuri, java.util.Map<java.lang.String,java.util.List<java.lang.String>> headerMap) Sends an INVITE with the request URI containing the value specified in sipuri and with the additional headers specified
CommandId	call(java.lang.String calleeUri, java.lang.String fromUri) Sends an INVITE with the request URI containing the value specified in calleeUri and From header containing the value specified in fromUri.
CommandId	callNoSdp(SIPAgent callee) Variant of call method where no SDP is sent
CommandId	callNoSdp(SIPAgent callee, java.lang.String fromUri) Variant of call method where no SDP is sent
CommandId	callNoSdp(java.lang.String calleeUri) Variant of call method where no SDP is sent
CommandId	callNoSdp(java.lang.String calleeUri, java.lang.String fromUri) Variant of call method where no SDP is sent
CommandId	cancel() Send a CANCEL to the peer endpoint
void	clearMediaBuffer() This primitive clears the internal data structures within a agent used to keep track of the received RTP packets.
void	enableAutoAnswer() Sends a 200 OK response to an incoming INVITE without any explicit answer() command from the test case.
CommandId	end() Send a BYE to the peer endpoint
CommandId	execUserCommand(UserCommand command) Execute user command.
BaseState	getCurrentState() Get the current state of the agent state machine
java.lang.String	getDTMFReceived() Gets the DTMF digits that were received earlier as part of the RTP stream and then stored in a buffer.
java.lang.String	getLastRecvdSDPAsString() Get the last received SDP in string format
java.lang.String	getName() Get the name of the agent
java.lang.String	getProxy() Get the SIP address of the proxy server this agent points to.
java.util.List<Response>	getResponses(CommandId cmdId, int respCode) Returns the list of responses for the request indicated by cmdId and with response code respCode .
java.lang.String	getRTPCaptureFileName() Returns the name of the file in which the RTP packets are captured.
java.lang.String	getRTPIP() Gets the IP address being used for listening in RTP sessions
int	getRTPPort() Gets port number being used for listening in RTP sessions
SipURI	getSipURI() Get the SIP URI of this agent as a SipURI so that it can be used in methods like call, answer.
java.lang.String	getSipURIAsString() Get the SIP URI of this agent as a string so that it can be used in methods like call, answer.
CommandId	info(java.lang.String contentType, java.lang.String contentSubType, java.lang.String content) Send a INFO message to the peer endpoint with the specified content type, content subtype and content.
void	markSDP() Saves the latest SDP received from the peer agent as a result of session negotiation.
void	playAudio(java.io.InputStream stream) Play raw audio from the specified input stream.
void	playAudio(java.lang.String fileName) Play raw audio from the file name specified.
void	printMessageHistory() Print the history of SIP messages received/sent by this agent
void	pushRoute(java.lang.String route) Specify route header(s) that needs to be included as part of an initial INVITE message that may be sent later.
void	pushSelfRoute() Specify a self route header that needs to be sent as part of an initial INVITE message that may be sent later.
void	recycle() Resets the agent and makes it ready for use again even after an end
CommandId	redirect(int redirectCode, Address address) Send a 302 redirect response to the peer endpoint with the specified contact address in the response
CommandId	redirect(int redirectCode, SipURI sipuri) Send a 302 redirect response to the peer endpoint with the specified contact URI in the response
CommandId	redirect(int redirectCode, java.lang.String address) Send a 302 redirect response to the peer endpoint with the specified contact address in the response
CommandId	register(java.lang.String domain, java.lang.String userid, java.lang.String passwd) Sends a REGISTER message.
CommandId	register(java.lang.String domain, java.lang.String userid, java.lang.String passwd, int expires) Sends a REGISTER message.
CommandId	reinvite() Send a re-INVITE to the peer endpoint with no change in SDPs.
CommandId	reinvite(SDPModifier sdpModifier) Send a re-INVITE to the peer endpoint with changes in SDP, the changes specified using the SDPModifier.
CommandId	reinviteHold() Send a re-INVITE to the peer endpoint with a hold SDP (a=sendonly media attribute).
CommandId	reinviteNoSdp() Send a re-INVITE with no SDP to solicit an offer from the peer endpoint.
CommandId	reinviteResume() Send a re-INVITE to the peer endpoint with a normal SDP (a=sendrecv media attribute).
void	removeAllMessageModifiers() Removes all previously added message modifiers.
void	removeMessageModifier(MessageModifier modifier) Removes a previously added message modifier.
CommandId	sendDTMF(java.lang.String keys) Sends DTMF keys to the remote SIP agent with which this agent has already established a SIP dialog and started an RTP session.
CommandId	sendResponse(int responseCode) Send a response to the peer end point with the response code specified as parameter
void	setProxy(java.lang.String proxy) Sets the proxy for this agent.
void	setStepMode(boolean b) Turns on/off user agent step execution mode.
void	step() Takes default action for the most recently received message.
int	waitForRtpAbsence(int silenceDuration, int maxWait) EXPERIMENTAL.
int	waitForRtpPresence(int maxWait) EXPERIMENTAL.

Field Detail

rcsid

static final java.lang.String rcsid

See Also:

Constant Field Values

Method Detail

getName

java.lang.String getName()

Get the name of the agent

Returns:

name of this agent

getProxy

java.lang.String getProxy()

Get the SIP address of the proxy server this agent points to. Returns null if no proxy is set.

Returns:

SIP URI of the proxy server.

getSipURIAsString

java.lang.String getSipURIAsString()
                                   throws CATException

Get the SIP URI of this agent as a string so that it can be used in methods like call, answer.

Returns:

the SIP URI as string

Throws:

CATException - If an exception occured

getSipURI

SipURI getSipURI()
                 throws CATException

Get the SIP URI of this agent as a SipURI so that it can be used in methods like call, answer.

Returns:

the SIP URI

Throws:

CATException - If an exception occured

setProxy

void setProxy(java.lang.String proxy)
              throws CATException

Sets the proxy for this agent. Once a proxy is set, the agent sends all SIP messages to the specified proxy server. This proxy server can be a SIP application server also. Currently we insert a Route header in the outgoing message. If the parameter is not prefixed with a "sip:", internally we prefix it with a "sip:". Moreover, we append a ";lr" parameter to the proxy address.

Throws:

CATException

sendDTMF

CommandId sendDTMF(java.lang.String keys)
                   throws CATException

Sends DTMF keys to the remote SIP agent with which this agent has already established a SIP dialog and started an RTP session. Note that this primitive is not a blocking primitive. The RTP packets are sent in a background thread and the calling thread returns after enqueueing the RTP packets for sending.

Throws:

CATException

register

CommandId register(java.lang.String domain,
                   java.lang.String userid,
                   java.lang.String passwd)
                   throws CATException

Sends a REGISTER message. The request URI in the REGISTER message contains sip:domain, From header contains sip:agentName@domain, To header contains sip:agentName@domain. The userid and passwd parameters are used only for MD5 digest authentication after the agent receives a challenge response. If no authentication is needed, these fields can be empty. The registration expiry time is internally set to 3600. The expiry time is sent in the REGISTER message using an Expiry header although this may be subject to change in the future.

Parameters:

domain - domain for registration

userid - userid for registration

passwd - password for registration

Throws:

CATException

register

CommandId register(java.lang.String domain,
                   java.lang.String userid,
                   java.lang.String passwd,
                   int expires)
                   throws CATException

Sends a REGISTER message. The request URI in the REGISTER message contains sip:domain, From header contains sip:agentName@domain, To header contains sip:agentName@domain. The userid and passwd parameters are used only for MD5 digest authentication after the agent receives a challenge response. If no authentication is needed, these fields can be empty. The specified expiry time is sent in the REGISTER message using an Expiry header although this may be subject to change in the future.

Parameters:

domain - domain for registration

userid - userid for registration

passwd - password for registration

expires - registration expiry

Throws:

CATException

execUserCommand

CommandId execUserCommand(UserCommand command)
                          throws CATException

Execute user command. This method is a generic method for executing user-specified commands. Most of the frequently used commands are supported by specific primitives - e.g call, answer, cancel. This method is useful in the context of a user-specified agent machine which executes user-specified commands. Implementation of primitives like call, answer etc. internally uses this method to pass on the command to the agent state machine. The command object in the argument to this method is directly passed to the agent machine. Unless the machine is designed to handle this command, it will throw an exception

Throws:

CATException

pushRoute

void pushRoute(java.lang.String route)
               throws CATException

Specify route header(s) that needs to be included as part of an initial INVITE message that may be sent later.

agent1.pushRoute("sip:R1.abc.com;lr");
agent1.pushRoute("sip:R2.xyz.com;lr");
agent1.pushSelfRoute();

The above example will result in the following route headers in the initial INVITE message

Route: <sip:thisagent@this.host;lr>,
<sip:R2.xyz.com;lr>,
<sip:R1.abc.com;lr>

Note that using the setProxy method adds another route header to the specified proxy at the very top. In the above example, the addition of the following statement

agent.setProxy("proxy.lmn.com");

results in the addition of a route header to the proxy as the very first route header irrespective of the relative ordering of the setProxy and the pushRoute calls. The resulting route headers will be as follows:

Route: <sip:proxy.lmn.com;lr>,
<sip:thisagent@this.host;lr>,
<sip:R2.xyz.com;lr>,
<sip:R1.abc.com;lr>


Throws:

CATException

pushSelfRoute

void pushSelfRoute()
                   throws CATException

Specify a self route header that needs to be sent as part of an initial INVITE message that may be sent later.

Throws:

CATException

call

CommandId call(java.lang.String calleeUri)
               throws CATException

Sends an INVITE with the request URI containing the value specified in calleeUri

Throws:

CATException

call

CommandId call(java.lang.String calleeUri,
               java.lang.String fromUri)
               throws CATException

Sends an INVITE with the request URI containing the value specified in calleeUri and From header containing the value specified in fromUri.

Throws:

CATException

call

CommandId call(SIPAgent callee)
               throws CATException

Sends an INVITE with the request URI containing the SipURI of the agent specified in callee

Throws:

CATException

call

CommandId call(SIPAgent callee,
               java.lang.String fromUri)
               throws CATException

Sends an INVITE with the request URI containing the SipURI of the agent specified in callee and From header containing the value specified in fromUri.

Throws:

CATException

call

CommandId call(SIPAgent callee,
               java.util.Map<java.lang.String,java.util.List<java.lang.String>> headerMap)
               throws CATException

Sends an INVITE with the request URI containing the SipURI of the agent specified in callee and with the additional headers specified

Throws:

CATException

call

CommandId call(java.lang.String sipuri,
               java.util.Map<java.lang.String,java.util.List<java.lang.String>> headerMap)
               throws CATException

Sends an INVITE with the request URI containing the value specified in sipuri and with the additional headers specified

Throws:

CATException

callNoSdp

CommandId callNoSdp(java.lang.String calleeUri)
                    throws CATException

Variant of call method where no SDP is sent

Throws:

CATException

callNoSdp

CommandId callNoSdp(java.lang.String calleeUri,
                    java.lang.String fromUri)
                    throws CATException

Variant of call method where no SDP is sent

Throws:

CATException

callNoSdp

CommandId callNoSdp(SIPAgent callee)
                    throws CATException

Variant of call method where no SDP is sent

Throws:

CATException

callNoSdp

CommandId callNoSdp(SIPAgent callee,
                    java.lang.String fromUri)
                    throws CATException

Variant of call method where no SDP is sent

Throws:

CATException

reinvite

CommandId reinvite()
                   throws CATException

Send a re-INVITE to the peer endpoint with no change in SDPs. This call is permitted only when this agent is already in a SIP dialog, otherwise it will throw an exception.

Throws:

CATException

reinviteHold

CommandId reinviteHold()
                       throws CATException

Send a re-INVITE to the peer endpoint with a hold SDP (a=sendonly media attribute).

Throws:

CATException

reinviteResume

CommandId reinviteResume()
                         throws CATException

Send a re-INVITE to the peer endpoint with a normal SDP (a=sendrecv media attribute).

Throws:

CATException

reinvite

CommandId reinvite(SDPModifier sdpModifier)
                   throws CATException

Send a re-INVITE to the peer endpoint with changes in SDP, the changes specified using the SDPModifier. This call is permitted only when this agent is already in a SIP dialog, otherwise it will throw an exception.

Throws:

CATException

reinviteNoSdp

CommandId reinviteNoSdp()
                        throws CATException

Send a re-INVITE with no SDP to solicit an offer from the peer endpoint. This call is permitted only when this agent is already in a SIP dialog, otherwise it will throw an exception.

Throws:

CATException

sendResponse

CommandId sendResponse(int responseCode)
                       throws CATException

Send a response to the peer end point with the response code specified as parameter

Throws:

CATException

cancel

CommandId cancel()
                 throws CATException

Send a CANCEL to the peer endpoint

Throws:

CATException

answer

CommandId answer()
                 throws CATException

Send a 200 OK response to the peer endpoint

Throws:

CATException

redirect

CommandId redirect(int redirectCode,
                   java.lang.String address)
                   throws CATException

Send a 302 redirect response to the peer endpoint with the specified contact address in the response

Throws:

CATException

redirect

CommandId redirect(int redirectCode,
                   SipURI sipuri)
                   throws CATException

Send a 302 redirect response to the peer endpoint with the specified contact URI in the response

Throws:

CATException

redirect

CommandId redirect(int redirectCode,
                   Address address)
                   throws CATException

Send a 302 redirect response to the peer endpoint with the specified contact address in the response

Throws:

CATException

end

CommandId end()
              throws CATException

Send a BYE to the peer endpoint

Throws:

CATException

recycle

void recycle()
             throws CATException

Resets the agent and makes it ready for use again even after an end

Throws:

CATException

info

CommandId info(java.lang.String contentType,
               java.lang.String contentSubType,
               java.lang.String content)
               throws CATException

Send a INFO message to the peer endpoint with the specified content type, content subtype and content.

Throws:

CATException

getCurrentState

BaseState getCurrentState()

Get the current state of the agent state machine

clearMediaBuffer

void clearMediaBuffer()

This primitive clears the internal data structures within a agent used to keep track of the received RTP packets. This is especially useful in re-INVITE scenarios where we want to check media connectivity after the re-INVITE. Typically this is used as follows:

//assume agent1 and agent2 are in a call
agent1.clearMediaBuffer();
agent2.playAudio("hello.raw");
processSIP(3000);
assertThat(agent1, has (incomingMedia()));

In the above example, we clear the media buffer in agent1 first and send audio packets to agent1. Then we assert whether any RTP packets were received by agent1. Irrespective of calls to this primitive, all the RTP packets received by an agent over its lifetime are stored in an agent-specific disk file.

playAudio

void playAudio(java.lang.String fileName)
               throws CATException

Play raw audio from the file name specified. Note that this primitive is not a blocking primitive. The RTP packets are sent in a background thread and the calling thread returns after enqueueing the RTP packets for sending.

Throws:

CATException

playAudio

void playAudio(java.io.InputStream stream)
               throws CATException

Play raw audio from the specified input stream.

Throws:

CATException

addMessageModifier

void addMessageModifier(MessageModifier modifier)
                        throws CATException

Adds a message modifier. You could chain message modifiers together. The invocation order will be the same as the order in which the modifiers were added. One possible use (e.g. HeaderAddHelper) of this method is to add user-defined headers to ALL messages that are sent out by an agent to which this modifier is added. For each message that is sent out, this modifier gets invoked and this modifier adds the specified headers to the message. To specify additional headers only during call establishment, use the call method with header map argument.

Throws:

CATException

removeMessageModifier

void removeMessageModifier(MessageModifier modifier)
                           throws CATException

Removes a previously added message modifier.

Throws:

CATException

removeAllMessageModifiers

void removeAllMessageModifiers()
                               throws CATException

Removes all previously added message modifiers.

Throws:

CATException

printMessageHistory

void printMessageHistory()

Print the history of SIP messages received/sent by this agent

getLastRecvdSDPAsString

java.lang.String getLastRecvdSDPAsString()

Get the last received SDP in string format

markSDP

void markSDP()

Saves the latest SDP received from the peer agent as a result of session negotiation. This will be used later in matchers like CATMatchers.recvdNewSDP().

getRTPIP

java.lang.String getRTPIP()

Gets the IP address being used for listening in RTP sessions

getRTPPort

int getRTPPort()

Gets port number being used for listening in RTP sessions

setStepMode

void setStepMode(boolean b)
                 throws java.lang.Exception

Turns on/off user agent step execution mode. By default, the step execution mode is turned off and the following tasks are performed implicitly by an agent machine:

1. UAS sends 200 OK response to an incoming BYE
2. UAC sends ACK response to an incoming 2xx response to an INVITE
3. UAS sends 200 OK response to an incoming re-INVITE and the UAC subsequently sends an ACK
4. UAS sends 200 OK response to an incoming INFO
5. UAC sends a new INVITE after getting a redirect response

When the step execution mode is turned on, the agent machine requires explicit instructions from the test case to perform the above tasks. When this mode is turned on, the agent machine execution is similar to that of execution within a debugger with breakpoints set. In this case, a "breakpoint" is an execution state in the agent's execution, where the agent usually does one of the above tasks by default. For example, under the step execution mode, when a BYE is received a 200 OK is NOT sent automatically. Instead, the execution has reached a "breakpoint" and the agent waits for an explicit instruction from the test case to proceed further. Once this explicit instruction is received from the test case, the agent proceeds with execution (a "step") until it hits the next "breakpoint". Turning this mode off amounts to clearing all the "breakpoints" and continue default execution. In this test below, we want to test a scenario where a callee sends an error response to a BYE from the caller. In the default execution mode, a 200 OK is automatically sent in response to a BYE. To change this default behavior, we make use of the step execution mode and then send a 500 error response to a BYE instead.

SIPAgent caller = createAgent("caller");
SIPAgent callee = createAgent("callee");
CommandId inv = caller.call(callee);
processSIP(1000);
assertThat(callee, invited());
callee.answer();
processSIP(1000);
assertThat(callee, connectedTo(caller));
//from this point on, turn on step execution mode
//for callee
callee.setStepMode(true);
CommandId cmd = caller.end();
processSIP(1000);
assertThat(callee, recvdRequest("BYE"));
//send a error response to the BYE.
caller.sendResponse(500);
processSIP(1000);
assertThat(caller, recvdResponse(cmd, 500));


The test below illustrates how setStepMode(false) causes the default execution to resume.


//from this point on, turn on step execution mode
//for callee
callee.setStepMode(true);
CommandId cmd = caller.end();
processSIP(1000);
assertThat(callee, recvdRequest("BYE"));
//resume default execution. this causes callee to
//send a default 200 OK response to the BYE.
callee.setStepMode(false);
processSIP(1000);
assertThat(caller, recvdResponse(cmd, 200));


Throws:

java.lang.Exception

step

void step()
          throws java.lang.Exception

Takes default action for the most recently received message. If there is no default action to be performed, then this amounts to a no-op. This method should be used only in the context of a step execution mode (setStepMode(boolean)(true)). Invoking this method causes an agent to proceed with default execution until the next "breakpoint".

......caller connected to callee at this point.......
//from this point on, turn on step execution mode
//for callee
callee.setStepMode(true);
CommandId cmd = caller.end();
processSIP(1000);
assertThat(callee, recvdRequest("BYE"));
//perform default execution which sends a 200
//OK response to BYE
caller.step();
processSIP(1000);
assertThat(caller, recvdResponse(cmd, 200));
//resume default execution for callee
callee.setStepMode(false);


Throws:

java.lang.Exception

getRTPCaptureFileName

java.lang.String getRTPCaptureFileName()

Returns the name of the file in which the RTP packets are captured.

getResponses

java.util.List<Response> getResponses(CommandId cmdId,
                                      int respCode)

Returns the list of responses for the request indicated by cmdId and with response code respCode .

enableAutoAnswer

void enableAutoAnswer()

Sends a 200 OK response to an incoming INVITE without any explicit answer() command from the test case.

getDTMFReceived

java.lang.String getDTMFReceived()

Gets the DTMF digits that were received earlier as part of the RTP stream and then stored in a buffer. This method also clears the buffer. This method is useful while testing IVR systems that send DTMF as part of the audio stream to the test system (from the SUT to the test case) and the test case needs to find out what DTMF sequence the SUT sent.

waitForRtpAbsence

int waitForRtpAbsence(int silenceDuration,
                      int maxWait)
                      throws CATException

EXPERIMENTAL. SUBJECT TO CHANGE. USE AT YOUR OWN RISK.

Wait for absence of incoming RTP packets for a minimum duration specified by silenceDuration. On reaching the maxWait duration, returns -1, else returns 0.

Throws:

CATException

waitForRtpPresence

int waitForRtpPresence(int maxWait)
                       throws CATException

EXPERIMENTAL. SUBJECT TO CHANGE. USE AT YOUR OWN RISK.

Wait for presence of incoming RTP packets. On reaching the maxWait duration, returns -1, else returns 0.

Throws:

CATException