X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;f=docs%2Frmr_api.rst;h=69caf590c228104e3f810dfe008544987c50221c;hb=b25bb4cf448766e8ce5113878a9cf4d7947ec00f;hp=4db5b7e0ec5b62b47135ed5604ca87f388bd1941;hpb=4b9552c36d910264474a25cd7c1520a2a816f4d4;p=ric-plt%2Fxapp-frame-py.git diff --git a/docs/rmr_api.rst b/docs/rmr_api.rst index 4db5b7e..69caf59 100644 --- a/docs/rmr_api.rst +++ b/docs/rmr_api.rst @@ -1,1101 +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:data:: RMR_MAX_RCV_BYTES - :module: ricxappframe.rmr.rmr - :value: 65536 - - - Maximum size message to receive - - - - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:data:: RMRFL_MTCALL - :module: ricxappframe.rmr.rmr - :value: 2 - - - Multi-threaded initialization flag - - - - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:data:: RMRFL_NONE - :module: ricxappframe.rmr.rmr - :value: 0 - - - Empty flag - - - - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:data:: RMR_OK - :module: ricxappframe.rmr.rmr - :value: 0 - - - State constant for OK - - - - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:data:: RMR_ERR_TIMEOUT - :module: ricxappframe.rmr.rmr - :value: 12 - - - State constant for timeout - - - - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:data:: RMR_ERR_RETRY - :module: ricxappframe.rmr.rmr - :value: 10 - - - State constant for retry - - - - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:class:: rmr_mbuf_t - :module: ricxappframe.rmr.rmr - - - Mirrors public members of type rmr_mbuf_t from RMR 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; - - 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: ctypes.c_char_p, max_msg_size: int, flags: int) -> ctypes.c_void_p - :module: ricxappframe.rmr.rmr - - - Prepares the environment for sending and receiving messages. - Refer to RMR C documentation for method:: - - extern void* rmr_init(char* uproto_port, int max_msg_size, int flags) - - This function raises an exception if the returned context is None. - - :Parameters: - - **uproto_port: c_char_p** - Pointer to a buffer with the port number as a string; e.g., "4550" - - **max_msg_size: integer** - Maximum message size to receive - - **flags: integer** - RMR option flags - - :Returns: - - c_void_p: - Pointer to RMR context - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:function:: rmr_ready(vctx: ctypes.c_void_p) -> int - :module: ricxappframe.rmr.rmr - - - Checks if a routing table has been received and installed. - Refer to RMR C documentation for method:: - - extern int rmr_ready(void* vctx) - - :Parameters: - - **vctx: ctypes c_void_p** - Pointer to RMR context - - :Returns: - - 1 for yes, 0 for no - .. - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:function:: rmr_close(vctx: ctypes.c_void_p) - :module: ricxappframe.rmr.rmr - - - Closes the listen socket. - Refer to RMR C documentation for method:: - - extern void rmr_close(void* vctx) - - :Parameters: - - **vctx: ctypes c_void_p** - Pointer to RMR context - - :Returns: - - None - .. - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:function:: rmr_set_stimeout(vctx: ctypes.c_void_p, rloops: int) -> int - :module: ricxappframe.rmr.rmr - - - Sets the configuration for how RMR will retry message send operations. - Refer to RMR C documentation for method:: - - extern int rmr_set_stimeout(void* vctx, int rloops) - - :Parameters: - - **vctx: ctypes c_void_p** - Pointer to RMR context - - **rloops: int** - Number of retry loops - - :Returns: - - 0 on success, -1 on failure - .. - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:function:: rmr_alloc_msg(vctx: ctypes.c_void_p, size: int, payload=None, gen_transaction_id: bool = False, mtype=None, meid=None, sub_id=None, fixed_transaction_id=None) - :module: ricxappframe.rmr.rmr - - - Allocates and returns a buffer to write and send through the RMR library. - Refer to RMR C documentation for method:: - - extern rmr_mbuf_t* rmr_alloc_msg(void* vctx, int size) - - Optionally populates the message from the remaining arguments. - - TODO: on next API break, clean up transaction_id ugliness. Kept for now to preserve API. - - :Parameters: - - **vctx: ctypes c_void_p** - Pointer to RMR context - - **size: int** - How much space to allocate - - **payload: bytes** - if not None, attempts to set the payload - - **gen_transaction_id: bool** - if True, generates and sets a transaction ID. - Note, option fixed_transaction_id overrides this option - - **mtype: bytes** - if not None, sets the sbuf's message type - - **meid: bytes** - if not None, sets the sbuf's meid - - **sub_id: bytes** - if not None, sets the sbuf's subscription id - - **fixed_transaction_id: bytes** - if not None, used as the transaction ID. - Note, this overrides the option gen_transaction_id - - :Returns: - - c_void_p: - Pointer to rmr_mbuf structure - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:function:: rmr_realloc_payload(ptr_mbuf: ctypes.c_void_p, new_len: int, copy: bool = False, clone: bool = False) - :module: ricxappframe.rmr.rmr - - - Allocates and returns a message buffer large enough for the new length. - Refer to RMR C documentation for method:: - - extern rmr_mbuf_t* rmr_realloc_payload(rmr_mbuf_t*, int, int, int) - - :Parameters: - - **ptr_mbuf: c_void_p** - Pointer to rmr_mbuf structure - - **new_len: int** - Length - - **copy: bool** - Whether to copy the original paylod - - **clone: bool** - Whether to clone the original buffer - - :Returns: - - c_void_p: - Pointer to rmr_mbuf structure - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:function:: rmr_free_msg(ptr_mbuf: ctypes.c_void_p) - :module: ricxappframe.rmr.rmr - - - Releases the message buffer. - Refer to RMR C documentation for method:: - - extern void rmr_free_msg(rmr_mbuf_t* mbuf ) - - :Parameters: - - **ptr_mbuf: c_void_p** - Pointer to rmr_mbuf structure - - :Returns: - - None - .. - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:function:: rmr_payload_size(ptr_mbuf: ctypes.c_void_p) -> int - :module: ricxappframe.rmr.rmr - - - Gets the number of bytes available in the payload. - Refer to RMR C documentation for method:: - - extern int rmr_payload_size(rmr_mbuf_t* msg) - - :Parameters: - - **ptr_mbuf: c_void_p** - Pointer to rmr_mbuf structure - - :Returns: - - int: - Number of bytes available - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:function:: rmr_send_msg(vctx: ctypes.c_void_p, ptr_mbuf: ricxappframe.rmr.rmr.LP_rmr_mbuf_t) -> ricxappframe.rmr.rmr.LP_rmr_mbuf_t - :module: ricxappframe.rmr.rmr - - - Sends the message according to the routing table and returns an empty buffer. - Refer to RMR C documentation for method:: - - extern rmr_mbuf_t* rmr_send_msg(void* vctx, rmr_mbuf_t* msg) - - :Parameters: - - **vctx: ctypes c_void_p** - Pointer to RMR context - - **ptr_mbuf: c_void_p** - Pointer to rmr_mbuf structure - - :Returns: - - c_void_p: - Pointer to rmr_mbuf structure - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:function:: rmr_rcv_msg(vctx: ctypes.c_void_p, ptr_mbuf: ricxappframe.rmr.rmr.LP_rmr_mbuf_t) -> ricxappframe.rmr.rmr.LP_rmr_mbuf_t - :module: ricxappframe.rmr.rmr - - - Waits for a message to arrive, and returns it. - Refer to RMR C documentation for method:: - - extern rmr_mbuf_t* rmr_rcv_msg(void* vctx, rmr_mbuf_t* old_msg) - - :Parameters: - - **vctx: ctypes c_void_p** - Pointer to RMR context - - **ptr_mbuf: c_void_p** - Pointer to rmr_mbuf structure - - :Returns: - - c_void_p: - Pointer to rmr_mbuf structure - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:function:: rmr_torcv_msg(vctx: ctypes.c_void_p, ptr_mbuf: ricxappframe.rmr.rmr.LP_rmr_mbuf_t, ms_to: int) -> ricxappframe.rmr.rmr.LP_rmr_mbuf_t - :module: ricxappframe.rmr.rmr - - - Waits up to the timeout value for a message to arrive, and returns it. - Refer to RMR C documentation for method:: - - extern rmr_mbuf_t* rmr_torcv_msg(void* vctx, rmr_mbuf_t* old_msg, int ms_to) - - :Parameters: - - **vctx: ctypes c_void_p** - Pointer to RMR context - - **ptr_mbuf: c_void_p** - Pointer to rmr_mbuf structure - - **ms_to: int** - Time out value in milliseconds - - :Returns: - - c_void_p: - Pointer to rmr_mbuf structure - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:function:: rmr_rts_msg(vctx: ctypes.c_void_p, ptr_mbuf: ricxappframe.rmr.rmr.LP_rmr_mbuf_t, payload=None, mtype=None) -> ricxappframe.rmr.rmr.LP_rmr_mbuf_t - :module: ricxappframe.rmr.rmr - - - Sends a message to the originating endpoint and returns an empty buffer. - Refer to RMR C documentation for method:: - - 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 - - :Parameters: - - **vctx: ctypes c_void_p** - Pointer to an RMR context - - **ptr_mbuf: ctypes c_void_p** - Pointer to an RMR message buffer - - **payload: bytes** - Payload - - **mtype: bytes** - Message type - - :Returns: - - c_void_p: - Pointer to rmr_mbuf structure - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:function:: rmr_call(vctx: ctypes.c_void_p, ptr_mbuf: ricxappframe.rmr.rmr.LP_rmr_mbuf_t) -> ricxappframe.rmr.rmr.LP_rmr_mbuf_t - :module: ricxappframe.rmr.rmr - - - Sends a message, waits for a response and returns it. - Refer to RMR C documentation for method:: - - extern rmr_mbuf_t* rmr_call(void* vctx, rmr_mbuf_t* msg) - - :Parameters: - - **ptr_mbuf: ctypes c_void_p** - Pointer to an RMR message buffer - - :Returns: - - c_void_p: - Pointer to rmr_mbuf structure - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:function:: rmr_set_meid(ptr_mbuf: ricxappframe.rmr.rmr.LP_rmr_mbuf_t, byte_str: bytes) -> int - :module: ricxappframe.rmr.rmr - - - Sets the managed entity field in the message and returns the number of bytes copied. - Refer to RMR C documentation for method:: - - 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 - - :Parameters: - - **ptr_mbuf: ctypes c_void_p** - Pointer to an RMR message buffer - - **byte_tr: bytes** - Managed entity ID value - - :Returns: - - int: - number of bytes copied - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:function:: rmr_get_meid(ptr_mbuf: ricxappframe.rmr.rmr.LP_rmr_mbuf_t) -> bytes - :module: ricxappframe.rmr.rmr - - - Gets the managed entity ID (meid) from the message header. - This is a python-friendly version of RMR C method:: - - extern unsigned char* rmr_get_meid(rmr_mbuf_t* mbuf, unsigned char* dest); - - :Parameters: - - **ptr_mbuf: ctypes c_void_p** - Pointer to an RMR message buffer - - :Returns: - - bytes: - Managed entity ID - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:function:: rmr_get_src(ptr_mbuf: ricxappframe.rmr.rmr.LP_rmr_mbuf_t, dest: ctypes.c_char_p) -> ctypes.c_char_p - :module: ricxappframe.rmr.rmr - - - Copies the message-source information to the buffer. - Refer to RMR C documentation for method:: - - extern unsigned char* rmr_get_src(rmr_mbuf_t* mbuf, unsigned char* dest); - - :Parameters: - - **ptr_mbuf: ctypes POINTER(rmr_mbuf_t)** - Pointer to an RMR message buffer - - **dest: ctypes c_char_p** - Pointer to a buffer to receive the message source - - :Returns: - - string: - message-source information - - - - - - - - - - - - - - .. - !! processed by numpydoc !! - -.. py:function:: get_payload(ptr_mbuf: ctypes.c_void_p) -> bytes - :module: ricxappframe.rmr.rmr - - - Gets the binary payload from the rmr_buf_t*. - - - :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: ctypes.c_void_p) -> bytes - :module: ricxappframe.rmr.rmr - - - Gets the transaction ID from the rmr_buf_t*. - - - :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: ctypes.c_void_p) -> dict - :module: ricxappframe.rmr.rmr - - - Returns a dict with the fields of an RMR 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: bytes, ptr_mbuf: ctypes.c_void_p) - :module: ricxappframe.rmr.rmr - - - Sets 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: ctypes.c_void_p) - :module: ricxappframe.rmr.rmr - - - Generates a UUID and sets the 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: ctypes.c_void_p, tid_bytes: bytes) - :module: ricxappframe.rmr.rmr - - - Sets 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: ctypes.c_void_p) -> str - :module: ricxappframe.rmr.rmr - - - Gets 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: - .. - !! processed by numpydoc !! +RMR Helper API +-------------- +.. automodule:: ricxappframe.rmr.helpers + :members: