--- /dev/null
+.if false
+==================================================================================
+ Copyright (c) 2019 Nokia
+ Copyright (c) 2018-2019 AT&T Intellectual Property.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+==================================================================================
+.fi
+.if false
+ Mnemonic rmr_alloc_msg.xfm
+ Abstract The manual page for the rmr_alloc_msg function.
+ Author E. Scott Daniels
+ Date 28 January 2019
+.fi
+
+.** if formatting with tfm, the roff.im will cause roff output to be generated
+.** if formatting with pfm, then pretty postscript will be generated
+.gv e LIB lib
+.if pfm
+ .im &{lib}/generic_ps.im
+.ei
+ .gv e OUTPUT_RST use_rst
+ .if .ev &use_rst 1 =
+ .im &{lib}/rst.im
+ .ei
+ .im &{lib}/roff.im
+ .fi
+.fi
+
+&line_len(6i)
+
+&h1(RMR Library Functions)
+&h2(NAME)
+ rmr_alloc_msg
+
+&h2(SYNOPSIS )
+&indent
+&ex_start
+#include <rmr/rmr.h>
+
+rmr_mbuf_t* rmr_alloc_msg( void* a, int size );
+&ex_end
+&uindent
+
+&h2(DESCRIPTION)
+The &cw(rmr_alloc_msg) function is used to allocate a buffer which the user
+programme can write into and then send through the RMR library.
+The buffer is allocated such that sending it requires no additional copying
+out of the buffer.
+If the value passed in &cw(size) is 0, then the default size supplied on the
+&ital(rmr_init) call will be used.
+The &ital(a) parameter is the void context pointer that was returned by
+the &ital(rmr_init) function.
+
+&space
+The pointer to the message buffer returned is a structure which has some
+user application visible fields; the structure is described in &cw(rmr.h,)
+and is illustrated below.
+
+&space
+&ex_start
+typedef struct {
+ int state;
+ int mtype;
+ int len;
+ unsigned char* payload;
+ unsigned char* a;
+} rmr_mbuf_t;
+&ex_end
+
+&space
+&beg_dlist(.75i : ^&bold_font )
+&ditem(state ) Is the current buffer state. Following a call to &cw(rmr_send_msg)
+the state indicates whether the buffer was successfully sent which determines
+exactly what the payload points to. If the send failed, the payload referenced
+by the buffer is the message that failed to send (allowing the application to
+attempt a retransmission).
+When the state is &cw(RMR_OK) the buffer represents an empty buffer that the application
+may fill in in preparation to send.
+
+&half_space
+&ditem(mtype ) When sending a message, the application is expected to set this field
+to the appropriate message type value (as determined by the user programme). Upon send
+this value determines how the RMR library will route the message.
+For a buffer which has been received, this field will contain the message type that was
+set by the sending application.
+
+&half_space
+&ditem(len ) The application using a buffer to send a message is expected to set the
+length value to the actual number of bytes that it placed into the message. This
+is likely less than the total number of bytes that the message can carry.
+For a message buffer that is passed to the application as the result of a receive
+call, this will be the value that the sending application supplied and should
+indicate the number of bytes in the payload which are valid.
+
+&half_space
+&ditem(payload ) The payload is a pointer to the actual received data. The
+user programme may read and write from/to the memory referenced by the payload
+up until the point in time that the buffer is used on a &cw(rmr_send, rmr_call)
+or &cw(rmr_reply) function call.
+Once the buffer has been passed back to a RMR library function the user programme
+should &bold(NOT) make use of the payload pointer.
+
+
+&half_space
+&ditem(a ) The &ital(a) field is a pointer to a fixed sized area in
+the message into which the user may write a transaction ID.
+The ID is optional with the exception of when the user application uses the &cw(rmr_call)
+function to send a message and wait for the reply; the underlying RMR processing
+expects that the matching reply message will also contain the same data in the
+&ital(a) field.
+&end_dlist
+
+&h2(RETURN VALUE)
+The function returns a pointer to a &cw(rmr_mbuf) structure, or NULL on error.
+
+&h2(ERRORS)
+&beg_dlist(.75i : ^&bold_font )
+&di(ENOMEM) Unable to allocate memory.
+&end_dlist
+
+.** &h2(EXAMPLE)
+
+&h2(SEE ALSO )
+rmr_mbuf(3)
+rmr_call(3),
+rmr_free_msg(3),
+rmr_init(3),
+rmr_payload_size(3),
+rmr_send_msg(3),
+rmr_rcv_msg(3),
+rmr_rcv_specific(3),
+rmr_rts_msg(3),
+rmr_ready(3),
+rmr_fib(3),
+rmr_has_str(3),
+rmr_tokenise(3),
+rmr_mk_ring(3),
+rmr_ring_free(3)
+
+
+.qu
+
Code Review / ric-plt / lib / rmr.git / blobdiff