librouteros(3): Added documentation for "system resource".

[routeros-api.git] / doc / librouteros.pod

diff --git a/doc/librouteros.pod b/doc/librouteros.pod
index d1ea98b..74f1863 100644 (file)
--- 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
@@ -163,7 +168,46 @@ when the callback returns.
 
 =head2 High level interface functions for "registration-table"
 
-B<TODO>: Describe the registration-table interface.
+This high level interface makes it easy to access the "registration table",
+which holds active wireless lan connections. The data returned is equivalent to
+running C</interface/wireless/registration-table/print>. The parsed data is
+passed to a callback function in form of a B<ros_registration_table_t>
+structure.
+
+The query function has the following prototype:
+
+ int ros_registration_table (ros_connection_t *c,
+     ros_registration_table_handler_t handler, void *user_data);
+
+I<c> is the usual connection ocject. I<handler> is a pointer to a function with
+the following prototype:
+
+ int callback (ros_connection_t *c,
+     const ros_registration_table_t *r, void *user_data);
+
+The usual semantics apply: You may not alter I<r> and the memory pointed to by
+I<r> is freed after the callback returned.
+
+=head2 High level interface functions for "system resource"
+
+This high level interface makes it easy to access several system related
+metrics, such as memory and disk space used. The data returned is equivalent to
+running C</system/resource/print>. The parsed data is passed to a callback
+function in form of a B<ros_system_resource_t> structure.
+
+The query function has the following prototype:
+
+ int ros_system_resource (ros_connection_t *c,
+     ros_system_resource_handler_t handler, void *user_data);
+
+I<c> is the usual connection ocject. I<handler> is a pointer to a function with
+the following prototype:
+
+ int callback (ros_connection_t *c,
+     const ros_system_resource_t *r, void *user_data);
+
+The usual semantics apply: You may not alter I<r> and the memory pointed to by
+I<r> is freed after the callback returned.
 
 =head1 ERROR HANDLING
 
@@ -187,6 +231,6 @@ applicable.
 =head1 AUTHOR
 
 librouteros is written by Florian octo Forster E<lt>octo at verplant.orgE<gt>.
-It's homepage can be found at L<http://verplant.org/librouteros/>.
+Its homepage can be found at L<http://verplant.org/librouteros/>.
 
 (c) 2009 by Florian octo Forster.