pespin has submitted this change. ( https://gerrit.osmocom.org/c/libosmo-netif/+/39413?usp=email )
Change subject: stream: osmo_stream_{cli,srv}_set_segmentation_cb(2): documentation improvements ......................................................................
stream: osmo_stream_{cli,srv}_set_segmentation_cb(2): documentation improvements
* Wrap lines to a shorter width * Improve osmo_stream_cli_set_segmentation_cb() adding text available in osmo_stream_srv_set_segmentation_cb() * Refer to segmentation_cb in segmentation_cb2 documentation and only outline the differences.
Change-Id: I55eb9a7781c22db68446265d2a174ae4f5e9f6ef --- M src/stream_cli.c M src/stream_srv.c 2 files changed, 21 insertions(+), 14 deletions(-)
Approvals: osmith: Looks good to me, approved fixeria: Looks good to me, but someone else must approve Jenkins Builder: Verified
diff --git a/src/stream_cli.c b/src/stream_cli.c index 6628ad7..fa3ac76 100644 --- a/src/stream_cli.c +++ b/src/stream_cli.c @@ -821,6 +821,11 @@ * \param[in,out] cli Stream Client to modify * \param[in] segmentation_cb Target segmentation callback * + * A segmentation call-back can optionally be used when a packet based protocol + * (like TCP) is used within a STREAM style socket that does not preserve + * message boundaries within the stream. If a segmentation call-back is given, + * the osmo_stream_srv library code will makes sure that the read_cb called + * only for complete single messages, and not arbitrary segments of the stream. */ void osmo_stream_cli_set_segmentation_cb(struct osmo_stream_cli *cli, osmo_stream_cli_segmentation_cb_t segmentation_cb) @@ -834,6 +839,10 @@ /*! Set the segmentation callback for the client. * \param[in,out] cli Stream Client to modify * \param[in] segmentation_cb2 Target segmentation callback + * + * Same as osmo_stream_cli_set_segmentation_cb(), but a + * osmo_stream_cli_segmentation_cb2_t is called instead which allows access to + * the related cli object. */ void osmo_stream_cli_set_segmentation_cb2(struct osmo_stream_cli *cli, osmo_stream_cli_segmentation_cb2_t segmentation_cb2) diff --git a/src/stream_srv.c b/src/stream_srv.c index 05f780c..366fe64 100644 --- a/src/stream_srv.c +++ b/src/stream_srv.c @@ -1104,13 +1104,15 @@ * \param[in,out] conn Target Stream Server to modify * \param[in] segmentation_cb Segmentation callback to be set * - * A segmentation call-back can optionally be used when a packet based protocol (like TCP) is used within a - * STREAM style socket that does not preserve message boundaries within the stream. If a segmentation - * call-back is given, the osmo_stream_srv library code will makes sure that the read_cb called only for - * complete single messages, and not arbitrary segments of the stream. + * A segmentation call-back can optionally be used when a packet based protocol + * (like TCP) is used within a STREAM style socket that does not preserve + * message boundaries within the stream. If a segmentation call-back is given, + * the osmo_stream_srv library code will makes sure that the read_cb called + * only for complete single messages, and not arbitrary segments of the stream. * - * This function only works with osmo_stream_srv in osmo_io mode, created by osmo_stream_srv_create2()! - * The connection has to have been established prior to calling this function. + * This function only works with osmo_stream_srv in osmo_io mode, created by + * osmo_stream_srv_create2()! The connection has to have been established prior + * to calling this function. * */ void osmo_stream_srv_set_segmentation_cb(struct osmo_stream_srv *conn, @@ -1128,16 +1130,12 @@ * \param[in,out] conn Target Stream Server to modify * \param[in] segmentation_cb2 Segmentation callback to be set * - * A segmentation call-back can optionally be used when a packet based protocol (like TCP) is used within a - * STREAM style socket that does not preserve message boundaries within the stream. If a segmentation - * call-back is given, the osmo_stream_srv library code will makes sure that the read_cb called only for - * complete single messages, and not arbitrary segments of the stream. - * - * This function only works with osmo_stream_srv in osmo_io mode, created by osmo_stream_srv_create2()! - * The connection has to have been established prior to calling this function. + * Same as osmo_stream_srv_set_segmentation_cb(), but a + * osmo_stream_srv_segmentation_cb2_t is called instead which allows access to + * the related conn object. */ void osmo_stream_srv_set_segmentation_cb2(struct osmo_stream_srv *conn, - osmo_stream_srv_segmentation_cb2_t segmentation_cb2) + osmo_stream_srv_segmentation_cb2_t segmentation_cb2) { /* Note that the following implies that iofd != NULL, since * osmo_stream_srv_create2() creates the iofd member, too */