res_parking: Update parking documentation for dynamic parking lots.

* Remove duplicate res_parking.conf courtesytone config option
documentation.

ASTERISK-24596 #close
Reported by:  Philip Correia

ASTERISK-24605
Reported by:  Philip Correia
Patches:
      call_park_app_doc.patch (license #6672) patch uploaded by Philip Correia

Change-Id: I90a92a891c6494dc08173e675856afcc4764c5b5

3 files changed, 138 insertions, 10 deletions

diff --git a/configs/samples/res_parking.conf.sample b/configs/samples/res_parking.conf.sample
index d24be2039..e13f780e0 100644
--- a/configs/samples/res_parking.conf.sample
+++ b/configs/samples/res_parking.conf.sample
@@ -1,5 +1,43 @@
 [general]
 ;parkeddynamic = yes            ; Enables dynamically created parkinglots. (default is no)
+                                ; If the option is enabled then the following
+                                ; variables can be used to dynamically create
+                                ; new parking lots.
+                                ;
+                                ; The PARKINGDYNAMIC variable specifies the
+                                ; parking lot to use as a template to create
+                                ; a dynamic parking lot.  It is an error to
+                                ; specify a non-existent parking lot for the
+                                ; template.  If not set then the default
+                                ; parking lot is used as the template.
+                                ;
+                                ; The PARKINGDYNCONTEXT variable specifies
+                                ; the dialplan context to use for the newly
+                                ; created dynamic parking lot.  If not set
+                                ; then the context from the parking lot
+                                ; template is used.  The context is created
+                                ; if it does not already exist and the new
+                                ; parking lot needs to create extensions.
+                                ;
+                                ; The PARKINGDYNEXTEN variable specifies the
+                                ; parkext to use for the newly created dynamic
+                                ; parking lot.  If not set then the parkext
+                                ; is used from the parking lot template.  If
+                                ; the template does not specify a parkext
+                                ; then no extensions are created for the
+                                ; newly created parking lot.  The dynamic
+                                ; parking lot cannot be created if it needs
+                                ; to create extensions that overlap existing
+                                ; parking lot extensions.  The only exception
+                                ; to this is for the parkext extension and
+                                ; only if neither of the overlaping parking
+                                ; lot's parkext is exclusive.
+                                ;
+                                ; The PARKINGDYNPOS variable specifies the
+                                ; parking positions to use for the newly
+                                ; created dynamic parking lot.  If not set
+                                ; then the parkpos from the parking lot
+                                ; template is used.
 
 ; A parking lot named 'default' will automatically be used when no other
 ; named parking lot is indicated for use by the park application or a
@@ -11,6 +49,10 @@
 parkext => 700                  ; What extension to dial to park. (optional; if
                                 ; specified, extensions will be created for parkext and
                                 ; the whole range of parkpos)
+                                ;
+                                ; Note: Generated parking extensions cannot overlap.
+                                ; The only exception is if neither overlapping parkext
+                                ; is exclusive.
 
 ;parkext_exclusive=yes          ; Specify that the parkext created for this parking lot
                                 ; will only access this parking lot. (default is no)
diff --git a/res/parking/parking_applications.c b/res/parking/parking_applications.c
index 0a0ea3c4b..3a9527c1f 100644
--- a/res/parking/parking_applications.c
+++ b/res/parking/parking_applications.c
@@ -90,6 +90,47 @@ ASTERISK_REGISTER_FILE()
 				call on that extension. If the extension is already in use then execution
 				will continue at the next priority.
 			</para>
+			<para>If the <literal>parkeddynamic</literal> option is enabled in
+				<filename>res_parking.conf</filename> the following variables can be
+				used to dynamically create new parking lots. When using dynamic parking
+				lots, be aware of the conditions as explained in the notes section
+				below.
+			</para>
+			<para>The <variable>PARKINGDYNAMIC</variable> variable specifies the
+				parking lot to use as a template to create a dynamic parking lot. It
+				is an error to specify a non-existent parking lot for the template.
+				If not set then the default parking lot is used as the template.
+			</para>
+			<para>The <variable>PARKINGDYNCONTEXT</variable> variable specifies the
+				dialplan context to use for the newly created dynamic parking lot. If
+				not set then the context from the parking lot template is used. The
+				context is created if it does not already exist and the new parking lot
+				needs to create extensions.
+			</para>
+			<para>The <variable>PARKINGDYNEXTEN</variable> variable specifies the
+				<literal>parkext</literal> to use for the newly created dynamic
+				parking lot. If not set then the <literal>parkext</literal> is used from
+				the parking lot template. If the template does not specify a
+				<literal>parkext</literal> then no extensions are created for the newly
+				created parking lot. The dynamic parking lot cannot be created if it
+				needs to create extensions that overlap existing parking lot extensions.
+				The only exception to this is for the <literal>parkext</literal>
+				extension and only if neither of the overlaping parking lot's
+				<literal>parkext</literal> is exclusive.
+			</para>
+			<para>The <variable>PARKINGDYNPOS</variable> variable specifies the
+				parking positions to use for the newly created dynamic parking lot. If
+				not set then the <literal>parkpos</literal> from the parking lot template
+				is used.
+			</para>
+			<note>
+				<para>This application must be used as the first extension priority
+					to be recognized as a parking access extension for blind transfers.
+					Blind transfers and the DTMF one-touch parking feature need this
+					distinction to operate properly. The parking access extension in
+					this case is treated like a dialplan hint.
+				</para>
+			</note>
 		</description>
 		<see-also>
 			<ref type="application">ParkedCall</ref>
diff --git a/res/res_parking.c b/res/res_parking.c
index 02740da61..727afd27d 100644
--- a/res/res_parking.c
+++ b/res/res_parking.c
@@ -35,6 +35,38 @@
 				<synopsis>Options that apply to every parking lot</synopsis>
 				<configOption name="parkeddynamic">
 					<synopsis>Enables dynamically created parkinglots.</synopsis>
+					<description>
+						<para>If the option is enabled then the following variables can
+							be used to dynamically create new parking lots.
+						</para>
+						<para>The <variable>PARKINGDYNAMIC</variable> variable specifies the
+							parking lot to use as a template to create a dynamic parking lot. It
+							is an error to specify a non-existent parking lot for the template.
+							If not set then the default parking lot is used as the template.
+						</para>
+						<para>The <variable>PARKINGDYNCONTEXT</variable> variable specifies the
+							dialplan context to use for the newly created dynamic parking lot. If
+							not set then the context from the parking lot template is used. The
+							context is created if it does not already exist and the new parking lot
+							needs to create extensions.
+						</para>
+						<para>The <variable>PARKINGDYNEXTEN</variable> variable specifies the
+							<literal>parkext</literal> to use for the newly created dynamic
+							parking lot. If not set then the <literal>parkext</literal> is used from
+							the parking lot template. If the template does not specify a
+							<literal>parkext</literal> then no extensions are created for the newly
+							created parking lot. The dynamic parking lot cannot be created if it
+							needs to create extensions that overlap existing parking lot extensions.
+							The only exception to this is for the <literal>parkext</literal>
+							extension and only if neither of the overlaping parking lot's
+							<literal>parkext</literal> is exclusive.
+						</para>
+						<para>The <variable>PARKINGDYNPOS</variable> variable specifies the
+							parking positions to use for the newly created dynamic parking lot. If
+							not set then the <literal>parkpos</literal> from the parking lot template
+							is used.
+						</para>
+					</description>
 				</configOption>
 			</configObject>
 			<configObject name="parking_lot">
@@ -45,19 +77,35 @@
 				</configOption>
 				<configOption name="parkext">
 					<synopsis>Extension to park calls to this parking lot.</synopsis>
-					<description><para>If this option is used, this extension will automatically be created to place calls into
-                        parking lots. In addition, if parkext_exclusive is set for this parking lot, the name of the parking lot
-                        will be included in the application's arguments so that it only parks to this parking lot. The extension
-                        will be created in <literal>context</literal>. Using this option also creates extensions for retrieving
-                        parked calls from the parking spaces in the same context.</para></description>
+					<description>
+						<para>If this option is used, this extension will automatically
+							be created to place calls into parking lots. In addition, if
+							<literal>parkext_exclusive</literal> is set for this parking
+							lot, the name of the parking lot will be included in the
+							application's arguments so that it only parks to this parking
+							lot. The extension will be created in <literal>context</literal>.
+							Using this option also creates extensions for retrieving
+							parked calls from the parking spaces in the same context.
+						</para>
+						<note>
+							<para>Generated parking extensions cannot overlap.
+								The only exception is if neither overlapping
+								<literal>parkext</literal> is exclusive.
+							</para>
+						</note>
+					</description>
 				</configOption>
 				<configOption name="parkext_exclusive" default="no">
 					<synopsis>If yes, the extension registered as parkext will park exclusively to this parking lot.</synopsis>
 				</configOption>
 				<configOption name="parkpos" default="701-750">
 					<synopsis>Numerical range of parking spaces which can be used to retrieve parked calls.</synopsis>
-					<description><para>If parkext is set, these extensions will automatically be mapped in <literal>context</literal>
-						in order to pick up calls parked to these parking spaces.</para></description>
+					<description>
+						<para>If <literal>parkext</literal> is set, these extensions
+							will automatically be mapped in <literal>context</literal>
+							in order to pick up calls parked to these parking spaces.
+						</para>
+					</description>
 				</configOption>
 				<configOption name="parkinghints" default="no">
 					<synopsis>If yes, this parking lot will add hints automatically for parking spaces.</synopsis>
@@ -178,9 +226,6 @@
 						</enumlist>
 					</description>
 				</configOption>
-				<configOption name="courtesytone">
-					<synopsis>If set, the sound set will be played to whomever is set by parkedplay</synopsis>
-				</configOption>
 			</configObject>
 		</configFile>
 	</configInfo>