SIP Tasks Reference

Introduction

This document describes the provided set of SIP tasks. Each task is described below. Before reading about the tasks also take a look at the description of Request Parameters, valid for most of the SIP tasks.

Another important task parameter is the Call Parameter used to simulate multiple Usare Agents.



SipInitTask

SipInitTask controls settings for all SIP tasks following this task within a scenario.

Parameters

Name Description
Client Host Used to control the client/local IP address (source) of all SIP requests sent.
Allocated Client Host Variable Used to save used client server host using specified variable name.
Client Port Used to control the client/local port used. A port number of 0 creates a socket on any free port.
Allocated Client Port Variable Used to save allocated client server port using specified variable name.
SIP Protocol SIP Protocol to be used when SIP requests sent (UDP, TCP or TLS).
TCP and UDP Listener Select to add TCP and UDP listener for incoming requests. By default tasks only listen for incoming requests using the protocol defined by "SIP Protocol" parameter.
Shared Stack Select to share internal SIP stack between all scenarios. See Shared SIP Stack.
Shared Stack User Specify a user or MSISDN (exact or regexp) to accept incoming messages for, leave blank for any. See Shared SIP Stack.
Proxy Host Default SIP Proxy host name or IP address.
Proxy Port Default SIP Proxy port.
Auth. Name Authentication user name to be used for digest authentication. Also used to create default contact parameter
Auth. Password Authentication password to be used for digest authentication.
Preemptive Authentication Select to use preemptive authentication. I.e send authentication header for all SIP tasks when authenticated.
TLS Certificate Path Server side SSL/TSL certificate in PKCS#12 format (see Using TLS).
TLS Certificate Password Server side SSL/TSL certificate password (see Using TLS).


SipCloseTask

Close any connections to SIP proxy and release any resources allocated by the internal SIP stack. Thhis task should always be used last in a scenario with SIP tasks.



SipRegisterTask

Send a SIP REGISTER request and wait  for a non-authenticate response. If authentication is requested by the server, authentication is handled using the authentication parameters provided with SipInitTask.

SipRegisterTask       SIP Server
    | REGISTER F1          |
    |--------------------->|
    | 401 Unauthorized F2  |
    |<---------------------|
    | REGISTER F3          |
    |--------------------->|
    | 200 OK F4            |
    |<---------------------|

Parameters

Name Description
Request URI SIP Request URI. Also see Request Parameters.
To SIP To header URI. Also see Request Parameters.
From SIP From header URI. Also see Request Parameters.
Contact SIP Contact header URI. Also see Request Parameters.
Registrar Host Registrar host name or IP adress (if empty defined proxy host is used).
Registrar Port Registrar host port number (if -1 defined proxy host is used).
Headers List of additional SIP headers to be be used. Specified as name/value pairs.
Response Codes Comma-separated list of valid response status codes. '*' and '?' can be used as wildcards. Empty value means accept all response codes < 400.


SipInviteTask

Send a SIP INVITE request and by default wait for a non-provisional response (provisional responses are ignored).

SipInviteTask     Proxy             UAS
    |                |                |
    | INVITE         |                |
    |--------------->| INVITE         |
    | 100            |--------------->|
    |<---------------|                |
    |                | 180            |
    | 180            |<---------------|
    |<---------------|                |
    |                | 200            |
    | 200            |<---------------|
    |<---------------|                |

To be able to handle situations where a UA is not registered, the task can be controlled to wait and repeat the INVITE requests.

Parameters

Name Description
Request URI SIP Request URI. Also see Request Parameters.
To SIP To header URI. Also see Request Parameters.
From SIP From header URI. Also see Request Parameters.
Contact SIP Contact header URI. Also see Request Parameters.
Max Retries Max number of retry attemts if invited account not registered. I.e number of times to retry sending INVITE if response 404 or 480 is received.
Retry delay Time (in milliseconds) between retries (see above).
Wait for Final Response Select to wait for a final response before the tasks finish execution.
Call String used to identify the created call. Also used to set the Call-ID header. See Call Parameter.
Content Type Describes the media type of the message body. Used to set the Content-Type header if content body specified.
Content The message body.
Headers List of additional SIP headers to be be used. Specified as name/value pairs.
Response Codes Comma-separated list of valid response status codes. '*' and '?' can be used as wildcards. Empty value means accept all response codes < 400.


SipWaitForInviteTask

Wait for a SIP INVITE request. When an INVITE request is received, by default a provisional 180 Ringing response is sent, before the final response.

  UAC             Proxy      SipWaitForInviteTask
   |                |                |
   | INVITE         |                |
   |--------------->| INVITE         |
   | 100            |--------------->|
   |<---------------|                |
   |                | 180            |
   | 180            |<---------------|
   |<---------------|                |
   |                | 200            |
   | 200            |<---------------|
   |<---------------|                |

Parameters

Name Description
Call String used to identify a call. See Call Parameter.
Wait for Headers List of header name/values to wait for. Invite equests not matching the specified headers will be ignored.
The values to match might be a string to match exactly or a regular expression. If multiple headers (with same name) is specified the order also must match.
Contact SIP Contact header URI. Also see Request Parameters.
Content Type Describes the media type of the message body in the final response sent Used to set the Content-Type header if content body specified.
Content The final response message content body.
Send Provisional Response Select to send provisional response when INVITE has been received. If not selected no provisional response is sent (and parameter below ignored).
Provisional response Provisional response status code
Send Final Response Select to send final response when INVITE has been received. If not selected no provisional response is sent (and parameter below ignored).
Response Code Final response status code


SipAckTask

Send a SIP ACK request in response to a previously received SIP INVITE final response. This task doesn't wait for any response.

Parameters

Name Description
Request URI SIP Request URI. Also see Request Parameters.
Call String used to identify an existing call. See Call Parameter.
Content Type Describes the media type of the message body sent. Used to set the Content-Type header if content body specified.
Content The message content body.


SipByeTask

Send a SIP BYE request to terminate a session.

Parameters

Name Description
Call String used to identify an existing call. See Call Parameter.
Wait for Final Response Select to wait for a final response before the tasks finish execution.
Content Type Describes the media type of the message body sent. Used to set the Content-Type header if content body specified.
Content The message content body.
Headers List of additional SIP headers to be be used. Specified as name/value pairs.


SipWaitForRequestTask

Wait for a specified SIP request. Typically used when simulating an UAS waiting for a (Non-Invite) SIP request.

Parameters

Name Description
Call String used to identify an existing call. See Call Parameter.
Wait for Method Wait for specified request method. Empty value means wait for any method.
Wait for Headers List of header name/values to wait for. Requests not matching the specified headers will be ignored.
The values to match might be a string to match exactly or a regular expression. If multiple headers (with same name) is specified the order also must match.
Contact SIP Contact header URI. Also see Request Parameters.
Send Final Response Select to send final response when request has been received. If not selected no provisional response is sent (and parameter below ignored).
Response Code Final response status code
Send 481 Response on OOD Send 481 response on out-of-dialog requests and ignore the received request
Matched Call Variable When matching multiple callsa>, set specified variable to actual matched Call
Ignore Timeout Ignore timeout waiting for request


SipWaitForResponseTask

Wait for a specified SIP response. Typically used when simulating an UAC waiting for a response to a previously sent request request.

Parameters

Name Description
Call String used to identify an existing call. See Call Parameter.
Wait for Method Wait for specified response method.
Wait for Headers List of header name/values to wait for. Responses not matching the specified headers will be ignored.
The values to match might be a string to match exactly or a regular expression. If multiple headers (with same name) is specified the order also must match.
Wait for Final Response Select to wait for final (non-provisional) response.
Wait for Response Codes Comma-separated list of response status codes to wait for. Use -1 to accept all response codes.
Matched Call Variable When matching multiple callsa>, set specified variable to actual matched Call
Ignore Timeout Comma-separated list of response status codes to wait for. Use -1 to accept all response codes.


SipWaitForAnyTask

This task is used to wait for a any SIP request or response. Selecting "Error on Message Received" can be useful to verify that no request or response is received.

Parameters

Name Description
Wait for Final Response Select to wait for a final response, and ignore provisional responses, before the tasks finish execution.
Response Code Response status code
Error on Message Received Consider receiving anything an error.
Ignore retransmissions Ignore any retransmitted messages
Error on Timeout Consider a timeout while waiting for a message an error.
Send 481 Response on OOD Send 481 response on out-of-dialog requests and ignore the received request


SipResponseTask

Send a specified SIP response. Typically used when simulating an UAS after a request has bee sent and we did not select to send a final response.

Parameters

Name Description
Call String used to identify an existing call. See Call Parameter.
Content Type Describes the media type of the message body sent. Used to set the Content-Type header if content body specified.
Content The message content body.
Headers List of additional SIP headers to be be used. Specified as name/value pairs.
Wait for Final Response Select to wait for a final response, and ignore provisional responses, before the tasks finish execution.
Response Code Response status code


SipOptionsTask

Send SIP OPTIONS request.

Parameters

Name Description
Request URI SIP Request URI. Also see Request Parameters.
To SIP To header URI. Also see Request Parameters.
From SIP From header URI. Also see Request Parameters.
Contact SIP Contact header URI. Also see Request Parameters.
Headers List of additional SIP headers to be be used. Specified as name/value pairs.
Wait for Final Response Select to wait for a final response before the tasks finish execution.
Response Codes Comma-separated list of valid response status codes. '*' and '?' can be used as wildcards. Empty value means accept all response codes < 400.


SipMessageTask

Send SIP MESSAGE request.

Parameters

Name Description
Request URI SIP Request URI. Also see Request Parameters.
To SIP To header URI. Also see Request Parameters.
From SIP From header URI. Also see Request Parameters.
Contact SIP Contact header URI. Also see Request Parameters.
Wait for Final Response Select to wait for a final response before the tasks finish execution.
Call String used to identify an existing call. See Call Parameter.
Content Type Describes the media type of the message body. Used to set the Content-Type header if content body specified.
Content The message body.
Headers List of additional SIP headers to be be used. Specified as name/value pairs.
Response Codes Comma-separated list of valid response status codes. '*' and '?' can be used as wildcards. Empty value means accept all response codes < 400.


SipCpmiContentTask

Task used to create CPIM message using the format described in RFC 3862. Typically used in combination with SipMessageTask to create CPMI content.

Message headers must include at least a Content-Type header and Content-Length is automatically generated. If MIME header DateTime specified with empty value, the value is generated automatically.

Parameters

Name Description
CPMI Content Variable Save created CPMI content using specified variable name.
MIME Headers MIME headers, not including Content-Type header
Message Headers Message metadata headers, not including Content-Length (autmatically generated)
Message Content Message content body


SipSubscribeTask

Send SIP SUBSCRIBE request.

Parameters

Name Description
Request URI SIP Request URI. Also see Request Parameters.
To SIP To header URI. Also see Request Parameters.
From SIP From header URI. Also see Request Parameters.
Contact SIP Contact header URI. Also see Request Parameters.
Wait for Final Response Select to wait for a final response before the tasks finish execution.
Call String used to identify a call. See Call Parameter.
Content Type Describes the media type of the message body. Used to set the Content-Type header if content body specified.
Content The message body.
Headers List of additional SIP headers to be be used. Specified as name/value pairs.
Response Codes Comma-separated list of valid response status codes. '*' and '?' can be used as wildcards. Empty value means accept all response codes < 400.


SipNotifyTask

Send SIP NOTIFY request.

Parameters

Name Description
Request URI SIP Request URI. Also see Request Parameters.
To SIP To header URI. Also see Request Parameters.
From SIP From header URI. Also see Request Parameters.
Contact SIP Contact header URI. Also see Request Parameters.
Call String used to identify a call. See Call Parameter.
Headers List of additional SIP headers to be be used. Specified as name/value pairs.
Response Codes Comma-separated list of valid response status codes. '*' and '?' can be used as wildcards. Empty value means accept all response codes < 400.


SipPublishTask

Send SIP PUBLISH request.

Parameters

Name Description
Request URI SIP Request URI. Also see Request Parameters.
To SIP To header URI. Also see Request Parameters.
From SIP From header URI. Also see Request Parameters.
Contact SIP Contact header URI. Also see Request Parameters.
Call String used to identify a call. See Call Parameter.
Content Type Describes the media type of the message body. Used to set the Content-Type header if content body specified.
Content The message body.
Headers List of additional SIP headers to be be used. Specified as name/value pairs.
Response Codes Comma-separated list of valid response status codes. '*' and '?' can be used as wildcards. Empty value means accept all response codes < 400.


SipReferTask

Send SIP REFER request.

Parameters

Name Description
Request URI SIP Request URI. Also see Request Parameters.
To SIP To header URI. Also see Request Parameters.
From SIP From header URI. Also see Request Parameters.
Contact SIP Contact header URI. Also see Request Parameters.
Wait for Final Response Select to wait for a final response before the tasks finish execution.
Call String used to identify an existing call. See Call Parameter.
Content Type Describes the media type of the message body. Used to set the Content-Type header if content body specified.
Content The message body.
Headers List of additional SIP headers to be be used. Specified as name/value pairs.
Response Codes Comma-separated list of valid response status codes. '*' and '?' can be used as wildcards. Empty value means accept all response codes < 400.


SipInfoTask

Send SIP INFO request.

Parameters

Name Description
Wait for Final Response Select to wait for a final response before the tasks finish execution.
Call String used to identify a call. See Call Parameter.
Content Type Describes the media type of the message body. Used to set the Content-Type header if content body specified.
Content The message body.
Headers List of additional SIP headers to be be used. Specified as name/value pairs.
Response Codes Comma-separated list of valid response status codes. '*' and '?' can be used as wildcards. Empty value means accept all response codes < 400.


SipPrackTask

Send SIP PRACK request.

Parameters

Name Description
Wait for Final Response Select to wait for a final response before the tasks finish execution.
Call String used to identify an existing call. See Call Parameter.
Headers List of additional SIP headers to be be used. Specified as name/value pairs.
Response Codes Comma-separated list of valid response status codes. '*' and '?' can be used as wildcards. Empty value means accept all response codes < 400.


SipForkTask

Simulate a SIP "forking". Used to create a new "Call" based on an existing "Call".

Parameters

Name Description
Call String used to identify an existing call.
New Forked Call String used to identify the created "forked" call.


SipUpdateTask

Send SIP UPDATE request.

Parameters

Name Description
Wait for Final Response Select to wait for a final response before the tasks finish execution.
Call String used to identify an existing call. See Call Parameter.
Content Type Describes the media type of the message body. Used to set the Content-Type header if content body specified.
Content The message body.
Headers List of additional SIP headers to be be used. Specified as name/value pairs.
Response Codes Comma-separated list of valid response status codes. '*' and '?' can be used as wildcards. Empty value means accept all response codes < 400.


SipSdpExtractTask

A specialized extract task to extract information from a previous request that returned an SDP (Session Description).

Values to extract are specified using a path based syntax:

    <field-name> [ / <path-element> ]*

Where <path-element> can be a numeric index, sub-filed name or attribute name.

An examples should give an idea how this can be used. Lest say that we have a SDP as follows:

    v=0
    o=alice 2890844526 2890844527 IN IP4 alice.example.com
    s=this session
    c=IN IP4 alice.example.com
    m=message 7394 TCP/MSRP *
    a=accept-types:text/plain
    a=path:msrp://alice.example.com:7394/2s93i;tcp
Extract path Result Comment
o/5 alice.example.com value no 5 (address) of the "o" (Origin) field
s this session the session id
c/1 IP4 value no 1 (address type) of the "c" (Connection Data) field
m/0/2 TCP/MSRP value no 2 (transport) of "m" () field, index 0 (note that the first index indicates index of media description)
m/0/a/accept-types text/plain accept-types attribute ("a") of first media field
m/0/a/path msrp://alice.example.com:7394/2s93i;tcp path attribute ("a") of first media field

Parameters

Name Description
Variable List List of variables and corresponding extract path


SipKeepAliveTask

A task to send keep alive message according to RFC 5626 (section 4.4.1). Keep-alive message is sent to the specified IP address and port and the task blocks until a keep alive response is received.

Only supported for connection oriented transports (TCP or TLS).

Parameters

Name Description
Remote Host Remote host IP address or host name
Remote Port Remote host port


SipHandleOptionsTask

A task to register a background handler that will send response to all received OPTIONS requests.

Note that receive OPTIONS request or sent responses will not be reported in any way other that debug logging.

Parameters

Name Description
Headers Headers to be sent when sending OPTIONS responses.
Response Code Response code to be used for sent OPTIONS responses.


SipHandleNotifyTask

A task to register a background handler that will send response to all received NOTIFY requests.

Note that receives NOTIFY request or sent responses will not be reported in any way other that debug logging.

Parameters

Name Description
Headers Headers to be sent when sending NOTIFY responses.
Response Code Response code to be used for sent NOTIFY responses.