Remove inconsistency in CEL eventtype for user defined events.
[asterisk/asterisk.git] / UPGRADE.txt
index 209ebd5..83c2b2b 100644 (file)
-=========================================================
-=== Information for upgrading from Asterisk 1.4 to 1.6
+===========================================================
 ===
+=== Information for upgrading between Asterisk versions
+===
+=== These files document all the changes that MUST be taken
+=== into account when upgrading between the Asterisk
+=== versions listed below. These changes may require that
+=== you modify your configuration files, dialplan or (in
+=== some cases) source code if you have your own Asterisk
+=== modules or patches. These files also include advance
+=== notice of any functionality that has been marked as
+=== 'deprecated' and may be removed in a future release,
+=== along with the suggested replacement functionality.
 ===
 === 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:
-
-* 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.
+=== UPGRADE-1.6.txt -- Upgrade info for 1.4 to 1.6
+=== UPGRADE-1.8.txt -- Upgrade info for 1.6 to 1.8
+=== UPGRADE-10.txt -- Upgrade info for 1.8 to 10
+===
+===========================================================
 
-* The arguments in ExecIf changed a bit, to be more like other applications.
-  The syntax is now ExecIf(<cond>?appiftrue(args):appiffalse(args)).
+From 10 to 11:
 
-* 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.
+Parking:
+ - The comebacktoorigin setting must now be set per parking lot. The setting in
+   the general section will not be applied automatically to each parking lot.
 
 Dialplan Functions:
+ - MAILBOX_EXISTS has been deprecated. Use VM_INFO with the 'exists' parameter
+   instead.
 
-* 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@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.
+func_enum:
+ - ENUM query functions now return a count of -1 on lookup error to
+   differentiate between a failed query and a successful query with 0 results
+   matching the specified type.
 
-* 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.
+Configuration Files:
+ - Files listed below have been updated to be more consistent with how Asterisk
+   parses configuration files.  This makes configuration files more consistent
+   with what is expected across modules.
 
-* 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.
+   - cdr.conf: [general] and [csv] sections
+   - dnsmgr.conf
+   - dsp.conf
 
-* 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.
+AMI:
+  - DBDelTree now correctly returns an error when 0 rows are deleted just as
+    the DBDel action does.
 
-* 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.
+SIP
+===
+ - A new option "tonezone" for setting default tonezone for the channel driver
+   or individual devices
+ - A new manager event, "SessionTimeout" has been added and is triggered when
+   a call is terminated due to RTP stream inactivity or SIP session timer
+   expiration.
+
+users.conf:
+ - A defined user with hasvoicemail=yes now finally uses a Gosub to stdexten
+   as documented in extensions.conf.sample since v1.6.0 instead of a Macro as
+   documented in v1.4.
+
+From 1.8 to 10:
+
+cel_pgsql:
+ - This module now expects an 'extra' column in the database for data added
+   using the CELGenUserEvent() application.
+
+ConfBridge
+ - ConfBridge's dialplan arguments have changed and are not
+   backwards compatible.
+
+File Interpreters
+ - The format interpreter formats/format_sln16.c for the file extension
+   '.sln16' has been removed. The '.sln16' file interpreter now exists
+   in the formats/format_sln.c module along with new support for sln12,
+   sln24, sln32, sln44, sln48, sln96, and sln192 file extensions.
+
+HTTP:
+ - A bindaddr must be specified in order for the HTTP server
+   to run. Previous versions would default to 0.0.0.0 if no
+   bindaddr was specified.
+
+Gtalk:
+ - The default value for 'context' and 'parkinglots' in gtalk.conf has
+   been changed to 'default', previously they were empty.
+
+chan_dahdi:
+ - The mohinterpret=passthrough setting is deprecated in favor of
+   moh_signaling=notify.
+
+pbx_lua:
+ - Execution no longer continues after applications that do dialplan jumps
+   (such as app.goto).  Now when an application such as app.goto() is called,
+   control is returned back to the pbx engine and the current extension
+   function stops executing.
+ - the autoservice now defaults to being on by default
+ - autoservice_start() and autoservice_start() no longer return a value.
+
+Queue:
+ - Mark QUEUE_MEMBER_PENALTY Deprecated it never worked for realtime members
+ - QUEUE_MEMBER is now R/W supporting setting paused, ignorebusy and penalty.
+
+Asterisk Database:
+ - The internal Asterisk database has been switched from Berkeley DB 1.86 to
+   SQLite 3. An existing Berkeley astdb file can be converted with the astdb2sqlite3
+   utility in the UTILS section of menuselect. If an existing astdb is found and no
+   astdb.sqlite3 exists, astdb2sqlite3 will be compiled automatically. Asterisk will
+   convert an existing astdb to the SQLite3 version automatically at runtime. If
+   moving back from Asterisk 10 to Asterisk 1.8, the astdb2bdb utility can be used
+   to create a Berkeley DB copy of the SQLite3 astdb that Asterisk 10 uses.
 
 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 AMI protocol version was incremented to 1.2 as a result of changing two
+   instances of the Unlink event to Bridge events. This change was documented
+   as part of the AMI 1.1 update, but two Unlink events were inadvertently left
+   unchanged.
+
+Module Support Level
+ - All modules in the addons, apps, bridge, cdr, cel, channels, codecs, 
+   formats, funcs, pbx, and res have been updated to include MODULEINFO data
+   that includes <support_level> tags with a value of core, extended, or deprecated.
+   More information is available on the Asterisk wiki at 
+   https://wiki.asterisk.org/wiki/display/AST/Asterisk+Module+Support+States
+
+   Deprecated modules are now marked to not build by default and must be explicitly
+   enabled in menuselect.
+
+chan_sip:
+ - Setting of HASH(SIP_CAUSE,<slave-channel-name>) on channels is now disabled
+   by default. It can be enabled using the 'storesipcause' option. This feature
+   has a significant performance penalty.
+
+UDPTL:
+ - The default UDPTL port range in udptl.conf.sample differed from the defaults
+   in the source. If you didn't have a config file, you got 4500 to 4599. Now the
+   default is 4000 to 4999.
+
+===========================================================
+===========================================================