3 ==================================================================================
4 Copyright (c) 2019 Nokia
5 Copyright (c) 2018-2019 AT&T Intellectual Property.
7 Licensed under the Apache License, Version 2.0 (the "License");
8 you may not use this file except in compliance with the License.
9 You may obtain a copy of the License at
11 http://www.apache.org/licenses/LICENSE-2.0
13 Unless required by applicable law or agreed to in writing, software
14 distributed under the License is distributed on an "AS IS" BASIS,
15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 See the License for the specific language governing permissions and
17 limitations under the License.
18 ==================================================================================
21 &h1(Appendix &mbuf_appendix -- Message Buffer Details)
23 The RMR message buffer is a C structure which is exposed in the &cw(rmr.h)
25 It is used to manage a message received from a peer endpoint, or a message
26 that is being sent to a peer.
27 Fields include payload length, amount of payload actually used, status,
28 and a reference to the payload.
29 There are also fields which the application should ignore, and could be
30 hidden in the header file, but we chose not to. These fields include
31 a reference to the RMR header information, and to the underlying transport
32 mechanism message struct which may or may not be the same as the RMR
36 The following is the C structure.
37 Readers are cautioned to examine the header file directly; the information
38 here may be out of date (old document in some cache), and thus it may
46 int state; // state of processing
47 int mtype; // message type
48 int len; // length of data in the payload (send or received)
49 unsigned char* payload; // transported data
50 unsigned char* xaction; // pointer to fixed length transaction id bytes
51 int sub_id; // subscription id
52 int tp_state; // transport state (errno)
54 // these things are off limits to the user application
55 void* tp_buf; // underlying transport allocated pointer (e.g. nng message)
56 void* header; // internal message header (whole buffer: header+payload)
57 unsigned char* id; // if we need an ID in the message separate from the xaction id
58 int flags; // various MFL_ (private) flags as needed
59 int alloc_len; // the length of the allocated space (hdr+payload)
65 &h2(State vs Transport State)
66 The state field reflects the state at the time the message buffer is returned to the
68 For a send operation, if the state is not &cw(RMR_OK) then the message buffer references
69 the payload that could not be sent, and when the state is &cw(RMR_OK) the buffer
70 references a &ital(fresh) payload that the application may fill in.
73 When the state is not &cw(RMR_OK,) C programmes may examine the global &cw(errno) value
74 which RMR will have left set, if it was set, by the underlying transport mechanism.
75 In some cases, wrapper modules are not able to directly access the C-library &cw(errno)
76 value, and to assist with possible transport error details, the send and receive
77 operations populate &cw(tp_state) with the value of &cw(errno.)
80 Regardless of whether the application makes use of the &cw(tp_state,) or the &cw(errno)
81 value, it should be noted that the underlying transport mechanism may not actually update
82 the errno value; in other words: it might not be accurate.
83 In addition, RMR populates the &cw(tp_state) value in the message buffer &bold(only) when
84 the state is not &cw(RMR_OK.)
87 The transaction field was exposed in the first version of RMR, and in hindsight this
88 shouldn't have been done.
89 Rather than break any existing code the reference was left, but additional fields
90 such as trace data, were not directly exposed to the application.
91 The application developer is strongly encouraged to use the functions which get and
92 set the transaction ID rather than using the pointer directly; any data overruns will
93 not be detected if the reference is used directly.
96 In contrast, the payload reference should be used directly by the application in the
97 interest of speed and ease of programming.
98 The same care to prevent writing more bytes to the payload buffer than it can hold
99 must be taken by the application.
100 By the nature of the allocation of the payload in transport space, RMR is unable to
101 add guard bytes and/or test for data overrun.
103 &h2(Actual Transmission)
104 When RMR sends the application's message, the message buffer is &bold(not) transmitted.
105 The transport buffer (tp_buf) which contains the RMR header and application payload
106 is the only set of bytes which are transmitted.
107 While it may seem to the caller like the function &func(rmr_send_msg) is returning a
108 new message buffer, the same struct is reused and only a new transport buffer is allocated.
109 The intent is to keep the alloc/free cycles to a minimum.