.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_torcv_msg_man.xfm
    Abstract    The manual page for the rmr_torcv_msg function.
    Author      E. Scott Daniels
    Date        29 January 2019
.fi

.gv e LIB lib
.im &{lib}/man/setup.im

&line_len(6i)

&h1(RMR Library Functions)
&h2(NAME)
    rmr_torcv_msg

&h2(SYNOPSIS )
&indent
&ex_start
#include <rmr/rmr.h>

rmr_mbuf_t* rmr_torcv_msg( void* vctx, rmr_mbuf_t* old_msg, int ms_to );
&ex_end
&uindent

&h2(DESCRIPTION)
The &cw(rmr_torcv_msg) function will pause for &ital(ms_to) milliseconds waiting
for a message to arrive.
If a message arrives before the timeout expires the message buffer returned
will have a status of RMR_OK and the payload will contain the data received.
If the timeout expires before the message is received, the status will
have the value RMR_ERR_TIMEOUT.
When a received message is returned the message buffer will also contain the
message type and length set by the sender.
If messages were queued while waiting for the response to a previous invocation
of &cw(rmr_call,)  the oldest message is removed from the queue and returned
without delay.

&space
The &ital(vctx) pointer is the pointer returned by the &cw(rmr_init) function.
&ital(Old_msg) is a pointer to a previously used message buffer or NULL.
The ability to reuse message buffers helps to avoid alloc/free cycles in the
user application.
When no buffer is available to supply, the receive function will allocate one.

&h2(RETURN VALUE)
The function returns a pointer to the &cw(rmr_mbuf_t) structure which references
the message information (state, length, payload), or a nil pointer in the case
of an extreme error.

&h2(ERRORS)
The &ital(state) field in the message buffer will be one of the following:
&space
&beg_dlist(.75i : ^&bold_font )
&di(RMR_OK) The message buffer (payload) references the received data.

&space
&di(RMR_ERR_INITFAILED) The first call to this function must initialise an underlying
    system notification mechanism. On failure, this error is returned and errno
    will have the system error status set.  If this function fails to intialise,
    the poll mechansim, it is likely that message receives will never be successful.

&space
&di(RMR_ERR_TIMEOUT) The timeout expired before a complete message was received.
    All other fields in the message buffer are not valid.

&space
&di(RMR_ERR_EMPTY) A message was received, but it had no payload. All other
    fields in the message buffer are not valid.
&end_dlist
&space

&beg_dlist(.75i : ^&bold_font )
&di(INVAL) Parameter(s) passed to the function were not valid.

&half_space
&di(EBADF) The underlying message transport is unable to process the request.

&half_space
&di(ENOTSUP) The underlying message transport is unable to process the request.

&half_space
&di(EFSM) The underlying message transport is unable to process the request.

&half_space
&di(EAGAIN) The underlying message transport is unable to process the request.

&half_space
&di(EINTR) The underlying message transport is unable to process the request.

&half_space
&di(ETIMEDOUT) The underlying message transport is unable to process the request.

&half_space
&di(ETERM) The underlying message transport is unable to process the request.
&end_dlist

&h2(EXAMPLE)

&h2(SEE ALSO )
.ju off
rmr_alloc_msg(3),
rmr_call(3),
rmr_free_msg(3),
rmr_get_rcvfd(3),
rmr_init(3),
rmr_payload_size(3),
rmr_rcv_msg(3),
rmr_send_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)
.ju on