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 DATA TYPES
  28
  29 The following data types are used and returned by librouteros:
  30
  31 =over 4
  32
  33 =item B<ros_connection_t>
  34
  35 The "connection object" represents the connection to one device.
  36 This is an opaque data type, meaning that you can only have pointers to such
  37 objects but not dereference or manipulate them directly.
  38
  39 =item B<ros_reply_t>
  40
  41 One part of a reply (which are stored as a list) received from a device. The
  42 head of the list (the first part) is passed to the callback function.
  43 This is an opaque data type, meaning that you can only have pointers to such
  44 objects but not dereference or manipulate them directly.
  45
  46 =item B<ros_reply_handler_t>
  47
  48 Convenience data type for the callback functions. Callback functions must have
  49 the following prototype:
  50
  51   int callback (ros_connection_t *c, const ros_reply_t *r, void *user_data);
  52
  53 The first and second arguments are objects representing the connection and the
  54 reply respectively. I<user_data> is a pointer as passed to B<ros_query> (see
  55 below).
  56
  57 The value returned by the callback function will be returned by B<ros_query> to
  58 the calling code. To distinguish from error codes returned by B<ros_query> upon
  59 errors, use negative values in the callback function.
  60
  61 =back
  62
  63 =head1 FUNCTIONS
  64
  65 The following functions are part of librouteros' API and exported. Functions
  66 not listed here are not part of the API, should not be exported and may change
  67 and disappear at any time. Please report such functions are bugs.
  68
  69 =over 4
  70
  71 =item ros_connection_t *B<ros_connect> (const char *I<node>, const char *I<service>, const char *I<username>, const char *I<password>)
  72
  73 Connects to the remote device using I<node> as the address or hostname. If
  74 I<service> is C<NULL>, the standard port B<8728> will be used. When a
  75 connection has been established, the library will try to authenticate using
  76 I<username> and I<password>.
  77
  78 On failure, C<NULL> is returned and B<errno> is set appropriately.
  79
  80 =item int B<ros_disconnect> (ros_connection_t *I<c>)
  81
  82 Disconnects from the device and frees all memory associated with the
  83 connection. After this call, I<c> may not be used anymore.
  84
  85 Returns zero upon success and an error code otherwise.
  86
  87 =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>)
  88
  89 Sends the command I<command> with the I<args_num> arguments I<args> via the
  90 connection I<c> and reads back the reply. The reply is parsed and passed to the
  91 callback function I<handler>. I<user_data> is a pointer passed through to the
  92 callback function. Please note that the callback function is called only once,
  93 even if the reply consists of multiple parts. Use the B<ros_reply_next>
  94 function (see below) to access the other parts.
  95
  96 Returns the value returned by the callback function upon success and an error
  97 code otherwise.
  98
  99 =item const ros_reply_t *B<ros_reply_next> (const ros_reply_t *I<r>)
 100
 101 Each reply can consist of several parts or "sentences". If there is more than
 102 one sentence returned by the device, this function will return the next part.
 103 When the end of the list is reached, C<NULL> is returned.
 104
 105 =item int B<ros_reply_num> (const ros_reply_t *I<r>)
 106
 107 Returns the number of replies in the list pointed to by and including I<r>.
 108
 109 =item const char *B<ros_reply_status> (const ros_reply_t *I<r>)
 110
 111 Returns the status message of this part or reply. This is usually "re" for data
 112 parts, "done" for the last part in a reply and "trap" for errors.
 113 The returned pointer must not be freed.
 114
 115 =item const char *B<ros_reply_param_key_by_index> (const ros_reply_t *I<r>, unsigned int I<index>)
 116
 117 Returns the parameter key at index I<index> (starting with zero) of reply I<r>.
 118 If I<index> is out of bounds, returns C<NULL>.
 119 The returned pointer must not be freed.
 120
 121 =item const char *B<ros_reply_param_val_by_index> (const ros_reply_t *I<r>, unsigned int I<index>)
 122
 123 Returns the parameter value at index I<index> (starting with zero) of reply
 124 I<r>. If I<index> is out of bounds, returns C<NULL>.
 125 The returned pointer must not be freed.
 126
 127 =item const char *ros_reply_param_val_by_key (const ros_reply_t *r, const char *key)
 128
 129 Returns the parameter value corresponding to key I<key> (or C<NULL> if there is
 130 no such key) of reply I<r>.
 131 The returned pointer must not be freed.
 132
 133 =back
 134
 135 =head1 ERROR HANDLING
 136
 137 Some of the functions above return an "error code". This error code can be
 138 transferred to a string describing the error using L<strerror(3)> or
 139 L<strerror_r(3)>. Since the error codes are all positive integers, it is
 140 recommended to use negative return values in the callback functions to indicate
 141 custom errors if appropriate.
 142
 143 =head1 THREAD SAFETY
 144
 145 librouteros uses only thread-safe functions and does not store any global data
 146 itself. It is therefore fully thread and reentrant safe as long as you don't
 147 call any functions with the same connection object.
 148
 149 =head1 LICENSE
 150
 151 librouteros is licensed under the GPLv2. No other version of the license is
 152 applicable.
 153
 154 =head1 AUTHOR
 155
 156 librouteros is written by Florian octo Forster E<lt>octo at verplant.orgE<gt>.
 157 It's homepage can be found at L<http://verplant.org/librouteros/>.
 158
 159 (c) 2009 by Florian octo Forster.