From: Vincent Bernat <vincent@bernat.ch>
Date: Thu, 23 Apr 2020 19:27:23 +0000 (+0200)
Subject: lib: emphasize `conn` cannot be used after lldpctl_watch_callback()
X-Git-Tag: 1.0.6~20^2~2
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=c0363157dc48a1da273261ecbf24792d9dfe9725;p=thirdparty%2Flldpd.git

lib: emphasize `conn` cannot be used after lldpctl_watch_callback()
---

diff --git a/src/lib/lldpctl.h b/src/lib/lldpctl.h
index 5e676e94..c9f4d474 100644
--- a/src/lib/lldpctl.h
+++ b/src/lib/lldpctl.h
@@ -460,7 +460,7 @@ typedef enum {
 /**
  * Callback function invoked when a change is detected.
  *
- * @param conn      Connection with lldpd.
+ * @param conn      Connection with lldpd. Should not be used.
  * @param type      Type of change detected.
  * @param interface Physical interface on which the change has happened.
  * @param neighbor  Changed neighbor.
@@ -470,6 +470,9 @@ typedef enum {
  * reference count are decremented when the callback ends. If you want to keep a
  * reference to it, be sure to increment the reference count in the callback.
  *
+ * @warning The provided connection should not be used at all. Do not use @c
+ * lldpctl_atom_set_*() functions on @c interface or @c neighbor either.
+ *
  * @see lldpctl_watch_callback
  */
 typedef void (*lldpctl_change_callback)(lldpctl_conn_t *conn,
@@ -490,8 +493,8 @@ typedef void (*lldpctl_change_callback)(lldpctl_conn_t *conn,
  * and therefore will issue IO operations. The error code could then be @c
  * LLDPCTL_ERR_WOULDBLOCK.
  *
- * Once a callback is registered, the connection shouldn't be used for anything
- * else than receiving notifications.
+ * @warning Once a callback is registered, the connection shouldn't be used for
+ * anything else than receiving notifications.
  */
 int lldpctl_watch_callback(lldpctl_conn_t *conn,
     lldpctl_change_callback cb,