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
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
30 .im &{lib}/generic_ps.im
32 .gv e OUTPUT_RST use_rst
42 &h1(RMR Library Functions)
51 rmr_mbuf_t* rmr_torcv_msg( void* vctx, rmr_mbuf_t* old_msg, int ms_to );
56 The &cw(rmr_torcv_msg) function will pause for &ital(ms_to) milliseconds waiting
57 for a message to arrive.
58 If a message arrives before the timeout expires the message buffer returned
59 will have a status of RMR_OK and the payload will contain the data received.
60 If the timeout expires before the message is received, the status will
61 have the value RMR_ERR_TIMEOUT.
62 When a received message is returned the message buffer will also contain the
63 message type and length set by the sender.
64 If messages were queued while waiting for the response to a previous invocation
65 of &cw(rmr_call,) the oldest message is removed from the queue and returned
69 The &ital(vctx) pointer is the pointer returned by the &cw(rmr_init) function.
70 &ital(Old_msg) is a pointer to a previously used message buffer or NULL.
71 The ability to reuse message buffers helps to avoid alloc/free cycles in the
73 When no buffer is available to supply, the receive function will allocate one.
76 The function returns a pointer to the &cw(rmr_mbuf_t) structure which references
77 the message information (state, length, payload), or a NULL pointer in the case
81 The &ital(state) field in the message buffer will be one of the following:
83 &beg_dlist(.75i : ^&bold_font )
84 &di(RMR_OK) The message buffer (payload) references the received data.
87 &di(RMR_ERR_TIMEOUT) The timeout expired before a complete message was received.
88 All other fields in the message buffer are not valid.
91 &di(RMR_ERR_EMPTY) A message was received, but it had no payload. All other
92 fields in the message buffer are not valid.
96 &beg_dlist(.75i : ^&bold_font )
97 &di(INVAL) Parameter(s) passed to the function were not valid.
100 &di(EBADF) The underlying message transport is unable to process the request.
103 &di(ENOTSUP) The underlying message transport is unable to process the request.
106 &di(EFSM) The underlying message transport is unable to process the request.
109 &di(EAGAIN) The underlying message transport is unable to process the request.
112 &di(EINTR) The underlying message transport is unable to process the request.
115 &di(ETIMEDOUT) The underlying message transport is unable to process the request.
118 &di(ETERM) The underlying message transport is unable to process the request.