doc/src/man/rmr_alloc_msg.3.xfm

   1 .if false
   2 ==================================================================================
   3         Copyright (c) 2019 Nokia
   4         Copyright (c) 2018-2019 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_alloc_msg.xfm
  21         Abstract        The manual page for the rmr_alloc_msg function.
  22         Author          E. Scott Daniels
  23         Date            28 January 2019
  24 .fi
  25
  26 .** if formatting with tfm, the roff.im will cause roff output to be generated
  27 .** if formatting with pfm, then pretty postscript will be generated
  28 .gv e LIB lib
  29 .if pfm
  30         .im &{lib}/generic_ps.im
  31 .ei
  32         .gv e OUTPUT_RST use_rst
  33         .if .ev &use_rst 1 =
  34                 .im &{lib}/rst.im
  35         .ei
  36                 .im &{lib}/roff.im
  37         .fi
  38 .fi
  39
  40 &line_len(6i)
  41
  42 &h1(RMR Library Functions)
  43 &h2(NAME)
  44         rmr_alloc_msg
  45
  46 &h2(SYNOPSIS )
  47 &indent
  48 &ex_start
  49 #include <rmr/rmr.h>
  50
  51 rmr_mbuf_t* rmr_alloc_msg( void* a, int size );
  52 &ex_end
  53 &uindent
  54
  55 &h2(DESCRIPTION)
  56 The &cw(rmr_alloc_msg) function is used to allocate a buffer which the user
  57 programme can write into and then send through the RMR library.
  58 The buffer is allocated such that sending it requires no additional copying
  59 out of the buffer.
  60 If the value passed in &cw(size) is 0, then the default size supplied on the
  61 &ital(rmr_init) call will be used.
  62 The &ital(a) parameter is the void context pointer that was returned by
  63 the &ital(rmr_init) function.
  64
  65 &space
  66 The pointer to the message buffer returned is a structure which has some
  67 user application visible fields; the structure is described in &cw(rmr.h,)
  68 and is illustrated below.
  69
  70 &space
  71 &ex_start
  72 typedef struct {
  73     int state;
  74     int mtype;
  75     int len;
  76     unsigned char* payload;
  77     unsigned char* a;
  78 } rmr_mbuf_t;
  79 &ex_end
  80
  81 &space
  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(RMR_OK) the buffer represents an empty buffer that the application
  89 may fill in in preparation to send.
  90
  91 &half_space
  92 &ditem(mtype )  When sending a message, the application is expected to set this field
  93 to the appropriate message type value (as determined by the user programme). Upon send
  94 this value determines how the RMR library will route the message.
  95 For a buffer which has been received, this field will contain the message type that was
  96 set by the sending application.
  97
  98 &half_space
  99 &ditem(len ) The application using a buffer to send a message is expected to set the
 100 length value to the actual number of bytes that it placed into the message. This
 101 is likely less than the total number of bytes that the message can carry.
 102 For a message buffer that is passed to the application as the result of a receive
 103 call, this will be the value that the sending application supplied and should
 104 indicate the number of bytes in the payload which are valid.
 105
 106 &half_space
 107 &ditem(payload ) The payload is a pointer to the actual received data.  The
 108 user programme may read and write from/to the memory referenced by the payload
 109 up until the point in time that the buffer is used on a &cw(rmr_send, rmr_call)
 110 or &cw(rmr_reply) function call.
 111 Once the buffer has been passed back to a RMR library function the user programme
 112 should &bold(NOT) make use of the payload pointer.
 113
 114
 115 &half_space
 116 &ditem(a ) The &ital(a) field is a pointer to a fixed sized area in
 117 the message into which the user may write a transaction ID.
 118 The ID is optional with the exception of when the user application uses the &cw(rmr_call)
 119 function to send a message and wait for the reply; the underlying RMR processing
 120 expects that the matching reply message will also contain the same data in the
 121 &ital(a) field.
 122 &end_dlist
 123
 124 &h2(RETURN VALUE)
 125 The function returns a pointer to a &cw(rmr_mbuf) structure, or NULL on error.
 126
 127 &h2(ERRORS)
 128 &beg_dlist(.75i : ^&bold_font )
 129 &di(ENOMEM) Unable to allocate memory.
 130 &end_dlist
 131
 132 .** &h2(EXAMPLE)
 133
 134 &h2(SEE ALSO )
 135 rmr_mbuf(3)
 136 rmr_call(3),
 137 rmr_free_msg(3),
 138 rmr_init(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
 151
 152 .qu
 153