Skip to content

Update 6586414.mdx #186

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update 6586414.mdx #186

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 36 additions & 31 deletions docs/FreeSWITCH-Explained/Modules/mod-dptools/6586414.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ However, **any non-matching digits will be sent through**. Therefore you should

Note that you cannot "capture" digits in `bind_digit_action`.

TODO Is this still valid? Section **3.4 Capture dialed** **digits** describes exactly this scenario, and there's even a channel variable for it.
`TODO` Is this still valid? Section **3.4 Capture dialed** **digits** describes exactly this scenario, and there's even a channel variable for it.

## 2\. Syntax

Expand All @@ -36,8 +36,8 @@ TODO Is this still valid? Section **3.4 Capture dialed** **digits** describes ex
| Parameter | Description | Example |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| \<realm> | Somewhat similar to a dialplan context (see [XML Dialplan](../../Dialplan/XML-Dialplan/index.mdx#about)) or a state in a finite state machine.To clear or remove the digit bindings, use [mod\_dptools: clear\_digit\_action](./6586422.mdx#about).To switch between realms, use [mod\_dptools: digit\_action\_set\_realm](./6586771.mdx#0-about). | get\_passcode |
| \<binding> | A \<binding> can either bea **sequence of digits to** **match** ora **[PCRE-compatible regular expression](https://www.pcre.org/)**that must start with a **\~** TODO Only assuming PCRE-compatibility because other module descriptions mention it, and [one of FreeSWITCH dependencies is the PCRE library.](https://freeswitch.org/confluence/display/FAH/FreeSWITCH+Dependencies) | 1234567\~7\\d\{3} |
| \<command\_string> | \<command\_string> Descriptionexec:\<dialplan\_app>To execute a [dialplan application](../mod_dptools_1970333.mdx#c). This can have an optional flag 'H' which disables putting the other leg on hold during this operation. Can have an optional flag 'i' which makes the command blocking (it will execute in the thread of of the digit callback). Setting 'i' means 'H' has no effect.api:\<api\_command>To issue a [FreeSWITCH API](../../Introduction/FreeSWITCH-API.mdx) command. | exec:execute\_extension,att\_xfer XML default,both,selfexec\[H\]:execute\_extension,start\_record XML defaultapi:hupall |
| \<binding> | A \<binding> can either bea **sequence of digits to** **match** ora [**PCRE-compatible regular expression**](https://www.pcre.org/)that must start with a `~` <br> `TODO` Only assuming PCRE-compatibility because other module descriptions mention it, and [one of FreeSWITCH dependencies is the PCRE library.](https://freeswitch.org/confluence/display/FAH/FreeSWITCH+Dependencies) | 1234567<br>\~7\\d\{3} |
| \<command\_string> | \<command\_string> Descriptionexec:\<dialplan\_app>To execute a [dialplan application](../mod_dptools_1970333.mdx#c). This can have an optional flag `H` which disables putting the other leg on hold during this operation. Can have an optional flag `i` which makes the command blocking (it will execute in the thread of of the digit callback). Setting `i` means `H` has no effect.api:\<api\_command>To issue a [FreeSWITCH API](../../Introduction/FreeSWITCH-API.mdx) command. | exec:execute\_extension,att\_xfer XML default,both,self<br>exec\[H\]:execute\_extension,start\_record XML default<br>api:hupall |
| \<value> | OPTIONAL Contains the arguments to the \<command\_string> | |
| \<dtmf\_target\_leg> | OPTIONAL Possible values: self (the default) peer both Any other value is treated as self. | peer |
| \<event\_target\_leg> | OPTIONAL See \<dtmf\_target\_leg> above | self |
Expand All @@ -47,33 +47,37 @@ TODO Is this still valid? Section **3.4 Capture dialed** **digits** describes ex

TODO Write this up properly. The following text is directly from the commit comment.

`<binding>` can have a flag, 'P' (for "Priority") to bind\_digit\_action so that a match is returned as soon as it is found, without waiting for the inter-digit timeout to expire.
`<binding>` can have a flag, `P` (for "Priority") to bind\_digit\_action so that a match is returned as soon as it is found, without waiting for the inter-digit timeout to expire.

This can be very useful where the system needs to be more responsive to the user.

By default, if multiple bindings are enabled and one or more use a regex, switch\_ivr\_dmachine\_check\_match waits for the inter-digit timeout to expire before returning a match. This ensures overlapping patterns, such as "^\\d\{4}$" and "^\\12\{3}$" can both be reliably matched

When the 'P' flag is specified with bind\_digit\_action, whose action is exec, a match is returned as soon as the condition is satisfied, regardless of whether or not a longer match may be possible if further digits were entered.
When the `P` flag is specified with bind\_digit\_action, whose action is exec, a match is returned as soon as the condition is satisfied, regardless of whether or not a longer match may be possible if further digits were entered.

For example:

\<action application="bind\_digit\_action" data="test,\~^\*\\d\{2}$, exec\[P\]:execute\_extension,myextn,self,self"/>
```xml
<action application="bind_digit_action" data="test, ~^*\d{2}$, exec[P]:execute_extension,myextn,self,self"/>

\<action application="bind\_digit\_action" data="test,\~^#\\d\{2}$", exec:execute\_extension,myotherextn,self,peer"/>
<action application="bind_digit_action" data="test, ~^#\d{2}$, exec:execute_extension,myotherextn,self,peer"/>
```

The first example causes a match to be returned immediately after the 2nd digit is received, whereas the second example defaults to waiting for the inter-digit timeout to expire before returning.

In cases where the 'P' flag is used with a regex and string, and both are matched, the more explicit, string match will be returned.

For example:

\<action application="bind\_digit\_action" data="test,\~^\*\\d\{2}$, exec\[P\]:execute\_extension,myextn,self,self"/>
```xml
<action application="bind_digit_action" data="test, ~^*\d{2}$, exec[P]:execute_extension,myextn,self,self"/>

\<action application="bind\_digit\_action" data="test,\*12, exec\[P\]:execute\_extension,myotherextn,self,self"/>
<action application="bind_digit_action" data="test, *12, exec[P]:execute_extension,myotherextn,self,self"/>
```

If "\*12" is matched, myotherextn is executed, because "\*12" is more explicit/specific than "^\*\\d\{2}$"

If the 'P'(riority) flag is not used, behaviour is unchanged from previous versions. This ensures backward compatibility.
If the `P`(riority) flag is not used, behaviour is unchanged from previous versions. This ensures backward compatibility.

## 3\. Examples

Expand All @@ -86,7 +90,7 @@ If the 'P'(riority) flag is not used, behaviour is unchanged from previous versi

### 3.1 Two-realm example 1

TODO Is this right? "_The initial realm is `test1` (set by_ _[mod\_dptools: digit\_action\_set\_realm](./6586771.mdx#0-about)), and realm `myrealm` is never used, but shows how to use multiple realms._"
`TODO` Is this right? "_The initial realm is `test1` (set by_ _[mod\_dptools: digit\_action\_set\_realm](./6586771.mdx#0-about)), and realm `myrealm` is never used, but shows how to use multiple realms._"

```xml
<action application="bind_digit_action" data="myrealm,500,exec:playback,ivr/ivr-welcome_to_freeswitch.wav"/>
Expand Down Expand Up @@ -235,17 +239,17 @@ Put this in your dialplan extension "Local\_Extension":

and this in $\{scripts\_dir}/test.lua file

```xml
wav1 = "ivr/ivr-welcome_to_freeswitch.wav"
wav2 = "ivr/ivr-you_are_number_one.wav"
```lua
local wav1 = "ivr/ivr-welcome_to_freeswitch.wav"
local wav2 = "ivr/ivr-you_are_number_one.wav"

session:execute("bind_digit_action","myrealm,555,exec:playback," .. wav1);
session:execute("bind_digit_action", "myrealm,555,exec:playback," .. wav1);

session:execute("set","playback_delimiter=#");
session:execute("set","playback_sleep_val=100");
session:execute("bind_digit_action","myrealm,556,exec:playback," .. wav1 .. "#" .. wav2);
session:execute("set", "playback_delimiter=#");
session:execute("set", "playback_sleep_val=100");
session:execute("bind_digit_action", "myrealm,556,exec:playback," .. wav1 .. "#" .. wav2);

session:execute("bind_digit_action","myrealm,557,exec:playback,file_string://" .. wav1 .. "!" .. wav2);
session:execute("bind_digit_action", "myrealm,557,exec:playback,file_string://" .. wav1 .. "!" .. wav2);
```

## 4\. Channel Variables
Expand All @@ -260,7 +264,7 @@ See [Channel Variables Catalog](../../../Channel-Variables-Catalog/index.mdx#com

### 4.1 Example use case: using [mod_dptools: play_and_get_digits](./6586933.mdx#about) and [mod_dptools: bind_digit_action](./6586414.mdx#0-about) together

TODO Still not sure why one would need to use these two together.
`TODO` Still not sure why one would need to use these two together.

Quoting from [\[Freeswitch-users\] problem with "play\_and\_get\_digits" command (DTMF delay time)](https://lists.freeswitch.org/pipermail/freeswitch-users/2015-August/115397.html):

Expand Down Expand Up @@ -297,13 +301,11 @@ Please find my dialplan as follows: 2015-08-25 18:05:37.535806 \[CRIT\] mod\_htt
<execute application="clear_digit_action" data="my_digit" />
</work>
</document>


```

It is working fine as expected if user input 16 digit number continuously without any delay. After getting full 16 digit number it will match the "bind\_digit\_action" and move to other dialplan. But my problem is if a user enter card number slowly then its trying to match already inputed DTMF values with matching binding and received next inputed value as different DTMF values. As a example, if I tried to input 55 and then wait for 1-2 seconds then Freeswitch tried to match 55 with binding.

```xml
```c
2015-08-25 18:05:39.535920 [DEBUG] switch_ivr_play_say.c:1305 Codec Activated L1 6 at 8000hz 1 channels 20ms
2015-08-25 18:05:39.755933 [DEBUG] switch_rtp.c:5819 RTP RECV DTMF 5:2080
2015-08-25 18:05:40.015948 [DEBUG] switch_rtp.c:5819 RTP RECV DTMF 5:2080
Expand Down Expand Up @@ -348,28 +350,29 @@ _Fri Aug 28 21:45:06 MSD 2015_

---

I found this in mod_dptools.c inside the bind_to_session function:
I found this in `mod_dptools.c` inside the `bind_to_session` function:

if (!(dmachine = switch_core_session_get_dmachine(session, target))) \{
```c
if (!(dmachine = switch_core_session_get_dmachine(session, target))) {
uint32_t digit_timeout = 1500;
uint32_t input_timeout = 0;
const char *var;

if ((var = switch_channel_get_variable(channel,
"bind_digit_digit_timeout"))) \{
"bind_digit_digit_timeout"))) {
digit_timeout = switch_atoul(var);
}

if ((var = switch_channel_get_variable(channel,
"bind_digit_input_timeout"))) \{
"bind_digit_input_timeout"))) {
input_timeout = switch_atoul(var);
}

switch_ivr_dmachine_create(&dmachine, "DPTOOLS", NULL,
digit_timeout, input_timeout, NULL, digit_nomatch_action_callback, session);
switch_core_session_set_dmachine(session, dmachine, target);
}

```

It appears that there might be two channel variables for you to try:
bind_digit_digit_timeout
Expand Down Expand Up @@ -401,9 +404,11 @@ Thanks for your help.

Its working fine now with setting the value of "bind_digit_digit_timeout" and "bind_digit_input_timeout" channel variable. I have set it as 10000 and its wait till 10 sec now for matching the regular expression.

\<execute application="set" data="bind_digit_digit_timeout=10000" />
```xml
<execute application="set" data="bind_digit_digit_timeout=10000" />

\<execute application="set" data="bind_digit_input_timeout=10000" />
<execute application="set" data="bind_digit_input_timeout=10000" />
```

Its working fine with me, your docs team can document this if required.

Expand All @@ -430,7 +435,7 @@ If you have a PIN on your conference then you will need to make sure that the PI

The `bind_digit_action` supports both inband and 2833 DTMFs. For an example on how to check the SDP for RFC 2833 and automatically start in-inband dtmf detection look in conf/dialplan/default.xml and locate the "global" extension. The 2833 detection is commented out by default.

TODO [RFC 2833](https://tools.ietf.org/html/rfc2833) is obsoleted by [RFC 4733](https://tools.ietf.org/html/rfc4733).
`TODO` [RFC 2833](https://tools.ietf.org/html/rfc2833) is obsoleted by [RFC 4733](https://tools.ietf.org/html/rfc4733).

### 5.3 Setting on the B leg

Expand Down
Loading