7 The xapp python framework repository includes a python submodule
8 called `rmr`. This package (`ricxappframe.rmr`) is a CTYPES wrapper
9 around the RMR shared library. Most Xapp users will never use this
10 package natively; however python apps that need access to the low
11 level RMR API can use this package. Usage of this python package
12 requires that you have the RMR shared-object library installed.
19 Sphinx can generate API documentation by running Python to pull doc strings
20 from the binding code using these Sphinx directives that are commented out:
21 .. automodule:: ricxappframe.rmr.rmr
23 But that approach requires the RMR library to be installed, which is difficult
24 to achieve at ReadTheDocs.io. Instead, the RST below was generated and captured
25 according to the method shown at
26 https://stackoverflow.com/questions/2668187/make-sphinx-generate-rst-class-documentation-from-pydoc
30 .. py:module:: ricxappframe.rmr.rmr
34 !! processed by numpydoc !!
36 .. py:data:: RMR_MAX_RCV_BYTES
37 :module: ricxappframe.rmr.rmr
41 Maximum size message to receive
59 !! processed by numpydoc !!
61 .. py:data:: RMRFL_MTCALL
62 :module: ricxappframe.rmr.rmr
66 Multi-threaded initialization flag
84 !! processed by numpydoc !!
86 .. py:data:: RMRFL_NONE
87 :module: ricxappframe.rmr.rmr
109 !! processed by numpydoc !!
112 :module: ricxappframe.rmr.rmr
116 State constant for OK
134 !! processed by numpydoc !!
136 .. py:data:: RMR_ERR_TIMEOUT
137 :module: ricxappframe.rmr.rmr
141 State constant for timeout
159 !! processed by numpydoc !!
161 .. py:data:: RMR_ERR_RETRY
162 :module: ricxappframe.rmr.rmr
166 State constant for retry
184 !! processed by numpydoc !!
186 .. py:class:: rmr_mbuf_t
187 :module: ricxappframe.rmr.rmr
190 Mirrors public members of type rmr_mbuf_t from RMR header file src/common/include/rmr.h
193 | int state; // state of processing
194 | int mtype; // message type
195 | int len; // length of data in the payload (send or received)
196 | unsigned char* payload; // transported data
197 | unsigned char* xaction; // pointer to fixed length transaction id bytes
198 | int sub_id; // subscription id
199 | int tp_state; // transport state (a.k.a errno)
201 | these things are off limits to the user application
203 | void* tp_buf; // underlying transport allocated pointer (e.g. nng message)
204 | void* header; // internal message header (whole buffer: header+payload)
205 | unsigned char* id; // if we need an ID in the message separate from the xaction id
206 | int flags; // various MFL (private) flags as needed
207 | int alloc_len; // the length of the allocated space (hdr+payload)
210 RE PAYLOADs type below, see the documentation for c_char_p:
211 class ctypes.c_char_p
212 Represents the C char * datatype when it points to a zero-terminated string.
213 For a general character pointer that may also point to binary data, POINTER(c_char)
214 must be used. The constructor accepts an integer address, or a bytes object.
231 Structure/Union member
234 Structure/Union member
237 Structure/Union member
240 Structure/Union member
243 Structure/Union member
246 Structure/Union member
249 Structure/Union member
253 !! processed by numpydoc !!
255 .. py:function:: rmr_init(uproto_port: ctypes.c_char_p, max_msg_size: int, flags: int) -> ctypes.c_void_p
256 :module: ricxappframe.rmr.rmr
259 Prepares the environment for sending and receiving messages.
260 Refer to RMR C documentation for method::
262 extern void* rmr_init(char* uproto_port, int max_msg_size, int flags)
264 This function raises an exception if the returned context is None.
268 **uproto_port: c_char_p**
269 Pointer to a buffer with the port number as a string; e.g., "4550"
271 **max_msg_size: integer**
272 Maximum message size to receive
280 Pointer to RMR context
295 !! processed by numpydoc !!
297 .. py:function:: rmr_ready(vctx: ctypes.c_void_p) -> int
298 :module: ricxappframe.rmr.rmr
301 Checks if a routing table has been received and installed.
302 Refer to RMR C documentation for method::
304 extern int rmr_ready(void* vctx)
308 **vctx: ctypes c_void_p**
309 Pointer to RMR context
329 !! processed by numpydoc !!
331 .. py:function:: rmr_close(vctx: ctypes.c_void_p)
332 :module: ricxappframe.rmr.rmr
335 Closes the listen socket.
336 Refer to RMR C documentation for method::
338 extern void rmr_close(void* vctx)
342 **vctx: ctypes c_void_p**
343 Pointer to RMR context
363 !! processed by numpydoc !!
365 .. py:function:: rmr_set_stimeout(vctx: ctypes.c_void_p, rloops: int) -> int
366 :module: ricxappframe.rmr.rmr
369 Sets the configuration for how RMR will retry message send operations.
370 Refer to RMR C documentation for method::
372 extern int rmr_set_stimeout(void* vctx, int rloops)
376 **vctx: ctypes c_void_p**
377 Pointer to RMR context
380 Number of retry loops
384 0 on success, -1 on failure
400 !! processed by numpydoc !!
402 .. 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)
403 :module: ricxappframe.rmr.rmr
406 Allocates and returns a buffer to write and send through the RMR library.
407 Refer to RMR C documentation for method::
409 extern rmr_mbuf_t* rmr_alloc_msg(void* vctx, int size)
411 Optionally populates the message from the remaining arguments.
413 TODO: on next API break, clean up transaction_id ugliness. Kept for now to preserve API.
417 **vctx: ctypes c_void_p**
418 Pointer to RMR context
421 How much space to allocate
424 if not None, attempts to set the payload
426 **gen_transaction_id: bool**
427 if True, generates and sets a transaction ID.
428 Note, option fixed_transaction_id overrides this option
431 if not None, sets the sbuf's message type
434 if not None, sets the sbuf's meid
437 if not None, sets the sbuf's subscription id
439 **fixed_transaction_id: bytes**
440 if not None, used as the transaction ID.
441 Note, this overrides the option gen_transaction_id
446 Pointer to rmr_mbuf structure
461 !! processed by numpydoc !!
463 .. py:function:: rmr_realloc_payload(ptr_mbuf: ctypes.c_void_p, new_len: int, copy: bool = False, clone: bool = False)
464 :module: ricxappframe.rmr.rmr
467 Allocates and returns a message buffer large enough for the new length.
468 Refer to RMR C documentation for method::
470 extern rmr_mbuf_t* rmr_realloc_payload(rmr_mbuf_t*, int, int, int)
474 **ptr_mbuf: c_void_p**
475 Pointer to rmr_mbuf structure
481 Whether to copy the original paylod
484 Whether to clone the original buffer
489 Pointer to rmr_mbuf structure
504 !! processed by numpydoc !!
506 .. py:function:: rmr_free_msg(ptr_mbuf: ctypes.c_void_p)
507 :module: ricxappframe.rmr.rmr
510 Releases the message buffer.
511 Refer to RMR C documentation for method::
513 extern void rmr_free_msg(rmr_mbuf_t* mbuf )
517 **ptr_mbuf: c_void_p**
518 Pointer to rmr_mbuf structure
538 !! processed by numpydoc !!
540 .. py:function:: rmr_payload_size(ptr_mbuf: ctypes.c_void_p) -> int
541 :module: ricxappframe.rmr.rmr
544 Gets the number of bytes available in the payload.
545 Refer to RMR C documentation for method::
547 extern int rmr_payload_size(rmr_mbuf_t* msg)
551 **ptr_mbuf: c_void_p**
552 Pointer to rmr_mbuf structure
557 Number of bytes available
572 !! processed by numpydoc !!
574 .. 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
575 :module: ricxappframe.rmr.rmr
578 Sends the message according to the routing table and returns an empty buffer.
579 Refer to RMR C documentation for method::
581 extern rmr_mbuf_t* rmr_send_msg(void* vctx, rmr_mbuf_t* msg)
585 **vctx: ctypes c_void_p**
586 Pointer to RMR context
588 **ptr_mbuf: c_void_p**
589 Pointer to rmr_mbuf structure
594 Pointer to rmr_mbuf structure
609 !! processed by numpydoc !!
611 .. 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
612 :module: ricxappframe.rmr.rmr
615 Waits for a message to arrive, and returns it.
616 Refer to RMR C documentation for method::
618 extern rmr_mbuf_t* rmr_rcv_msg(void* vctx, rmr_mbuf_t* old_msg)
622 **vctx: ctypes c_void_p**
623 Pointer to RMR context
625 **ptr_mbuf: c_void_p**
626 Pointer to rmr_mbuf structure
631 Pointer to rmr_mbuf structure
646 !! processed by numpydoc !!
648 .. 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
649 :module: ricxappframe.rmr.rmr
652 Waits up to the timeout value for a message to arrive, and returns it.
653 Refer to RMR C documentation for method::
655 extern rmr_mbuf_t* rmr_torcv_msg(void* vctx, rmr_mbuf_t* old_msg, int ms_to)
659 **vctx: ctypes c_void_p**
660 Pointer to RMR context
662 **ptr_mbuf: c_void_p**
663 Pointer to rmr_mbuf structure
666 Time out value in milliseconds
671 Pointer to rmr_mbuf structure
686 !! processed by numpydoc !!
688 .. 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
689 :module: ricxappframe.rmr.rmr
692 Sends a message to the originating endpoint and returns an empty buffer.
693 Refer to RMR C documentation for method::
695 extern rmr_mbuf_t* rmr_rts_msg(void* vctx, rmr_mbuf_t* msg)
697 additional features beyond c-rmr:
698 if payload is not None, attempts to set the payload
699 if mtype is not None, sets the sbuf's message type
703 **vctx: ctypes c_void_p**
704 Pointer to an RMR context
706 **ptr_mbuf: ctypes c_void_p**
707 Pointer to an RMR message buffer
718 Pointer to rmr_mbuf structure
733 !! processed by numpydoc !!
735 .. 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
736 :module: ricxappframe.rmr.rmr
739 Sends a message, waits for a response and returns it.
740 Refer to RMR C documentation for method::
742 extern rmr_mbuf_t* rmr_call(void* vctx, rmr_mbuf_t* msg)
746 **ptr_mbuf: ctypes c_void_p**
747 Pointer to an RMR message buffer
752 Pointer to rmr_mbuf structure
767 !! processed by numpydoc !!
769 .. py:function:: rmr_set_meid(ptr_mbuf: ricxappframe.rmr.rmr.LP_rmr_mbuf_t, byte_str: bytes) -> int
770 :module: ricxappframe.rmr.rmr
773 Sets the managed entity field in the message and returns the number of bytes copied.
774 Refer to RMR C documentation for method::
776 extern int rmr_bytes2meid(rmr_mbuf_t* mbuf, unsigned char const* src, int len);
778 Caution: the meid length supported in an RMR message is 32 bytes, but C applications
779 expect this to be a nil terminated string and thus only 31 bytes are actually available.
781 Raises: exceptions.MeidSizeOutOfRang
785 **ptr_mbuf: ctypes c_void_p**
786 Pointer to an RMR message buffer
789 Managed entity ID value
794 number of bytes copied
809 !! processed by numpydoc !!
811 .. py:function:: rmr_get_meid(ptr_mbuf: ricxappframe.rmr.rmr.LP_rmr_mbuf_t) -> bytes
812 :module: ricxappframe.rmr.rmr
815 Gets the managed entity ID (meid) from the message header.
816 This is a python-friendly version of RMR C method::
818 extern unsigned char* rmr_get_meid(rmr_mbuf_t* mbuf, unsigned char* dest);
822 **ptr_mbuf: ctypes c_void_p**
823 Pointer to an RMR message buffer
843 !! processed by numpydoc !!
845 .. py:function:: rmr_get_src(ptr_mbuf: ricxappframe.rmr.rmr.LP_rmr_mbuf_t, dest: ctypes.c_char_p) -> ctypes.c_char_p
846 :module: ricxappframe.rmr.rmr
849 Copies the message-source information to the buffer.
850 Refer to RMR C documentation for method::
852 extern unsigned char* rmr_get_src(rmr_mbuf_t* mbuf, unsigned char* dest);
856 **ptr_mbuf: ctypes POINTER(rmr_mbuf_t)**
857 Pointer to an RMR message buffer
859 **dest: ctypes c_char_p**
860 Pointer to a buffer to receive the message source
865 message-source information
880 !! processed by numpydoc !!
882 .. py:function:: get_payload(ptr_mbuf: ctypes.c_void_p) -> bytes
883 :module: ricxappframe.rmr.rmr
886 Gets the binary payload from the rmr_buf_t*.
891 **ptr_mbuf: ctypes c_void_p**
892 Pointer to an rmr message buffer
912 !! processed by numpydoc !!
914 .. py:function:: get_xaction(ptr_mbuf: ctypes.c_void_p) -> bytes
915 :module: ricxappframe.rmr.rmr
918 Gets the transaction ID from the rmr_buf_t*.
923 **ptr_mbuf: ctypes c_void_p**
924 Pointer to an rmr message buffer
944 !! processed by numpydoc !!
946 .. py:function:: message_summary(ptr_mbuf: ctypes.c_void_p) -> dict
947 :module: ricxappframe.rmr.rmr
950 Returns a dict with the fields of an RMR message.
955 **ptr_mbuf: ctypes c_void_p**
956 Pointer to an rmr message buffer
976 !! processed by numpydoc !!
978 .. py:function:: set_payload_and_length(byte_str: bytes, ptr_mbuf: ctypes.c_void_p)
979 :module: ricxappframe.rmr.rmr
982 Sets an rmr payload and content length.
983 In place method, no return.
989 the bytes to set the payload to
991 **ptr_mbuf: ctypes c_void_p**
992 Pointer to an rmr message buffer
1008 !! processed by numpydoc !!
1010 .. py:function:: generate_and_set_transaction_id(ptr_mbuf: ctypes.c_void_p)
1011 :module: ricxappframe.rmr.rmr
1014 Generates a UUID and sets the RMR transaction id to it
1019 **ptr_mbuf: ctypes c_void_p**
1020 Pointer to an rmr message buffer
1036 !! processed by numpydoc !!
1038 .. py:function:: set_transaction_id(ptr_mbuf: ctypes.c_void_p, tid_bytes: bytes)
1039 :module: ricxappframe.rmr.rmr
1042 Sets an RMR transaction id
1043 TODO: on next API break, merge these two functions. Not done now to preserve API.
1048 **ptr_mbuf: ctypes c_void_p**
1049 Pointer to an rmr message buffer
1051 **tid_bytes: bytes**
1052 bytes of the desired transaction id
1068 !! processed by numpydoc !!
1070 .. py:function:: get_src(ptr_mbuf: ctypes.c_void_p) -> str
1071 :module: ricxappframe.rmr.rmr
1074 Gets the message source (likely host:port)
1079 **ptr_mbuf: ctypes c_void_p**
1080 Pointer to an rmr message buffer
1100 !! processed by numpydoc !!