todo check if there ever would be a case of receiving messages from different transports for the same session. Yes it is possible. UDP to TCP or TLS or back to UDP etc.

A UAS that receives a second INVITE before it sends the final response to a first INVITE with a lower CSeq sequence number on the same dialog MUST return a 500 (Server Internal Error) response to the second INVITE and MUST include a Retry-After header field with a randomly chosen value of between 0 and 10 seconds.

A UAS that receives an INVITE on a dialog while an INVITE it had sent on that dialog is in progress MUST return a 491 (Request Pending) response to the received INVITE.

Reject the request if we have seen thsi CSeq before and there is no transaction found for this request which rules out a retransmission.

this is internally called when the timer is acted upon

Sometimes you create a new session but would like to continue the recording process from previous session for validation purposes. This would typically be used when you drop a leg and create a new one.

 To be called by controller to generate an ACK for 2xx response.

13.2.2.4 The UAC core MUST generate an ACK request for each 2xx received from the transaction layer. The header fields of the ACK are constructed in the same way as for any request sent within a dialog (see Section 12) with the exception of the CSeq and the header fields related to authentication. The sequence number of the CSeq header field MUST be the same as the INVITE being acknowledged, but the CSeq method MUST be ACK. The ACK MUST contain the same credentials as the INVITE. If the 2xx contains an offer (based on the rules above), the ACK MUST carry an answer in its body. If the offer in the 2xx response is not acceptable, the UAC core MUST generate a valid answer in the ACK and then send a BYE immediately .

 Once the ACK has been constructed, the procedures of [4] are used to determine the destination address,
 port and transport.  However, the request is passed to the transport layer directly for transmission,
 rather than a client transaction.  This is because the UAC core handles retransmissions of the ACK,
 not the transaction layer.  The ACK MUST be passed to the client transport every time a
 retransmission of the 2xx final response that triggered the ACK arrives.

To be used only by the controllers on receipt of a response which will be used to figure out if the ACK is for 2xx or non-2xx. If it is required to generate an ACK to a response received previously (not the latest response) then create the ACK using the appropriate method (create_2xx_ack or create_non_2xx_ack) and then send it using session.send

todo check for strict / lax operation waiting for prov. creating only for the INVITE request etc.

Create an initial request, initial request is one which does not have any existing dialog state in sipper. Specifically the new initial request will not have a to tag.

Provided such that it can be used by controllers those are not using the transactions, otherwise this method is invoked from the ICT. 17.1.1.3 The ACK request constructed by the client transaction MUST contain values for the Call-ID, From, and Request-URI that are equal to the values of those header fields in the request passed to the transport by the client transaction (call this the "original request" ). The To header field in the ACK MUST equal the To header field in the response being acknowledged, and therefore will usually differ from the To header field in the original request by the addition of the tag parameter. The ACK MUST contain a single Via header field, and this MUST be equal to the top Via header field of the original request. The CSeq header field in the ACK MUST contain the same value for the sequence number as was present in the original request, but the method parameter MUST be equal to "ACK". If the INVITE request whose response is being acknowledged had Route header fields, those header fields MUST appear in the ACK. This is to ensure that the ACK can be routed properly through any downstream stateless proxies.

Challenge here is the header object of WWW-Authenticate or Proxy-Authenticate header.

Create a new subsequent request. A subsequent request is created either within a dialog or for cases when a request is to be sent after some request was originally sent as an example a CANCEL request. However for generating a CANCEL use helper methods for it like create_cancel or create_and_send_cancel_when_ready

The rip and rp are set by looking at the dialog state, remote target route headers etc. However, if it cannot be ascertained from the message (like name instead of IP/port in RURI or Route) then we default to the rp and rip provided at the time of session creation.

From RFC 3581

  When a server attempts to send a response, it examines the topmost
  Via header field value of that response.  If the "sent-protocol"
  component indicates an unreliable unicast transport protocol, such as
  UDP, and there is no "maddr" parameter, but there is both a
  "received" parameter and an "rport" parameter, the response MUST be
  sent to the IP address listed in the "received" parameter, and the
  port in the "rport" parameter.  The response MUST be sent from the
  same address and port that the corresponding request was received on.
  This effectively adds a new processing step between bullets two and
  three in Section 18.2.2 of SIP 3261

Invoked when the HTTP response is ready to be consumed

Invoked when either the Sipper media response or an actual media event is received.

todo write tests for on_message, on_request, on_response when doing IT

public method called when the timer of this session target is fired

creates a failure response and also rolls back the session state, this is called when the request is rejected by Sipper itself.

A simple operation to create and send a request, initial or subsequent as the case may be.

A simple operation to create and send the response to the request received todo automatically look up reason phrases

3261 Section 8.2 Note that request processing is atomic. If a request is accepted, all state changes associated with it MUST be performed. If it is rejected, all state changes MUST NOT be performed.

This rollback is invoked automatically when Sipper rejects the request before it invokes the controller. The controller can invoke it to rollback any dialog state if it is going to reject the request or alternatively if the compliance flag is set to strict this will automatically be called on request rejection. Note that the snapshot is single-depth state capture, does not save any contained object‘s state.

Useful when you create a subsequent request but do not send it. This resets the state to the time when the request was not created.

13.3.1.4 Once the response has been constructed, it is passed to the INVITE server transaction. Note, however, that the INVITE server transaction will be destroyed as soon as it receives this final response and passes it to the transport. Therefore, it is necessary to periodically pass the response directly to the transport until the ACK arrives. The 2xx response is passed to the transport with an interval that starts at T1 seconds and doubles for each retransmission until it reaches T2 seconds (T1 and T2 are defined in Section 17). Response retransmissions cease when an ACK request for the response is received. This is independent of whatever transport protocols are used to send the response . Since 2xx is retransmitted end-to-end, there may be hops between UAS and UAC that are UDP. To ensure reliable delivery across these hops , the response is retransmitted periodically even if the transport at the UAS is reliable. If the server retransmits the 2xx response for 64*T1 seconds without receiving an ACK, the dialog is confirmed, but the session SHOULD be terminated. This is accomplished with a BYE, as described in Section 15.

The headers which are required to be expressed in their compact form. e.g.

  set_compact_headers [:from, :via]
  shall use the compact form for headers From and Via and the message shall
  look like -
  f: sut <sip:service@127.0.0.1:5060>;tag=azxs21
  To: sipp <sip:sipp@127.0.0.1:6061>;tag=1
  Call-Id: 6766_112@127.0.0.1
  v: SIP/2.0/UDP 127.0.0.1:6061;branch=z9hG4bK-2352-1-0

  In case all possible headers are required in compact form then use
  [:all_headers] as the argument value.
  A complete list of headers with known compact form can be obtained
  from - http://www.iana.org/assignments/sip-parameters

The partial or full list of headers in the order in which the message is to be formatted. In the absense of this the header ordering is arbitrary. e.g.

  set_header_order([:from, :to, :call_id, :via])
  shall format the headers in the order
  ....
  From: sut <sip:service@127.0.0.1:5060>;tag=azxs21
  To: sipp <sip:sipp@127.0.0.1:6061>;tag=1
  Call-Id: 6766_112@127.0.0.1
  Via: SIP/2.0/UDP 127.0.0.1:6061;branch=z9hG4bK-2352-1-0
  ....

once set this setting affects all the messages created by this session.

The media attributes set here shall be used in the next request or response sent from the controller. The argument is an attribute hash and can take the form set_media_attributes(:codec=>["G711U", "DTMF"] :type=>"SENDONLY", :play=>{:file=><file_name>}) set_media_attributes can be called any number of times, as soon as ":codec" can be from of G711U, G711A or DTMF and will be in the form of an array and

         there may be more that one value for it. This can be added or removed at a later
         time with a new set_media_attributes() invocation. If a new codec is added
         then the earlier codec should still be listed in the array. Absense of codec
         from the list would mean that it is being withdrawn from the offers.

":type" can be one of SENDONLY or RECVONLY or SENDRECV ":play" can be hash of {file=> <file_to_play>, repeat=> true|false, duration=> <seconds>} ":play_spec" can be string "PLAY [file] [duration] | PLAY_REPEAT [file] [duration] | SLEEP [duration] | file" ":play_spec" can also be used to send out DTMF like "5,SLEEP 3,6,SLEEP 2,9" note if play_spec is present the play attribute will be ignored ":record_file" is the name of the file to record the incoming stream ":remote_m_line" the selected "m" line from the remote media stream. It can also be selected as the value "any" in which case the system selects the best option from the offer. ":remote_a_line" "a" line corresponding to the m line. This is an array, corresponding to

  the payloads.

"remote_session_a_line" the "a" line (if any) from the session part of SDP. ":remote_c_line" the selected "c" line from session or media for the remote media stream This function can be called repeatedly, when you send out your offer and when to received an answer. As soon as media object has enough information the media is established. As an example you may have set attributes to set your prefered codec, type and what you want to play but do not have the remote information as you may have just sent out the offer. So initially you will set attributes with :codec, :type, :play. Then when you receive the 200 OK you may select a media line of your choice and call set_attributes with :remote_m_line and :remote_c_line. Alternatively you could have selected :remote_m_line as "any" upfront and on getting answer sipper could have selected the best answer from the given options.

the hash of 3 timer values that affect 2xx retransmissions for UAS i.e {:Start=>100, :Cap=>400, :Limit=>1600} that roughly correspond with T1, T2 and 64*T1 respectively, which are also the defaults.

boolean, whether the 2xx retransmission timer is to be used or not for the UAS

e.g. :Ict=>MyIctHandler, :Nict=>MyNictHandler, :Base=>CatchAllHandler

returns the consolidated hash of timers which can be set to the transaction in question by calling SipperUtil.hash_to_iv(@timers, txn) if @timers the type of transactions can be either the names of transactions as @transation_name defined in the transaction or it can be :Base which is the override for all types of transactions.

The timeout happens for IST on TimerH(completed state) and TimerI(confirmed state) expiry For ICT it happens for TimerB expiry when 408 is to be simulated

NICT does not send 408 as per RFC 4320 4.2. Action 2 A transaction-stateful SIP element MUST NOT send a response with Status-Code of 408 to a non-INVITE request. As a consequence, an element that cannot respond before the transaction expires will not send a final response at all. But this is a notification from the transaction to the TU and onwards to the controller.