From: Florian Forster Date: Wed, 25 Nov 2009 20:03:10 +0000 (+0100) Subject: doc/librouteros.pod: Added first draft of a manpage. X-Git-Tag: librouteros-0.1.0~3 X-Git-Url: https://git.octo.it/?p=routeros-api.git;a=commitdiff_plain;h=e35c4218ea84a0b0f69f6b10cd1bc74d4e4099e2 doc/librouteros.pod: Added first draft of a manpage. --- diff --git a/doc/librouteros.pod b/doc/librouteros.pod new file mode 100644 index 0000000..c6fc532 --- /dev/null +++ b/doc/librouteros.pod @@ -0,0 +1,159 @@ +=head1 NAME + +librouteros - Library for accessing MikroTik's RouterOS via its API + +=head1 DESCRIPTION + +B is a library to communicate with I, the operating +system of I I. It uses the "API port" provided by +those systems to connect and talk to the devices. librouteros is a low-level +library in that it abstracts the network protocol used but has next to no +knowledge about the commands and responses available. Should such an high-level +interface prove useful, it will be added as the need arises. + +=head1 GENERAL USAGE + +The interface of librouteros is designed to be lightweight and simple to use. +The first thing when using the library is to create a connection object. Once a +connection has been established and logging in succeeded, queries can be sent +to the remote device. The library will encode and send the request, read back a +reply, decode it and pass it to a callback function. The callback function has +access to the parsed reply and can easily access all parts and parameters. It +does not need to worry about memory management because everything provided to +it will be freed by the library before returning to where the query was called +from. When the application is done talking to the device and disconnects, the +connection object will be freed. + +=head1 DATA TYPES + +The following data types are used and returned by librouteros: + +=over 4 + +=item B + +The "connection object" represents the connection to one device. +This is an opaque data type, meaning that you can only have pointers to such +objects but not dereference or manipulate them directly. + +=item B + +One part of a reply (which are stored as a list) received from a device. The +head of the list (the first part) is passed to the callback function. +This is an opaque data type, meaning that you can only have pointers to such +objects but not dereference or manipulate them directly. + +=item B + +Convenience data type for the callback functions. Callback functions must have +the following prototype: + + int callback (ros_connection_t *c, const ros_reply_t *r, void *user_data); + +The first and second arguments are objects representing the connection and the +reply respectively. I is a pointer as passed to B (see +below). + +The value returned by the callback function will be returned by B to +the calling code. To distinguish from error codes returned by B upon +errors, use negative values in the callback function. + +=back + +=head1 FUNCTIONS + +The following functions are part of librouteros' API and exported. Functions +not listed here are not part of the API, should not be exported and may change +and disappear at any time. Please report such functions are bugs. + +=over 4 + +=item ros_connection_t *B (const char *I, const char *I, const char *I, const char *I) + +Connects to the remote device using I as the address or hostname. If +I is C, the standard port B<8728> will be used. When a +connection has been established, the library will try to authenticate using +I and I. + +On failure, C is returned and B is set appropriately. + +=item int B (ros_connection_t *I) + +Disconnects from the device and frees all memory associated with the +connection. After this call, I may not be used anymore. + +Returns zero upon success and an error code otherwise. + +=item int B (ros_connection_t *I, const char *I, size_t I, const char * const *I, ros_reply_handler_t I, void *I) + +Sends the command I with the I arguments I via the +connection I and reads back the reply. The reply is parsed and passed to the +callback function I. I is a pointer passed through to the +callback function. Please note that the callback function is called only once, +even if the reply consists of multiple parts. Use the B +function (see below) to access the other parts. + +Returns the value returned by the callback function upon success and an error +code otherwise. + +=item const ros_reply_t *B (const ros_reply_t *I) + +Each reply can consist of several parts or "sentences". If there is more than +one sentence returned by the device, this function will return the next part. +When the end of the list is reached, C is returned. + +=item int B (const ros_reply_t *I) + +Returns the number of replies in the list pointed to by and including I. + +=item const char *B (const ros_reply_t *I) + +Returns the status message of this part or reply. This is usually "re" for data +parts, "done" for the last part in a reply and "trap" for errors. +The returned pointer must not be freed. + +=item const char *B (const ros_reply_t *I, unsigned int I) + +Returns the parameter key at index I (starting with zero) of reply I. +If I is out of bounds, returns C. +The returned pointer must not be freed. + +=item const char *B (const ros_reply_t *I, unsigned int I) + +Returns the parameter value at index I (starting with zero) of reply +I. If I is out of bounds, returns C. +The returned pointer must not be freed. + +=item const char *ros_reply_param_val_by_key (const ros_reply_t *r, const char *key) + +Returns the parameter value corresponding to key I (or C if there is +no such key) of reply I. +The returned pointer must not be freed. + +=back + +=head1 ERROR HANDLING + +Some of the functions above return an "error code". This error code can be +transferred to a string describing the error using L or +L. Since the error codes are all positive integers, it is +recommended to use negative return values in the callback functions to indicate +custom errors if appropriate. + +=head1 THREAD SAFETY + +librouteros uses only thread-safe functions and does not store any global data +itself. It is therefore fully thread and reentrant safe as long as you don't +call any functions with the same connection object. + +=head1 LICENSE + +librouteros is licensed under the GPLv2. No other version of the license is +applicable. + +=head1 AUTHOR + +librouteros is written by Florian octo Forster Eocto at verplant.orgE. +It's homepage can be found at L. + +(c) 2009 by Florian octo Forster.