doc/librouteros.pod

   1 =head1 NAME
   2
   3 librouteros - Library for accessing MikroTik's RouterOS via its API
   4
   5 =head1 DESCRIPTION
   6
   7 B<librouteros> is a library to communicate with I<RouterOS>, the operating
   8 system of I<MikroTik's> I<RouterBoards>. It uses the "API port" provided by
   9 those systems to connect and talk to the devices. librouteros is a low-level
  10 library in that it abstracts the network protocol used but has next to no
  11 knowledge about the commands and responses available. Should such an high-level
  12 interface prove useful, it will be added as the need arises.
  13
  14 =head1 GENERAL USAGE
  15
  16 The interface of librouteros is designed to be lightweight and simple to use.
  17 The first thing when using the library is to create a connection object. Once a
  18 connection has been established and logging in succeeded, queries can be sent
  19 to the remote device. The library will encode and send the request, read back a
  20 reply, decode it and pass it to a callback function. The callback function has
  21 access to the parsed reply and can easily access all parts and parameters. It
  22 does not need to worry about memory management because everything provided to
  23 it will be freed by the library before returning to where the query was called
  24 from. When the application is done talking to the device and disconnects, the
  25 connection object will be freed.
  26
  27 =head1 INTERFACES
  28
  29 =head2 Connection
  30
  31 The connection to a I<RouterOS> device is represented by a pointer to a
  32 B<ros_connection_t> type. This is an opaque data type which cannot be
  33 dereferenced or manipulated directly.
  34
  35 Connection management is done with the following functions:
  36
  37 =over 4
  38
  39 =item ros_connection_t *B<ros_connect> (const char *I<node>, const char *I<service>, const char *I<username>, const char *I<password>)
  40
  41 Connects to the remote device using I<node> as the address or hostname. If
  42 I<service> is C<NULL>, the standard port B<8728> will be used. When a
  43 connection has been established, the library will try to authenticate using
  44 I<username> and I<password>.
  45
  46 On failure, C<NULL> is returned and B<errno> is set appropriately.
  47
  48 =item int B<ros_disconnect> (ros_connection_t *I<c>)
  49
  50 Disconnects from the device and frees all memory associated with the
  51 connection. After this call, I<c> may not be used anymore.
  52
  53 Returns zero upon success and an error code otherwise.
  54
  55 =back
  56
  57 =head2 General / low level queries
  58
  59 This interface abstracts the network protocol only and leaves actually
  60 formulating queries and interpreting replies to the calling code. This is meant
  61 for queries and features for which no higher level interface exists.
  62
  63 The query is sent to the daemon using the B<ros_query> function. The reply is
  64 decoded and passed to a callback function with the following prototype, also
  65 called B<ros_reply_handler_t>:
  66
  67   int callback (ros_connection_t *c, const ros_reply_t *r, void *user_data);
  68
  69 The reply is broken into parts (or "sentences") and passed to the callback
  70 function as a linked list of type B<ros_reply_t>. It is only called once for
  71 query and must traverse the linked list itself. The callback uses a couple of
  72 helper functions to iterate over this list and fetch parameters as necessary.
  73
  74 The first and second arguments are objects representing the connection and the
  75 reply respectively. I<user_data> is a pointer as passed to B<ros_query> (see
  76 below). The arguments I<c> and I<r> may not be modified or freed. They will be
  77 freed after the function returns, so pointers to this data are invalid after
  78 this.
  79
  80 The value returned by the callback function will be returned by B<ros_query> to
  81 the calling code. To distinguish from error codes returned by B<ros_query> upon
  82 errors, use negative values in the callback function.
  83
  84 Because the entire reply is read back from the connection before the callback
  85 function is called, it is legal for the callback function to send out another
  86 query.
  87
  88 General queries / replies are handled using the following functions:
  89
  90 =over 4
  91
  92 =item int B<ros_query> (ros_connection_t *I<c>, const char *I<command>, size_t I<args_num>, const char * const *I<args>, ros_reply_handler_t I<handler>, void *I<user_data>)
  93
  94 Sends the command I<command> with the I<args_num> arguments I<args> via the
  95 connection I<c> and reads back the reply. The reply is parsed and passed to the
  96 callback function I<handler>. I<user_data> is a pointer passed through to the
  97 callback function. Please note that the callback function is called only once,
  98 even if the reply consists of multiple parts. Use the B<ros_reply_next>
  99 function (see below) to access the other parts.
 100
 101 Returns the value returned by the callback function upon success and an error
 102 code otherwise.
 103
 104 =item const ros_reply_t *B<ros_reply_next> (const ros_reply_t *I<r>)
 105
 106 Each reply can consist of several parts or "sentences". If there is more than
 107 one sentence returned by the device, this function will return the next part.
 108 When the end of the list is reached, C<NULL> is returned.
 109
 110 =item int B<ros_reply_num> (const ros_reply_t *I<r>)
 111
 112 Returns the number of replies in the list pointed to by and including I<r>.
 113
 114 =item const char *B<ros_reply_status> (const ros_reply_t *I<r>)
 115
 116 Returns the status message of this part or reply. This is usually "re" for data
 117 parts, "done" for the last part in a reply and "trap" for errors.
 118 The returned pointer must not be freed.
 119
 120 =item const char *B<ros_reply_param_key_by_index> (const ros_reply_t *I<r>, unsigned int I<index>)
 121
 122 Returns the parameter key at index I<index> (starting with zero) of reply I<r>.
 123 If I<index> is out of bounds, returns C<NULL>.
 124 The returned pointer must not be freed.
 125
 126 =item const char *B<ros_reply_param_val_by_index> (const ros_reply_t *I<r>, unsigned int I<index>)
 127
 128 Returns the parameter value at index I<index> (starting with zero) of reply
 129 I<r>. If I<index> is out of bounds, returns C<NULL>.
 130 The returned pointer must not be freed.
 131
 132 =item const char *B<ros_reply_param_val_by_key> (const ros_reply_t *I<r>, const char *I<key>)
 133
 134 Returns the parameter value corresponding to key I<key> (or C<NULL> if there is
 135 no such key) of reply I<r>.
 136 The returned pointer must not be freed.
 137
 138 =back
 139
 140 =head2 High level interface functions for "interface"
 141
 142 This function and the associated struct provide basic information about the
 143 device's interfaces in an easy and intuitive to use form. It is equivalent to
 144 issuing the C</interface/print> command. As with the generic interface above, a
 145 query function is called with a pointer to a callback function. That callback
 146 function is then called with a list of B<ros_interface_t> structures.
 147
 148 The query function has the following prototype:
 149
 150  int ros_interface (ros_connection_t *c,
 151      ros_interface_handler_t handler, void *user_data);
 152
 153 I<c> is a pointer to a connection object as returned by B<ros_connect>.
 154
 155 I<handler> is a function pointer to a callback function handling the result.
 156 The callback function must have the following prototype, called
 157 B<ros_interface_handler_t> for convenience:
 158
 159  int callback (ros_connection_t *c,
 160      const ros_interface_t *i, void *user_data);
 161
 162 The argument I<i> is a pointer to the first element of the list of interfaces
 163 received from the device. This struct is defined in E<lt>routeros_api.hE<gt>
 164 and contains information such as the name of the device, received and
 165 transmitted bytes and whether or not the interface is currently running. No
 166 element of the list nor any of their members may be modified and will be freed
 167 when the callback returns.
 168
 169 =head2 High level interface functions for "registration-table"
 170
 171 This high level interface makes it easy to access the "registration table",
 172 which holds active wireless lan connections. The data returned is equivalent to
 173 running C</interface/wireless/registration-table/print>. The parsed data is
 174 passed to a callback function in form of a B<ros_registration_table_t>
 175 structure.
 176
 177 The query function has the following prototype:
 178
 179  int ros_registration_table (ros_connection_t *c,
 180      ros_registration_table_handler_t handler, void *user_data);
 181
 182 I<c> is the usual connection ocject. I<handler> is a pointer to a function with
 183 the following prototype:
 184
 185  int callback (ros_connection_t *c,
 186      const ros_registration_table_t *r, void *user_data);
 187
 188 The usual semantics apply: You may not alter I<r> and the memory pointed to by
 189 I<r> is freed after the callback returned.
 190
 191 =head1 ERROR HANDLING
 192
 193 Some of the functions above return an "error code". This error code can be
 194 transferred to a string describing the error using L<strerror(3)> or
 195 L<strerror_r(3)>. Since the error codes are all positive integers, it is
 196 recommended to use negative return values in the callback functions to indicate
 197 custom errors if appropriate.
 198
 199 =head1 THREAD SAFETY
 200
 201 librouteros uses only thread-safe functions and does not store any global data
 202 itself. It is therefore fully thread and reentrant safe as long as you don't
 203 call any functions with the same connection object.
 204
 205 =head1 LICENSE
 206
 207 librouteros is licensed under the GPLv2. No other version of the license is
 208 applicable.
 209
 210 =head1 AUTHOR
 211
 212 librouteros is written by Florian octo Forster E<lt>octo at verplant.orgE<gt>.
 213 Its homepage can be found at L<http://verplant.org/librouteros/>.
 214
 215 (c) 2009 by Florian octo Forster.