Channel States
Table of Contents (click to expand)
0. About
A channel (a call) will go through many different states during its lifetime. Here we will describe the different states that a channel might find itself in, and what each of those states mean.
TODO channel states and Call States (see TODO there too) do not seem to be the same though. At least, there is a specific Channel-Call-State header besides the Channel-State header so how are they related? (Not to be confused with CHANNEL_CALLSTATE and CHANNEL_STATE events, although there should a correspondence between them as well. See TODO in Event List's 3.1 CHANNEL_CALLSTATE event section.
1. Channel states
From switch_types.h:
TODO
What is the purpose of Channel-State-Number header? (click to expand)
The associations in in the table below seem to hold, but encountered a Channel-State: CS_REPORTING with Channel-State-Number: 11 in an event (see below), which is kind of confusing. See TODO also in Event List section 3.1 CHANNEL_CALLSTATE event (maybe connected to the main FreeSWITCH core state machine?).
Shell got {event,["26c739fc-8d49-43ee-9c9e-129e81236cd2",
{"Answer-State","hangup"},
{"Call-Direction","inbound"},
{"Caller-ANI","+18083218036"},
{"Caller-Caller-ID-Name","+18083218036"},
{"Caller-Caller-ID-Number","+18083218036"},
{"Caller-Channel-Answered-Time","0"},
{"Caller-Channel-Bridged-Time","0"},
{"Caller-Channel-Created-Time","1575391730378323"},
{"Caller-Channel-Hangup-Time","1575391730378323"},
{"Caller-Channel-Hold-Accum","0"},
{"Caller-Channel-Last-Hold","0"},
{"Caller-Channel-Name", "sofia/signalwire/+18083218036@sip.signalwire.com"},
{"Caller-Channel-Progress-Media-Time","0"},
{"Caller-Channel-Progress-Time","0"},
{"Caller-Channel-Resurrect-Time","0"},
{"Caller-Channel-Transfer-Time","0"},
{"Caller-Context","default"},
{"Caller-Destination-Number","+19162510217"},
{"Caller-Dialplan","XML"},
{"Caller-Direction","inbound"},
{"Caller-Logical-Direction","inbound"},
{"Caller-Network-Addr","104.248.176.184"},
{"Caller-Orig-Caller-ID-Name","+18083218036"},
{"Caller-Orig-Caller-ID-Number","+18083218036"},
{"Caller-Privacy-Hide-Name","false"},
{"Caller-Privacy-Hide-Number","false"},
{"Caller-Profile-Created-Time","1575391730378323"},
{"Caller-Profile-Index","2"},
{"Caller-RDNIS","+19162510217"},
{"Caller-Screen-Bit","true"},
{"Caller-Source","mod_sofia"},
{"Caller-Transfer-Source", "1575391730:bfc8a77b-1c76-4e08-b112-3dce53920bf3:bl_xfer:+19162510217/default/XML"},
{"Caller-Unique-ID","26c739fc-8d49-43ee-9c9e-129e81236cd2"},
{"Caller-Username","+18083218036"},
{"Channel-Call-State","HANGUP"},
{"Channel-Call-UUID","26c739fc-8d49-43ee-9c9e-129e81236cd2"},
{"Channel-HIT-Dialplan","true"},
{"Channel-Name", "sofia/signalwire/+18083218036@sip.signalwire.com"},
{"Channel-State","CS_REPORTING"},
{"Channel-State-Number","12"},
{"Core-UUID","ecd4d804-eb44-45eb-8efe-74205ab97d25"},
{"Event-Calling-File","switch_core_session.c"},
{"Event-Calling-Function", "switch_core_session_perform_destroy"},
{"Event-Calling-Line-Number","1565"},
{"Event-Date-GMT","Tue, 03 Dec 2019 16:48:50 GMT"},
{"Event-Date-Local","2019-12-03 16:48:50"},
{"Event-Date-Timestamp","1575391730378323"},
{"Event-Name","CHANNEL_DESTROY"},
{"Event-Sequence","624"},
{"FreeSWITCH-Hostname","tr2"},
{"FreeSWITCH-IPv4","10.0.0.5"},
{"FreeSWITCH-IPv6","::1"},
{"FreeSWITCH-Switchname","tr2"},
{"Hangup-Cause","NO_ROUTE_DESTINATION"},
{"Presence-Call-Direction","inbound"},
{"Unique-ID","26c739fc-8d49-43ee-9c9e-129e81236cd2"},
{"variable_DP_MATCH","ARRAY::+19162510217|:+19162510217"},
{"variable_answer_epoch","0"},
{"variable_answer_uepoch","0"},
{"variable_answermsec","0"},
{"variable_answersec","0"},
{"variable_answerusec","0"},
{"variable_audio_media_flow","disabled"},
{"variable_billmsec","0"},
{"variable_billsec","0"},
{"variable_billusec","0"},
{"variable_bridge_epoch","0"},
{"variable_bridge_uepoch","0"},
{"variable_call_uuid", "26c739fc-8d49-43ee-9c9e-129e81236cd2"},
{"variable_caller_id","\"+18083218036\" <+18083218036>"},
{"variable_channel_name", "sofia/signalwire/+18083218036@sip.signalwire.com"},
{"variable_current_application","transfer"},
{"variable_current_application_data", "+19162510217 XML default"},
{"variable_digits_dialed","none"},
{"variable_direction","inbound"},
{"variable_duration","0"},
{"variable_end_epoch","1575391730"},
{"variable_end_stamp","2019-12-03 16:48:50"},
{"variable_end_uepoch","1575391730378323"},
{"variable_endpoint_disposition","DELAYED NEGOTIATION"},
{"variable_ep_codec_string", "CORE_PCM_MODULE.PCMU@8000h@20i@64000b,mod_g729.G729@8000h@20i@8000b,mod_opus.opus@48000h@20i@2c,mod_spandsp.G722@8000h@20i@64000b,CORE_PCM_MODULE.PCMA@8000h@20i@64000b"},
{"variable_flow_billmsec","0"},
{"variable_flow_billsec","0"},
{"variable_flow_billusec","0"},
{"variable_hangup_cause","NO_ROUTE_DESTINATION"},
{"variable_hangup_cause_q850","3"},
{"variable_hold_accum_ms","0"},
{"variable_hold_accum_seconds","0"},
{"variable_hold_accum_usec","0"},
{"variable_last_app","transfer"},
{"variable_last_arg","+19162510217 XML default"},
{"variable_last_hold_epoch","0"},
{"variable_last_hold_uepoch","0"},
{"variable_max_forwards","62"},
{"variable_mduration","0"},
{"variable_profile_start_epoch","1575391730"},
{"variable_profile_start_stamp","2019-12-03 16:48:50"},
{"variable_profile_start_uepoch","1575391730378323"},
{"variable_progress_epoch","0"},
{"variable_progress_media_epoch","0"},
{"variable_progress_media_uepoch","0"},
{"variable_progress_mediamsec","0"},
{"variable_progress_mediasec","0"},
{"variable_progress_mediausec","0"},
{"variable_progress_uepoch","0"},
{"variable_progressmsec","0"},
{"variable_progresssec","0"},
{"variable_progressusec","0"},
{"variable_recovery_profile_name","signalwire"},
{"variable_resurrect_epoch","0"},
{"variable_resurrect_uepoch","0"},
{"variable_rtp_secure_media", "optional:AEAD_AES_256_GCM_8:AES_256_CM_HMAC_SHA1_80:AES_CM_128_HMAC_SHA1_80:AES_256_CM_HMAC_SHA1_32:AES_CM_128_HMAC_SHA1_32"},
{"variable_rtp_use_codec_string", "OPUS,G722,PCMU,PCMA,G729,VP8,H264"},
{"variable_session_id","1"},
{"variable_sip_P-Asserted-Identity","+18083218036"},
{"variable_sip_Privacy","none"},
{"variable_sip_call_id", "9f63ade5-908f-1238-4db0-0242ac110002"},
{"variable_sip_cid_type","pid"},
{"variable_sip_contact_host","159.65.253.227"},
{"variable_sip_contact_params", "transport=tls;alias=159.65.253.227~53179~3"},
{"variable_sip_contact_port","35181"},
{"variable_sip_contact_uri", "mod_sofia@159.65.253.227:35181"},
{"variable_sip_contact_user","mod_sofia"},
{"variable_sip_from_display","+18083218036"},
{"variable_sip_from_host","sip.signalwire.com"},
{"variable_sip_from_tag","FS8g4cca771DH"},
{"variable_sip_from_uri","+18083218036@sip.signalwire.com"},
{"variable_sip_from_user","+18083218036"},
{"variable_sip_from_user_stripped","18083218036"},
{"variable_sip_full_from", "\"+18083218036\" <sip:+18083218036@sip.signalwire.com>;tag=FS8g4cca771DH"},
{"variable_sip_full_to", "<sip:+19162510217@sftb-51fcb84cb47e44c1a0683b6c71bb271a.sip.signalwire.com>"}, {"variable_sip_allow", "INVITE, ACK, BYE, CANCEL, OPTIONS, MESSAGE, INFO, UPDATE, REGISTER, REFER, NOTIFY"},
{"variable_sip_full_via", "SIP/2.0/TLS 104.248.176.184:5061;branch=z9hG4bK2ea1.ae886e7a4401a599b1b9decee65b70af.0;i=8199;rport=5061,SIP/2.0/TLS 159.65.253.227:35181;received=159.65.253.227;rport=53179;branch=z9hG4bKHSNBaXU5a882r"},
{"variable_sip_gateway","signalwire"},
{"variable_sip_h_P-SRC-IP","147.75.65.195"},
{"variable_sip_h_X-CID","1560744285_66595977@23.29.27.70"},
{"variable_sip_h_X-Relay-Call-ID", "c7d4eab3-9ebf-4e4e-a7b8-94019ef5620e"},
{"variable_sip_hangup_disposition","send_refuse"}]}
{"variable_sip_invite_record_route", "<sip:104.248.176.184:5061;transport=tls;lr;nat=yes>"},
{"variable_sip_invite_route_uri", "<sip:104.248.176.184:5061;transport=tls;lr;nat=yes>"},
{"variable_sip_invite_stamp","1575391730378323"},
{"variable_sip_local_network_addr","52.229.38.115"},
{"variable_sip_network_ip","104.248.176.184"},
{"variable_sip_network_port","5061"},
{"variable_sip_received_ip","104.248.176.184"},
{"variable_sip_received_port","5061"},
{"variable_sip_req_host","52.229.38.115"},
{"variable_sip_req_params","transport=tls;gw=signalwire"},
{"variable_sip_req_port","6050"},
{"variable_sip_req_uri","gw+signalwire@52.229.38.115:6050"},
{"variable_sip_req_user","gw+signalwire"},
{"variable_sip_to_host", "sftb-51fcb84cb47e44c1a0683b6c71bb271a.sip.signalwire.com"},
{"variable_sip_to_uri", "+19162510217@sftb-51fcb84cb47e44c1a0683b6c71bb271a.sip.signalwire.com"},
{"variable_sip_to_user","+19162510217"},
{"variable_sip_user_agent","SignalWire STACK"},
{"variable_sip_via_host","104.248.176.184"},
{"variable_sip_via_port","5061"},
{"variable_sip_via_protocol","tls"},
{"variable_sip_via_rport","5061"},
{"variable_sofia_profile_name","signalwire"},
{"variable_sofia_profile_url", "sip:mod_sofia@52.229.38.115:6051"},
{"variable_start_epoch","1575391730"},
{"variable_start_stamp","2019-12-03 16:48:50"},
{"variable_start_uepoch","1575391730378323"},
{"variable_switch_r_sdp", "v=0\r\no=SignalWire-STACK 1575372444 1575372445 IN IP4 159.65.253.227\r\ns=SignalWire-STACK\r\nc=IN IP4 159.65.253.227\r\nt=0 0\r\nm=audio 19286 RTP/SAVP 0 18 102 9 8 101 13 103 104\r\na=rtpmap:0 PCMU/8000\r\na=rtpmap:18 G729/8000\r\na=fmtp:18 annexb=no\r\na=rtpmap:102 opus/48000/2\r\na=fmtp:102 useinbandfec=1; maxaveragebitrate=30000; maxplaybackrate=48000; ptime=20; minptime=10; maxptime=40\r\na=rtpmap:9 G722/8000\r\na=rtpmap:8 PCMA/8000\r\na=rtpmap:101 telephone-event/8000\r\na=fmtp:101 0-16\r\na=rtpmap:13 CN/8000\r\na=rtpmap:103 telephone-event/48000\r\na=fmtp:103 0-16\r\na=rtpmap:104 CN/48000\r\na=crypto:1 AEAD_AES_256_GCM_8 inline:5IbCXiK37EXXPsf4a7mCdyuWWyiIYhU4/azzKtY8lwGq0uWXAvCZBjfVPxA=\r\na=crypto:3 AES_256_CM_HMAC_SHA1_80 inline:BFUQfHCY8rgwoQrRG0ljaQZ5xSQLAL0WM/t0vrbvIkrZECuzHl9SWcFd1ISSKA==\r\na=crypto:5 AES_CM_128_HMAC_SHA1_80 inline:6a4cFCTNyoMoqSo557U67ZehZAvhtL0e7+8Iw1Bc\r\na=crypto:6 AES_256_CM_HMAC_SHA1_32 inline:BETh7THI1mZLwEWFdqXKNSjYXOZQpkVizXYkdA1niVGBD1WdwRliqIYAalABfQ==\r\na=crypto:8 AES_CM_128_HMAC_SHA1_32 inline:k/tnVI7h5bh0fmxd+HmE2HyoCccNbyqgr+y6AtM3\r\na=ptime:20\r\n"},
{"variable_text_media_flow","disabled"},
{"variable_transfer_history", "1575391730:bfc8a77b-1c76-4e08-b112-3dce53920bf3:bl_xfer:+19162510217/default/XML"},
{"variable_transfer_source", "1575391730:bfc8a77b-1c76-4e08-b112-3dce53920bf3:bl_xfer:+19162510217/default/XML"},
{"variable_uduration","0"},
{"variable_uuid","26c739fc-8d49-43ee-9c9e-129e81236cd2"},
{"variable_video_media_flow","disabled"},
{"variable_waitmsec","0"},
{"variable_waitsec","0"},
{"variable_waitusec","0"},
Shell got {event,["26c739fc-8d49-43ee-9c9e-129e81236cd2",
{"Answer-State","hangup"},
{"Call-Direction","inbound"},
{"Caller-ANI","+18083218036"},
{"Caller-Caller-ID-Name","+18083218036"},
{"Caller-Caller-ID-Number","+18083218036"},
{"Caller-Channel-Answered-Time","0"},
{"Caller-Channel-Bridged-Time","0"},
{"Caller-Channel-Created-Time","1575391730378323"},
{"Caller-Channel-Hangup-Time","1575391730378323"},
{"Caller-Channel-Hold-Accum","0"},
{"Caller-Channel-Last-Hold","0"},
{"Caller-Channel-Name", "sofia/signalwire/+18083218036@sip.signalwire.com"},
{"Caller-Channel-Progress-Media-Time","0"},
{"Caller-Channel-Progress-Time","0"},
{"Caller-Channel-Resurrect-Time","0"},
{"Caller-Channel-Transfer-Time","0"},
{"Caller-Context","default"},
{"Caller-Destination-Number","+19162510217"},
{"Caller-Dialplan","XML"},
{"Caller-Direction","inbound"},
{"Caller-Logical-Direction","inbound"},
{"Caller-Network-Addr","104.248.176.184"},
{"Caller-Orig-Caller-ID-Name","+18083218036"},
{"Caller-Orig-Caller-ID-Number","+18083218036"},
{"Caller-Privacy-Hide-Name","false"},
{"Caller-Privacy-Hide-Number","false"}]}
{"Caller-Profile-Created-Time","1575391730378323"},
{"Caller-Profile-Index","2"},
{"Caller-RDNIS","+19162510217"},
{"Caller-Screen-Bit","true"},
{"Caller-Source","mod_sofia"},
{"Caller-Transfer-Source", "1575391730:bfc8a77b-1c76-4e08-b112-3dce53920bf3:bl_xfer:+19162510217/default/XML"},
{"Caller-Unique-ID","26c739fc-8d49-43ee-9c9e-129e81236cd2"},
{"Caller-Username","+18083218036"},
{"Channel-Call-State","HANGUP"},
{"Channel-Call-UUID","26c739fc-8d49-43ee-9c9e-129e81236cd2"},
{"Channel-HIT-Dialplan","true"},
{"Channel-Name", "sofia/signalwire/+18083218036@sip.signalwire.com"},
{"Channel-State","CS_REPORTING"},
{"Channel-State-Number","11"},
{"Core-UUID","ecd4d804-eb44-45eb-8efe-74205ab97d25"},
{"Event-Calling-File","switch_channel.c"},
{"Event-Calling-Function", "switch_channel_perform_set_running_state"},
{"Event-Calling-Line-Number","2341"},
{"Event-Date-GMT","Tue, 03 Dec 2019 16:48:50 GMT"},
{"Event-Date-Local","2019-12-03 16:48:50"},
{"Event-Date-Timestamp","1575391730378323"},
{"Event-Name","CHANNEL_STATE"},
{"Event-Sequence","622"},
{"FreeSWITCH-Hostname","tr2"},
{"FreeSWITCH-IPv4","10.0.0.5"},
{"FreeSWITCH-IPv6","::1"},
{"FreeSWITCH-Switchname","tr2"},
{"Hangup-Cause","NO_ROUTE_DESTINATION"},
{"Presence-Call-Direction","inbound"},
{"Unique-ID","26c739fc-8d49-43ee-9c9e-129e81236cd2"},
| State(Channel-State) | State Number(Channel-State-Number) | Description |
|---|---|---|
| CS_NEW | 0 | Channel is newly created. |
| CS_INIT | 1 | Channel has been initialized. |
| CS_ROUTING | 2 | In the routing state, FreeSWITCH hunts through the XML Dialplan. When it finds a condition test that returns true, it builds a to-do list with name–value action pairs, including lists of variables to set and dialplan applications to execute later (such as "bridge"). During this routing state, none of the applications encountered will be executed, except for a limited number that can be run immediately by including the "inline" attribute. |
| CS_SOFT_EXECUTE | 3 | Channel is ready to execute from 3rd party control.TODO How is this different from CS_EXECUTE ? |
| CS_EXECUTE | 4 | The execute state performs the instructions compiled in the routing state. The name–value pairs are parsed and executed. |
| CS_EXCHANGE_MEDIA | 5 | Channel is exchanging media with another channel. |
| CS_PARK | 6 | Channel is accepting media awaiting commands. |
| CS_CONSUME_MEDIA | 7 | Channel is consuming all media and dropping it. |
| CS_HIBERNATE | 8 | Channel is in a sleep state. |
| CS_RESET | 9 | Channel is in a reset state. |
| CS_HANGUP | 10 | Channel is flagged for hangup and ready to end. Media will now end, and no further call routing will occur.The hangup state either transfers the call back to the routing state, if there is a name–value pair that requests it, or else it will hang up the call.TODO The above two sentences contradict each other on the routing part. The second sentence was moved her from Life Cycle of a Call (before it got moved to Call States). |
| CS_REPORTING | 11 | The channel is already hung up, media is already down, and now it's time to do any sort of reporting processes such as CDR logging. |
| CS_DESTROY | 12 | Channel is ready to be destroyed and out of the state machine. Memory pools are returned to the core and utilized memory from the channel is freed. |
| CS_NONE | 13 | TODO What does this do? In the source, it simply calls C's abort(). |
2. State Handlers
Custom state handlers can be added to the channels either globally or on a per-channel basis. This will allow you to do your own custom reporting or clean up your own dynamically created objects, for example. Custom handlers can also be then removed from a channel.
3. See Also
- Channel Variables - specifically the
statevariable - Life Cycle of a Call
- Call States