X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;ds=sidebyside;f=docs%2Frmr_api.rst;h=69caf590c228104e3f810dfe008544987c50221c;hb=da91199662c2d6d871f21d6d597df39545d26be1;hp=d1f6d98acfeddfbab19db6b7e825c0236e9faf90;hpb=2e1c18a96f7978cc24acc157c0e53067ebd677f1;p=ric-plt%2Fxapp-frame-py.git diff --git a/docs/rmr_api.rst b/docs/rmr_api.rst index d1f6d98..69caf59 100644 --- a/docs/rmr_api.rst +++ b/docs/rmr_api.rst @@ -1,746 +1,34 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. Copyright (C) 2020 AT&T Intellectual Property + RMR Python Bindings =================== Overview -------- -The xapp python framework repository includes a python submodule -called `rmr`. This package (`ricxappframe.rmr`) is a CTYPES wrapper +The xapp python framework package includes a python subpackage called +`rmr`. This subpackage (`ricxappframe.rmr`) is a CTYPES wrapper around the RMR shared library. Most Xapp users will never use this -package natively; however python apps that need access to the low -level RMR API can use this package. Usage of this python package -requires that you have the RMR shared-object library installed. +subpackage natively; however python apps that need access to the +low-level RMR API can use it. + +Usage of this python package requires that the RMR shared-object +library is installed in a system library that is included in the +directories found by default, usually something like /usr/local/lib. +The RMR library man pages are available here: :doc:`RMR Man Pages ` RMR API ------- -.. - Sphinx can generate API documentation by running Python to pull doc strings - from the binding code using these Sphinx directives that are commented out: - .. automodule:: ricxappframe.rmr.rmr - :members: - But that approach requires the RMR library to be installed, which is difficult - to achieve at ReadTheDocs.io. Instead, the RST below was generated and captured - according to the method shown at - https://stackoverflow.com/questions/2668187/make-sphinx-generate-rst-class-documentation-from-pydoc - - - -.. py:module:: ricxappframe.rmr.rmr - - -.. - !! processed by numpydoc !! - -.. py:class:: rmr_mbuf_t - :module: ricxappframe.rmr.rmr - - - Reimplementation of rmr_mbuf_t which is in an unaccessible header file (src/common/include/rmr.h) - - | typedef struct { - | int state; // state of processing - | int mtype; // message type - | int len; // length of data in the payload (send or received) - | unsigned char* payload; // transported data - | unsigned char* xaction; // pointer to fixed length transaction id bytes - | int sub_id; // subscription id - | int tp_state; // transport state (a.k.a errno) - | - | these things are off limits to the user application - | - | void* tp_buf; // underlying transport allocated pointer (e.g. nng message) - | void* header; // internal message header (whole buffer: header+payload) - | unsigned char* id; // if we need an ID in the message separate from the xaction id - | int flags; // various MFL (private) flags as needed - | int alloc_len; // the length of the allocated space (hdr+payload) - | } rmr_mbuf_t; - - We do not include the fields we are not supposed to mess with - - RE PAYLOADs type below, see the documentation for c_char_p: - class ctypes.c_char_p - Represents the C char * datatype when it points to a zero-terminated string. For a general character pointer that may also point to binary data, POINTER(c_char) must be used. The constructor accepts an integer address, or a bytes object. - - - - - - - - - - - - - - :Attributes: - - **len** - Structure/Union member - - **mtype** - Structure/Union member - - **payload** - Structure/Union member - - **state** - Structure/Union member - - **sub_id** - Structure/Union member - - **tp_state** - Structure/Union member - - **xaction** - Structure/Union member - - - .. - !! processed by numpydoc !! - -.. py:function:: rmr_init(uproto_port, max_msg_size, flags) - :module: ricxappframe.rmr.rmr - - - Refer to rmr C documentation for rmr_init - extern void* rmr_init(char* uproto_port, int max_msg_size, int flags) - - This python function checks that the context is not None and raises - an excption if it is. - - - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:function:: rmr_ready(vctx) - :module: ricxappframe.rmr.rmr - - - Refer to rmr C documentation for rmr_ready - extern int rmr_ready(void* vctx) - - - - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:function:: rmr_close(vctx) - :module: ricxappframe.rmr.rmr - - - Refer to rmr C documentation for rmr_close - extern void rmr_close(void* vctx) - - - - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:function:: rmr_set_stimeout(vctx, time) - :module: ricxappframe.rmr.rmr - - - Refer to the rmr C documentation for rmr_set_stimeout - extern int rmr_set_stimeout(void* vctx, int time) - - - - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:function:: rmr_alloc_msg(vctx, size, payload=None, gen_transaction_id=False, mtype=None, meid=None, sub_id=None, fixed_transaction_id=None) - :module: ricxappframe.rmr.rmr - - - Refer to the rmr C documentation for rmr_alloc_msg - extern rmr_mbuf_t* rmr_alloc_msg(void* vctx, int size) - TODO: on next API break, clean up transaction_id ugliness. Kept for now to preserve API. - - if payload is not None, attempts to set the payload - if gen_transaction_id is True, it generates and sets a transaction id. Note, fixed_transaction_id supersedes this option - if mtype is not None, sets the sbuf's message type - if meid is not None, sets the sbuf's meid - if sub_id is not None, sets the sbud's subscription id - if fixed_transaction_id is set, it deterministically sets the transaction_id. This overrides the option gen_transation_id - - - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:function:: rmr_realloc_payload(ptr_mbuf, new_len, copy=False, clone=False) - :module: ricxappframe.rmr.rmr - - - Refer to the rmr C documentation for rmr_realloc_payload(). - extern rmr_mbuf_t* rmr_realloc_payload(rmr_mbuf_t*, int, int, int) - - - - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:function:: rmr_free_msg(mbuf) - :module: ricxappframe.rmr.rmr - - - Refer to the rmr C documentation for rmr_free_msg - extern void rmr_free_msg(rmr_mbuf_t* mbuf ) - - - - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:function:: rmr_payload_size(ptr_mbuf) - :module: ricxappframe.rmr.rmr - - - Refer to the rmr C documentation for rmr_payload_size - extern int rmr_payload_size(rmr_mbuf_t* msg) - - - - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:function:: rmr_send_msg(vctx, ptr_mbuf) - :module: ricxappframe.rmr.rmr - - - Refer to the rmr C documentation for rmr_send_msg - extern rmr_mbuf_t* rmr_send_msg(void* vctx, rmr_mbuf_t* msg) - - - - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:function:: rmr_rcv_msg(vctx, ptr_mbuf) - :module: ricxappframe.rmr.rmr - - - Refer to the rmr C documentation for rmr_rcv_msg - extern rmr_mbuf_t* rmr_rcv_msg(void* vctx, rmr_mbuf_t* old_msg) - - - - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:function:: rmr_torcv_msg(vctx, ptr_mbuf, ms_to) - :module: ricxappframe.rmr.rmr - - - Refer to the rmr C documentation for rmr_torcv_msg - extern rmr_mbuf_t* rmr_torcv_msg(void* vctx, rmr_mbuf_t* old_msg, int ms_to) - - - - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:function:: rmr_rts_msg(vctx, ptr_mbuf, payload=None, mtype=None) - :module: ricxappframe.rmr.rmr - - - Refer to the rmr C documentation for rmr_rts_msg - extern rmr_mbuf_t* rmr_rts_msg(void* vctx, rmr_mbuf_t* msg) - - additional features beyond c-rmr: - if payload is not None, attempts to set the payload - if mtype is not None, sets the sbuf's message type - - - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:function:: rmr_call(vctx, ptr_mbuf) - :module: ricxappframe.rmr.rmr - - - Refer to the rmr C documentation for rmr_call - extern rmr_mbuf_t* rmr_call(void* vctx, rmr_mbuf_t* msg) - - - - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:function:: rmr_set_meid(ptr_mbuf, byte_str) - :module: ricxappframe.rmr.rmr - - - Refer to the rmr C documentation for rmr_bytes2meid - extern int rmr_bytes2meid(rmr_mbuf_t* mbuf, unsigned char const* src, int len); - - Caution: the meid length supported in an RMR message is 32 bytes, but C applications - expect this to be a nil terminated string and thus only 31 bytes are actually available. - - Raises: exceptions.MeidSizeOutOfRang - - - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:function:: rmr_get_meid(ptr_mbuf) - :module: ricxappframe.rmr.rmr - - - Get the managed equipment ID (meid) from the message header. - - - :Parameters: - - **ptr_mbuf: ctypes c_void_p** - Pointer to an rmr message buffer - - :Returns: - - string: - meid - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:function:: rmr_get_src(ptr_mbuf, dest) - :module: ricxappframe.rmr.rmr - - - Refer to the rmr C documentation for rmr_get_src - extern unsigned char* rmr_get_src(rmr_mbuf_t* mbuf, unsigned char* dest); - - - - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:function:: get_payload(ptr_mbuf) - :module: ricxappframe.rmr.rmr - - - Given a rmr_buf_t*, get it's binary payload as a bytes object - - - :Parameters: - - **ptr_mbuf: ctypes c_void_p** - Pointer to an rmr message buffer - - :Returns: - - bytes: - the message payload - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:function:: get_xaction(ptr_mbuf) - :module: ricxappframe.rmr.rmr - - - given a rmr_buf_t*, get it's transaction id - - - :Parameters: - - **ptr_mbuf: ctypes c_void_p** - Pointer to an rmr message buffer - - :Returns: - - bytes: - the transaction id - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:function:: message_summary(ptr_mbuf) - :module: ricxappframe.rmr.rmr - - - Returns a dict that contains the fields of a message - - - :Parameters: - - **ptr_mbuf: ctypes c_void_p** - Pointer to an rmr message buffer - - :Returns: - - dict: - dict message summary - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:function:: set_payload_and_length(byte_str, ptr_mbuf) - :module: ricxappframe.rmr.rmr - - - | Set an rmr payload and content length - | In place method, no return - - - :Parameters: - - **byte_str: bytes** - the bytes to set the payload to - - **ptr_mbuf: ctypes c_void_p** - Pointer to an rmr message buffer - - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:function:: generate_and_set_transaction_id(ptr_mbuf) - :module: ricxappframe.rmr.rmr - - - Generate a UUID and Set an rmr transaction id to it - - - :Parameters: - - **ptr_mbuf: ctypes c_void_p** - Pointer to an rmr message buffer - - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:function:: set_transaction_id(ptr_mbuf, tid_bytes) - :module: ricxappframe.rmr.rmr - - - Set an rmr transaction id - TODO: on next API break, merge these two functions. Not done now to preserve API. - - - :Parameters: - - **ptr_mbuf: ctypes c_void_p** - Pointer to an rmr message buffer - - **tid_bytes: bytes** - bytes of the desired transaction id - - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:function:: get_src(ptr_mbuf) - :module: ricxappframe.rmr.rmr - - - Get the message source (likely host:port) - - - :Parameters: - - **ptr_mbuf: ctypes c_void_p** - Pointer to an rmr message buffer - - :Returns: - - string: - message source - - - - - - - - - - +.. automodule:: ricxappframe.rmr.rmr + :members: +RMR Helper API +-------------- - .. - !! processed by numpydoc !! +.. automodule:: ricxappframe.rmr.helpers + :members: