From 7b40db442c2fccaa484c6162b238b4e707e8733e Mon Sep 17 00:00:00 2001
From: Linus Nordberg <linus@nordberg.se>
Date: Tue, 29 Jan 2013 15:27:26 +0100
Subject: Improve documentation.
---
lib/include/radsec/radsec.h | 21 +++++++++++++--------
1 file changed, 13 insertions(+), 8 deletions(-)
(limited to 'lib/include')
diff --git a/lib/include/radsec/radsec.h b/lib/include/radsec/radsec.h
index 7bd7f10..fb2aea9 100644
--- a/lib/include/radsec/radsec.h
+++ b/lib/include/radsec/radsec.h
@@ -296,16 +296,21 @@ int rs_packet_create(struct rs_connection *conn, struct rs_packet **pkt_out);
/** Free all memory allocated for packet \a pkt. */
void rs_packet_destroy(struct rs_packet *pkt);
-/** Send packet \a pkt on the connection associated with \a pkt. \a
- user_data is sent to the \a rs_conn_packet_received_cb callback
- registered with the connection. If no callback is registered with
+/** Send packet \a pkt on the connection associated with \a pkt.
+ \a user_data is passed to the \a rs_conn_packet_received_cb callback
+ registered with the connection. If no callback is registered with
the connection, the event loop is run by \a rs_packet_send and it
- blocks until the packet has been succesfully sent.
-
- \return On success, RSE_OK (0) is returned. On error, !0 is
+ blocks until the full packet has been sent. Note that sending can
+ fail in several ways, f.ex. if the transmission protocol in use
+ is connection oriented (\a RS_CONN_TYPE_TCP and \a RS_CONN_TYPE_TLS)
+ and the connection can not be established. Also note that no
+ retransmission is done, something that is required for connectionless
+ transport protocols (\a RS_CONN_TYPE_UDP and \a RS_CONN_TYPE_DTLS).
+ The "request" API with \a rs_request_send can help with this.
+
+ \return On success, RSE_OK (0) is returned. On error, !0 is
returned and a struct \a rs_error is pushed on the error stack for
- the connection. The error can be accessed using \a
- rs_err_conn_pop. */
+ the connection. The error can be accessed using \a rs_err_conn_pop. */
int rs_packet_send(struct rs_packet *pkt, void *user_data);
/** Create a RADIUS authentication request packet associated with
--
cgit v1.1