Add Device State Information CCSS for Generic Devices.
authorRichard Mudgett <rmudgett@digium.com>
Thu, 14 Apr 2011 18:22:35 +0000 (18:22 +0000)
committerRichard Mudgett <rmudgett@digium.com>
Thu, 14 Apr 2011 18:22:35 +0000 (18:22 +0000)
commitae2926b5d0669babfe9d84704357d3f9323896ea
tree3469127aaa20cdaab645335f46416ddff09b4dfb
parentb26a16dbcf5b06e709a3d2c215792d434eba5bd6
Add Device State Information CCSS for Generic Devices.

Add Asterisk Device State information and callbacks to the Call Completion
Supplemental Services for generic agents.

There are currently not many devices that have native support for CCSS.
Even as the devices become available there may be other reasons why one
may choose to not take advantage of the native abilities and stick with
the generic implementation.  The generic implementation is quite capable
and could be greatly enhanced by adding device state capabilities.  A
phone could then subscribe to the device state with a BLF key in
conjunction with Asterisk hints.

The advantages of the device state information would allow a single button
to: request CCSS, cancel a CCSS request, and display the current state of
a CCSS request.

For example, you may have a single button that when not lit, there is no
active CCSS request.  When you press that button, the dialplan can query
the DEVICE_STATE() associated with that caller to determine whether they
should be calling CallCompletionRequest() or CallCompletionCancel().  If
there is currently a pending request, then the dialplan would cancel it.
This also has the advantage of showing the true state of a request, which
is an asynchronous call, even when CallCompletionRequest() thinks it was
successful.  The actual request could ultimately fail.  Once lit, further
feedback can be provided to the caller about the current state of their
request since it will be updated by the CCSS State Machine as appropriate.

The DEVICE_STATE mapping is configurable since the BLF being used on a
given phone type may vary.  The idea is to allow some level of
customization as to the phone's behavior.

As an example, you may want the BLF key to go solid once you have
requested a callback.  You may then want the LED to blink (typically
ringing) when either the callback is in process, which is a visual
indication that the incoming call is the desired callback.  You may want
it to blink when the callee is ready but you are busy, giving you a visual
indication that the target is available as you may want to get off the
line so that the callback can be successful.

Device state information is sent back via the ast_devstate_prov_add()
callback for any generic CCSS device as it traverses through the state
machine.  You simply provide a map between CC_STATE values and the
corresponding AST_DEVICE state values.

You could then generate hints against these states similar to what is
possible today with Custom Devstates or MeetMe states.  For example, you
may have an extension 3000 that is currently associated with device
SIP/3000.  You could then create a feature code for that extension that
may look something like:

exten => *823000,hint,ccss:sip/3000

You would then subscribe a BLF button to *823000 which would point to the
dialplan that handled CCSS requests/cancels using the available
DEVICE_STATE() information about ccss:sip/3000 to make the decision about
what to do.

(closes issue #18788)
Reported by: p_lindheimer
Patches:
      ccss.trunk.18788.patch uploaded by p lindheimer (license 558)
      Modified with final reviewboard comments.
Tested by: p_lindheimer, loloski

Review: https://reviewboard.asterisk.org/r/1105/

git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@313744 65c4cc65-6c06-0410-ace0-fbb531ad65f3
CREDITS
configs/ccss.conf.sample
main/ccss.c