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
   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
 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.
 
 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
 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"
 
 
 =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
 
 
 =head1 ERROR HANDLING
 


@@ -187,6 +231,6 @@ applicable.
 =head1 AUTHOR
 
 librouteros is written by Florian octo Forster E<lt>octo at verplant.orgE<gt>.
 =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.
 
 (c) 2009 by Florian octo Forster.