[asterisk-commits] kpfleming: branch kpfleming/agi_multiple-api-fix r157224 - in /team/kpfleming...
SVN commits to the Asterisk project
asterisk-commits at lists.digium.com
Sat Nov 15 14:59:37 CST 2008
Author: kpfleming
Date: Sat Nov 15 14:59:36 2008
New Revision: 157224
URL: http://svn.digium.com/view/asterisk?view=rev&rev=157224
Log:
save this in a branch for later merging
Added:
team/kpfleming/agi_multiple-api-fix/
- copied from r157222, trunk/
team/kpfleming/agi_multiple-api-fix/UPGRADE-1.6.txt (contents, props changed)
- copied, changed from r157222, trunk/UPGRADE.txt
Modified:
team/kpfleming/agi_multiple-api-fix/UPGRADE.txt
team/kpfleming/agi_multiple-api-fix/include/asterisk/agi.h
team/kpfleming/agi_multiple-api-fix/res/res_agi.c
Copied: team/kpfleming/agi_multiple-api-fix/UPGRADE-1.6.txt (from r157222, trunk/UPGRADE.txt)
URL: http://svn.digium.com/view/asterisk/team/kpfleming/agi_multiple-api-fix/UPGRADE-1.6.txt?view=diff&rev=157224&p1=trunk/UPGRADE.txt&r1=157222&p2=team/kpfleming/agi_multiple-api-fix/UPGRADE-1.6.txt&r2=157224
==============================================================================
--- trunk/UPGRADE.txt (original)
+++ team/kpfleming/agi_multiple-api-fix/UPGRADE-1.6.txt Sat Nov 15 14:59:36 2008
@@ -4,7 +4,6 @@
===
=== UPGRADE-1.2.txt -- Upgrade info for 1.0 to 1.2
=== UPGRADE-1.4.txt -- Upgrade info for 1.2 to 1.4
-=== UPGRADE.txt -- Upgrade info for 1.4 to 1.6
=========================================================
AEL:
Propchange: team/kpfleming/agi_multiple-api-fix/UPGRADE-1.6.txt
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: team/kpfleming/agi_multiple-api-fix/UPGRADE-1.6.txt
------------------------------------------------------------------------------
svn:keywords = Author Date Id Revision
Propchange: team/kpfleming/agi_multiple-api-fix/UPGRADE-1.6.txt
------------------------------------------------------------------------------
svn:mergeinfo =
Propchange: team/kpfleming/agi_multiple-api-fix/UPGRADE-1.6.txt
------------------------------------------------------------------------------
svn:mime-type = text/plain
Modified: team/kpfleming/agi_multiple-api-fix/UPGRADE.txt
URL: http://svn.digium.com/view/asterisk/team/kpfleming/agi_multiple-api-fix/UPGRADE.txt?view=diff&rev=157224&r1=157222&r2=157224
==============================================================================
--- team/kpfleming/agi_multiple-api-fix/UPGRADE.txt (original)
+++ team/kpfleming/agi_multiple-api-fix/UPGRADE.txt Sat Nov 15 14:59:36 2008
@@ -1,312 +1,22 @@
-=========================================================
-=== Information for upgrading from Asterisk 1.4 to 1.6
+===========================================================
+=== Information for upgrading between Asterisk 1.6 versions
===
===
=== UPGRADE-1.2.txt -- Upgrade info for 1.0 to 1.2
=== UPGRADE-1.4.txt -- Upgrade info for 1.2 to 1.4
-=== UPGRADE.txt -- Upgrade info for 1.4 to 1.6
-=========================================================
+=== UPGRADE-1.6.txt -- Upgrade info for 1.4 to 1.6
+===========================================================
-AEL:
+From 1.6.0.1 to 1.6.0.2 or later, or 1.6.1 or later:
-* Macros are now implemented underneath with the Gosub() application.
- Heaven Help You if you wrote code depending on any aspect of this!
- Previous to 1.6, macros were implemented with the Macro() app, which
- provided a nice feature of auto-returning. The compiler will do its
- best to insert a Return() app call at the end of your macro if you did
- not include it, but really, you should make sure that all execution
- paths within your macros end in "return;".
-
-* The conf2ael program is 'introduced' in this release; it is in a rather
- crude state, but deemed useful for making a first pass at converting
- extensions.conf code into AEL. More intelligence will come with time.
-
-Core:
-
-* The 'languageprefix' option in asterisk.conf is now deprecated, and
- the default sound file layout for non-English sounds is the 'new
- style' layout introduced in Asterisk 1.4 (and used by the automatic
- sound file installer in the Makefile).
-
-* The ast_expr2 stuff has been modified to handle floating-point numbers.
- Numbers of the format D.D are now acceptable input for the expr parser,
- Where D is a string of base-10 digits. All math is now done in "long double",
- if it is available on your compiler/architecture. This was half-way between
- a bug-fix (because the MATH func returns fp by default), and an enhancement.
- Also, for those counting on, or needing, integer operations, a series of
- 'functions' were also added to the expr language, to allow several styles
- of rounding/truncation, along with a set of common floating point operations,
- like sin, cos, tan, log, pow, etc. The ability to call external functions
- like CDR(), etc. was also added, without having to use the ${...} notation.
-
-* The delimiter passed to applications has been changed to the comma (','), as
- that is what people are used to using within extensions.conf. If you are
- using realtime extensions, you will need to translate your existing dialplan
- to use this separator. To use a literal comma, you need merely to escape it
- with a backslash ('\'). Another possible side effect is that you may need to
- remove the obscene level of backslashing that was necessary for the dialplan
- to work correctly in 1.4 and previous versions. This should make writing
- dialplans less painful in the future, albeit with the pain of a one-time
- conversion. If you would like to avoid this conversion immediately, set
- pbx_realtime=1.4 in the [compat] section of asterisk.conf. After
- transitioning, set pbx_realtime=1.6 in the same section.
-
-* For the same purpose as above, you may set res_agi=1.4 in the [compat]
- section of asterisk.conf to continue to use the '|' delimiter in the EXEC
- arguments of AGI applications. After converting to use the ',' delimiter,
- change this option to res_agi=1.6.
-
-* The logger.conf option 'rotatetimestamp' has been deprecated in favor of
- 'rotatestrategy'. This new option supports a 'rotate' strategy that more
- closely mimics the system logger in terms of file rotation.
-
-* The concise versions of various CLI commands are now deprecated. We recommend
- using the manager interface (AMI) for application integration with Asterisk.
-
-* The following core commands dealing with dialplan has been deprecated: 'core
- show globals', 'core set global' and 'core set chanvar'. Use the equivalent
- 'dialplan show globals', 'dialplan set global' and 'dialplan set chanvar'
- instead.
-
-* The silencethreshold used for various applications is now settable via a
- centralized config option in dsp.conf.
-
-* The logical value of spaces immediately preceding a standalone 0 previously
- evaluated to true. It now evaluates to false. This has confused a good
- many people in the past (typically because they failed to realize the space
- had any significance). Since this violates the Principle of Least Surprise,
- it has been changed.
-
-* The default console now will use colors according to the default background
- color, instead of forcing the background color to black. If you are using a
- light colored background for your console, you may wish to use the option
- flag '-W' to present better color choices for the various messages. However,
- if you'd prefer the old method of forcing colors to white text on a black
- background, the compatiblity option -B is provided for this purpose.
-
-Voicemail:
-
-* The voicemail configuration values 'maxmessage' and 'minmessage' have
- been changed to 'maxsecs' and 'minsecs' to clarify their purpose and
- to make them more distinguishable from 'maxmsgs', which sets folder
- size. The old variables will continue to work in this version, albeit
- with a deprecation warning.
-
-* If you use any interface for modifying voicemail aside from the built in
- dialplan applications, then the option "pollmailboxes" *must* be set in
- voicemail.conf for message waiting indication (MWI) to work properly. This
- is because Voicemail notification is now event based instead of polling
- based. The channel drivers are no longer responsible for constantly manually
- checking mailboxes for changes so that they can send MWI information to users.
- Examples of situations that would require this option are web interfaces to
- voicemail or an email client in the case of using IMAP storage.
-
-* The externnotify script should accept an additional (last) parameter
- containing the number of urgent messages in the INBOX.
-
-Applications:
-
-* SendImage() no longer hangs up the channel on transmission error or on
- another type of error; in those cases, a FAILURE status is stored in
- SENDIMAGESTATUS and dialplan execution continues. The possible return values
- stored in SENDIMAGESTATUS are: SUCCESS, FAILURE, and UNSUPPORTED. ('OK' has
- been replaced with 'SUCCESS', and 'NOSUPPORT' has been replaced with
- 'UNSUPPORTED'). This change makes the SendImage application more consistent
- with other applications.
-
-* ChanIsAvail() now has a 't' option, which allows the specified device
- to be queried for state without consulting the channel drivers. This
- performs mostly a 'ChanExists' sort of function.
-
-* ChannelRedirect() will not terminate the channel that fails to do a
- channelredirect as it has done previously. Instead CHANNELREDIRECT_STATUS
- will reflect if the attempt was successful of not.
-
-* SetCallerPres() has been replaced with the CALLERPRES() dialplan function
- and is now deprecated.
-
-* DISA()'s fifth argument is now an options argument. If you have previously
- used 'NOANSWER' in this argument, you'll need to convert that to the new
- option 'n'.
-
-* Macro() is now deprecated. If you need subroutines, you should use the
- Gosub()/Return() applications. To replace MacroExclusive(), we have
- introduced dialplan functions LOCK(), TRYLOCK(), and UNLOCK(). You may use
- these functions in any location where you desire to ensure that only one
- channel is executing that path at any one time. The Macro() applications
- are deprecated for performance reasons. However, since Macro() has been
- around for a long time and so many dialplans depend heavily on it, for the
- sake of backwards compatibility it will not be removed . It is also worth
- noting that using both Macro() and GoSub() at the same time is _heavily_
- discouraged.
-
-* Read() now sets a READSTATUS variable on exit. It does NOT automatically
- return -1 (and hangup) anymore on error. If you want to hangup on error,
- you need to do so explicitly in your dialplan.
-
-* Privacy() no longer uses privacy.conf, so any options must be specified
- directly in the application arguments.
-
-* MusicOnHold application now has duration parameter which allows specifying
- timeout in seconds.
-
-* WaitMusicOnHold application is now deprecated in favor of extended MusicOnHold.
-
-* SetMusicOnHold is now deprecated. You should use Set(CHANNEL(musicclass)=...)
- instead.
-
-* While app_directory has always relied on having a voicemail.conf or users.conf file
- correctly set up, it now is dependent on app_voicemail being compiled as well.
-
-* The arguments in ExecIf changed a bit, to be more like other applications.
- The syntax is now ExecIf(<cond>?appiftrue(args):appiffalse(args)).
-
-* The behavior of the Set application now depends upon a compatibility option,
- set in asterisk.conf. To use the old 1.4 behavior, which allowed Set to take
- multiple key/value pairs, set app_set=1.4 in [compat] in asterisk.conf. To
- use the new behavior, which permits variables to be set with embedded commas,
- set app_set=1.6 in [compat] in asterisk.conf. Note that you can have both
- behaviors at the same time, if you switch to using MSet if you want the old
- behavior.
-
-Dialplan Functions:
-
-* QUEUE_MEMBER_COUNT() has been deprecated in favor of the QUEUE_MEMBER() function. For
- more information, issue a "show function QUEUE_MEMBER" from the CLI.
-
-CDR:
-
-* The cdr_sqlite module has been marked as deprecated in favor of
- cdr_sqlite3_custom. It will potentially be removed from the tree
- after Asterisk 1.6 is released.
-
-* The cdr_odbc module now uses res_odbc to manage its connections. The
- username and password parameters in cdr_odbc.conf, therefore, are no
- longer used. The dsn parameter now points to an entry in res_odbc.conf.
-
-* The uniqueid field in the core Asterisk structure has been changed from a
- maximum 31 character field to a 149 character field, to account for all
- possible values the systemname prefix could be. In the past, if the
- systemname was too long, the uniqueid would have been truncated.
-
-* The cdr_tds module now supports all versions of FreeTDS that contain
- the db-lib frontend. It will also now log the userfield variable if
- the target database table contains a column for it.
-
-Formats:
-
-* format_wav: The GAIN preprocessor definition and source code that used it
- is removed. This change was made in response to user complaints of
- choppiness or the clipping of loud signal peaks. To increase the volume
- of voicemail messages, use the 'volgain' option in voicemail.conf
-
-Channel Drivers:
-
-* SIP: a small upgrade to support the "Record" button on the SNOM360,
- which sends a sip INFO message with a "Record: on" or "Record: off"
- header. If Asterisk is set up (via features.conf) to accept "One Touch Monitor"
- requests (by default, via '*1'), then the user-configured dialpad sequence
- is generated, and recording can be started and stopped via this button. The
- file names and formats are all controlled via the normal mechanisms. If the
- user has not configured the automon feature, the normal "415 Unsupported media type"
- is returned, and nothing is done.
-
-* SIP: The "call-limit" option is marked as deprecated. It still works in this version of
- Asterisk, but will be removed in the following version. Please use the groupcount functions
- in the dialplan to enforce call limits. The "limitonpeer" configuration option is
- now renamed to "counteronpeer".
-
-* SIP: The "username" option is now renamed to "defaultuser" to match "defaultip".
- These are used only before registration to call a peer with the uri
- sip:defaultuser at defaultip
- The "username" setting still work, but is deprecated and will not work in
- the next version of Asterisk.
-
-* SIP: All of the functionality in SIPCHANINFO() has been implemented in CHANNEL(),
- and you should start using that function instead for retrieving information about
- the channel in a technology-agnostic way.
-
-* chan_local.c: the comma delimiter inside the channel name has been changed to a
- semicolon, in order to make the Local channel driver compatible with the comma
- delimiter change in applications.
-
-* H323: The "tos" setting has changed name to "tos_audio" and "cos" to "cos_audio"
- to be compatible with settings in sip.conf. The "tos" and "cos" configuration
- is deprecated and will stop working in the next release of Asterisk.
-
-* Console: A new console channel driver, chan_console, has been added to Asterisk.
- This new module can not be loaded at the same time as chan_alsa or chan_oss. The
- default modules.conf only loads one of them (chan_oss by default). So, unless you
- have modified your modules.conf to not use the autoload option, then you will need
- to modify modules.conf to add another "noload" line to ensure that only one of
- these three modules gets loaded.
-
-* DAHDI: The chan_zap module that supported PSTN interfaces using
- Zaptel has been renamed to chan_dahdi, and only supports the DAHDI
- telephony driver package for PSTN interfaces. See the
- Zaptel-to-DAHDI.txt file for more details on this transition.
-
-* DAHDI: The "msdstrip" option has been deprecated, as it provides no value over
- the method of stripping digits in the dialplan using variable substring syntax.
-
-Configuration:
-
-* pbx_dundi.c: tos parameter changed to use new values. Old values like lowdelay,
- lowcost and other is not acceptable now. Look into qos.tex for description of
- this parameter.
-
-* queues.conf: the queue-lessthan sound file option is no longer available, and the
- queue-round-seconds option no longer takes '1' as a valid parameter.
-
-* If you have any third party modules which use a config file variable whose
- name ends in a '+', please note that the append capability added to this
- version may now conflict with that variable naming scheme. An easy
- workaround is to ensure that a space occurs between the '+' and the '=',
- to differentiate your variable from the append operator. This potential
- conflict is unlikely, but is documented here to be thorough.
-
-* skinny.conf now has seperate sections for lines and devices.
- Please have a look at configs/skinny.conf.sample and update
- your skinny.conf.
-
-Manager:
-
-* Manager has been upgraded to version 1.1 with a lot of changes.
- Please check doc/manager_1_1.txt for information
-
-* The IAXpeers command output has been changed to more closely resemble the
- output of the SIPpeers command.
-
-* cdr_manager now reports at the "cdr" level, not at "call" You may need to
- change your manager.conf to add the level to existing AMI users, if they
- want to see the CDR events generated.
-
-* The Originate command now requires the Originate write permission. For
- Originate with the Application parameter, you need the additional System
- privilege if you want to do anything that calls out to a subshell.
-
-Queues:
-
-* New queue log events ADDMEMBER and REMOVEMEMBER have been added. Also, a
- new value has been added to the TRANSFER event that indicates the caller's
- original position in the queue they are being transfered from.
-
-* Prior to Asterisk 1.6.2, queue names were treated in a case-sensitive
- manner, meaning that queues with names like "sales" and "sALeS" would
- be seen as unique queues. The parsing logic has changed to use case-
- insensitive comparisons now when originally hashing based on queue
- names, meaning that now the two queues mentioned as examples earlier
- will be seen as having the same name.
-
-iLBC Codec:
-
-* Previously, the Asterisk source code distribution included the iLBC
- encoder/decoder source code, from Global IP Solutions
- (http://www.gipscorp.com). This code is not licensed for
- distribution, and thus has been removed from the Asterisk source
- code distribution. If you wish to use codec_ilbc to support iLBC
- channels in Asterisk, you can run the contrib/scripts/get_ilbc_source.sh
- script to download the source and put it in the proper place in
- the Asterisk build tree. Once that is done you can follow your normal
- steps of building Asterisk. You will need to run 'menuselect' and enable
- the iLBC codec in the 'Codec Translators' category.
+* The ast_agi_register_multiple() and ast_agi_unregister_multiple()
+ API calls were added in 1.6.0, so that modules that provide multiple
+ AGI commands could register/unregister them all with a single
+ step. However, these API calls were not implemented properly, and did
+ not allow the caller to know whether registration or unregistration
+ succeeded or failed. They have been redefined to now return success
+ or failure, but this means any code using these functions will need
+ be recompiled after upgrading to a version of Asterisk containing
+ these changes. In addition, the source code using these functions
+ should be reviewed to ensure it can properly react to failure
+ of registration or unregistration of its API commands.
Modified: team/kpfleming/agi_multiple-api-fix/include/asterisk/agi.h
URL: http://svn.digium.com/view/asterisk/team/kpfleming/agi_multiple-api-fix/include/asterisk/agi.h?view=diff&rev=157224&r1=157222&r2=157224
==============================================================================
--- team/kpfleming/agi_multiple-api-fix/include/asterisk/agi.h (original)
+++ team/kpfleming/agi_multiple-api-fix/include/asterisk/agi.h Sat Nov 15 14:59:36 2008
@@ -69,8 +69,39 @@
int AGI_WEAK ast_agi_fdprintf(struct ast_channel *chan, int fd, char *fmt, ...);
int AGI_WEAK ast_agi_register(struct ast_module *mod, agi_command *cmd);
int AGI_WEAK ast_agi_unregister(struct ast_module *mod, agi_command *cmd);
-void AGI_WEAK ast_agi_register_multiple(struct ast_module *mod, agi_command *cmd, int len);
-void AGI_WEAK ast_agi_unregister_multiple(struct ast_module *mod, agi_command *cmd, int len);
+
+/*!
+ * \brief
+ *
+ * Registers a group of AGI commands, provided as an array of struct agi_command
+ * entries.
+ *
+ * \param mod Pointer to the module_info structure for the module that is registering the commands
+ * \param cmd Pointer to the first entry in the array of commands
+ * \param len Length of the array (use the ARRAY_LEN macro to determine this easily)
+ * \return 0 on success, -1 on failure
+ *
+ * \note If any command fails to register, all commands previously registered during the operation
+ * will be unregistered. In other words, this function registers all the provided commands, or none
+ * of them.
+ */
+int AGI_WEAK ast_agi_register_multiple(struct ast_module *mod, agi_command *cmd, unsigned int len);
+
+/*!
+ * \brief
+ *
+ * Unregisters a group of AGI commands, provided as an array of struct agi_command
+ * entries.
+ *
+ * \param mod Pointer to the module_info structure for the module that is unregistering the commands
+ * \param cmd Pointer to the first entry in the array of commands
+ * \param len Length of the array (use the ARRAY_LEN macro to determine this easily)
+ * \return 0 on success, -1 on failure
+ *
+ * \note If any command fails to unregister, this function will continue to unregister the
+ * remaining commands in the array; it will not reregister the already-unregistered commands.
+ */
+int AGI_WEAK ast_agi_unregister_multiple(struct ast_module *mod, agi_command *cmd, unsigned int len);
#if defined(__cplusplus) || defined(c_plusplus)
}
Modified: team/kpfleming/agi_multiple-api-fix/res/res_agi.c
URL: http://svn.digium.com/view/asterisk/team/kpfleming/agi_multiple-api-fix/res/res_agi.c?view=diff&rev=157224&r1=157222&r2=157224
==============================================================================
--- team/kpfleming/agi_multiple-api-fix/res/res_agi.c (original)
+++ team/kpfleming/agi_multiple-api-fix/res/res_agi.c Sat Nov 15 14:59:36 2008
@@ -2545,21 +2545,47 @@
return unregistered;
}
-void ast_agi_register_multiple(struct ast_module *mod, agi_command *cmd, int len)
-{
- int i;
-
- for (i = 0; i < len; i++)
- ast_agi_register(mod, cmd + i);
-
-}
-
-void ast_agi_unregister_multiple(struct ast_module *mod, agi_command *cmd, int len)
-{
- int i;
-
- for (i = 0; i < len; i++)
- ast_agi_unregister(mod, cmd + i);
+int ast_agi_register_multiple(struct ast_module *mod, agi_command *cmd, unsigned int len)
+{
+ unsigned int i;
+
+ for (i = 0; i < len; i++) {
+ if (ast_agi_register(mod, cmd + i) != 1) {
+ /* registration failed, unregister everything
+ that had been registered up to that point
+ */
+ for (; i > 0; i--) {
+ /* we are intentionally ignoring the
+ result of ast_agi_unregister() here,
+ but it should be safe to do so since
+ we just registered these commands and
+ the only possible way for unregistration
+ to fail is if the command is not
+ registered
+ */
+ (void) ast_agi_unregister(mod, cmd + i);
+ return -1;
+ }
+ }
+ }
+
+ return 0;
+}
+
+int ast_agi_unregister_multiple(struct ast_module *mod, agi_command *cmd, unsigned int len)
+{
+ unsigned int i;
+ int res = 0;
+
+ for (i = 0; i < len; i++) {
+ /* remember whether any of the unregistration
+ attempts failed... there is no recourse if
+ any of them do
+ */
+ res |= ast_agi_unregister(mod, cmd + i);
+ }
+
+ return res;
}
static agi_command *find_command(char *cmds[], int exact)
@@ -3195,7 +3221,10 @@
static int unload_module(void)
{
ast_cli_unregister_multiple(cli_agi, sizeof(cli_agi) / sizeof(struct ast_cli_entry));
- ast_agi_unregister_multiple(ast_module_info->self, commands, sizeof(commands) / sizeof(struct agi_command));
+ /* we can safely ignore the result of ast_agi_unregister_multiple() here, since it cannot fail, as
+ we know that these commands were registered by this module and are still registered
+ */
+ (void) ast_agi_unregister_multiple(ast_module_info->self, commands, ARRAY_LEN(commands));
ast_unregister_application(eapp);
ast_unregister_application(deadapp);
ast_manager_unregister("AGI");
@@ -3205,7 +3234,10 @@
static int load_module(void)
{
ast_cli_register_multiple(cli_agi, sizeof(cli_agi) / sizeof(struct ast_cli_entry));
- ast_agi_register_multiple(ast_module_info->self, commands, sizeof(commands) / sizeof(struct agi_command));
+ /* we can safely ignore the result of ast_agi_register_multiple() here, since it cannot fail, as
+ no other commands have been registered yet
+ */
+ (void) ast_agi_register_multiple(ast_module_info->self, commands, ARRAY_LEN(commands));
ast_register_application(deadapp, deadagi_exec, deadsynopsis, descrip);
ast_register_application(eapp, eagi_exec, esynopsis, descrip);
ast_manager_register2("AGI", EVENT_FLAG_CALL, action_add_agi_cmd, "Add an AGI command to execute by Async AGI", mandescr_asyncagi);
More information about the asterisk-commits
mailing list