docs/rmr_api.rst

   1 RMR Python Bindings
   2 ===================
   3
   4 Overview
   5 --------
   6
   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.
  13
  14
  15 RMR API
  16 -------
  17
  18 ..
  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
  22              :members:
  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
  27
  28
  29
  30 .. py:module:: ricxappframe.rmr.rmr
  31
  32
  33 ..
  34     !! processed by numpydoc !!
  35
  36 .. py:class:: rmr_mbuf_t
  37    :module: ricxappframe.rmr.rmr
  38
  39
  40    Reimplementation of rmr_mbuf_t which is in an unaccessible header file (src/common/include/rmr.h)
  41
  42    | typedef struct {
  43    |    int     state;          // state of processing
  44    |    int     mtype;          // message type
  45    |    int     len;            // length of data in the payload (send or received)
  46    |    unsigned char* payload; // transported data
  47    |    unsigned char* xaction; // pointer to fixed length transaction id bytes
  48    |    int sub_id;             // subscription id
  49    |    int      tp_state;      // transport state (a.k.a errno)
  50    |
  51    | these things are off limits to the user application
  52    |
  53    |    void*   tp_buf;         // underlying transport allocated pointer (e.g. nng message)
  54    |    void*   header;         // internal message header (whole buffer: header+payload)
  55    |    unsigned char* id;      // if we need an ID in the message separate from the xaction id
  56    |    int flags;              // various MFL (private) flags as needed
  57    |    int alloc_len;          // the length of the allocated space (hdr+payload)
  58    | } rmr_mbuf_t;
  59
  60    We do not include the fields we are not supposed to mess with
  61
  62    RE PAYLOADs type below, see the documentation for c_char_p:
  63       class ctypes.c_char_p
  64           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.
  65
  66
  67
  68
  69
  70
  71
  72
  73
  74
  75
  76
  77
  78    :Attributes:
  79
  80        **len**
  81            Structure/Union member
  82
  83        **mtype**
  84            Structure/Union member
  85
  86        **payload**
  87            Structure/Union member
  88
  89        **state**
  90            Structure/Union member
  91
  92        **sub_id**
  93            Structure/Union member
  94
  95        **tp_state**
  96            Structure/Union member
  97
  98        **xaction**
  99            Structure/Union member
 100
 101
 102    ..
 103        !! processed by numpydoc !!
 104
 105 .. py:function:: rmr_init(uproto_port, max_msg_size, flags)
 106    :module: ricxappframe.rmr.rmr
 107
 108
 109    Refer to rmr C documentation for rmr_init
 110    extern void* rmr_init(char* uproto_port, int max_msg_size, int flags)
 111
 112    This python function checks that the context is not None and raises
 113    an excption if it is.
 114
 115
 116
 117
 118
 119
 120
 121
 122
 123
 124
 125
 126
 127
 128
 129    ..
 130        !! processed by numpydoc !!
 131
 132 .. py:function:: rmr_ready(vctx)
 133    :module: ricxappframe.rmr.rmr
 134
 135
 136    Refer to rmr C documentation for rmr_ready
 137    extern int rmr_ready(void* vctx)
 138
 139
 140
 141
 142
 143
 144
 145
 146
 147
 148
 149
 150
 151
 152
 153
 154    ..
 155        !! processed by numpydoc !!
 156
 157 .. py:function:: rmr_close(vctx)
 158    :module: ricxappframe.rmr.rmr
 159
 160
 161    Refer to rmr C documentation for rmr_close
 162    extern void rmr_close(void* vctx)
 163
 164
 165
 166
 167
 168
 169
 170
 171
 172
 173
 174
 175
 176
 177
 178
 179    ..
 180        !! processed by numpydoc !!
 181
 182 .. py:function:: rmr_set_stimeout(vctx, time)
 183    :module: ricxappframe.rmr.rmr
 184
 185
 186    Refer to the rmr C documentation for rmr_set_stimeout
 187    extern int rmr_set_stimeout(void* vctx, int time)
 188
 189
 190
 191
 192
 193
 194
 195
 196
 197
 198
 199
 200
 201
 202
 203
 204    ..
 205        !! processed by numpydoc !!
 206
 207 .. py:function:: rmr_alloc_msg(vctx, size, payload=None, gen_transaction_id=False, mtype=None, meid=None, sub_id=None, fixed_transaction_id=None)
 208    :module: ricxappframe.rmr.rmr
 209
 210
 211    Refer to the rmr C documentation for rmr_alloc_msg
 212    extern rmr_mbuf_t* rmr_alloc_msg(void* vctx, int size)
 213    TODO: on next API break, clean up transaction_id ugliness. Kept for now to preserve API.
 214
 215    if payload is not None, attempts to set the payload
 216    if gen_transaction_id is True, it generates and sets a transaction id. Note, fixed_transaction_id supersedes this option
 217    if mtype is not None, sets the sbuf's message type
 218    if meid is not None, sets the sbuf's meid
 219    if sub_id is not None, sets the sbud's subscription id
 220    if fixed_transaction_id is set, it deterministically sets the transaction_id. This overrides the option gen_transation_id
 221
 222
 223
 224
 225
 226
 227
 228
 229
 230
 231
 232
 233
 234
 235
 236    ..
 237        !! processed by numpydoc !!
 238
 239 .. py:function:: rmr_realloc_payload(ptr_mbuf, new_len, copy=False, clone=False)
 240    :module: ricxappframe.rmr.rmr
 241
 242
 243    Refer to the rmr C documentation for rmr_realloc_payload().
 244    extern rmr_mbuf_t* rmr_realloc_payload(rmr_mbuf_t*, int, int, int)
 245
 246
 247
 248
 249
 250
 251
 252
 253
 254
 255
 256
 257
 258
 259
 260
 261    ..
 262        !! processed by numpydoc !!
 263
 264 .. py:function:: rmr_free_msg(mbuf)
 265    :module: ricxappframe.rmr.rmr
 266
 267
 268    Refer to the rmr C documentation for rmr_free_msg
 269    extern void rmr_free_msg(rmr_mbuf_t* mbuf )
 270
 271
 272
 273
 274
 275
 276
 277
 278
 279
 280
 281
 282
 283
 284
 285
 286    ..
 287        !! processed by numpydoc !!
 288
 289 .. py:function:: rmr_payload_size(ptr_mbuf)
 290    :module: ricxappframe.rmr.rmr
 291
 292
 293    Refer to the rmr C documentation for rmr_payload_size
 294    extern int rmr_payload_size(rmr_mbuf_t* msg)
 295
 296
 297
 298
 299
 300
 301
 302
 303
 304
 305
 306
 307
 308
 309
 310
 311    ..
 312        !! processed by numpydoc !!
 313
 314 .. py:function:: rmr_send_msg(vctx, ptr_mbuf)
 315    :module: ricxappframe.rmr.rmr
 316
 317
 318    Refer to the rmr C documentation for rmr_send_msg
 319    extern rmr_mbuf_t* rmr_send_msg(void* vctx, rmr_mbuf_t* msg)
 320
 321
 322
 323
 324
 325
 326
 327
 328
 329
 330
 331
 332
 333
 334
 335
 336    ..
 337        !! processed by numpydoc !!
 338
 339 .. py:function:: rmr_rcv_msg(vctx, ptr_mbuf)
 340    :module: ricxappframe.rmr.rmr
 341
 342
 343    Refer to the rmr C documentation for rmr_rcv_msg
 344    extern rmr_mbuf_t* rmr_rcv_msg(void* vctx, rmr_mbuf_t* old_msg)
 345
 346
 347
 348
 349
 350
 351
 352
 353
 354
 355
 356
 357
 358
 359
 360
 361    ..
 362        !! processed by numpydoc !!
 363
 364 .. py:function:: rmr_torcv_msg(vctx, ptr_mbuf, ms_to)
 365    :module: ricxappframe.rmr.rmr
 366
 367
 368    Refer to the rmr C documentation for rmr_torcv_msg
 369    extern rmr_mbuf_t* rmr_torcv_msg(void* vctx, rmr_mbuf_t* old_msg, int ms_to)
 370
 371
 372
 373
 374
 375
 376
 377
 378
 379
 380
 381
 382
 383
 384
 385
 386    ..
 387        !! processed by numpydoc !!
 388
 389 .. py:function:: rmr_rts_msg(vctx, ptr_mbuf, payload=None, mtype=None)
 390    :module: ricxappframe.rmr.rmr
 391
 392
 393    Refer to the rmr C documentation for rmr_rts_msg
 394    extern rmr_mbuf_t*  rmr_rts_msg(void* vctx, rmr_mbuf_t* msg)
 395
 396    additional features beyond c-rmr:
 397        if payload is not None, attempts to set the payload
 398        if mtype is not None, sets the sbuf's message type
 399
 400
 401
 402
 403
 404
 405
 406
 407
 408
 409
 410
 411
 412
 413
 414    ..
 415        !! processed by numpydoc !!
 416
 417 .. py:function:: rmr_call(vctx, ptr_mbuf)
 418    :module: ricxappframe.rmr.rmr
 419
 420
 421    Refer to the rmr C documentation for rmr_call
 422    extern rmr_mbuf_t* rmr_call(void* vctx, rmr_mbuf_t* msg)
 423
 424
 425
 426
 427
 428
 429
 430
 431
 432
 433
 434
 435
 436
 437
 438
 439    ..
 440        !! processed by numpydoc !!
 441
 442 .. py:function:: rmr_set_meid(ptr_mbuf, byte_str)
 443    :module: ricxappframe.rmr.rmr
 444
 445
 446    Refer to the rmr C documentation for rmr_bytes2meid
 447    extern int rmr_bytes2meid(rmr_mbuf_t* mbuf, unsigned char const* src, int len);
 448
 449    Caution:  the meid length supported in an RMR message is 32 bytes, but C applications
 450    expect this to be a nil terminated string and thus only 31 bytes are actually available.
 451
 452    Raises: exceptions.MeidSizeOutOfRang
 453
 454
 455
 456
 457
 458
 459
 460
 461
 462
 463
 464
 465
 466
 467
 468    ..
 469        !! processed by numpydoc !!
 470
 471 .. py:function:: rmr_get_meid(ptr_mbuf)
 472    :module: ricxappframe.rmr.rmr
 473
 474
 475    Get the managed equipment ID (meid) from the message header.
 476
 477
 478    :Parameters:
 479
 480        **ptr_mbuf: ctypes c_void_p**
 481            Pointer to an rmr message buffer
 482
 483    :Returns:
 484
 485        string:
 486            meid
 487
 488
 489
 490
 491
 492
 493
 494
 495
 496
 497
 498
 499
 500    ..
 501        !! processed by numpydoc !!
 502
 503 .. py:function:: rmr_get_src(ptr_mbuf, dest)
 504    :module: ricxappframe.rmr.rmr
 505
 506
 507    Refer to the rmr C documentation for rmr_get_src
 508    extern unsigned char*  rmr_get_src(rmr_mbuf_t* mbuf, unsigned char* dest);
 509
 510
 511
 512
 513
 514
 515
 516
 517
 518
 519
 520
 521
 522
 523
 524
 525    ..
 526        !! processed by numpydoc !!
 527
 528 .. py:function:: get_payload(ptr_mbuf)
 529    :module: ricxappframe.rmr.rmr
 530
 531
 532    Given a rmr_buf_t*, get it's binary payload as a bytes object
 533
 534
 535    :Parameters:
 536
 537        **ptr_mbuf: ctypes c_void_p**
 538            Pointer to an rmr message buffer
 539
 540    :Returns:
 541
 542        bytes:
 543            the message payload
 544
 545
 546
 547
 548
 549
 550
 551
 552
 553
 554
 555
 556
 557    ..
 558        !! processed by numpydoc !!
 559
 560 .. py:function:: get_xaction(ptr_mbuf)
 561    :module: ricxappframe.rmr.rmr
 562
 563
 564    given a rmr_buf_t*, get it's transaction id
 565
 566
 567    :Parameters:
 568
 569        **ptr_mbuf: ctypes c_void_p**
 570            Pointer to an rmr message buffer
 571
 572    :Returns:
 573
 574        bytes:
 575            the transaction id
 576
 577
 578
 579
 580
 581
 582
 583
 584
 585
 586
 587
 588
 589    ..
 590        !! processed by numpydoc !!
 591
 592 .. py:function:: message_summary(ptr_mbuf)
 593    :module: ricxappframe.rmr.rmr
 594
 595
 596    Returns a dict that contains the fields of a message
 597
 598
 599    :Parameters:
 600
 601        **ptr_mbuf: ctypes c_void_p**
 602            Pointer to an rmr message buffer
 603
 604    :Returns:
 605
 606        dict:
 607            dict message summary
 608
 609
 610
 611
 612
 613
 614
 615
 616
 617
 618
 619
 620
 621    ..
 622        !! processed by numpydoc !!
 623
 624 .. py:function:: set_payload_and_length(byte_str, ptr_mbuf)
 625    :module: ricxappframe.rmr.rmr
 626
 627
 628    | Set an rmr payload and content length
 629    | In place method, no return
 630
 631
 632    :Parameters:
 633
 634        **byte_str: bytes**
 635            the bytes to set the payload to
 636
 637        **ptr_mbuf: ctypes c_void_p**
 638            Pointer to an rmr message buffer
 639
 640
 641
 642
 643
 644
 645
 646
 647
 648
 649
 650
 651
 652
 653    ..
 654        !! processed by numpydoc !!
 655
 656 .. py:function:: generate_and_set_transaction_id(ptr_mbuf)
 657    :module: ricxappframe.rmr.rmr
 658
 659
 660    Generate a UUID and Set an rmr transaction id to it
 661
 662
 663    :Parameters:
 664
 665        **ptr_mbuf: ctypes c_void_p**
 666            Pointer to an rmr message buffer
 667
 668
 669
 670
 671
 672
 673
 674
 675
 676
 677
 678
 679
 680
 681    ..
 682        !! processed by numpydoc !!
 683
 684 .. py:function:: set_transaction_id(ptr_mbuf, tid_bytes)
 685    :module: ricxappframe.rmr.rmr
 686
 687
 688    Set an rmr transaction id
 689    TODO: on next API break, merge these two functions. Not done now to preserve API.
 690
 691
 692    :Parameters:
 693
 694        **ptr_mbuf: ctypes c_void_p**
 695            Pointer to an rmr message buffer
 696
 697        **tid_bytes: bytes**
 698            bytes of the desired transaction id
 699
 700
 701
 702
 703
 704
 705
 706
 707
 708
 709
 710
 711
 712
 713    ..
 714        !! processed by numpydoc !!
 715
 716 .. py:function:: get_src(ptr_mbuf)
 717    :module: ricxappframe.rmr.rmr
 718
 719
 720    Get the message source (likely host:port)
 721
 722
 723    :Parameters:
 724
 725        **ptr_mbuf: ctypes c_void_p**
 726            Pointer to an rmr message buffer
 727
 728    :Returns:
 729
 730        string:
 731            message source
 732
 733
 734
 735
 736
 737
 738
 739
 740
 741
 742
 743
 744
 745    ..
 746        !! processed by numpydoc !!