res_speech_aeap: check for null format on response

* Fixed issue in res_speech_aeap when unable to provide an
  input format to check against.

func_periodic_hook: Don't truncate channel name

func_periodic_hook was truncating long channel names which
causes issues when you need to run other dialplan functions/apps
on the channel.

Resolves: #319

safe_asterisk: Change directory permissions to 755

If the safe_asterisk script detects that the /var/lib/asterisk
directory doesn't exist, it now creates it with 755 permissions
instead of 770.  safe_asterisk needing to create that directory
should be extremely rare though because it's normally created
by 'make install' which already sets the permissions to 755.

Resolves: #316

chan_rtp: Implement RTP glue for UnicastRTP channels

Resolves: #298

UserNote: The dial string option 'g' was added to the UnicastRTP channel
which enables RTP glue and therefore native RTP bridges with those
channels.

app_queue: periodic announcement configurable start time.

This newly introduced periodic-announce-startdelay makes it possible to
configure the initial start delay of the first periodic announcement
after which periodic-announce-frequency takes over.

UserNote: Introduce a new queue configuration option called
'periodic-announce-startdelay' which will vary the normal (historic)
behavior of starting the periodic announcement cycle at
periodic-announce-frequency seconds after entering the queue to start
the periodic announcement cycle at period-announce-startdelay seconds
after joining the queue.  The default behavior if this config option is
not set remains unchanged.

Signed-off-by: Jaco Kroon <jaco@uls.co.za>

variables: Add additional variable dialplan functions.

Using the Set dialplan application does not actually
delete channel or global variables. Instead the
variables are set to an empty value.

This change adds two dialplan functions,
GLOBAL_DELETE and DELETE which can be used to
delete global and channel variables instead
of just setting them to empty.

There is also no ability within the dialplan to
determine if a global or channel variable has
actually been set or not.

This change also adds two dialplan functions,
GLOBAL_EXISTS and VARIABLE_EXISTS which can be
used to determine if a global or channel variable
has been set or not.

Resolves: #289

UserNote: Four new dialplan functions have been added.
GLOBAL_DELETE and DELETE have been added which allows
the deletion of global and channel variables.
GLOBAL_EXISTS and VARIABLE_EXISTS have been added
which checks whether a global or channel variable has
been set.

ari-stubs: Fix more local anchor references

Also allow CreateDocs job to be run manually with default branches.

ari-stubs: Fix more local anchor references

Also allow CreateDocs job to be run manually with default branches.

ari-stubs: Fix broken documentation anchors

All of the links that reference page anchors with capital letters in
the ids (#Something) have been changed to lower case to match the
anchors that are generated by mkdocs.

res_pjsip_session: Send Session Interval too small response

Handle session interval lower than endpoint's configured minimum timer
when sending first answer. Timer setting is checked during this step and
needs to handled appropriately.
Before this change, no response was sent at all. After this change a
response with 422 Session Interval too small is sent to UAC.

.github: Update workflow-application-token-action to v2

app_dial: Fix infinite loop when sending digits.

If the called party hangs up while digits are being
sent, -1 is returned to indicate so, but app_dial
was not checking the return value, resulting in
the hangup being lost and looping forever until
the caller manually hangs up the channel. We now
abort if digit sending fails.

ASTERISK-29428 #close

Resolves: #281

app_voicemail: Fix for loop declarations

Resolve for loop initial declarations added in cli changes.

Resolves: #275

alembic: Fix quoting of the 100rel column

Add quoting around the ps_endpoints 100rel column in the ALTER
statements.  Although alembic doesn't complain when generating
sql statements, postgresql does (rightly so).

Resolves: #274

pbx.c: Fix gcc 12 compiler warning.

Resolves: #277

app_audiosocket: Fixed timeout with -1 to avoid busy loop.

Resolves: asterisk#234

download_externals:  Fix a few version related issues

* Fixed issue with the script not parsing the new tag format for
  certified releases.  The format changed from certified/18.9-cert5
  to certified-18.9-cert5.

* Fixed issue where the asterisk version wasn't being considered
  when looking for cached versions.

Resolves: #263

main/refer.c: Fix double free in refer_data_destructor + potential leak

Resolves: #267

sig_analog: Add Called Subscriber Held capability.

This adds support for Called Subscriber Held for FXS
lines, which allows users to go on hook when receiving
a call and resume the call later from another phone on
the same line, without disconnecting the call. This is
a convenience mechanism that most real PSTN telephone
switches support.

ASTERISK-30372 #close

Resolves: #240

UserNote: Called Subscriber Held is now supported for analog
FXS channels, using the calledsubscriberheld option. This allows
a station  user to go on hook when receiving an incoming call
and resume from another phone on the same line by going on hook,
without disconnecting the call.

Revert "app_stack: Print proper exit location for PBXless channels."

This reverts commit 617dad4cba1513dddce87b8e95a61415fb587cf1.

apps/app_stack.c: Revert buggy gosub patch

This seems to break the case when a predial macro calls a gosub.
When the gosub calls return, the Return function outputs:

app_stack.c:423 return_exec: Return without Gosub: stack is empty

This returns -1 to the calling macro, which returns to app_dial
and causes the call to hangup instead of proceeding with the macro
that invoked the gosub.

Resolves: #253

install_prereq: Fix dependency install on aarch64.

Fixes dependency solutions in install_prereq for Debian aarch64
platforms. install_prereq was attempting to forcibly install 32-bit
armhf packages due to the aptitude search for dependencies.

Resolves: #37

res_pjsip.c: Set contact_user on incoming call local Contact header

If the contact_user is configured on the endpoint it will now be set on the local Contact header URI for incoming calls. The contact_user has already been set on the local Contact header URI for outgoing calls.

Resolves: #226

extconfig: Allow explicit DB result set ordering to be disabled.

Added a new boolean configuration flag -
`order_multi_row_results_by_initial_column` - to both res_pgsql.conf
and res_config_odbc.conf that allows the administrator to disable the
explicit `ORDER BY` that was previously being added to all generated
SQL statements that returned multiple rows.

Fixes: #179

rest-api: Run make ari-stubs

An earlier cherry-pick that involved rest-api somehow didn't include
a comment change in res/ari/resource_endpoints.h.  This commit
corrects that.  No changes other than the comment.

res_pjsip_header_funcs: Make prefix argument optional.

The documentation for PJSIP_HEADERS claims that
prefix is optional, but in the code it is actually not.
However, there is no inherent reason for this, as users
may want to retrieve all header names, not just those
beginning with a certain prefix.

This makes the prefix optional for this function,
simply fetching all header names if not specified.
As a result, the documentation is now correct.

Resolves: #230

UserNote: The prefix argument to PJSIP_HEADERS is now
optional. If not specified, all header names will be
returned.

pjproject_bundled: Increase PJSIP_MAX_MODULE to 38

The default is 32 with 8 being used by pjproject itself.  Recent
commits have put us over the limit resulting in assertions in
pjproject.  Since this value is used in invites, dialogs,
transports and subscriptions as well as the global pjproject
endpoint, we don't want to increase it too much.

Resolves: #255

manager: Tolerate stasis messages with no channel snapshot.

In some cases I have yet to determine some stasis messages may
be created without a channel snapshot. This change adds some
tolerance to this scenario, preventing a crash from occurring.

Remove unneeded CHANGES and UPGRADE files

Update version for Asterisk 21

core/ari/pjsip: Add refer mechanism

This change adds support for refers that are not session based. It
includes a refer implementation for the PJSIP technology which results
in out-of-dialog REFERs being sent to a PJSIP endpoint. These can be
triggered using the new ARI endpoint `/endpoints/refer`.

Resolves: #71

UserNote: There is a new ARI endpoint `/endpoints/refer` for referring
an endpoint to some URI or endpoint.

chan_dahdi: Allow autoreoriginating after hangup.

Currently, if an FXS channel is still off hook when
all calls on the line have hung up, the user is provided
reorder tone until going back on hook again.

In addition to not reflecting what most commercial switches
actually do, it's very common for switches to automatically
reoriginate for the user so that dial tone is provided without
the user having to depress and release the hookswitch manually.
This can increase convenience for users.

This behavior is now supported for kewlstart FXS channels.
It's supported only for kewlstart (FXOKS) mainly because the
behavior doesn't make any sense for ground start channels,
and loop start signalling doesn't provide the necessary DAHDI
event that makes this easy to implement. Likely almost everyone
is using FXOKS over FXOLS anyways since FXOLS is pretty useless
these days.

ASTERISK-30357 #close

Resolves: #224

UserNote: The autoreoriginate setting now allows for kewlstart FXS
channels to automatically reoriginate and provide dial tone to the
user again after all calls on the line have cleared. This saves users
from having to manually hang up and pick up the receiver again before
making another call.

audiohook: Unlock channel in mute if no audiohooks present.

In the case where mute was called on a channel that had no
audiohooks the code was not unlocking the channel, resulting
in a deadlock.

Resolves: #233

sig_analog: Allow three-way flash to time out to silence.

sig_analog allows users to flash and use the three-way dial
tone as a primitive hold function, simply by never timing
it out.

Some systems allow this dial tone to time out to silence,
so the user is not annoyed by a persistent dial tone.
This option allows the dial tone to time out normally to
silence.

ASTERISK-30004 #close
Resolves: #205

UserNote: The threewaysilenthold option now allows the three-way
dial tone to time out to silence, rather than continuing forever.

res_prometheus: Do not generate broken metrics

In 8d6fdf9c3adede201f0ef026dab201b3a37b26b6 invisible bridges were
skipped but that lead to producing metrics with no name and no help.

Keep track of the number of metrics configured and then only emit these.
Add a basic testcase that verifies that there is no '(NULL)' in the
output.

ASTERISK-30474

res_pjsip: Enable TLS v1.3 if present.

Fixes #221

UserNote: res_pjsip now allows TLS v1.3 to be enabled if supported by
the underlying PJSIP library. The bundled version of PJSIP supports
TLS v1.3.

func_cut: Add example to documentation.

This adds an example to the XML documentation clarifying usage
of the CUT function to address a common misusage.

extensions.conf.sample: Remove reference to missing context.

c3ff4648 removed the [iaxtel700] context but neglected to remove
references to it.

This commit addresses that and also removes iaxtel and freeworlddialup
references from other config files.

func_export: Use correct function argument as variable name.

Fixes #208

app_queue: Add support for applying caller priority change immediately.

The app_queue module provides both an AMI action and a CLI command
to change the priority of a caller in a queue. Up to now this change
of priority has only been reflected to new callers into the queue.

This change adds an "immediate" option to both the AMI action and
CLI command which immediately applies the priority change respective
to the other callers already in the queue. This can allow, for example,
a caller to be placed at the head of the queue immediately if their
priority is sufficient.

Resolves: #202

UserNote: The 'queue priority caller' CLI command and
'QueueChangePriorityCaller' AMI action now have an 'immediate'
argument which allows the caller priority change to be reflected
immediately, causing the position of a caller to move within the
queue depending on the priorities of the other callers.

.github: Fix cherry-pick reminder issues

app.h: Move declaration of ast_getdata_result before its first use

The ast_app_getdata() and ast_app_getdata_terminator() declarations
in app.h were changed recently to return enum ast_getdata_result
(which is how they were defined in app.c).  The existing
declaration of ast_getdata_result in app.h was about 1000 lines
after those functions however so under certain circumstances,
a "use before declaration" error was thrown by the compiler.
The declaration of the enum was therefore moved to before those
functions.

Resolves: #200

chan_iax2.c: Avoid crash with IAX2 switch support.

A change made in 82cebaa0 did not properly handle the case when a
channel was not provided, triggering a crash. ast_check_hangup(...)
does not protect against NULL pointers.

Fixes #180

res_geolocation: Ensure required 'location_info' is present.

Fixes #189

Adds manager actions to allow move/remove/forward individual messages
in a particular mailbox folder. The forward command can be used
to copy a message within a mailbox or to another mailbox. Also adds
a VoicemailBoxSummarry, required to retrieve message ID's.

Resolves: #181

UserNote: The following manager actions have been added

VoicemailBoxSummary - Generate message list for a given mailbox

VoicemailRemove - Remove a message from a mailbox folder

VoicemailMove - Move a message from one folder to another within a mailbox

VoicemailForward - Copy a message from one folder in one mailbox
to another folder in another or the same mailbox.

app_voicemail: add CLI commands for message manipulation

Adds CLI commands to allow move/remove/forward individual messages
from a particular mailbox folder. The forward command can be used
to copy a message within a mailbox or to another mailbox. Also adds
a show mailbox, required to retrieve message ID's.

Resolves: #170

UserNote: The following CLI commands have been added to app_voicemail

voicemail show mailbox <mailbox> <context>
Show contents of mailbox <mailbox>@<context>

voicemail remove <mailbox> <context> <from_folder> <messageid>
Remove message <messageid> from <from_folder> in mailbox <mailbox>@<context>

voicemail move <mailbox> <context> <from_folder> <messageid> <to_folder>
Move message <messageid> in mailbox <mailbox>&<context> from <from_folder> to <to_folder>

voicemail forward <from_mailbox> <from_context> <from_folder> <messageid> <to_mailbox> <to_context> <to_folder>
Forward message <messageid> in mailbox <mailbox>@<context> <from_folder> to
mailbox <mailbox>@<context> <to_folder>

res_rtp_asterisk: Move ast_rtp_rtcp_report_alloc using `rtp->themssrc_valid` into the scope of the rtp_instance lock.

From the gdb information, it was found that when calling __ast_free, the size of the
allocated space pointed to by the pointer matches the size created when rtp->themssrc_valid
is equal to 0. However, in reality, when reading the value of rtp->themssrc_valid in gdb,
it is found to be 1.

Within ast_rtcp_write(), the call to ast_rtp_rtcp_report_alloc() uses rtp->themssrc_valid,
which is outside the protection of the rtp_instance lock. However,
ast_rtcp_generate_report(), which is called by ast_rtcp_generate_compound_prefix(), uses
rtp->themssrc_valid within the protection of the rtp_instance lock.

This can lead to the possibility that the value of rtp->themssrc_valid used in the call to
ast_rtp_rtcp_report_alloc() may be different from the value of rtp->themssrc_valid used
within ast_rtcp_generate_report().

Resolves: asterisk#63

users.conf: Deprecate users.conf configuration.

This deprecates the users.conf config file, which
is no longer as widely supported but still integrated
with a number of different modules.

Because there is no real mechanism for marking a
configuration file as "deprecated", and users.conf
is not just used in a single place, this now emits
a warning to the user when the PBX loads to notify
about the deprecation.

This configuration mechanism has been widely criticized
and discouraged since its inception, and is no longer
relevant to the configuration that most users are doing
today. Removing it will allow for some simplification
and cleanup in the codebase.

Resolves: #183

UpgradeNote: The users.conf config is now deprecated
and will be removed in a future version of Asterisk.

.github: Minor tweak to Asterisk Releaser

.github: Suppress cherry-pick reminder for some situations

In PROpenedOrUpdated, the cherry-pick reminder will now be
suppressed if there are already valid 'cherry-pick-to' comments
in the PR or the PR contained a 'cherry-pick-to: none' comment.

sig_analog: Allow immediate fake ring to be suppressed.

When immediate=yes on an FXS channel, sig_analog will
start fake audible ringback that continues until the
channel is answered. Even if it answers immediately,
the ringback is still audible for a brief moment.
This can be disruptive and unwanted behavior.

This adds an option to disable this behavior, though
the default behavior remains unchanged.

ASTERISK-30003 #close
Resolves: #118

UserNote: The immediatering option can now be set to no to suppress
the fake audible ringback provided when immediate=yes on FXS channels.

.github: Update AsteriskReleaser for security releases

apply_patches: Use globbing instead of file/sort.

This accomplishes the same thing as a `find ... | sort` but with the
added benefit of clarity and avoiding a call to a subshell.

Additionally drop the -s option from call to patch as it is not POSIX.

apply_patches: Sort patch list before applying

The apply_patches script wasn't sorting the list of patches in
the "patches" directory before applying them. This left the list
in an indeterminate order. In most cases, the list is actually
sorted but rarely, they can be out of order and cause dependent
patches to fail to apply.

We now sort the list but the "sort" program wasn't in the
configure scripts so we needed to add that and regenerate
the scripts as well.

Resolves: #193

pjsip: Upgrade bundled version to pjproject 2.13.1

.github: Updates for AsteriskReleaser

app_voicemail: fix imap compilation errors

Fixes two compilation errors in app_voicemail_imap, one due to an unsed
variable and one due to a new variable added in the incorrect location
in _163.

Resolves: #174

res_musiconhold: avoid moh state access on unlocked chan

Move channel unlock to after moh state access to avoid
potential unlocked access to state.

Resolves: #133

utils: add lock timestamps for DEBUG_THREADS

Adds last locked and unlocked timestamps as well as a
counter for the number of times the lock has been
attempted (vs locked/unlocked) to debug output printed
using the DEBUG_THREADS option.

Resolves: #110

.github: Back out triggering PROpenedOrUpdated by label

.github: Move publish docs to new file CreateDocs.yml

rest-api: Updates for new documentation site

The new documentation site uses traditional markdown instead
of the Confluence flavored version.  This required changes in
the mustache templates and the python that generates the files.

rest-api: Ran make ari stubs to fix resource_endpoints inconsistency

.github: Remove result check from PROpenUpdateGateTests

.github: Fix use of 'contains'

.github: Add recheck label test to additional jobs

.github: Fix recheck label typos

.github: Fix recheck label manipulation

.github: Allow PR submit checks to be re-run by label

app_voicemail_imap: Fix message count when IMAP server is unavailable

Some callers of __messagecount did not correctly handle error return,
instead returning a -1 message count.
This caused a notification with "Messages-Waiting: yes" and
"Voice-Message: -1/0 (0/0)" if the IMAP server was unavailable.

Fixes: #64

res_pjsip_rfc3326: Prefer Q.850 cause code over SIP.

Resolves: #116

Update config.yml

res_pjsip_session: Added new function calls to avoid ABI issues.

Added two new functions (ast_sip_session_get_dialog and
ast_sip_session_get_pjsip_inv_state) that retrieve the dialog and the
pjsip_inv_state respectively from the pjsip_inv_session on the
ast_sip_session struct. This is due to pjproject adding a new field to
the pjsip_inv_session struct that caused crashes when trying to access
fields that were no longer where they were expected to be if a module
was compiled against a different version of pjproject.

Resolves: #145

app_queue: Add force_longest_waiting_caller option.

This adds an option 'force_longest_waiting_caller' which changes the
global behavior of the queue engine to prevent queue callers from
'jumping ahead' when an agent is in multiple queues.

Resolves: #108

Also closes old asterisk issues:
- ASTERISK-17732
- ASTERISK-17570

Change-Id: I0f84e27903fefbe2018d0afa2d67b23aa0b321ce

pjsip_transport_events.c: Use %zu printf specifier for size_t.

Partially resolves #143.

res_crypto.c: Gracefully handle potential key filename truncation.

Partially resolves #143.

configure: Remove obsolete and deprecated constructs.

These were uncovered when trying to run `bootstrap.sh` with Autoconf
2.71:

* AC_CONFIG_HEADER() is deprecated in favor of AC_CONFIG_HEADERS().
* AC_HEADER_TIME is obsolete.
* $as_echo is deprecated in favor of AS_ECHO() which requires an update
  to ax_pthread.m4.

Note that the generated artifacts in this commit are from Autoconf 2.69.

Resolves #139

res_fax_spandsp.c: Clean up a spaces/tabs issue

ast-db-manage: Synchronize revisions between comments and code.

In a handful of migrations, the comment header that indicates the
current and previous revisions has drifted from the identifiers
revision and down_revision variables. This updates the comment headers
to match the code.

test_statis_endpoints:  Fix channel_messages test again

res_crypto.c: Avoid using the non-portable ALLPERMS macro.

ALLPERMS is not POSIX and it's trivial enough to not jump through
autoconf hoops to check for it.

Fixes #149.

tcptls: when disabling a server port, we should set the accept_fd to -1.

If we don't set this to -1 if the structure can be potentially re-used
later then it's possible that we'll issue a close() on an unrelated file
descriptor, breaking asterisk in other interesting ways.

I believe this to be an unlikely scenario, but it costs nothing to be
safe.

Signed-off-by: Jaco Kroon <jaco@uls.co.za>

AMI: Add parking position parameter to Park action

Add a parking space extension parameter (ParkingSpace) to the Park action.
Park action will attempt to park the call to that extension.
If the extension is already in use, then execution will continue at the next priority.

UserNote: New ParkingSpace parameter has been added to AMI action Park.

test_stasis_endpoints.c: Make channel_messages more stable

The channel_messages test was assuming that stasis would return
messages in a specific order.  This is an incorrect assumption as
message ordering was never guaranteed.  This was causing the test
to fail occasionally.  We now test all the messages for the
required message types instead of testing one by one.

Resolves: #158

build: Fix a few gcc 13 issues

* gcc 13 is now catching when a function is declared as returning
  an enum but defined as returning an int or vice versa.  Fixed
  a few in app.h, loader.c, stasis_message.c.

* gcc 13 is also now (incorrectly) complaining of dangling pointers
  when assigning a pointer to a local char array to a char *. Had
  to change that to an ast_alloca.

Resolves: #155

.github: Rework for merge approval

ast-db-manage: Fix alembic branching error caused by #122.

Fixes #147.

sounds: Update download URL to use HTTPS.

Related to #136

configure: Makefile downloader enable follow redirects.

If curl is used for building, any download such as a sounds package
will fail to follow HTTP redirects and will download wrong data.

Resolves: #136

res_musiconhold: Add option to loop last file.

Adds the loop_last option to res_musiconhold,
which allows the last audio file in the directory
to be looped perpetually once reached, rather than
circling back to the beginning again.

Resolves: #122
ASTERISK-30462

UserNote: The loop_last option in musiconhold.conf now
allows the last file in the directory to be looped once reached.

chan_dahdi: Fix Caller ID presentation for FXO ports.

Currently, the presentation for incoming channels is
always available, because it is never actually set,
meaning the channel presentation can be nonsensical.
If the presentation from the incoming Caller ID spill
is private or unavailable, we now update the channel
presentation to reflect this.

Resolves: #120
ASTERISK-30333
ASTERISK-21741

AMI: Add CoreShowChannelMap action.

Adds a new AMI action (CoreShowChannelMap) that takes in a channel name
and provides a list of all channels that are connected to that channel,
following local channel connections as well.

Resolves: #104

UserNote: New AMI action CoreShowChannelMap has been added.

sig_analog: Add fuller Caller ID support.

A previous change, ASTERISK_29991, made it possible
to send additional Caller ID parameters that were
not previously supported.

This change adds support for analog DAHDI channels
to now be able to receive these parameters for
on-hook Caller ID, in order to enhance the usability
of CPE that support these parameters.

Resolves: #94
ASTERISK-30331

UserNote: Additional Caller ID properties are now supported on
incoming calls to FXS stations, namely the
redirecting reason and call qualifier.

res_stasis.c: Add new type 'sdp_label' for bridge creation.

Add new type 'sdp_label' when creating a bridge using the ARI. This will
add labels to the SDP for each stream, the label is set to the
corresponding channel id.

Resolves: #91

UserNote: When creating a bridge using the ARI the 'type' argument now
accepts a new value 'sdp_label' which will configure the bridge to add
labels for each stream in the SDP with the corresponding channel id.

app_followme: fix issue with enable_callee_prompt=no (#88)

* app_followme: fix issue with enable_callee_prompt=no

If the FollowMe option 'enable_callee_prompt' is set to 'no' then Asterisk
incorrectly sets a winner channel to the channel from which any control frame was read.

This fix sets the winner channel only to the answered channel.

Resolves: #87

ASTERISK-30326

app_queue: Preserve reason for realtime queues

When Asterisk is restarted it does not preserve paused reason for
members of realtime queues. This was fixed for non-realtime queues in
ASTERISK_25732

Resolves: #66

UpgradeNote: Add a new column to the queue_member table:
reason_paused VARCHAR(80) so the reason can be preserved.

UserNote: Make paused reason in realtime queues persist an
Asterisk restart. This was fixed for non-realtime
queues in ASTERISK_25732.

.github: Fix issues with cherry-pick-reminder

indications: logging changes

Increase verbosity to indicate failure due to missing country
and to specify default on CLI dump

Resolves: #89

.github Ignore error when adding reviewrs to PR

.github: Update field descriptions for AsteriskReleaser

callerid: Allow specifying timezone for date/time.

The Caller ID generation routine currently is hardcoded
to always use the system time zone. This makes it possible
to optionally specify any TZ-format time zone.

Resolves: #98
ASTERISK-30330