Connection types and capabilities

Connection types & capabilities

tik4net talks to a RouterOS device through one of several transports, all hidden behind the same ITikConnection interface. You pick the transport when you open the connection:

using (ITikConnection connection = ConnectionFactory.CreateConnection(TikConnectionType.Api))
{
    connection.Open(HOST, USER, PASS);
    // ... same API regardless of the transport ...
}

Not every transport can do everything the binary API can. A transport declares the set of features it supports as TikConnectionCapability flags, and the library is fail-closed: a feature that the active transport does not declare throws TikConnectionCapabilityNotSupportedException instead of silently misbehaving.

🆕 4.x / alpha preview. Only Api / ApiSsl are stable (shipped since the early 3.x line). Every other transport in the table below is new in the unreleased 4.x line and an alpha preview — it works and is covered by tests, but the API and behaviour may still change before the public 4.0 release. WinboxNative / WinboxNativeMac carry an additional maturity caveat (⚠️) on their own pages.

Connection types

TikConnectionType	Transport	Port	Status	Notes
Api / ApiSsl	Binary MikroTik API protocol	8728 / 8729	Stable	Reference transport. Full feature set (tagged async, streaming, raw sentences, Safe Mode).
Rest / RestSsl	HTTP REST API (RouterOS 7.1+)	80 / 443	🆕 4.x alpha	Stateless request/reply. CRUD only — no server push, no session-bound Safe Mode.
Telnet	Plain-text CLI over TCP	23	🆕 4.x alpha	CLI family.
Ssh	Encrypted CLI over an SSH shell	22	🆕 4.x alpha	CLI family. Separate tik4net.ssh package.
MacTelnet	Layer-2 CLI over UDP	20561	🆕 4.x alpha	CLI family. No IP route needed (EC-SRP5 auth).
WinboxCli	Encrypted CLI over the WinBox channel	8291	🆕 4.x alpha	CLI family. EC-SRP5 + AES, no certificates.
WinboxCliMac	Encrypted WinBox CLI over the MAC layer	20561	🆕 4.x alpha	CLI family. No IP route needed.
WinboxNative	Structured CRUD via native WinBox M2 calls	8291	🆕 4.x ⚠️ alpha	No terminal; EC-SRP5 + AES.
WinboxNativeMac	Native WinBox M2 CRUD over the MAC layer	20561	🆕 4.x ⚠️ alpha	No IP route needed.

The CLI family (Telnet / Ssh / MacTelnet / WinboxCli / WinboxCliMac) drives the router's textual command shell. WinboxNative issues structured WinBox M2 calls instead of a terminal. Both emulate live change notifications (Listen) by polling + diffing, so they report Listen even though only the binary API gets it natively.

How does the same ExecuteList / Save call work over a terminal or M2 instead of the binary API? See Command translation on non-API transports — what gets translated into what, and in which layer.

Capabilities

Flag	Meaning
Crud	Create / read / update / delete of RouterOS records (LoadAll, Save, Delete). Every transport.
Listen	Live /path/listen change notifications and async loads (LoadAsync / LoadListenAsync / ExecuteAsync). Native on the API; emulated by poll+diff on CLI / WinBox.
Streaming	Streaming monitor windows that push successive snapshots (ExecuteListWithDuration, e.g. /interface/monitor-traffic, /tool/torch, /tool/traceroute, ping).
RawSentences	Direct access to raw !re / !done / !trap sentences below the O/R mapper.
Tagging	Per-command .tag multiplexing of concurrent commands on one channel (CallCommandAsync).
SafeMode	Connection-bound RouterOS Safe Mode (SafeModeTake / SafeModeRelease / SafeModeUnroll / SafeModeGet) — see Safe Mode. Requires a persistent, session-bound channel.
RawCommand	Raw command pass-through (CreateRawCommand) — send a payload in the transport's own dialect (API sentence / verbatim CLI line) verbatim, bypassing the builder/mapper. See Command translation. Distinct from RawSentences (reading raw response sentences).

Capability matrix

Transport	Crud	Listen	Streaming	RawSentences	Tagging	SafeMode	RawCommand
Api / ApiSsl	✅	✅	✅	✅	✅	✅	✅
Rest / RestSsl	✅	—	—	—	—	—	—
Telnet	✅	✅	—	—	—	✅	✅
Ssh	✅	✅	—	—	—	✅	✅
MacTelnet	✅	✅	—	—	—	✅	✅
WinboxCli	✅	✅	—	—	—	✅	✅
WinboxCliMac	✅	✅	—	—	—	✅	✅
WinboxNative	✅	✅	—	—	—	✅	—
WinboxNativeMac	✅	✅	—	—	—	✅	—

Need streaming monitors, tagged async or raw sentences? Use Api / ApiSsl. It is the only transport that supports the full set.

Checking capabilities at runtime

Test support before using a feature with the Supports extension:

if (connection.Supports(TikConnectionCapability.Streaming))
{
    // safe to call ExecuteListWithDuration / torch / monitor-traffic
}

Or guard an entry point and let it throw TikConnectionCapabilityNotSupportedException (a TikConnectionException) when unsupported:

connection.Require(TikConnectionCapability.SafeMode, "lockout-protected change");
connection.SafeModeTake();

Invoking an unsupported feature directly throws the same exception:

try
{
    // Rest does not support Safe Mode
    restConnection.SafeModeTake();
}
catch (TikConnectionCapabilityNotSupportedException ex)
{
    // ex.Capability == TikConnectionCapability.SafeMode
}

Fail-closed: a connection that does not implement ITikConnectionCapabilities is treated as supporting nothing. Every built-in transport declares its capabilities explicitly (the binary API declares the full set), so this only affects custom third-party ITikConnection implementations — they must declare a capability to be allowed to use it.