Merge "CLI: Create ast_cli_completion_add function."
[asterisk/asterisk.git] / UPGRADE-1.2.txt
1 =========================================================
2 ===
3 === Information for upgrading from Asterisk 1.0 to 1.2
4 ===
5 === This file documents 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 =========================================================
16
17 Compiling:
18
19 * The Asterisk 1.2 source code now uses C language features
20   supported only by 'modern' C compilers.  Generally, this means GCC
21   version 3.0 or higher, although some GCC 2.96 releases will also
22   work.  Some non-GCC compilers that support C99 and the common GCC
23   extensions (including anonymous structures and unions) will also
24   work.  All releases of GCC 2.95 do _not_ have the requisite feature
25   support; systems using that compiler will need to be upgraded to
26   a more recent compiler release.
27
28 Dialplan Expressions:
29
30 * The dialplan expression parser (which handles $[ ... ] constructs)
31   has gone through a major upgrade, but has one incompatible change:
32   spaces are no longer required around expression operators, including
33   string comparisons. However, you can now use quoting to keep strings
34   together for comparison. For more details, please read the
35   doc/README.variables file, and check over your dialplan for possible
36   problems.
37
38 Agents:
39
40 * The default for ackcall has been changed to "no" instead of "yes" 
41   because of a bug which caused the "yes" behavior to generally act like
42   "no".  You may need to adjust the value if your agents behave 
43   differently than you expect with respect to acknowledgement.
44
45 * The AgentCallBackLogin application now requires a second '|' before
46   specifying an extension@context.  This is to distinguish the options
47   string from the extension, so that they do not conflict.  See
48   'show application AgentCallbackLogin' for more details.
49
50 Parking:
51
52 * Parking behavior has changed slightly; when a parked call times out,
53   Asterisk will attempt to deliver the call back to the extension that
54   parked it, rather than the 's' extension. If that extension is busy
55   or unavailable, the parked call will be lost.
56
57 Dialing:
58
59 * The Caller*ID of the outbound leg is now the extension that was 
60   called, rather than the Caller*ID of the inbound leg of the call.  The 
61   "o" flag for Dial can be used to restore the original behavior if 
62   desired.  Note that if you are looking for the originating callerid
63   from the manager event, there is a new manager event "Dial" which 
64   provides the source and destination channels and callerid.
65
66 IAX: 
67
68 * The naming convention for IAX channels has changed in two ways: 
69    1. The call number follows a "-" rather than a "/" character.
70    2. The name of the channel has been simplified to IAX2/peer-callno,
71    rather than IAX2/peer@peer-callno or even IAX2/peer@peer/callno.
72
73 SIP:
74
75 * The global option "port" in 1.0.X that is used to set which port to
76   bind to has been changed to "bindport" to be more consistent with
77   the other channel drivers and to avoid confusion with the "port"
78   option for users/peers.
79
80 * The "Registry" event now uses "Username" rather than "User" for 
81   consistency with IAX.
82
83 Applications:
84
85 * With the addition of dialplan functions (which operate similarly
86   to variables), the SetVar application has been renamed to Set.
87
88 * The CallerPres application has been removed.  Use SetCallerPres 
89   instead.  It accepts both numeric and symbolic names.
90
91 * The applications GetGroupCount, GetGroupMatchCount, SetGroup, and
92   CheckGroup have been deprecated in favor of functions.  Here is a
93   table of their replacements:
94
95   GetGroupCount([groupname][@category]         GROUP_COUNT([groupname][@category])      Set(GROUPCOUNT=${GROUP_COUNT()})
96   GroupMatchCount(groupmatch[@category])       GROUP_MATCH_COUNT(groupmatch[@category]) Set(GROUPCOUNT=${GROUP_MATCH_COUNT(SIP/.*)})
97   SetGroup(groupname[@category])               GROUP([category])=groupname              Set(GROUP()=test)
98   CheckGroup(max[@category])                   N/A                                      GotoIf($[ ${GROUP_COUNT()} > 5 ]?103)
99
100   Note that CheckGroup does not have a direct replacement.  There is
101   also a new function called GROUP_LIST() which will return a space
102   separated list of all of the groups set on a channel.  The GROUP()
103   function can also return the name of the group set on a channel when
104   used in a read environment.
105
106 * The applications DBGet and DBPut have been deprecated in favor of
107   functions.  Here is a table of their replacements:
108
109   DBGet(foo=family/key)        Set(foo=${DB(family/key)})
110   DBPut(family/key=${foo})     Set(DB(family/key)=${foo})
111
112 * The application SetLanguage has been deprecated in favor of the
113   function LANGUAGE().
114
115   SetLanguage(fr)               Set(LANGUAGE()=fr)
116
117   The LANGUAGE function can also return the currently set language:
118
119   Set(MYLANG=${LANGUAGE()})
120
121 * The applications AbsoluteTimeout, DigitTimeout, and ResponseTimeout
122   have been deprecated in favor of the function TIMEOUT(timeouttype):
123
124   AbsoluteTimeout(300)          Set(TIMEOUT(absolute)=300)
125   DigitTimeout(15)              Set(TIMEOUT(digit)=15)
126   ResponseTimeout(15)           Set(TIMEOUT(response)=15)
127
128   The TIMEOUT() function can also return the currently set timeouts:
129
130   Set(DTIMEOUT=${TIMEOUT(digit)})
131
132 * The applications SetCIDName, SetCIDNum, and SetRDNIS have been
133   deprecated in favor of the CALLERID(datatype) function:
134
135   SetCIDName(Joe Cool)          Set(CALLERID(name)=Joe Cool)
136   SetCIDNum(2025551212)         Set(CALLERID(number)=2025551212)
137   SetRDNIS(2024561414)          Set(CALLERID(RDNIS)=2024561414)
138
139 * The application Record now uses the period to separate the filename
140   from the format, rather than the colon.
141
142 * The application VoiceMail now supports a 'temporary' greeting for each
143   mailbox. This greeting can be recorded by using option 4 in the
144   'mailbox options' menu, and 'change your password' option has been
145   moved to option 5.
146
147 * The application VoiceMailMain now only matches the 'default' context if
148   none is specified in the arguments.  (This was the previously 
149   documented behavior, however, we didn't follow that behavior.)  The old
150   behavior can be restored by setting searchcontexts=yes in voicemail.conf.
151
152 Queues:
153
154 * A queue is now considered empty not only if there are no members but if
155   none of the members are available (e.g. agents not logged on).  To
156   restore the original behavior, use "leavewhenempty=strict" or 
157   "joinwhenempty=strict" instead of "=yes" for those options.
158
159 * It is now possible to use multi-digit extensions in the exit context
160   for a queue (although you should not have overlapping extensions,
161   as there is no digit timeout). This means that the EXITWITHKEY event
162   in queue_log can now contain a key field with more than a single
163   character in it.
164
165 Extensions:
166
167 * By default, there is a new option called "autofallthrough" in
168   extensions.conf that is set to yes.  Asterisk 1.0 (and earlier) 
169   behavior was to wait for an extension to be dialed after there were no 
170   more extensions to execute.  "autofallthrough" changes this behavior
171   so that the call will immediately be terminated with BUSY,
172   CONGESTION, or HANGUP based on Asterisk's best guess.  If you are
173   writing an extension for IVR, you must use the WaitExten application
174   if "autofallthrough" is set to yes.
175
176 AGI:
177
178 * AGI scripts did not always get SIGHUP at the end, previously.  That 
179   behavior has been fixed.  If you do not want your script to terminate 
180   at the end of AGI being called (e.g. on a hangup) then set SIGHUP to 
181   be ignored within your application.
182
183 * CallerID is reported with agi_callerid and agi_calleridname instead
184   of a single parameter holding both.
185
186 Music On Hold:
187
188 * The preferred format for musiconhold.conf has changed; please see the
189   sample configuration file for the new format. The existing format
190   is still supported but will generate warnings when the module is loaded.
191
192 chan_modem:
193
194 * All the chan_modem channel drivers (aopen, bestdata and i4l) are deprecated
195   in this release, and will be removed in the next major Asterisk release.
196   Please migrate to chan_misdn for ISDN interfaces; there is no upgrade
197   path for aopen and bestdata modem users.
198
199 MeetMe:
200
201 * The conference application now allows users to increase/decrease their
202   speaking volume and listening volume (independently of each other and 
203   other users); the 'admin' and 'user' menus have changed, and new sound 
204   files are included with this release. However, if a user calling in 
205   over a Zaptel channel that does NOT have hardware DTMF detection 
206   increases their speaking volume, it is likely they will no longer be 
207   able to enter/exit the menu or make any further adjustments, as the  
208   software DTMF detector will not be able to recognize the DTMF coming 
209   from their device.
210
211 GetVar Manager Action:
212
213 * Previously, the behavior of the GetVar manager action reported the value
214   of a variable in the following manner:
215    > name: value
216   This has been changed to a manner similar to the SetVar action and is now
217    > Variable: name
218    > Value: value