doc/src/man/rmr_tralloc_msg.3.xfm

   1 .if false
   2 ==================================================================================
   3    Copyright (c) 2019-2020 Nokia
   4    Copyright (c) 2018-2020 AT&T Intellectual Property.
   5
   6    Licensed under the Apache License, Version 2.0 (the "License");
   7    you may not use this file except in compliance with the License.
   8    You may obtain a copy of the License at
   9
  10        http://www.apache.org/licenses/LICENSE-2.0
  11
  12    Unless required by applicable law or agreed to in writing, software
  13    distributed under the License is distributed on an "AS IS" BASIS,
  14    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15    See the License for the specific language governing permissions and
  16    limitations under the License.
  17 ==================================================================================
  18 .fi
  19 .if false
  20     Mnemonic    rmr_tralloc_msg.xfm
  21     Abstract    The manual page for the rmr_tralloc_msg function.
  22     Author      E. Scott Daniels
  23     Date        19 April 2019
  24 .fi
  25
  26 .gv e LIB lib
  27 .im &{lib}/man/setup.im
  28
  29 &line_len(6i)
  30
  31 &h1(RMR Library Functions)
  32 &h2(NAME)
  33     rmr_tralloc_msg
  34
  35 &h2(SYNOPSIS )
  36 &indent
  37 &ex_start
  38 #include <rmr/rmr.h>
  39
  40 rmr_mbuf_t* rmr_tralloc_msg( void* vctx, int size,
  41                              int trace_size, unsigned const char *tr_data );
  42 &ex_end
  43 &uindent
  44
  45 &h2(DESCRIPTION)
  46 The &cw(rmr_tralloc_msg) function is used to allocate a buffer which the user
  47 programme can write into and then send through the library.
  48 The buffer is allocated such that sending it requires no additional copying
  49 from the buffer as it passes through the underlying transport mechanism.
  50 .sp
  51
  52 The &ital(size) parameter is used to set the payload length in the message.
  53 If it is 0, then the default size supplied on the &ital(rmr_init) call will be used.
  54 In addition to allocating the payload, a space in the buffer is
  55 reserved for &ital(trace) data (tr_size bytes), and the bytes pointed to
  56 by &ital(tr_data) are copied into that portion of the message.
  57
  58 The &ital(vctx) parameter is the void context pointer that was returned by
  59 the &ital(rmr_init) function.
  60
  61
  62 &space
  63 The pointer to the message buffer returned is a structure which has some
  64 user application visible fields; the structure is described in &cw(rmr.h,)
  65 and is illustrated below.
  66
  67 &space
  68 &ex_start
  69 typedef struct {
  70     int state;
  71     int mtype;
  72     int len;
  73     unsigned char* payload;
  74     unsigned char* xaction;
  75 } rmr_mbuf_t;
  76 &ex_end
  77
  78 &space
  79 Where:
  80 &half_space
  81
  82 &beg_dlist(.75i : ^&bold_font )
  83 &ditem(state)  Is the current buffer state.  Following a call to &cw(rmr_send_msg)
  84         the state indicates whether the buffer was successfully sent which determines
  85         exactly what the payload points to.  If the send failed, the payload referenced
  86         by the buffer is the message that failed to send (allowing the application to
  87         attempt a retransmission).
  88         When the state is &cw(a_OK) the buffer represents an empty buffer that the application
  89         may fill in in preparation to send.
  90
  91 &ditem(mtype)  When sending a message, the application is expected to set this field
  92         to the appropriate message type value (as determined by the user programme). Upon send
  93         this value determines how the a library will route the message.
  94         For a buffer which has been received, this field will contain the message type that was
  95         set by the sending application.
  96
  97 &ditem(len) The application using a buffer to send a message is expected to set the
  98         length value to the actual number of bytes that it placed into the message. This
  99         is likely less than the total number of bytes that the message can carry.
 100         For a message buffer that is passed to the application as the result of a receive
 101         call, this will be the value that the sending application supplied and should
 102         indicate the number of bytes in the payload which are valid.
 103
 104 &ditem(payload) The payload is a pointer to the actual received data.  The
 105         user programme may read and write from/to the memory referenced by the payload
 106         up until the point in time that the buffer is used on a &cw(rmr_send, rmr_call)
 107         or &cw(rmr_reply) function call.
 108         Once the buffer has been passed back to a a library function the user programme
 109         should &bold(NOT) make use of the payload pointer.
 110
 111 &ditem(xaction) The &ital(xaction) field is a pointer to a fixed sized area in
 112         the message into which the user may write a transaction ID.
 113         The ID is optional with the exception of when the user application uses the &cw(rmr_call)
 114         function to send a message and wait for the reply; the underlying processing
 115         expects that the matching reply message will also contain the same data in the
 116         &ital(xaction) field.
 117 &end_dlist
 118
 119 &h2(RETURN VALUE)
 120 The function returns a pointer to a &cw(rmr_mbuf) structure, or NULL on error.
 121
 122 &h2(ERRORS)
 123 &beg_dlist(.75i : ^&bold_font )
 124 &ditem(ENOMEM) Unable to allocate memory.
 125 &end_dlist
 126
 127 .** &h2(EXAMPLE)
 128
 129 &h2(SEE ALSO )
 130 .ju off
 131 rmr_alloc_msg(3),
 132 rmr_mbuf(3)
 133 rmr_call(3),
 134 rmr_free_msg(3),
 135 rmr_init(3),
 136 rmr_init_trace(3),
 137 rmr_get_trace(3),
 138 rmr_get_trlen(3),
 139 rmr_payload_size(3),
 140 rmr_send_msg(3),
 141 rmr_rcv_msg(3),
 142 rmr_rcv_specific(3),
 143 rmr_rts_msg(3),
 144 rmr_ready(3),
 145 rmr_fib(3),
 146 rmr_has_str(3),
 147 rmr_tokenise(3),
 148 rmr_mk_ring(3),
 149 rmr_ring_free(3),
 150 rmr_set_trace(3)
 151 .ju on
 152