Change in libosmocore[master]: ipa: Document ipa_msg_recv* functions

[Harald Welte]

Harald Welte has submitted this change and it was merged. ( https://gerrit.osmocom.org/10569 )

Change subject: ipa: Document ipa_msg_recv* functions
......................................................................

ipa: Document ipa_msg_recv* functions

Change-Id: Ie81e9dd9f9936a414e7cebb2bccffa6f42a302a7
---
M src/gsm/ipa.c
1 file changed, 22 insertions(+), 0 deletions(-)

Approvals:
  Harald Welte: Looks good to me, approved
  Jenkins Builder: Verified



diff --git a/src/gsm/ipa.c b/src/gsm/ipa.c
index 508cc13..d423c26 100644
--- a/src/gsm/ipa.c
+++ b/src/gsm/ipa.c
@@ -528,6 +528,9 @@
 #ifdef HAVE_SYS_SOCKET_H
 #include <sys/socket.h>
 
+/*! Read one ipa message from socket fd without caching not fully received
+ * messages. See \ref ipa_msg_recv_buffered for further information.
+ */
 int ipa_msg_recv(int fd, struct msgb **rmsg)
 {
 	int rc = ipa_msg_recv_buffered(fd, rmsg, NULL);
@@ -538,6 +541,25 @@
 	return rc;
 }
 
+/*! Read one ipa message from socket fd or store part if still not fully received.
+ *  \param[in] fd The fd for the socket to read from.
+ *  \param[out] rmsg internally allocated msgb containing a fully received ipa message.
+ *  \param[inout] tmp_msg internally allocated msgb caching data for not yet fully received message.
+ *
+ *  As ipa can run on top of stream based protocols such as TCP, there's the
+ *  possibility that such lower layers split ipa messages in several low level
+ *  packets. If a low layer packet is received containing several ipa frames,
+ *  this function will pull from the socket and return only the first one
+ *  available in the stream. As the socket will remain with data, it will
+ *  trigger again during next select() and then this function will fetch the
+ *  next ipa message, and so on.
+ *
+ *  \returns -EAGAIN and allocated tmp_msg if message was not yet fully
+ *  received. Other negative values indicate an error and cached msgb will be
+ *  freed. 0 if socket is found dead. Positive value indicating l2 msgb len and
+ *  rmsg pointing to internally allocated msgb containing the ipa frame on
+ *  scucess.
+ */
 int ipa_msg_recv_buffered(int fd, struct msgb **rmsg, struct msgb **tmp_msg)
 {
 	struct msgb *msg = tmp_msg ? *tmp_msg : NULL;

-- 
To view, visit https://gerrit.osmocom.org/10569
To unsubscribe, or for help writing mail filters, visit https://gerrit.osmocom.org/settings

Gerrit-Project: libosmocore
Gerrit-Branch: master
Gerrit-MessageType: merged
Gerrit-Change-Id: Ie81e9dd9f9936a414e7cebb2bccffa6f42a302a7
Gerrit-Change-Number: 10569
Gerrit-PatchSet: 2
Gerrit-Owner: Pau Espin Pedrol <pespin at sysmocom.de>
Gerrit-Reviewer: Harald Welte <laforge at gnumonks.org>
Gerrit-Reviewer: Jenkins Builder (1000002)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osmocom.org/pipermail/gerrit-log/attachments/20180822/6942adea/attachment.htm>