2 ==================================================================================
3 Copyright (c) 2019 Nokia
4 Copyright (c) 2018-2019 AT&T Intellectual Property.
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
10 http://www.apache.org/licenses/LICENSE-2.0
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 ==================================================================================
20 Mnemonic rmr_torcv_msg_man.xfm
21 Abstract The manual page for the rmr_torcv_msg function.
22 Author E. Scott Daniels
27 .im &{lib}/man/setup.im
31 &h1(RMR Library Functions)
40 rmr_mbuf_t* rmr_torcv_msg( void* vctx, rmr_mbuf_t* old_msg, int ms_to );
45 The &cw(rmr_torcv_msg) function will pause for &ital(ms_to) milliseconds waiting
46 for a message to arrive.
47 If a message arrives before the timeout expires the message buffer returned
48 will have a status of RMR_OK and the payload will contain the data received.
49 If the timeout expires before the message is received, the status will
50 have the value RMR_ERR_TIMEOUT.
51 When a received message is returned the message buffer will also contain the
52 message type and length set by the sender.
53 If messages were queued while waiting for the response to a previous invocation
54 of &cw(rmr_call,) the oldest message is removed from the queue and returned
58 The &ital(vctx) pointer is the pointer returned by the &cw(rmr_init) function.
59 &ital(Old_msg) is a pointer to a previously used message buffer or NULL.
60 The ability to reuse message buffers helps to avoid alloc/free cycles in the
62 When no buffer is available to supply, the receive function will allocate one.
65 The function returns a pointer to the &cw(rmr_mbuf_t) structure which references
66 the message information (state, length, payload), or a NULL pointer in the case
70 The &ital(state) field in the message buffer will be one of the following:
72 &beg_dlist(.75i : ^&bold_font )
73 &di(RMR_OK) The message buffer (payload) references the received data.
76 &di(RMR_ERR_TIMEOUT) The timeout expired before a complete message was received.
77 All other fields in the message buffer are not valid.
80 &di(RMR_ERR_EMPTY) A message was received, but it had no payload. All other
81 fields in the message buffer are not valid.
85 &beg_dlist(.75i : ^&bold_font )
86 &di(INVAL) Parameter(s) passed to the function were not valid.
89 &di(EBADF) The underlying message transport is unable to process the request.
92 &di(ENOTSUP) The underlying message transport is unable to process the request.
95 &di(EFSM) The underlying message transport is unable to process the request.
98 &di(EAGAIN) The underlying message transport is unable to process the request.
101 &di(EINTR) The underlying message transport is unable to process the request.
104 &di(ETIMEDOUT) The underlying message transport is unable to process the request.
107 &di(ETERM) The underlying message transport is unable to process the request.