.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_mbuf_t* rmr_alloc_msg( void* ctx, 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(ctx) 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* xaction; } 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(xaction) The &ital(xaction) 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(xaction) 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_tralloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3), rmr_init_trace(3), rmr_get_trace(3), rmr_get_trlen(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), rmr_set_trace(3) .qu