From: Alan T. DeKok <aland@freeradius.org>
Date: Sun, 31 Mar 2024 15:57:26 +0000 (-0400)
Subject: add API documentation
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=c338727477c12443a15231f1bf9cff00392ee004;p=thirdparty%2Ffreeradius-server.git

add API documentation
---

diff --git a/src/lib/bio/packet.h b/src/lib/bio/packet.h
index ec0b537f87a..c1151a99c4a 100644
--- a/src/lib/bio/packet.h
+++ b/src/lib/bio/packet.h
@@ -76,11 +76,40 @@ struct fr_bio_packet_s {
 };
 
 
+/** Read a packet from a packet BIO
+ *
+ *  Note that the bio MAY return fr_bio_error(IO_WOULD_BLOCK), which is not a fatal error.  The caller has to
+ *  check for that case, and handle blocking errors.  Typically by pushing the packet to a queue, and trying
+ *  it again later.
+ *
+ * @param bio		the packet-based bio
+ * @param[out] request_ctx_p	the larger context for the original request packet
+ * @param[out] packet_p	Where the allocated #fr_packet_t will be stored
+ * @param[out_ctx]	for the output pairs
+ * @param[out]		decoded output pairs
+ * @return
+ *	- <0 on error.  This is fr_bio_error(FOO)
+ *	- 0 for success
+ */
 static inline CC_HINT(nonnull) int fr_bio_packet_read(fr_bio_packet_t *bio, void **request_ctx_p, fr_packet_t **packet_p, TALLOC_CTX *out_ctx, fr_pair_list_t *out)
 {
 	return bio->read(bio, request_ctx_p, packet_p, out_ctx, out);
 }
 
+/** Write a packet to a packet BIO
+ *
+ *  Note that the bio MAY return fr_bio_error(IO_WOULD_BLOCK), which is not a fatal error.  The caller has to
+ *  check for that case, and handle blocking errors.  Typically by pushing the packet to a queue, and trying
+ *  it again later.
+ *
+ * @param bio		the packet-based bio
+ * @param request_ctx	the larger context for the packet
+ * @param packet	the output packet descriptor.  Contains raw protocol data (IDs, counts, etc.)
+ * @param list		of pairs to write
+ * @return
+ *	- <0 on error.  This is fr_bio_error(FOO)
+ *	- 0 for success
+ */
 static inline CC_HINT(nonnull) int fr_bio_packet_write(fr_bio_packet_t *bio, void *request_ctx, fr_packet_t *packet, fr_pair_list_t *list)
 {
 	return bio->write(bio, request_ctx, packet, list);