func_hangupcause.c

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 1999-2012, Digium, Inc.
00005  *
00006  * Kinsey Moore <kmoore@digium.com>
00007  *
00008  * See http://www.asterisk.org for more information about
00009  * the Asterisk project. Please do not directly contact
00010  * any of the maintainers of this project for assistance;
00011  * the project provides a web site, mailing lists and IRC
00012  * channels for your use.
00013  *
00014  * This program is free software, distributed under the terms of
00015  * the GNU General Public License Version 2. See the LICENSE file
00016  * at the top of the source tree.
00017  */
00018 
00019 /*! \file
00020  *
00021  * \brief Functions related to retreiving per-channel hangupcause information
00022  *
00023  * \author Kinsey Moore <kmoore@digium.com>
00024  * \ingroup functions
00025  *
00026  * See Also:
00027  * \arg \ref AstCREDITS
00028  */
00029 
00030 /*** MODULEINFO
00031    <support_level>core</support_level>
00032  ***/
00033 
00034 #include "asterisk.h"
00035 
00036 ASTERISK_FILE_VERSION(__FILE__, "$Revision: 431000 $")
00037 
00038 #include "asterisk/module.h"
00039 #include "asterisk/channel.h"
00040 #include "asterisk/pbx.h"
00041 #include "asterisk/utils.h"
00042 #include "asterisk/app.h"
00043 
00044 /*** DOCUMENTATION
00045    <function name="HANGUPCAUSE" language="en_US">
00046       <synopsis>
00047          Gets per-channel hangupcause information from the channel.
00048       </synopsis>
00049       <syntax>
00050          <parameter name="channel" required="true">
00051             <para>The name of the channel for which to retrieve cause information.</para>
00052          </parameter>
00053          <parameter name="type" required="true">
00054             <para>Parameter describing which type of information is requested. Types are:</para>
00055             <enumlist>
00056                <enum name="tech"><para>Technology-specific cause information</para></enum>
00057                <enum name="ast"><para>Translated Asterisk cause code</para></enum>
00058             </enumlist>
00059          </parameter>
00060       </syntax>
00061       <description>
00062          <para>Gets technology-specific or translated Asterisk cause code information
00063          from the channel for the specified channel that resulted from a dial.</para>
00064       </description>
00065       <see-also>
00066          <ref type="function">HANGUPCAUSE_KEYS</ref>
00067          <ref type="application">HangupCauseClear</ref>
00068       </see-also>
00069    </function>
00070    <function name="HANGUPCAUSE_KEYS" language="en_US">
00071       <synopsis>
00072          Gets the list of channels for which hangup causes are available.
00073       </synopsis>
00074       <description>
00075          <para>Returns a comma-separated list of channel names to be used with the HANGUPCAUSE function.</para>
00076       </description>
00077       <see-also>
00078          <ref type="function">HANGUPCAUSE</ref>
00079          <ref type="application">HangupCauseClear</ref>
00080       </see-also>
00081    </function>
00082    <application name="HangupCauseClear" language="en_US">
00083       <synopsis>
00084          Clears hangup cause information from the channel that is available through HANGUPCAUSE.
00085       </synopsis>
00086       <description>
00087          <para>Clears all channel-specific hangup cause information from the channel.
00088          This is never done automatically (i.e. for new Dial()s).</para>
00089       </description>
00090       <see-also>
00091          <ref type="function">HANGUPCAUSE</ref>
00092          <ref type="function">HANGUPCAUSE_KEYS</ref>
00093       </see-also>
00094    </application>
00095  ***/
00096 
00097 /*!
00098  * \internal
00099  * \brief Read values from the hangupcause ao2 container.
00100  *
00101  * \param chan Asterisk channel to read
00102  * \param cmd Not used
00103  * \param data HANGUPCAUSE function argument string
00104  * \param buf Buffer to fill with read value.
00105  * \param len Length of the buffer
00106  *
00107  * \retval 0 on success.
00108  * \retval -1 on error.
00109  */
00110 static int hangupcause_read(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t len)
00111 {
00112    char *parms;
00113    struct ast_control_pvt_cause_code *cause_code;
00114    int res = 0;
00115    AST_DECLARE_APP_ARGS(args,
00116       AST_APP_ARG(channel);   /*!< Channel name */
00117       AST_APP_ARG(type);   /*!< Type of information requested (ast or tech) */
00118       );
00119 
00120    /* Ensure that the buffer is empty */
00121    *buf = 0;
00122 
00123    if (!chan) {
00124       return -1;
00125    }
00126 
00127    parms = ast_strdupa(data);
00128    AST_STANDARD_APP_ARGS(args, parms);
00129    if (args.argc != 2) {
00130       /* Must have two arguments. */
00131       ast_log(LOG_WARNING, "The HANGUPCAUSE function must have 2 parameters, not %u\n", args.argc);
00132       return -1;
00133    }
00134 
00135    ast_channel_lock(chan);
00136    cause_code = ast_channel_dialed_causes_find(chan, args.channel);
00137    ast_channel_unlock(chan);
00138 
00139    if (!cause_code) {
00140       ast_log(LOG_WARNING, "Unable to find information for channel %s\n", args.channel);
00141       return -1;
00142    }
00143 
00144    if (!strcmp(args.type, "ast")) {
00145       ast_copy_string(buf, ast_cause2str(cause_code->ast_cause), len);
00146    } else if (!strcmp(args.type, "tech")) {
00147       ast_copy_string(buf, cause_code->code, len);
00148    } else {
00149       ast_log(LOG_WARNING, "Information type not recognized (%s)\n", args.type);
00150       res = -1;
00151    }
00152 
00153    ao2_ref(cause_code, -1);
00154 
00155    return res;
00156 }
00157 
00158 /*!
00159  * \internal
00160  * \brief Read keys from the hangupcause ao2 container.
00161  *
00162  * \param chan Asterisk channel to read
00163  * \param cmd Not used
00164  * \param data HANGUPCAUSE_KEYS function argument string
00165  * \param buf Buffer to fill with read value.
00166  * \param len Length of the buffer
00167  *
00168  * \retval 0 on success.
00169  * \retval -1 on error.
00170  */
00171 static int hangupcause_keys_read(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t len)
00172 {
00173    struct ast_str *chanlist;
00174 
00175    /* Ensure that the buffer is empty */
00176    *buf = 0;
00177 
00178    if (!chan) {
00179       return -1;
00180    }
00181 
00182    ast_channel_lock(chan);
00183    chanlist = ast_channel_dialed_causes_channels(chan);
00184    ast_channel_unlock(chan);
00185 
00186    if (chanlist && ast_str_strlen(chanlist)) {
00187       ast_copy_string(buf, ast_str_buffer(chanlist), len);
00188    }
00189 
00190    ast_free(chanlist);
00191    return 0;
00192 }
00193 
00194 /*!
00195  * \internal
00196  * \brief Remove all keys from the hangupcause ao2 container.
00197  *
00198  * \param chan Asterisk channel to read
00199  * \param data Not used
00200  *
00201  * \retval 0 on success.
00202  * \retval -1 on error.
00203  */
00204 static int hangupcause_clear_exec(struct ast_channel *chan, const char *data) {
00205    ast_channel_lock(chan);
00206    ast_channel_dialed_causes_clear(chan);
00207    ast_channel_unlock(chan);
00208    return 0;
00209 }
00210 
00211 static struct ast_custom_function hangupcause_function = {
00212    .name = "HANGUPCAUSE",
00213    .read = hangupcause_read,
00214 };
00215 
00216 static struct ast_custom_function hangupcause_keys_function = {
00217    .name = "HANGUPCAUSE_KEYS",
00218    .read = hangupcause_keys_read,
00219 };
00220 
00221 static const char app[] = "HangupCauseClear";
00222 
00223 /*!
00224  * \internal
00225  * \brief Unload the function module
00226  *
00227  * \retval 0 on success.
00228  * \retval -1 on error.
00229  */
00230 static int unload_module(void)
00231 {
00232    int res;
00233 
00234    res = ast_custom_function_unregister(&hangupcause_function);
00235    res |= ast_custom_function_unregister(&hangupcause_keys_function);
00236    res |= ast_unregister_application(app);
00237    return res;
00238 }
00239 
00240 /*!
00241  * \internal
00242  * \brief Load and initialize the function module.
00243  *
00244  * \retval AST_MODULE_LOAD_SUCCESS on success.
00245  * \retval AST_MODULE_LOAD_DECLINE on error.
00246  */
00247 static int load_module(void)
00248 {
00249    int res;
00250 
00251    res = ast_custom_function_register(&hangupcause_function);
00252    res |= ast_custom_function_register(&hangupcause_keys_function);
00253    res |= ast_register_application_xml(app, hangupcause_clear_exec);
00254    return res ? AST_MODULE_LOAD_DECLINE : AST_MODULE_LOAD_SUCCESS;
00255 }
00256 
00257 /* Do not wrap the following line. */
00258 AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "HANGUPCAUSE related functions and applications");

Generated on Thu Apr 16 06:27:35 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6