API Delphi

This document describes a Delphi class to access RouterOs using API interface.

Enable API's in RouterOs devices

By default API interface is disabled in the device, then enable it using the simple command in a terminal connection:

/ip service enable api

Using API: send commands and receive output through the socket

The mikrotik protocol to talk with api interface is well documented in the main page API. You can connect to the API interface of an RouterOs device using a TCP socket connected to 8728 port.

In this page you can found a Delphi class which encapsulate the details of the connection and give you the ability to use some simple methods to create applications usin API.

All methods return 0 if the execution is correct (<0 otherwise)

The Delphi class tr_mkrouter

This class is defined in a Delphi unit. I used Delphi 7 but is simple to adapt to other versions. This class publish this methods:

constructor create(i_logger: TLogger);

Create the object. Passing the object TLogger, enable you to log the activity to a memo control and/or to a file.

function open(ip_router, user, password: string): integer;

Open the socket with the router and executes the login handshake.

function msend(vs: string; fl_execute: boolean): integer;

Send the string vs tho the router (send an api word). If fl_execute=true it concatenate a #0 (send an api sentence) wich cause the command to be executed.

function send_command(cmd_arr: array of string): integer;

Send the strings contained in the array, then send a #0 (example: res:=send_command(['/ppp/active/print','=stats=','=without-paging=']); ). Each send_command increase the command counter of the object. Each !done decrease this counter. You can test if there are pending commands calling the following method: function tr_mkrouter.command_pending: boolean;

function mrecv_sentence(var vs: string): integer;

Wait for output from router, in the vs string return the text until #0 is received. It receive an api sentence.

function mrecv_done(var vs: string): integer;

Wait for output from router, in the vs string return the text until !done is received. It receive the full response of a command.

function query_router(cmd_arr: array of string; var res: string): integer;

Is the union of a send_command and a mrecv_done.

Build the project: the libraries used

The download, contains this libraries:

- MD5.pas class (form Francois Piette), used in login handshake, at MD5.PAS

- Synapse library to work with sockets at Synapse

- Logger library: class used to log in a memo and/or in a file the application activity

- Utils library: contain some useful procedures to work with IP and strings

- Synapse library to work with sockets at Synapse

To build the sample application, add the word "synapse" to the Project>Options>Directory Conditionals>Search path.

In different versions of delphi, could be necessary to modify some links to used units (ex. is you use Delphi 5, you must provide StrUtil.pas (thanks to pedja) at strutil.pas)

The API_STUDIO application

I usually develop using mikrotik API and the API STUDIO allow me to test API commands before implementing it in other software.

This application is very simple but useful and is a demo for this delphi class (you can also read the simple help in the main form).

LOGIN

- Insert login informations of router you want to test then print connect.

- The objet of class tr_mkrouter is created and open method is called.

- If the router is connected, api studio perform a /system/identity/getall to retrieve the identity of the router.

EXECUTE COMMANDS

- Insert the command you want to send to the router, each word in a field.

- By pressing execute button the send_command method is called and a timer is activated.

- The timer call the method mrecv_sentence and show results until command_pending returns false.

- You can break the result stream (example, in case you have asked for a ping) by pressing the cancel button. This button call a send_command(['/cancel']) (this increase the number of pending commands); you could wait for a while before the stream stops because the timer must receive the !done for the previous command and the !done for the /cancel.

DOWNLOADS

Please refer to this forum thread for download: API_STUDIO. The download contain all source code and the executable (compiled for i386) of the client to test api commands.