kenmirrors/asterisk
1
0
Fork 0
mirror of https://github.com/asterisk/asterisk.git synced 2025-09-02 19:16:15 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Add version information to configObject and configOption XML elements

Browse Source 
Most of the configObjects and configOptions that are implemented with
ACO or Sorcery now have `<since>/<version>` elements added.  There are
probably some that the script I used didn't catch.  The version tags were
determined by the following...
 * Do a git blame on the API call that created the object or option.
 * From the commit hash, grab the summary line.
 * Do a `git log --grep <summary>` to find the cherry-pick commits in all
   branches that match.
 * Do a `git patch-id` to ensure the commits are all related and didn't get
   a false match on the summary.
 * Do a `git tag --contains <commit>` to find the tags that contain each
   commit.
 * Weed out all tags not <major>.<minor>.0.
 * Sort and discard any <major>.0.0 and following tags where the commit
   appeared in an earlier branch.
 * The result is a single tag for each branch where the API was last touched.

configObjects and configOptions elements implemented with the base
ast_config APIs were just not possible to find due to the non-deterministic
way they are accessed.

Also note that if the API call was on modified after it was added, the
version will be the one it was last modified in.

Final note:  The configObject and configOption elements were introduced in
12.0.0 so options created before then may not have any XML documentation.

(cherry picked from commit a22dc33057)
This commit is contained in:
George Joseph
2025-01-16 14:54:35 -07:00
committed by Asterisk Development Team
parent e7801702c6
commit 1ccf0ae7e8
31 changed files with 650 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
apps/app_agent_pool.c
View File

@@ -268,11 +268,13 @@
<synopsis>Unused, but reserved.</synopsis>
</configObject>
<configObject name="agent-id">
<since><version>12.0.0</version></since>
<synopsis>Configure an agent for the pool.</synopsis>
<description>
<xi:include xpointer="xpointer(/docs/configInfo[@name='app_agent_pool']/description/note)" />
</description>
<configOption name="ackcall">
<since><version>12.0.0</version></since>
<synopsis>Enable to require the agent to acknowledge a call.</synopsis>
<description>
<para>Enable to require the agent to give a DTMF acknowledgement
@@ -282,6 +284,7 @@
</description>
</configOption>
<configOption name="acceptdtmf">
<since><version>12.0.0</version></since>
<synopsis>DTMF key sequence the agent uses to acknowledge a call.</synopsis>
<description>
<note><para>The option is overridden by <variable>AGENTACCEPTDTMF</variable> on agent login.</para></note>
@@ -290,6 +293,7 @@
</description>
</configOption>
<configOption name="autologoff">
<since><version>12.0.0</version></since>
<synopsis>Time the agent has to acknowledge a call before being logged off.</synopsis>
<description>
<para>Set how many seconds a call for the agent has to wait for the
@@ -302,6 +306,7 @@
</description>
</configOption>
<configOption name="wrapuptime">
<since><version>12.0.0</version></since>
<synopsis>Minimum time the agent has between calls.</synopsis>
<description>
<para>Set the minimum amount of time in milliseconds after
@@ -311,12 +316,14 @@
</description>
</configOption>
<configOption name="musiconhold">
<since><version>12.0.0</version></since>
<synopsis>Music on hold class the agent listens to between calls.</synopsis>
<description>
<xi:include xpointer="xpointer(/docs/configInfo[@name='app_agent_pool']/description/note)" />
</description>
</configOption>
<configOption name="recordagentcalls">
<since><version>12.0.0</version></since>
<synopsis>Enable to automatically record calls the agent takes.</synopsis>
<description>
<para>Enable recording calls the agent takes automatically by
@@ -327,12 +334,14 @@
</description>
</configOption>
<configOption name="custom_beep">
<since><version>12.4.0</version></since>
<synopsis>Sound file played to alert the agent when a call is present.</synopsis>
<description>
<xi:include xpointer="xpointer(/docs/configInfo[@name='app_agent_pool']/description/note)" />
</description>
</configOption>
<configOption name="fullname">
<since><version>12.0.0</version></since>
<synopsis>A friendly name for the agent used in log messages.</synopsis>
<description>
<xi:include xpointer="xpointer(/docs/configInfo[@name='app_agent_pool']/description/note)" />

13
apps/app_skel.c
View File

@@ -88,42 +88,55 @@
<configInfo name="app_skel" language="en_US">
<configFile name="app_skel.conf">
<configObject name="globals">
<since><version>12.0.0</version></since>
<synopsis>Options that apply globally to app_skel</synopsis>
<configOption name="games">
<since><version>11.0.0</version></since>
<synopsis>The number of games a single execution of SkelGuessNumber will play</synopsis>
</configOption>
<configOption name="cheat">
<since><version>11.0.0</version></since>
<synopsis>Should the computer cheat?</synopsis>
<description><para>If enabled, the computer will ignore winning guesses.</para></description>
</configOption>
</configObject>
<configObject name="sounds">
<since><version>12.0.0</version></since>
<synopsis>Prompts for SkelGuessNumber to play</synopsis>
<configOption name="prompt" default="please-enter-your&amp;number&amp;queue-less-than">
<since><version>11.0.0</version></since>
<synopsis>A prompt directing the user to enter a number less than the max number</synopsis>
</configOption>
<configOption name="wrong_guess" default="vm-pls-try-again">
<since><version>11.0.0</version></since>
<synopsis>The sound file to play when a wrong guess is made</synopsis>
</configOption>
<configOption name="right_guess" default="auth-thankyou">
<since><version>11.0.0</version></since>
<synopsis>The sound file to play when a correct guess is made</synopsis>
</configOption>
<configOption name="too_low">
<since><version>11.0.0</version></since>
<synopsis>The sound file to play when a guess is too low</synopsis>
</configOption>
<configOption name="too_high">
<since><version>11.0.0</version></since>
<synopsis>The sound file to play when a guess is too high</synopsis>
</configOption>
<configOption name="lose" default="vm-goodbye">
<since><version>11.0.0</version></since>
<synopsis>The sound file to play when a player loses</synopsis>
</configOption>
</configObject>
<configObject name="level">
<since><version>12.0.0</version></since>
<synopsis>Defined levels for the SkelGuessNumber game</synopsis>
<configOption name="max_number">
<since><version>11.0.0</version></since>
<synopsis>The maximum in the range of numbers to guess (1 is the implied minimum)</synopsis>
</configOption>
<configOption name="max_guesses">
<since><version>11.22.0</version><version>13.9.0</version></since>
<synopsis>The maximum number of guesses before a game is considered lost</synopsis>
</configOption>
</configObject>

59
apps/confbridge/conf_config_parser.c
View File

@@ -48,6 +48,7 @@
<synopsis>Unused, but reserved.</synopsis>
</configObject>
<configObject name="user_profile">
<since><version>12.0.0</version></since>
<synopsis>A named profile to apply to specific callers.</synopsis>
<description><para>Callers in a ConfBridge have a profile associated with them
that determine their options. A configuration section is determined to be a
@@ -55,6 +56,7 @@
of <literal>user</literal>.
</para></description>
<configOption name="type">
<since><version>11.0.0</version></since>
<synopsis>Define this configuration category as a user profile.</synopsis>
<description><para>The type parameter determines how a context in the
configuration file is interpreted.</para>
@@ -66,9 +68,11 @@
</description>
</configOption>
<configOption name="admin">
<since><version>11.0.0</version></since>
<synopsis>Sets if the user is an admin or not</synopsis>
</configOption>
<configOption name="send_events" default="no">
<since><version>15.5.0</version></since>
<synopsis>Sets if events are send to the user</synopsis>
<description><para>If events are enabled for this bridge and this option is
set, users will receive events like join, leave, talking, etc. via text
@@ -78,6 +82,7 @@
interface.</para></description>
</configOption>
<configOption name="echo_events" default="yes">
<since><version>15.5.0</version></since>
<synopsis>Sets if events are echoed back to the user that
triggered them</synopsis>
<description><para>If events are enabled for this user and this option
@@ -86,24 +91,31 @@
</para></description>
</configOption>
<configOption name="marked">
<since><version>11.0.0</version></since>
<synopsis>Sets if this is a marked user or not</synopsis>
</configOption>
<configOption name="startmuted">
<since><version>11.0.0</version></since>
<synopsis>Sets if all users should start out muted</synopsis>
</configOption>
<configOption name="music_on_hold_when_empty">
<since><version>11.0.0</version></since>
<synopsis>Play MOH when user is alone or waiting on a marked user</synopsis>
</configOption>
<configOption name="quiet">
<since><version>11.0.0</version></since>
<synopsis>Silence enter/leave prompts and user intros for this user</synopsis>
</configOption>
<configOption name="hear_own_join_sound">
<since><version>16.26.0</version><version>18.12.0</version><version>19.4.0</version></since>
<synopsis>Determines if the user also hears the join sound when they enter a conference</synopsis>
</configOption>
<configOption name="announce_user_count">
<since><version>11.0.0</version></since>
<synopsis>Sets if the number of users should be announced to the user</synopsis>
</configOption>
<configOption name="announce_user_count_all">
<since><version>11.0.0</version></since>
<synopsis>Announce user count to all the other users when this user joins</synopsis>
<description><para>Sets if the number of users should be announced to all the other users
in the conference when this user joins. This option can be either set to 'yes' or
@@ -112,40 +124,52 @@
</para></description>
</configOption>
<configOption name="announce_only_user">
<since><version>11.0.0</version></since>
<synopsis>Announce to a user when they join an empty conference</synopsis>
</configOption>
<configOption name="wait_marked">
<since><version>11.0.0</version></since>
<synopsis>Sets if the user must wait for a marked user to enter before joining a conference</synopsis>
</configOption>
<configOption name="end_marked">
<since><version>11.0.0</version></since>
<synopsis>Kick the user from the conference when the last marked user leaves</synopsis>
</configOption>
<configOption name="end_marked_any">
<since><version>16.29.0</version><version>18.15.0</version><version>19.7.0</version></since>
<synopsis>Kick the user from the conference when any marked user leaves</synopsis>
</configOption>
<configOption name="talk_detection_events">
<since><version>11.0.0</version></since>
<synopsis>Set whether or not notifications of when a user begins and ends talking should be sent out as events over AMI</synopsis>
</configOption>
<configOption name="dtmf_passthrough">
<since><version>11.0.0</version></since>
<synopsis>Sets whether or not DTMF should pass through the conference</synopsis>
</configOption>
<configOption name="announce_join_leave">
<since><version>11.0.0</version></since>
<synopsis>Prompt user for their name when joining a conference and play it to the conference when they enter</synopsis>
</configOption>
<configOption name="announce_join_leave_review">
<since><version>13.0.0</version></since>
<synopsis>Prompt user for their name when joining a conference and play it to the conference when they enter.
The user will be asked to review the recording of their name before entering the conference.</synopsis>
</configOption>
<configOption name="pin">
<since><version>11.0.0</version></since>
<synopsis>Sets a PIN the user must enter before joining the conference</synopsis>
</configOption>
<configOption name="music_on_hold_class">
<since><version>11.0.0</version></since>
<synopsis>The MOH class to use for this user</synopsis>
</configOption>
<configOption name="announcement">
<since><version>11.0.0</version></since>
<synopsis>Sound file to play to the user when they join a conference</synopsis>
</configOption>
<configOption name="denoise">
<since><version>11.0.0</version></since>
<synopsis>Apply a denoise filter to the audio before mixing</synopsis>
<description><para>Sets whether or not a denoise filter should be applied
to the audio before mixing or not. Off by default. Requires
@@ -157,6 +181,7 @@
</para></description>
</configOption>
<configOption name="dsp_drop_silence">
<since><version>11.0.0</version></since>
<synopsis>Drop what Asterisk detects as silence from audio sent to the bridge</synopsis>
<description><para>
This option drops what Asterisk detects as silence from
@@ -167,6 +192,7 @@
</para></description>
</configOption>
<configOption name="dsp_silence_threshold">
<since><version>11.0.0</version></since>
<synopsis>The number of milliseconds of silence necessary to declare talking stopped.</synopsis>
<description>
<para>The time in milliseconds of sound falling below the
@@ -200,6 +226,7 @@
</description>
</configOption>
<configOption name="dsp_talking_threshold">
<since><version>11.10.0</version><version>12.3.0</version></since>
<synopsis>Average magnitude threshold to determine talking.</synopsis>
<description>
<para>The minimum average magnitude per sample in a frame
@@ -230,6 +257,7 @@
</description>
</configOption>
<configOption name="jitterbuffer">
<since><version>11.0.0</version></since>
<synopsis>Place a jitter buffer on the user's audio stream before audio mixing is performed</synopsis>
<description><para>
Enabling this option places a jitterbuffer on the user's audio stream
@@ -241,12 +269,15 @@
</para></description>
</configOption>
<configOption name="template">
<since><version>11.0.0</version></since>
<synopsis>When using the CONFBRIDGE dialplan function, use a user profile as a template for creating a new temporary profile</synopsis>
</configOption>
<configOption name="timeout">
<since><version>13.7.0</version></since>
<synopsis>Kick the user out of the conference after this many seconds. 0 means there is no timeout for the user.</synopsis>
</configOption>
<configOption name="text_messaging" default="yes">
<since><version>16.10.0</version><version>17.4.0</version></since>
<synopsis>Sets if text messages are sent to the user.</synopsis>
<description><para>If text messaging is enabled for this user then
text messages will be sent to it. These may be events or from other
@@ -254,10 +285,12 @@
messages are sent to the user.</para></description>
</configOption>
<configOption name="answer_channel" default="yes">
<since><version>16.19.0</version><version>18.5.0</version></since>
<synopsis>Sets if a user's channel should be answered if currently unanswered.</synopsis>
</configOption>
</configObject>
<configObject name="bridge_profile">
<since><version>12.0.0</version></since>
<synopsis>A named profile to apply to specific bridges.</synopsis>
<description><para>ConfBridge bridges have a profile associated with them
that determine their options. A configuration section is determined to be a
@@ -265,6 +298,7 @@
of <literal>bridge</literal>.
</para></description>
<configOption name="type">
<since><version>12.0.0</version></since>
<synopsis>Define this configuration category as a bridge profile</synopsis>
<description><para>The type parameter determines how a context in the
configuration file is interpreted.</para>
@@ -276,9 +310,11 @@
</description>
</configOption>
<configOption name="jitterbuffer">
<since><version>11.0.0</version></since>
<synopsis>Place a jitter buffer on the conference's audio stream</synopsis>
</configOption>
<configOption name="internal_sample_rate">
<since><version>18.22.0</version><version>20.7.0</version><version>21.2.0</version></since>
<synopsis>Set the internal native sample rate for mixing the conference</synopsis>
<description><para>
Sets the internal native sample rate the
@@ -291,6 +327,7 @@
</para></description>
</configOption>
<configOption name="maximum_sample_rate">
<since><version>18.22.0</version><version>20.7.0</version><version>21.2.0</version></since>
<synopsis>Set the maximum native sample rate for mixing the conference</synopsis>
<description><para>
Sets the maximum native sample rate the
@@ -300,6 +337,7 @@
</para></description>
</configOption>
<configOption name="language" default="en">
<since><version>11.7.0</version></since>
<synopsis>The language used for announcements to the conference.</synopsis>
<description><para>
By default, announcements to a conference use English. Which means
@@ -309,6 +347,7 @@
</para></description>
</configOption>
<configOption name="mixing_interval">
<since><version>11.0.0</version></since>
<synopsis>Sets the internal mixing interval in milliseconds for the bridge</synopsis>
<description><para>
Sets the internal mixing interval in milliseconds for the bridge. This
@@ -320,6 +359,7 @@
</para></description>
</configOption>
<configOption name="binaural_active">
<since><version>15.0.0</version></since>
<synopsis>If true binaural conferencing with stereo audio is active</synopsis>
<description><para>
Activates binaural mixing for a conference bridge.
@@ -327,6 +367,7 @@
</para></description>
</configOption>
<configOption name="record_conference">
<since><version>11.0.0</version></since>
<synopsis>Record the conference starting with the first active user's entrance and ending with the last active user's exit</synopsis>
<description><para>
Records the conference call starting when the first user
@@ -338,6 +379,7 @@
</para></description>
</configOption>
<configOption name="record_file" default="confbridge-${name of conference bridge}-${start time}.wav">
<since><version>11.0.0</version></since>
<synopsis>The filename of the conference recording</synopsis>
<description><para>
When <replaceable>record_conference</replaceable> is set to yes, the specific name of the
@@ -351,6 +393,7 @@
</para></description>
</configOption>
<configOption name="record_file_append" default="yes">
<since><version>12.0.0</version></since>
<synopsis>Append to record file when starting/stopping on same conference recording</synopsis>
<description><para>
When <replaceable>record_file_append</replaceable> is set to yes, stopping and starting recording on a
@@ -360,6 +403,7 @@
</para></description>
</configOption>
<configOption name="record_file_timestamp" default="yes">
<since><version>14.0.0</version></since>
<synopsis>Append the start time to the record_file name so that it is unique.</synopsis>
<description><para>
When <replaceable>record_file_timestamp</replaceable> is set to yes, the start time is appended to
@@ -368,6 +412,7 @@
</para></description>
</configOption>
<configOption name="record_options" default="">
<since><version>14.0.0</version></since>
<synopsis>Pass additional options to MixMonitor when recording</synopsis>
<description><para>
Pass additional options to MixMonitor when <replaceable>record_conference</replaceable> is set to yes.
@@ -375,6 +420,7 @@
</para></description>
</configOption>
<configOption name="record_command" default="">
<since><version>14.0.0</version></since>
<synopsis>Execute a command after recording ends</synopsis>
<description><para>
Executes the specified command when recording ends. Any strings matching <literal>^{X}</literal> will be
@@ -382,6 +428,7 @@
</para></description>
</configOption>
<configOption name="regcontext">
<since><version>13.10.0</version></since>
<synopsis>The name of the context into which to register the name of the conference bridge as NoOP() at priority 1</synopsis>
<description><para>
When set this will cause the name of the created conference to be registered
@@ -398,6 +445,7 @@
</para></description>
</configOption>
<configOption name="video_mode">
<since><version>11.0.0</version></since>
<synopsis>Sets how confbridge handles video distribution to the conference participants</synopsis>
<description><para>
Sets how confbridge handles video distribution to the conference participants.
@@ -435,6 +483,7 @@
</description>
</configOption>
<configOption name="max_members">
<since><version>11.0.0</version></since>
<synopsis>Limit the maximum number of participants for a single conference</synopsis>
<description><para>
This option limits the number of participants for a single
@@ -446,6 +495,7 @@
</para></description>
</configOption>
<configOption name="sound_">
<since><version>13.19.0</version><version>15.2.0</version></since>
<synopsis>Override the various conference bridge sound files</synopsis>
<description><para>
All sounds in the conference are customizable using the bridge profile options below.
@@ -491,6 +541,7 @@
</description>
</configOption>
<configOption name="video_update_discard" default="2000">
<since><version>15.0.0</version></since>
<synopsis>Sets the amount of time in milliseconds after sending a video update to discard subsequent video updates</synopsis>
<description><para>
Sets the amount of time in milliseconds after sending a video update request
@@ -501,6 +552,7 @@
</para></description>
</configOption>
<configOption name="remb_send_interval" default="0">
<since><version>15.4.0</version></since>
<synopsis>Sets the interval in milliseconds that a combined REMB frame will be sent to video sources</synopsis>
<description><para>
Sets the interval in milliseconds that a combined REMB frame will be sent
@@ -513,6 +565,7 @@
</para></description>
</configOption>
<configOption name="remb_behavior" default="average">
<since><version>15.4.0</version></since>
<synopsis>Sets how REMB reports are generated from multiple sources</synopsis>
<description><para>
Sets how REMB reports are combined from multiple sources to form one. A REMB report
@@ -551,6 +604,7 @@
<see-also><ref type="configOption">remb_estimated_bitrate</ref></see-also>
</configOption>
<configOption name="remb_estimated_bitrate">
<since><version>16.15.0</version><version>17.9.0</version><version>18.1.0</version></since>
<synopsis>Sets the estimated bitrate sent to each participant in REMB reports</synopsis>
<description><para>
When <literal>remb_behavior</literal> is set to <literal>force</literal>,
@@ -560,6 +614,7 @@
<see-also><ref type="configOption">remb_behavior</ref></see-also>
</configOption>
<configOption name="enable_events" default="no">
<since><version>15.5.0</version></since>
<synopsis>Enables events for this bridge</synopsis>
<description><para>
If enabled, recipients who joined the bridge via a channel driver
@@ -571,10 +626,12 @@
</description>
</configOption>
<configOption name="template">
<since><version>11.0.0</version></since>
<synopsis>When using the CONFBRIDGE dialplan function, use a bridge profile as a template for creating a new temporary profile</synopsis>
</configOption>
</configObject>
<configObject name="menu">
<since><version>12.0.0</version></since>
<synopsis>A conference user menu</synopsis>
<description>
<para>Conference users, as defined by a <replaceable>conf_user</replaceable>,
@@ -582,6 +639,7 @@
<literal>ConfBridge</literal> application.</para>
</description>
<configOption name="type">
<since><version>12.0.0</version></since>
<synopsis>Define this configuration category as a menu</synopsis>
<description><para>The type parameter determines how a context in the
configuration file is interpreted.</para>
@@ -593,6 +651,7 @@
</description>
</configOption>
<configOption name="template">
<since><version>13.0.0</version></since>
<synopsis>When using the CONFBRIDGE dialplan function, use a menu profile as a template for creating a new temporary profile</synopsis>
</configOption>
<configOption name="^[0-9A-D*#]+$">