WinBox Native GUI syntax

WinBox native — GUI-like syntax

A WinBox native connection can be addressed by the names the WinBox screen shows — /IP/Firewall/Firewall Rule, Src. Address — instead of API names. Use it when you write code while looking at WinBox, or for a window whose API name you do not know. It is the WinBox counterpart of CLI raw commands, with one difference: WinBox has no command language, so what you write are its names, and tik4net still turns them into the numbers WinBox sends.

Experimental, like WinBox native itself. For production work over the WinBox channel use WinBox CLI.

using tik4net;
using tik4net.WinboxNative;

using ITikWinboxNativeConnection connection =
    new TikConnectionSetup(HOST, USER, PASS).CreateWinboxNativeConnection(c => c.UseGuiNames = true);

// System ▸ Resources — the window is named "Resources" too
var resource = connection.CreateCommand("/System/Resources/Resources/print").ExecuteSingleRow();
Console.WriteLine(resource.GetResponseField("cpu-load"));             // rows come back with API names

// IP ▸ Firewall ▸ Filter Rules — write a field by its caption
connection.CreateCommandAndParameters("/IP/Firewall/Firewall Rule/set",
    ".id", "*5", "Comment", "managed-by-tik4net").ExecuteNonQuery();

• UseGuiNames folds case, turns spaces and _ into - and drops abbreviation dots, then resolves against the router's catalog. A name that is already an API name is used as it is, so turning it on never changes the meaning of code that uses API names.
• Rows always come back with API field names.
• The flag is read when a command runs, so it can be switched for a single call — but not while another thread uses the connection.

What resolves

The rule: the menu breadcrumb, then the window's name — the caption of the dialog that opens on a row, not the caption of the list:

You write	Resolves to
/IP/Firewall/Filter	/ip/firewall/filter	the API path, any case
/IP/Firewall/Firewall Rule	/ip/firewall/filter	menu + the window's name
/IP/Firewall/Address List	/ip/firewall/address-list
/IP/DNS/DNS Static Entry	/ip/dns/static
/System/Resources/Resources	/system/resource
/IP/Addresses/Address	/ip/address
/Interfaces/Interface	/interface
/PPP/PPP Secret	/ppp/secret	the window sits directly under the PPP menu
/IP/Firewall/Filter Rules	—	the list's caption, not the window's name
/System/Resources	—	a menu without its window
/PPP/Secrets/PPP Secret	—	Secrets is a list caption, not a level of the tree

A path that does not resolve throws TikPathNotMappedException before anything is sent. To teach a connection which window an API path means, use a PathAlias — see Session mappings.

Limits

• Names in, API names out — GUI names are accepted for the path, a written field and a read's filter.
• A caption is folded, not looked up. A caption that does not fold to its API name — Tx for tx-byte — needs a built-in alias or a FieldOverride.
• Not a raw level — there is no text to pass through. For a command the native mapping does not cover, use WinBox CLI with CLI raw commands.

Why the names look like this

WinBox draws a tree of windows that the router describes in its own catalog (roteros.jg and friends):

{name:'Firewall Rule', title:'Filter Rules', type:'map', path:[ 20,3 ], c:[
    {name:'Chain',  type:'string', id:'s14'},
    {name:'Action', type:'enm',    id:'u13'}, ... ]}

• A menu is what you click in WinBox's left bar; it has no number.
• A window is one table or form, with a name (Firewall Rule, the dialog caption), a title (Filter Rules, the list caption) and a path — the handler numbers the message is sent to, which change between versions.
• A field is a caption; its id is a type letter and the key the value travels under (s14 = string, key 0x14).

So a GUI path is a walk through that tree, and tik4net follows the router's own catalog to the numbers.

See also

• WinBox native connection — the transport, mappings and limits
• CLI raw commands — native syntax on the console transports
• Communication debugging — the handler and keys each request used