Using testUA

From reSIProcate
Jump to navigation Jump to search

User Agent Tester (testUA) Instructions[edit]

TestUA is a test console for the recon (Conversation Manager) API.


External Dependencies[edit]

  • Codec plug-in DLL's in working directory - codec_*.dll from sipXtapi/sipXmediaLib/bin directory
  • ca.pem file in working directory - contains acceptable root certificate authority (CA) certificates for TURN over TLS


Startup Command Line Parameters[edit]

Command line options are:

  • -?, --?, --help, /? - display command line options
  • -aa - enable autoanswer
 Enabling autoanswer will cause testUA to automatically answer any inbound SIP calls
 and place them in the lowest numbered conversation currently created.
  • -a <IP Address> - bind SIP transports to this IP address
 In general the IP address to bind to is queried from the host OS.  This switch allows
 specification of the IP address for OS's that cannot be queried, or for machines that
 have mulitple NICs.
  • -u <SIP URI> - URI of this SIP user
 This option is used to specify the SIP URI for this instance of testUA.  testUA uses
 this setting (-ip is not specified) in order to find the regisration server.  If 
 nothing is specified, then the default of sip:noreg@<ipaddress> will be used.
  • -p <password> - SIP password of this this SIP user
 Use this switch in cases where the proxy digest challenges sip messaging.
  • -nr - no registration, set this to disable registration with SIP Proxy
 By default, if a SIP uri is specified, testUA will attempt to register with it.  Use 
 this switch to disable this.
  • -d <DNS servers> - comma seperated list of DNS servers, overrides OS detected list
 By default, testUA will query the OS for a list of DNS servers.  Use this option in 
 cases where the OS does not return any, or the correct values.
  • -sp <port num> - local port number to use for SIP messaging (UDP/TCP)
 By default, testUA will use port 5062 for SIP messaging, use this switch to specify
 something different.
  • -mp <port num> - local port number to start allocating from for RTP media
 By default, testUA will use media ports starting at 17384, use this switch to specify
 something different.
  • -tp <port num> - local port number to use for TLS SIP messaging
 By default, testUA will listen for TLS connections on port 5063, use this switch to
 specify something different.  Note SIP certificiates must be present in executable 
 directory for windows hosts and ~/.sipCerts directory on linux hosts.
  • -td <domain name> - domain name to use for TLS server connections
 By default, testUA will query the OS for a local hostname for TLS, use this switch
 to override the OS queried result.
  • -nk - no keepalives, set this to disable sending of keepalives
 By default, testUA will enable UDP CRLF keepalives every 30 seconds and TCP keepalives 
 every 180 seconds.  Use this switch to disable CRLF keepalives.
  • -op <SIP URI> - URI of a proxy server to use a SIP outbound proxy
 By default testUA does not use an outbound proxy.  Use this switch to route all 
 outbound, out-of-dialog requests through a fixed proxy despite the destination URI.
  • -sm <Srtp|SrtpReq|SrtpDtls|SrtpDtlsReq> - sets the secure media mode
 By default, no secure media is offered in outbound SIP requests.  Use this option to
 change that behaviour.  Note:  Inbound secure media is always accepted.
 Srtp     - use SRTP with keying outside of media stream (SDES key negotiation)
            via SDP.  RTP/AVP profile is used, and transport capability of RTP/SAVP is 
            listed, in order to implement best-effort SRTP.  Note:  The crypo attribute
            is provided outside of the SDP capability, as this is required by SNOM for
            optional SRTP offers.
 SrtpReq  - use SRTP with keying outside of media stream (SDES key negotiation)
            via SDP.  RTP/SAVP profile is used to indicate that SRTP is mandatory.
 SrtpDtls - use SRTP with DTLS key negotiation.  RTP/AVP is use as a default, and a 
            transport capability of UDP/TLS/RTP/SAVP is listed, in order to impelement
            best-effort DTLS-SRTP.  
 SrtpDtlsReq - use SRTP with DTLS key negotiation.  UDP/TLS/RTP/SAVP profile is used to
            indicate that Dtls-Srtp use is mandatory.
  • -nm <Bind|UdpAlloc|TcpAlloc|TlsAlloc> - sets the NAT traversal mode
 By default, no NAT traversal strategies are used.  Use this switch to specify one:  
 Bind - use Binding discovery on a STUN server, to discover and use "public" address 
        and port in SDP negotiations
 UdpAlloc - Use a TURN server as a media relay.  Communicate to the TURN
            server over UDP and Allocate a UDP relay address and port to 
            use in SDP negotiations
 TcpAlloc - Use a TURN server as a media relay.  Communicate to the TURN
            server over TCP and Allocate a UDP relay address and port to 
            use in SDP negotiations
 TlsAlloc - Use a TURN server as a media relay.  Communicate to the TURN
            server over TLS and Allocate a UDP relay address and port to 
            use in SDP negotiations
  • -ns <server:port> - set the hostname and port of the NAT STUN/TURN server
 If -nm switch is used then you MUST specify the STUN/TURN server name/address and port.
  • -nu <username> - sets the STUN/TURN username to use for NAT server
 Use this option if the STUN/TURN server requires authentication.
  • -np <password> - sets the STUN/TURN password to use for NAT server
 Use this option if the STUN/TURN server requires authentication.
  • -nl - disables local audio support - removes requirement for local audio hardware.
  Note:  if local audio support is disabled, then local participants cannot be created.
  • -l <NONE|CRIT|ERR|WARNING|INFO|DEBUG|STACK> - logging level
 By default the logging level is INFO, use this switch to change it.


Sample Command line:

 testUA -a 192.168.1.100 -u sip:1000@myproxy.com -p 123 -aa


Console Command Reference[edit]

Once the console is started, testUA will automatically register with a proxy server, if required.

When starting testUA, one Conversation (Handle=1) and one local participant (Handle=1) is automatically created for convienience.

The console then accepts the following commands:

  • createConversation: <'createconv'|'cc'>
 Create a new empty conversation.
  • destroyConversation: <'destroyconv'|'dc'> <convHandle>
 Destroys conversation and ends all participants that solely belong to this conversation.
  • joinConversation: <'joinconv'|'jc'> <sourceConvHandle> <destConvHandle>
 Add all participants from source conversation to destination conversation
 and destroys source conversation.
  • createLocalParticipant: <'createlocal'|'cl'>
 Creates a new local participant.
  • createRemoteParticipant: <'createremote'|'crp'> <convHandle> <destURI> [<'manual'>] (last arg is fork select mode, 'auto' is default)
 Creates a new remote participant (outbound SIP call) in conversation specified.
 Dest URI must be provided.  When ForkSelectMode is set to auto the conversation 
 manager will automatically dispose of any related conversations that were created, 
 due to forking. 
  • createMediaResourceParticipant: <'createmedia'|'cmp'> <convHandle> <mediaURL> [<durationMs>]
 Creates a new media resource participant in the specified conversation.  Media is played 
 from a source specified by the url and may be a local audio file, audio file fetched via 
 HTTP or tones.  The URL can contain parameters that specify properties of the media 
 playback, such as number of repeats.  
 Media Urls are of the following format: 
      	"tone"|"file":<tone|filepath>[;duration=<duration>][;local-only]
                                    [;remote-only][;repeat][;prefetch]
 Tones can be any DTMF digit 0-9,*,#,A-D or a special tone: 
   	dialtone, busy, fastbusy, ringback, ring, backspace, callwaiting, holding, or 
       loudfastbusy
 Note: 'repeat' option only makes sense for file and http URLs
 Note2: 'prefetch' option only makes sense for http URLs
 Note3: audio files may be AU, WAV or RAW formats.  Audiofiles should be 16bit mono, 
        8khz, PCM to avoid runtime conversion.
  • destroyParticipant: <'destroypart'|'dp'> <parthandle>
 Ends connections to the participant and removes it from all active conversations.
  • addPartcipant: <'addpart'|'ap'> <convHandle> <partHandle>
 Adds a participant to an existing conversation.
  • removePartcipant: <'removepart'|'rp'> <convHandle> <partHandle>
 Removes a participant from a conversation.  If the participant no longer exists in 
 any conversation, then they are destroyed (local participants exempt).  For a remote 
 participant this means the call will be released.
  • moveParticipant: <'movepart'|'mp'> <partHandle> <srcConvHandle> <dstConvHandle>
 Removes participant from src conversation and adds them to the dst conversation. 
  • modifyParticipantContribution: <'partcontrib'|'pc'> <convHandle> <partHandle> <inputGain> <outputGain> (gain in percentage)
 Sets a participants input and output gain towards the specified conversation.  
  • outputBridgeMatrix: <'bridgematrix'|'bm'>
 Outputs the sipX mixing bridge matrix for debugging purposes.
  • alertPartcipant: <'alert'|'al'> <partHandle> [<'noearly'>] (last arg is early flag, enabled by default)
 Sends a 180 response to the far end.  If noearly is enabled then SDP is not sent in the 
 response.
  • answerParticipant: <'answer'|'an'> <partHandle>
 Sends a 200 response to the far end.
  • rejectParticipant: <'reject'|'rj'> <partHandle> [<statusCode>]
 Sends the specied response code to the far end.  (default status code is 486)
  • redirectPartcipant: <'redirect'|'rd'> <partHandle> <destURI>
 If unanswered - sends a 302 response to the far end with the destURI in the 
 contact header.  Otherwise sends a REFER request to the far end.
  • redirectToPartcipant: <'redirectTo'|'rt'> <partHandle> <destPartHandle>
 Sends a REFER request to the far end with a 'replaces' header corresponding to the
 partHandle specified.
  • setSpeakerVolume: <'volume'|'sv'> <volume>
  • setMicrophoneGain: <'gain'|'sg'> <gain>
  • muteMicrophone: <'mute'|'mm'> <'0'|'1'> (1 to enable/mute)
  • enableEchoCancel: <'echocancel'|'aec'> <'0'|'1'> (1 to enable)
  • enableAutoGainControl: <'autogain'|'agc'> <'0'|'1'> (1 to enable)
  • enableNoiseReduction: <'noisereduction'|'nr'> <'0'|'1'> (1 to enable)
  • createSubscription: <'subscribe'|'cs'> <eventType> <targetUri> <subTime> <mimeType> <mimeSubType>
 Creates a SIP subscription to the targetURI of the corresponding eventType. 
 Expected mimeType and subType must be specified.
  • destroySubscription: <'destsub'|'ds'> <subHandle>
 Unsubscribes an existing subscription.
  • setAutoAnswer <'autoans'|'aa'> <'0'|'1'> (1 to enable (default)
 Enable this to have testUA automatically answer incoming calls and add to the
 lowest numbered created conversation.
  • setCodecs <'setcodecs'|'sc'> <codecId>[,<codecId>]+ (comma separated list)
 Changes the default codec list/order.  Note a codec plugin must have been 
 present at startup time, in order to use that codec.  Unknown id's are 
 ignored.  Default is: 0,8,96,98,99,108,97,3,109 
 Acceptable sipX codec Ids are:
   0   - G.711 mu-law
   3   - GSM codec
   8   - G.711 a-law
   96  - Speex NB,  8,000bps
   97  - Speex NB,  5,950bps
   98  - Speex NB, 15,000bps
   99  - Speex NB, 24,600bps
   108 - Internet Low Bit Rate Codec - iLBC (RFC3951)
   109 - AVT/DTMF Tones, RFC 2833
  • setSecureMediaMode <'securemedia'|'sm'> <'None'|'Srtp'|'SrtpReq'|'SrtpDtls'|'SrtpDtlsReq'>
 Allows changing the secure media mode at runtime.  Controls what is present
 for secure media in our SDP offers.  Note:  Inbound secure media is always accepted.
 Srtp     - use SRTP with keying outside of media stream (SDES key negotiation)
            via SDP.  RTP/AVP profile is used, and transport capability of RTP/SAVP is 
            listed, in order to implement best-effort SRTP.  Note:  The crypo attribute
            is provided outside of the SDP capability, as this is required by SNOM for
            optional SRTP offers.
 SrtpReq  - use SRTP with keying outside of media stream (SDES key negotiation)
            via SDP.  RTP/SAVP profile is used to indicate that SRTP is mandatory.
 SrtpDtls - use SRTP with DTLS key negotiation.  RTP/AVP is use as a default, and a 
            transport capability of UDP/TLS/RTP/SAVP is listed, in order to impelement
            best-effort DTLS-SRTP.  
 SrtpDtlsReq - use SRTP with DTLS key negotiation.  UDP/TLS/RTP/SAVP profile is used to
            indicate that Dtls-Srtp use is mandatory.
  • setNATTraversalMode <'natmode'|'nm'> <'None'|'Bind'|'UdpAlloc'|'TcpAlloc'|'TlsAlloc'>
 Allows changing the NAT traversal mode at runtime.
 Bind - use Binding discovery on a STUN server, to discover and use "public" address 
        and port in SDP negotiations
 UdpAlloc - Use a TURN server as a media relay.  Communicate to the TURN
            server over UDP and Allocate a UDP relay address and port to 
            use in SDP negotiations
 TcpAlloc - Use a TURN server as a media relay.  Communicate to the TURN
            server over TCP and Allocate a UDP relay address and port to 
            use in SDP negotiations
 TlsAlloc - Use a TURN server as a media relay.  Communicate to the TURN
            server over TLS and Allocate a UDP relay address and port to 
            use in SDP negotiations
  • setNATTraversalServer <'natserver'|'ns'> <server:port>
 Allows changing the STUN/TURN server hostname and port at runtime.
  • setNATUsername <'natuser'|'nu'> <username>
 Allows changing the STUN/TURN username at runtime.
  • setNATPassword <'natpwd'|'np'> <password>
 Allows chaning the STUN/TURN password at runtime.
  • startApplicationTimer: <'starttimer'|'st'> <timerId> <durationMs> <seqNo>
 Test interface for application time API.
  • displayInfo: <'info'|'i'>
 Display information about all of the currently created conversation handles, and
 participant handles.
  • exitProgram: <'exit'|'quit'|'q'>