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 ==================================================================================
22 Mnemonic rmr_realloc_payload.3.xfm
23 Abstract The manual page for the rmr_realloc_payload function.
24 Author E. Scott Daniels
29 .im &{lib}/man/setup.im
33 &h1(RMR Library Functions)
42 extern rmr_mbuf_t* rmr_realloc_payload( rmr_mbuf_t* msg, int new_len, int copy, int clone );
47 The &cw(rmr_realloc_payload) function will return a pointer to an RMR message
48 buffer struct (rmr_mbuf_t) which has a payload large enough to accomodate &ital(new_len)
50 If necessary, the underlying payload is reallocated, and the bytes from the original
51 payload are copied if the &ital(copy) parameter is true (1).
52 If the message passed in has a payload large enough, there is no additional
53 memory allocation and copying.
55 &h3(Cloning The Message Buffer)
56 This function can also be used to generate a separate copy of the original message,
57 with the desired payload size, without destroying the original message buffer or the
59 A standalone copy is made only when the &ital(clone) parameter is true (1).
60 When cloning, the payload is copied to the cloned message &bold(only) if the &ital(copy)
63 &h3(Message Buffer Metadata)
64 The metadata in the original message buffer (message type, subscription ID, and payload
65 length) will be preserved if the &ital(copy) parameter is true.
66 When this parameter is not true (0), then these values are set to the
67 uninitialised value (-1) for type and ID, and the length is set to 0.
70 The &cw(rmr_realloc_payload) function returns a pointer to the message buffer with the
71 payload which is large enough to hold &ital(new_len) bytes.
72 If the &ital(clone) option is true, this will be a pointer to the newly cloned
73 message buffer; the original message buffer pointer may still be used to referenced
75 It is the calling application's responsibility to free the memory associateed with
76 both messages using the rmr_free_msg() function.
79 When the &ital(clone) option is not used, it is still good practice by the calling
80 application to capture and use this reference as it is possible that the message
81 buffer, and not just the payload buffer, was reallocated.
83 In the event of an error, a nil pointer will be returned and the value of &ital(errno)
84 will be set to reflect the problem.
87 These value of &ital(errno) will reflect the error condition if a nil pointer is returned:
90 &beg_dlist(.75i : ^&bold_font )
91 &di(ENOMEM) Memory allocation of the new payload failed.
94 &di(EINVAL) The pointer passed in was nil, or refrenced an invalid message, or the required
100 The following code bit illustrates how this function can be used to
101 reallocate a buffer for a return to sender acknowledgement message which
102 is larger than the message received.
106 if( rmr_payload_size( msg ) < ack_sz ) { // received message too small for ack
107 msg = rmr_realloc_payload( msg, ack_sz, 0, 0 ); // reallocate the message with a payload big enough
109 fprintf( stderr, "[ERR] realloc returned a nil pointer: %s\n", strerror( errno ) );
111 // populate and send ack message