Asterisk cmd ChanIsAvail

Synopsis

Check if channel is available

Description

ChanIsAvail (Technology/resource[&Technology2/resource2...][|options])

Checks if any of the requested channels are available.

Note that the AVAILSTATUS variable is used for both device state and cause code. It is therefore possible for it to give a value that may indicate a device is available when it is not. It is suggested that the AVAILORIGCHAN variable is used instead to see whether a device is available or not.
New in Asterisk 1.8: The ChanIsAvail application now exposes the returned cause code using a separate variable, AVAILCAUSECODE, instead of overwriting the device state in AVAILSTATUS

The following variables will be set by this application:

  • ${AVAILCHAN} - the name of the available channel, if one exists
  • ${AVAILORIGCHAN} - the canonical channel name that was used to create the channel

  • ${AVAILSTATUS} - the status code for the available channel (see "devicestate.c")
    • 0 AST_DEVICE_UNKNOWN - "Unknown"; channel is valid, but unknown state.
    • 1 AST_DEVICE_NOT_INUSE - "Not in use"
    • 2 AST_DEVICE IN USE - "In use"; channel is in use.
    • 3 AST_DEVICE_BUSY - "Busy"; channel is busy.
    • 4 AST_DEVICE_INVALID - "Invalid", not known to Asterisk.
    • 5 AST_DEVICE_UNAVAILABLE - "Unavailable"; channel is unavailable (not registred)
    • 6 AST_DEVICE_RINGING - "Ringing"; ring, ring, ring (someone is calling us), or
    • 6 AST_CAUSE_CHANNEL_UNACCEPTABLE (as cause code)
    • 7 AST_DEVICE_RINGINUSE "Ring+Inuse"; channel rings (outbound) and is in use
    • 8 AST_DEVICE_ONHOLD "On Hold"; channels is on hold
    • ...
    • 20 AST_CAUSE_SUBSCRIBER_ABSENT (as cause code)
    • ...

The application returns "both a device state and a cause code". This behaviour is probably bad since cause codes and device states overlap in name-space (i.e. they both have values from 0 through 9 which collide).

Options (new in Asterisk v1.2?):

s - Consider the channel unavailable if the channel is in use at all (buggy with SIP, always returning 0?!)
j - Support jumping to priority n+101 if no channel is available

Details

Currently, ChanIsAvail only works with ZAP, IAX2, mISDN, Skinny and SIP channels. MGCP channels are not supported. If none of the requested channels are available the new priority will be n+101 (unless such a priority does not exist).
If any of the requested channels are available, the next priority will be n+1, the channel variable ${AVAILCHAN} will be set to the name of the available channel.

The channels are checked in the order listed, returning the first available channel in the list in ${AVAILCHAN}.

Note that ChanIsAvail() returns not only the name of the channel in $AVAILCHAN, but also appends the channel's session ID. You will probably need to strip the session ID off, as illustrated in the example below.

SIP, IAX

ChanIsAvail is not a solution to tell you conclusively whether the channel is busy or not, it is primarily to tell you whether it would be possible to send a call there. Whether that call would end up being accepted or not is entirely up to the peer that we send the call to, and they could easily reject the call even though they do not appear to be 'busy'.
So: If you want to use ChanIsAvail to determine whether the SIP peer is known and registered, it will work fine. If you want to use it for limiting simultaneous calls to the peer, it will not work reliably for you.

For telling if Sip peers are online or not, when you are using qualify, then you may wish to just use the SipPeer('name':status) function, and jump based on that. ChanIsAvail doesn't seem to tell you the difference between a Sip peer that's online, and one that's offline. Example snippet:

exten => s,n,Set(VOIPCHECK=0)
exten => s,n,Set(PEERCHECK1=myprovider-out) ; SIP peer name as defined in sip.conf
; Make sure to have qualify=yes enabled for this SIP peer!
exten => s,n,NoOp(-- ${PEERCHECK1} status: ${SIPPEER(${PEERCHECK1}:status)} --)
exten => s,n,ExecIf($["${SIPPEER(${PEERCHECK1}:status):0:2}" = "OK"]|Set|VOIPCHECK=1)
; Now route and dial any way you like based on the value of VOIPCHECK

If you are not using Realtime you could also check the SIP/Registry tree of AstDB for the peer in questions, for example with the help of the Asterisk func DB_EXIST function.

Example


; See if line 2 is available. If not, try line 1.
exten => s,1,ChanIsAvail(Zap/2&Zap/1)

${AVAILCHAN} might now contain the value
Zap/2-1
; We need to strip off the session ID and Dial '12345678' at Zap/2
exten => s,2,Dial(${CUT(AVAILCHAN||1)}/12345678)
exten => s,3,Hangup

; If neither line 2 nor line 1 is available, play a message
exten => s,102,Playback(all-circuits-busy-now)
exten => s,103,Hangup^



User comments

SIP and ChanIsAvail (Dec 2005)

According to bug 4506 Chanisavail is not intended to detect if a phone is in use or not at all, it's only intended to check if asterisk could send the call there.
I tried using call-limit and Chanisavail, but it's broken in SIP. inuse gets applied only to peers, and when it gets an incoming call that is not answered it gets decremented and doesnt stay the same, which is a bug.
You should consider using groups instead

Limit incoming calls using DEVICE_STATE and Asterisk 1.6

To limit incoming simultaneous calls to the peer, try DEVICE_STATE.

See also



Asterisk | Applications | Functions | Variables | Expressions | Asterisk FAQ

Synopsis

Check if channel is available

Description

ChanIsAvail (Technology/resource[&Technology2/resource2...][|options])

Checks if any of the requested channels are available.

Note that the AVAILSTATUS variable is used for both device state and cause code. It is therefore possible for it to give a value that may indicate a device is available when it is not. It is suggested that the AVAILORIGCHAN variable is used instead to see whether a device is available or not.
New in Asterisk 1.8: The ChanIsAvail application now exposes the returned cause code using a separate variable, AVAILCAUSECODE, instead of overwriting the device state in AVAILSTATUS

The following variables will be set by this application:

  • ${AVAILCHAN} - the name of the available channel, if one exists
  • ${AVAILORIGCHAN} - the canonical channel name that was used to create the channel

  • ${AVAILSTATUS} - the status code for the available channel (see "devicestate.c")
    • 0 AST_DEVICE_UNKNOWN - "Unknown"; channel is valid, but unknown state.
    • 1 AST_DEVICE_NOT_INUSE - "Not in use"
    • 2 AST_DEVICE IN USE - "In use"; channel is in use.
    • 3 AST_DEVICE_BUSY - "Busy"; channel is busy.
    • 4 AST_DEVICE_INVALID - "Invalid", not known to Asterisk.
    • 5 AST_DEVICE_UNAVAILABLE - "Unavailable"; channel is unavailable (not registred)
    • 6 AST_DEVICE_RINGING - "Ringing"; ring, ring, ring (someone is calling us), or
    • 6 AST_CAUSE_CHANNEL_UNACCEPTABLE (as cause code)
    • 7 AST_DEVICE_RINGINUSE "Ring+Inuse"; channel rings (outbound) and is in use
    • 8 AST_DEVICE_ONHOLD "On Hold"; channels is on hold
    • ...
    • 20 AST_CAUSE_SUBSCRIBER_ABSENT (as cause code)
    • ...

The application returns "both a device state and a cause code". This behaviour is probably bad since cause codes and device states overlap in name-space (i.e. they both have values from 0 through 9 which collide).

Options (new in Asterisk v1.2?):

s - Consider the channel unavailable if the channel is in use at all (buggy with SIP, always returning 0?!)
j - Support jumping to priority n+101 if no channel is available

Details

Currently, ChanIsAvail only works with ZAP, IAX2, mISDN, Skinny and SIP channels. MGCP channels are not supported. If none of the requested channels are available the new priority will be n+101 (unless such a priority does not exist).
If any of the requested channels are available, the next priority will be n+1, the channel variable ${AVAILCHAN} will be set to the name of the available channel.

The channels are checked in the order listed, returning the first available channel in the list in ${AVAILCHAN}.

Note that ChanIsAvail() returns not only the name of the channel in $AVAILCHAN, but also appends the channel's session ID. You will probably need to strip the session ID off, as illustrated in the example below.

SIP, IAX

ChanIsAvail is not a solution to tell you conclusively whether the channel is busy or not, it is primarily to tell you whether it would be possible to send a call there. Whether that call would end up being accepted or not is entirely up to the peer that we send the call to, and they could easily reject the call even though they do not appear to be 'busy'.
So: If you want to use ChanIsAvail to determine whether the SIP peer is known and registered, it will work fine. If you want to use it for limiting simultaneous calls to the peer, it will not work reliably for you.

For telling if Sip peers are online or not, when you are using qualify, then you may wish to just use the SipPeer('name':status) function, and jump based on that. ChanIsAvail doesn't seem to tell you the difference between a Sip peer that's online, and one that's offline. Example snippet:

exten => s,n,Set(VOIPCHECK=0)
exten => s,n,Set(PEERCHECK1=myprovider-out) ; SIP peer name as defined in sip.conf
; Make sure to have qualify=yes enabled for this SIP peer!
exten => s,n,NoOp(-- ${PEERCHECK1} status: ${SIPPEER(${PEERCHECK1}:status)} --)
exten => s,n,ExecIf($["${SIPPEER(${PEERCHECK1}:status):0:2}" = "OK"]|Set|VOIPCHECK=1)
; Now route and dial any way you like based on the value of VOIPCHECK

If you are not using Realtime you could also check the SIP/Registry tree of AstDB for the peer in questions, for example with the help of the Asterisk func DB_EXIST function.

Example


; See if line 2 is available. If not, try line 1.
exten => s,1,ChanIsAvail(Zap/2&Zap/1)

${AVAILCHAN} might now contain the value
Zap/2-1
; We need to strip off the session ID and Dial '12345678' at Zap/2
exten => s,2,Dial(${CUT(AVAILCHAN||1)}/12345678)
exten => s,3,Hangup

; If neither line 2 nor line 1 is available, play a message
exten => s,102,Playback(all-circuits-busy-now)
exten => s,103,Hangup^



User comments

SIP and ChanIsAvail (Dec 2005)

According to bug 4506 Chanisavail is not intended to detect if a phone is in use or not at all, it's only intended to check if asterisk could send the call there.
I tried using call-limit and Chanisavail, but it's broken in SIP. inuse gets applied only to peers, and when it gets an incoming call that is not answered it gets decremented and doesnt stay the same, which is a bug.
You should consider using groups instead

Limit incoming calls using DEVICE_STATE and Asterisk 1.6

To limit incoming simultaneous calls to the peer, try DEVICE_STATE.

See also



Asterisk | Applications | Functions | Variables | Expressions | Asterisk FAQ

Created by: oej, Last modification: Fri 22 of Jul, 2011 (16:19 UTC) by atheos
Please update this page with new information, just login and click on the "Edit" or "Discussion" tab. Get a free login here: Register Thanks! - Find us on Google+