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