[sr-dev] [kamailio/kamailio] dialog: Add dlg_get_matches function (PR #3005)

[rhys-hanrahan]

<!-- Kamailio Pull Request Template -->

<!--
IMPORTANT:
  - for detailed contributing guidelines, read:
    https://github.com/kamailio/kamailio/blob/master/.github/CONTRIBUTING.md
  - pull requests must be done to master branch, unless they are backports
    of fixes from master branch to a stable branch
  - backports to stable branches must be done with 'git cherry-pick -x ...'
  - code is contributed under BSD for core and main components (tm, sl, auth, tls)
  - code is contributed GPLv2 or a compatible license for the other components
  - GPL code is contributed with OpenSSL licensing exception
-->

#### Pre-Submission Checklist
<!-- Go over all points below, and after creating the PR, tick all the checkboxes that apply -->
<!-- All points should be verified, otherwise, read the CONTRIBUTING guidelines from above-->
<!-- If you're unsure about any of these, don't hesitate to ask on sr-dev mailing list -->
- [X] Commit message has the format required by CONTRIBUTING guide
- [X] Commits are split per component (core, individual modules, libs, utils, ...)
- [X] Each component has a single commit (if not, squash them into one commit)
- [X] No commits to README files for modules (changes must be done to docbook files
in `doc/` subfolder, the README file is autogenerated)

#### Type Of Change
- [ ] Small bug fix (non-breaking change which fixes an issue)
- [X] New feature (non-breaking change which adds new functionality)
- [X] Breaking change (fix or feature that would change existing functionality)

#### Checklist:
<!-- Go over all points below, and after creating the PR, tick the checkboxes that apply -->
- [ ] PR should be backported to stable branches
- [X] Tested changes locally
- [ ] Related to issue #XXXX (replace XXXX with an open issue number)

#### Description
I've marked this as a "breaking change" only because it slightly alters the error handling of the RPC dlg.list_match command, to draw attention to it. But the actual functionality is unchanged.

This PR adds a new script function to the dialog module: `dlg_get_matches`. This has the same behaviour as the RPC `dlg.list_match` command, but allows use in scripts. The results are returned in an XAVP of a specified name, as an array of fields.

```
dlg_get_matches(mkey, mop, mval, xavp_name[, max_results]);

Returns number of matches found. Or -1 if there's an error.
```

An example of use would be:
```
        xlog("Extension is: $var(ext)\n");

        $avp(dlg_count) = dlg_get_matches("turi", "sw", "sip:nexusone$var(ext)@", "dlg_matches");

        xlog("Got $avp(dlg_count) matches.\n");
        $var(i) = 0;
        $var(matched) = 0;
        while ($var(i) < $avp(dlg_count))
        {
                //Skip dialogs that are not early state
                if ($xavp(dlg_matches[$var(i)]=>state) == 2)
                {
                        xlog("Found matching dlg[$var(i)]: $xavp(dlg_matches[$var(i)]=>from_uri)\n");
                }
        }
```

You can view, comment on, or merge this pull request online at:

  https://github.com/kamailio/kamailio/pull/3005

-- Commit Summary --

  * dialog: Adding dlg_get_matches function based on RPC dlg.list_match command.
  * dialog: Adding documentation for dlg_get_matches function.
  * dialog: Refactored dlg_get_matches and dlg.list_match RPC command to use a shared dlg_list_matches function.

-- File Changes --

    M src/modules/dialog/dialog.c (793)
    M src/modules/dialog/doc/dialog_admin.xml (92)

-- Patch Links --

https://github.com/kamailio/kamailio/pull/3005.patch
https://github.com/kamailio/kamailio/pull/3005.diff

-- 
Reply to this email directly or view it on GitHub:
https://github.com/kamailio/kamailio/pull/3005
You are receiving this because you are subscribed to this thread.

Message ID: <kamailio/kamailio/pull/3005 at github.com>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.kamailio.org/pipermail/sr-dev/attachments/20220121/953f758d/attachment.htm>