Add helpers module to python wrapper

[ric-plt/lib/rmr.git] / src / bindings / rmr-python / rmr / helpers.py

diff --git a/src/bindings/rmr-python/rmr/helpers.py b/src/bindings/rmr-python/rmr/helpers.py
new file mode 100644 (file)
index 0000000..1f6ef28
--- /dev/null
+++ b/src/bindings/rmr-python/rmr/helpers.py
@@ -0,0 +1,65 @@
+# vim: ts=4 sw=4 expandtab:
+# ==================================================================================
+#       Copyright (c) 2019 Nokia
+#       Copyright (c) 2018-2019 AT&T Intellectual Property.
+#
+#   Licensed under the Apache License, Version 2.0 (the "License");
+#   you may not use this file except in compliance with the License.
+#   You may obtain a copy of the License at
+#
+#          http://www.apache.org/licenses/LICENSE-2.0
+#
+#   Unless required by applicable law or agreed to in writing, software
+#   distributed under the License is distributed on an "AS IS" BASIS,
+#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#   See the License for the specific language governing permissions and
+#   limitations under the License.
+# ==================================================================================
+
+#   Mnemonic:   helpers.py
+#   Abstract:   This is a colleciton of extensions to the RMR base package
+#               which are likely to be convenient for python programmes.
+#   Date:       26 September 2019
+# ---------------------------------------------------------------------------
+
+from rmr import rmr
+
+
+def rmr_rcvall_msgs(mrc, pass_filter=[]):
+    """
+        Assemble an array of all messages which can be received without
+        blocking.  Effectively draining the message queue if RMR is started
+        in mt-call mode, or draining any waiting TCP buffers.  If the
+        pass_filter parameter is supplied it is treated as one or more message
+        types to accept (pass through). Using the default, an empty list, results
+        in messages with any type being captured.
+
+        Parameters
+        ----------
+            mrc: ctypes c_void_p
+                Pointer to the RMR context
+
+            pass_filter: list (optional)
+                The message type(s) to capture.
+
+        Returns
+        -------
+            list
+            List of message summaries, one for each message captured.
+    """
+
+    new_messages = []
+    mbuf = rmr.rmr_alloc_msg(mrc, 4096)         # allocate buffer to have something for a return status
+
+    while True:
+        mbuf = rmr.rmr_torcv_msg(mrc, mbuf, 0)  # set the timeout to 0 so this doesn't block!!
+
+        summary = rmr.message_summary(mbuf)
+        if summary["message status"] != "RMR_OK":      # ok indicates msg received, stop on all other states
+            break
+        else:
+            if len(pass_filter) == 0 or summary["message type"] in pass_filter:      # no filter, or passes; capture it
+                new_messages.append(summary)
+
+    rmr.rmr_free_msg(mbuf)            # must free message to avoid leak
+    return new_messages