[asterisk-commits] mmichelson: branch group/CCSS r222105 - /team/group/CCSS/doc/tex/ccss.tex

Mon Oct 5 12:17:22 CDT 2009

Author: mmichelson
Date: Mon Oct  5 12:17:21 2009
New Revision: 222105

URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=222105
Log:
Finish the user guide.

Everyone can go ahead now and laugh at my
tex nubbitude.


Modified:
    team/group/CCSS/doc/tex/ccss.tex

Modified: team/group/CCSS/doc/tex/ccss.tex
URL: http://svnview.digium.com/svn/asterisk/team/group/CCSS/doc/tex/ccss.tex?view=diff&rev=222105&r1=222104&r2=222105
==============================================================================

--- team/group/CCSS/doc/tex/ccss.tex (original)
+++ team/group/CCSS/doc/tex/ccss.tex Mon Oct  5 12:17:21 2009
@@ -78,7 +78,7 @@
 alerted that the recipient is available, this action is referred to
 as a "recall."
 
-\section{How to Use CC}
+\section{The CC Process}
 
 \subsection{The Initial Call}
 
@@ -117,6 +117,19 @@
 natively support CC but do not know the means by which to request it,
 then contact the equipment manufacturer for more information.
 
+\subsection{Cancelling CC}
+
+	CC may be canceled after it has been requested. The method by which
+this is accomplished differs based on the type of agent the calling
+party uses.
+
+	When using a generic agent, the dialplan application
+CallRequestCancel is used to cancel CC. When using a native monitor,
+the method by which CC is cancelled depends on the protocol used.
+Likely, this will be done using a button on a phone.
+
+	Keep in mind that if CC is cancelled, it cannot be un-cancelled.
+
 \subsection{Monitoring the Called Party}
 
 	Once the caller has requested CC, then Asterisk's job is to monitor
@@ -140,3 +153,150 @@
 parties will use different types of monitors for the same CC request.
 
 \subsection{Alerting the Caller}
+
+	Once Asterisk has determined that the called party has become available
+the time comes for Asterisk to alert the caller that the called party has
+become available. The method by which this is done differs based on the
+type of agent in use.
+
+	If a generic agent is used, then Asterisk will originate a call to
+the calling party. Upon answering the call, if a callback macro has
+been configured, then that macro will be executed on the calling
+party's channel. After the macro has completed, an outbound call
+will be issued to the parties involved in the original call.
+
+	If a native agent is used, then Asterisk will send an appropriate
+notification message to the calling party to alert it that it may now
+attempt its recall. How this is presented to the caller is dependent
+upon the protocol and equipment that the caller is using. It is
+possible that the calling party's phone will ring and a recall will
+be triggered upon answering the phone, or it may be that the user
+has a specific button that he may press to initiate a recall.
+
+\subsection{If the Caller is unavailable}
+
+	When the called party has become available, it is possible that
+when Asterisk attempts to alert the calling party of the called party's
+availability, the calling party itself will have become unavailable.
+If this is the case, then Asterisk will suspend monitoring of the
+called party and will instead monitor the availability of the calling
+party. The monitoring procedure for the calling party is the same
+as is used in the section "Monitoring the Called Party." In other
+words, the method by which the calling party is monitored is dependent
+upon the type of agent used by the caller.
+
+	Once Asterisk has determined that the calling party has become
+available again, Asterisk will then move back to the process used
+in the section "Monitoring the Called Party."
+
+\subsection{The CC recall}
+
+	The calling party will make its recall to the same extension
+that was dialed. Asterisk will provide a channel variable,
+CC_INTERFACES, to be used as an argument to the Dial application
+for CC recalls. It is strongly recommended that you use this
+channel variable during a CC recall. Listed are two reasons:
+
+\begin{itemize}
+\item The dialplan may be written in such a way that the dialed
+destintations are dynamically generated. With such a dialplan, it
+cannot be guaranteed that the same interfaces will be recalled.
+\item For calling destinations with native CC monitors, it may be
+necessary to dial a special string in order to notify the channel
+driver that the number being dialed is actually part of a CC recall.
+\end{itemize}
+
+	Note that even if your call gets routed through local channels,
+the CC_INTERFACES variable will be populated with the appropriate
+values for that specific extension.
+	When the called parties are dialed, it is expected that a called
+party will answer, since Asterisk had previously determined that the
+party was available. However, it is possible that the called party
+may choose not to respond to the call, or he could have become busy
+again. In such a situation, the calling party must re-request CC if
+he wishes to still be alerted when the calling party has become
+available.
+
+\section{Miscellaneous Information and Tips}
+
+\begin{itemize}
+\item Be aware when using a generic agent that the max_cc_agents
+configuration parameter is ignored. The main driving reason for
+this is that the mechanism for cancelling CC when using a generic
+agent would become much more potentially confusing to execute. By
+limiting a calling party to having a single request, there is only
+ever a single request to be cancelled, making the process simple.
+
+\item Keep in mind that no matter what CC agent type is being used,
+a CC request can only be made for the latest call issued.
+
+\item If available timers are running on multiple called parties,
+it is possible that one of the timers may expire before the others
+do. If such a situation occurs, then the interface on which the
+timer expired will ceased to be monitored. If, though, one of the
+other called parties becomes available before his available timer
+expires, the called party whose available timer had previously
+expired will still be included in the CC_INTERFACES channel
+variable on the recall.
+
+\item It is strongly recommended that lots of thought is placed
+into the settings of the CC timers. Our general recommendation is
+that timers for phones should be set shorter than those for trunks.
+The reason for this is that it makes it less likely for a link in
+the middle of a network to cause CC to fail.
+
+\item CC can potentially be a memory hog if used irresponsibly. The
+following are recommendations to help curb the amount of resources
+required by the CC engine. First, limit the number of maximum number
+of CC requests in the system using the cc\_max\_requests option in
+ccss.conf. Second, set the cc\_offer\_timer low for your callers. Since
+it is likely that most calls will not result in a CC request, it is
+a good idea to set this value to something low so that information
+for calls does not stick around in memory for long. The final thing
+that can be done is to conditionally set the cc\_agent\_policy to
+"never" using the CALLCOMPLETION dialplan function. By doing this,
+no CC information will be kept around after the call completes.
+
+\item It is possible to request CCNR on answered calls. The reason
+for this is that it is impossible to know whether a call that is
+answered has actually been answered by a person or by something
+such as voicemail or some other IVR.
+
+\item Not all channel drivers have had the ability to set CC config
+parameters in their configuration files added yet. At the time of
+this writing (2009 Oct), only chan_sip has had this ability added, with
+short-term plans to add this to chan_dahdi and chan_misdn. It is
+possible to set CC configuration parameters for other channel types,
+though. For these channel types, the setting of the parameters can
+only be accomplished using the CALLCOMPLETION dialplan function.
+
+\item It is documented in many places that generic agents and monitors
+can only be used for phones. In most cases, however, Asterisk has no
+way of distinguishing between a phone and a trunk itself. The result
+is that Asterisk will happily let you violate the advice given and
+allow you to set up a trunk with a generic monitor or agent. While this
+will not cause anything catastrophic to occur, the behavior will most
+definitely be buggy.
+
+\item At the time of this writing (2009 Oct), Asterisk is the only
+known SIP stack to write an implementation of
+draft-ietf-bliss-call-completion-04. As a result, it is recommended
+that for your SIP phones, use a generic agent and monitor. For SIP
+trunks, you will only be able to use CC if the other end is
+terminated by another Asterisk server running version 1.6.4 or later.
+
+\item If the Dial application is called multiple times by a single
+extension, CC will only be offered to the caller for the parties called
+by the first instantiation of Dial.
+
+\item CC is currently only supported by the Dial application. Queue,
+Followme, and Page do not support CC because it is not particularly
+useful for those applications.
+
+\item As with all Asterisk components, CC is not perfect. If you should
+find a bug or wish to enhance the feature, please open an issue on
+https://issues.asterisk.org. If writing an enhancement, please be sure
+to include a patch for the enhancement, or else the issue will be
+closed.
+
+\end{itemize}


