From: Florian Forster <octo@leeloo.lan.home.verplant.org>
Date: Fri, 27 Nov 2009 08:07:04 +0000 (+0100)
Subject: librouteros(3): Added some details about the semantic of callbacks.
X-Git-Tag: librouteros-0.2.0~8
X-Git-Url: https://git.verplant.org/?a=commitdiff_plain;h=7d47df8425792ff76e469259242c0d57011bc244;p=routeros-api.git

librouteros(3): Added some details about the semantic of callbacks.
---

diff --git a/doc/librouteros.pod b/doc/librouteros.pod
index 9e083a7..8a98f87 100644
--- a/doc/librouteros.pod
+++ b/doc/librouteros.pod
@@ -67,7 +67,8 @@ called B<ros_reply_handler_t>:
   int callback (ros_connection_t *c, const ros_reply_t *r, void *user_data);
 
 The reply is broken into parts (or "sentences") and passed to the callback
-function as a linked list of type B<ros_reply_t>. The callback uses a couple of
+function as a linked list of type B<ros_reply_t>. It is only called once for
+query and must traverse the linked list itself. The callback uses a couple of
 helper functions to iterate over this list and fetch parameters as necessary.
 
 The first and second arguments are objects representing the connection and the
@@ -80,6 +81,10 @@ The value returned by the callback function will be returned by B<ros_query> to
 the calling code. To distinguish from error codes returned by B<ros_query> upon
 errors, use negative values in the callback function.
 
+Because the entire reply is read back from the connection before the callback
+function is called, it is legal for the callback function to send out another
+query.
+
 General queries / replies are handled using the following functions:
 
 =over 4