app_read does not break from prompt loop with user terminated empty string
[asterisk/asterisk.git] / UPGRADE-1.6.txt
1 =========================================================
2 ===
3 === Information for upgrading from Asterisk 1.4 to 1.6
4 ===
5 === These files document all the changes that MUST be taken
6 === into account when upgrading between the Asterisk
7 === versions listed below. These changes may require that
8 === you modify your configuration files, dialplan or (in
9 === some cases) source code if you have your own Asterisk
10 === modules or patches. These files also includes advance
11 === notice of any functionality that has been marked as
12 === 'deprecated' and may be removed in a future release,
13 === along with the suggested replacement functionality.
14 ===
15 === UPGRADE-1.2.txt -- Upgrade info for 1.0 to 1.2
16 === UPGRADE-1.4.txt -- Upgrade info for 1.2 to 1.4
17 ===
18 =========================================================
19
20 AEL:
21
22 * Macros are now implemented underneath with the Gosub() application.
23   Heaven Help You if you wrote code depending on any aspect of this!
24   Previous to 1.6, macros were implemented with the Macro() app, which
25   provided a nice feature of auto-returning. The compiler will do its
26   best to insert a Return() app call at the end of your macro if you did
27   not include it, but really, you should make sure that all execution
28   paths within your macros end in "return;".
29
30 * The conf2ael program is 'introduced' in this release; it is in a rather
31   crude state, but deemed useful for making a first pass at converting
32   extensions.conf code into AEL. More intelligence will come with time.
33
34 Core:
35
36 * The 'languageprefix' option in asterisk.conf is now deprecated, and
37   the default sound file layout for non-English sounds is the 'new
38   style' layout introduced in Asterisk 1.4 (and used by the automatic
39   sound file installer in the Makefile).
40
41 * The ast_expr2 stuff has been modified to handle floating-point numbers.
42   Numbers of the format D.D are now acceptable input for the expr parser, 
43   Where D is a string of base-10 digits. All math is now done in "long double",
44   if it is available on your compiler/architecture. This was half-way between
45   a bug-fix (because the MATH func returns fp by default), and an enhancement.
46   Also, for those counting on, or needing, integer operations, a series of
47   'functions' were also added to the expr language, to allow several styles
48   of rounding/truncation, along with a set of common floating point operations,
49   like sin, cos, tan, log, pow, etc. The ability to call external functions
50   like CDR(), etc. was also added, without having to use the ${...} notation.
51  
52 * The delimiter passed to applications has been changed to the comma (','), as
53   that is what people are used to using within extensions.conf.  If you are
54   using realtime extensions, you will need to translate your existing dialplan
55   to use this separator.  To use a literal comma, you need merely to escape it
56   with a backslash ('\').  Another possible side effect is that you may need to
57   remove the obscene level of backslashing that was necessary for the dialplan
58   to work correctly in 1.4 and previous versions.  This should make writing
59   dialplans less painful in the future, albeit with the pain of a one-time
60   conversion.  If you would like to avoid this conversion immediately, set
61   pbx_realtime=1.4 in the [compat] section of asterisk.conf.  After
62   transitioning, set pbx_realtime=1.6 in the same section.
63
64 * For the same purpose as above, you may set res_agi=1.4 in the [compat]
65   section of asterisk.conf to continue to use the '|' delimiter in the EXEC
66   arguments of AGI applications.  After converting to use the ',' delimiter,
67   change this option to res_agi=1.6.
68
69 * As a side effect of the application delimiter change, many places that used
70   to need quotes in order to get the proper meaning are no longer required.
71   You now only need to quote strings in configuration files if you literally
72   want quotation marks within a string.
73
74 * The logger.conf option 'rotatetimestamp' has been deprecated in favor of
75   'rotatestrategy'.  This new option supports a 'rotate' strategy that more
76   closely mimics the system logger in terms of file rotation.
77
78 * The concise versions of various CLI commands are now deprecated. We recommend
79   using the manager interface (AMI) for application integration with Asterisk.
80
81 Voicemail:
82
83 * The voicemail configuration values 'maxmessage' and 'minmessage' have
84   been changed to 'maxsecs' and 'minsecs' to clarify their purpose and
85   to make them more distinguishable from 'maxmsgs', which sets folder
86   size.  The old variables will continue to work in this version, albeit
87   with a deprecation warning.
88
89 * If you use any interface for modifying voicemail aside from the built in
90   dialplan applications, then the option "pollmailboxes" *must* be set in
91   voicemail.conf for message waiting indication (MWI) to work properly.  This
92   is because Voicemail notification is now event based instead of polling
93   based.  The channel drivers are no longer responsible for constantly manually
94   checking mailboxes for changes so that they can send MWI information to users.
95   Examples of situations that would require this option are web interfaces to
96   voicemail or an email client in the case of using IMAP storage.
97
98 Applications:
99
100
101 * ChanIsAvail() now has a 't' option, which allows the specified device
102   to be queried for state without consulting the channel drivers. This
103   performs mostly a 'ChanExists' sort of function.
104
105 * ChannelRedirect() will not terminate the channel that fails to do a
106   channelredirect as it has done previously. Instead CHANNELREDIRECT_STATUS
107   will reflect if the attempt was successful of not.
108
109 * SetCallerPres() has been replaced with the CALLERPRES() dialplan function
110   and is now deprecated.
111
112 * DISA()'s fifth argument is now an options argument.  If you have previously
113   used 'NOANSWER' in this argument, you'll need to convert that to the new
114   option 'n'.
115
116 * Macro() is now deprecated.  If you need subroutines, you should use the
117   Gosub()/Return() applications.  To replace MacroExclusive(), we have
118   introduced dialplan functions LOCK(), TRYLOCK(), and UNLOCK().  You may use
119   these functions in any location where you desire to ensure that only one
120   channel is executing that path at any one time.  The Macro() applications
121   are deprecated for performance reasons.  However, since Macro() has been
122   around for a long time and so many dialplans depend heavily on it, for the
123   sake of backwards compatibility it will not be removed .  It is also worth
124   noting that using both Macro() and GoSub() at the same time is _heavily_
125   discouraged.
126
127 * Read() now sets a READSTATUS variable on exit.  It does NOT automatically
128   return -1 (and hangup) anymore on error.  If you want to hangup on error,
129   you need to do so explicitly in your dialplan.
130
131 * Privacy() no longer uses privacy.conf, so any options must be specified
132   directly in the application arguments.
133
134 * MusicOnHold application now has duration parameter which allows specifying
135   timeout in seconds.
136
137 * WaitMusicOnHold application is now deprecated in favor of extended MusicOnHold.
138
139 * SetMusicOnHold is now deprecated. You should use Set(CHANNEL(musicclass)=...)
140   instead.
141
142 * The arguments in ExecIf changed a bit, to be more like other applications.
143   The syntax is now ExecIf(<cond>?appiftrue(args):appiffalse(args)).
144
145 * The behavior of the Set application now depends upon a compatibility option,
146   set in asterisk.conf.  To use the old 1.4 behavior, which allowed Set to take
147   multiple key/value pairs, set app_set=1.4 in [compat] in asterisk.conf.  To
148   use the new behavior, which permits variables to be set with embedded commas,
149   set app_set=1.6 in [compat] in asterisk.conf.  Note that you can have both
150   behaviors at the same time, if you switch to using MSet if you want the old
151   behavior.
152
153 Dialplan Functions:
154
155 * QUEUE_MEMBER_COUNT() has been deprecated in favor of the QUEUE_MEMBER() function. For
156   more information, issue a "show function QUEUE_MEMBER" from the CLI.
157
158 CDR:
159
160 * The cdr_sqlite module has been marked as deprecated in favor of
161   cdr_sqlite3_custom.  It will potentially be removed from the tree
162   after Asterisk 1.6 is released.
163
164 * The cdr_odbc module now uses res_odbc to manage its connections.  The
165   username and password parameters in cdr_odbc.conf, therefore, are no
166   longer used.  The dsn parameter now points to an entry in res_odbc.conf.
167
168 * The uniqueid field in the core Asterisk structure has been changed from a
169   maximum 31 character field to a 149 character field, to account for all
170   possible values the systemname prefix could be.  In the past, if the
171   systemname was too long, the uniqueid would have been truncated.
172
173 * The cdr_tds module now supports all versions of FreeTDS that contain
174   the db-lib frontend.  It will also now log the userfield variable if
175   the target database table contains a column for it.
176
177 Formats:
178
179 * format_wav: The GAIN preprocessor definition and source code that used it
180   is removed.  This change was made in response to user complaints of
181   choppiness or the clipping of loud signal peaks.  To increase the volume
182   of voicemail messages, use the 'volgain' option in voicemail.conf
183
184 Channel Drivers:
185
186 * SIP: a small upgrade to support the "Record" button on the SNOM360,
187   which sends a sip INFO message with a "Record: on" or "Record: off" 
188   header. If Asterisk is set up (via features.conf) to accept "One Touch Monitor"
189   requests (by default, via '*1'), then the user-configured dialpad sequence
190   is generated, and recording can be started and stopped via this button. The
191   file names and formats are all controlled via the normal mechanisms. If the
192   user has not configured the automon feature, the normal "415 Unsupported media type"
193   is returned, and nothing is done.
194
195 * SIP: The "call-limit" option is marked as deprecated. It still works in this version of
196   Asterisk, but will be removed in the following version. Please use the groupcount functions
197   in the dialplan to enforce call limits. The "limitonpeer" configuration option is
198   now renamed to "counteronpeer".
199
200 * SIP: The "username" option is now renamed to "defaultuser" to match "defaultip".
201   These are used only before registration to call a peer with the uri 
202         sip:defaultuser@defaultip
203   The "username" setting still work, but is deprecated and will not work in 
204   the next version of Asterisk.
205
206 * chan_local.c: the comma delimiter inside the channel name has been changed to a
207   semicolon, in order to make the Local channel driver compatible with the comma
208   delimiter change in applications.
209
210 * H323: The "tos" setting has changed name to "tos_audio" and "cos" to "cos_audio"
211   to be compatible with settings in sip.conf. The "tos" and "cos" configuration
212   is deprecated and will stop working in the next release of Asterisk.
213
214 * Console: A new console channel driver, chan_console, has been added to Asterisk.
215   This new module can not be loaded at the same time as chan_alsa or chan_oss.  The
216   default modules.conf only loads one of them (chan_oss by default).  So, unless you
217   have modified your modules.conf to not use the autoload option, then you will need
218   to modify modules.conf to add another "noload" line to ensure that only one of
219   these three modules gets loaded.
220
221 * DAHDI: The chan_zap module that supported PSTN interfaces using
222   Zaptel has been renamed to chan_dahdi, and only supports the DAHDI
223   telephony driver package for PSTN interfaces. See the
224   Zaptel-to-DAHDI.txt file for more details on this transition.
225
226 * DAHDI: The "msdstrip" option has been deprecated, as it provides no value over
227   the method of stripping digits in the dialplan using variable substring syntax.
228
229 Configuration:
230
231 * pbx_dundi.c: tos parameter changed to use new values. Old values like lowdelay,
232   lowcost and other is not acceptable now. Look into qos.tex for description of 
233   this parameter.
234
235 * queues.conf: the queue-lessthan sound file option is no longer available, and the
236   queue-round-seconds option no longer takes '1' as a valid parameter.
237
238 Manager:
239
240 * Manager has been upgraded to version 1.1 with a lot of changes. 
241   Please check doc/manager_1_1.txt for information
242
243 * The IAXpeers command output has been changed to more closely resemble the
244   output of the SIPpeers command.
245
246 * cdr_manager now reports at the "cdr" level, not at "call"  You may need to
247    change your manager.conf to add the level to existing AMI users, if they
248    want to see the CDR events generated.
249
250 * The Originate command now requires the Originate write permission.  For
251    Originate with the Application parameter, you need the additional System
252    privilege if you want to do anything that calls out to a subshell.
253
254 iLBC Codec:
255
256 * Previously, the Asterisk source code distribution included the iLBC
257   encoder/decoder source code, from Global IP Solutions
258   (http://www.gipscorp.com). This code is not licensed for
259   distribution, and thus has been removed from the Asterisk source
260   code distribution. If you wish to use codec_ilbc to support iLBC
261   channels in Asterisk, you can run the contrib/scripts/get_ilbc_source.sh
262   script to download the source and put it in the proper place in
263   the Asterisk build tree. Once that is done you can follow your normal
264   steps of building Asterisk. You will need to run 'menuselect' and enable
265   the iLBC codec in the 'Codec  Translators' category.