Communicator.php

Show:

inherited

Classes
- \PEAR2\Net\RouterOS\Communicator

Table of Contents

RouterOS API client implementation.

RouterOS is the flag product of the company MikroTik and is a powerful router software. One of its many abilities is to allow control over it via an API. This package provides a client for that API, in turn allowing you to use PHP to control RouterOS hosts. PHP version 5

Author: Vasil Rangelov
Category: Net
Copyright: 2011 Vasil Rangelov
License: LGPL License 2.1
Link: http://pear2.php.net/PEAR2_Net_RouterOS
Package: PEAR2_Net_RouterOS
Version: 1.0.0b4

\PEAR2\Net\RouterOS\Communicator
jump to top

Package: PEAR2_Net_RouterOS

A RouterOS communicator.

Implementation of the RouterOS API protocol. Unlike the other classes in this package, this class doesn't provide any conviniences beyond the low level implementation details (automatic word length encoding/decoding, charset translation and data integrity), and because of that, its direct usage is strongly discouraged.

See
Author: Vasil Rangelov
Category: Net
License: LGPL License 2.1
Link: http://pear2.php.net/PEAR2_Net_RouterOS

Constants

 
                CHARSET_ALL
                = -1

Used when getting/setting all (default) charsets.

 
                CHARSET_REMOTE
                = 0

Used when getting/setting the (default) remote charset.

The remote charset is the charset in which RouterOS stores its data. If you want to keep compatibility with your Winbox, this charset should match the default charset from your Windows' regional settings.

 
                CHARSET_LOCAL
                = 1

Used when getting/setting the (default) local charset.

The local charset is the charset in which the data from RouterOS will be returned as. This charset should match the charset of the place the data will eventually be written to.

Properties

array $charsets = array()

An array with the current charset types as keys, and the current charsets as values.

Default valuearray()Details

Type: array

array $defaultCharsets = array(self::CHARSET_REMOTE => null, self::CHARSET_LOCAL => null)

static

An array with the default charset types as keys, and the default charsets as values.

Default valuearray(self::CHARSET_REMOTE => null, self::CHARSET_LOCAL => null)Details

Type: array

\PEAR2\Net\Transmitter\TcpClient $trans

The transmitter for the connection.

Details

Type: \PEAR2\Net\Transmitter\TcpClient

Methods

__construct(string $host, int | null $port = 8728, bool $persist = false, float $timeout = null, string $key = '', string $crypto = \PEAR2\Net\Transmitter\NetworkStream::CRYPTO_OFF, resource $context = null) : void

Creates a new connection with the specified options.

Parameters

Name	Type	Description
$host	string	Hostname (IP or domain) of the RouterOS server.
$port	int \| null	The port on which the RouterOS server provides the API service. You can also specify NULL, in which case the port will automatically be chosen between 8728 and 8729, depending on the value of $crypto.
$persist	bool	Whether or not the connection should be a persistent one.
$timeout	float	The timeout for the connection.
$key	string	A string that uniquely identifies the connection.
$crypto	string	The encryption for this connection. Must be one of the PEAR2\Net\Transmitter\NetworkStream::CRYPTO_* constants. Off by default. RouterOS currently supports only TLS, but the setting is provided in this fashion for forward compatibility's sake. And for the sake of simplicity, if you specify an encryption, don't specify a context and your default context uses the value "DEFAULT" for ciphers, "ADH" will be automatically added to the list of ciphers.
$context	resource	A context for the socket.

Details

See

__invoke(string $string = null) : int | string

A shorthand gateway.

This is a magic PHP method that allows you to call the object as a function. Depending on the argument given, one of the other functions in the class is invoked and its returned value is returned by this function.

Parameters

Name	Type	Description
$string	string	A string of the word to send, or NULL to get the next word as a string.

Returns

Type	Description
int \| string	If a string is provided, returns the number of bytes sent, otherwise retuns the next word as a string.

_decodeLength(\PEAR2\Net\Transmitter\Stream $trans) : int

static

Decodes the lenght of the incoming message.

Decodes the lenght of the incoming message, as specified by the RouterOS API. Difference with the non private function is that this one doesn't perform locking if the connection is a persistent one.

Parameters

Name	Type	Description
$trans	\PEAR2\Net\Transmitter\Stream	The transmitter from which to decode the length of the incoming message.

Returns

Type	Description
int	The decoded length.

close() : bool

Closes the opened connection, even if it is a persistent one.

Returns

Type	Description
bool	TRUE on success, FALSE on failure.

decodeLength(\PEAR2\Net\Transmitter\Stream $trans) : int

static

Decodes the lenght of the incoming message.

Decodes the lenght of the incoming message, as specified by the RouterOS API.

Parameters

Name	Type	Description
$trans	\PEAR2\Net\Transmitter\Stream	The transmitter from which to decode the length of the incoming message.

Returns

Type	Description
int	The decoded length.

encodeLength(int $length) : string

static

Encodes the length as requred by the RouterOS API.

Parameters

Name	Type	Description
$length	int	The length to encode.

Returns

Type	Description
string	The encoded length.

getCharset(int $charsetType) : string | array

Gets the charset(s) for this connection.

Parameters

Name	Type	Description
$charsetType	int	Which charset to get. Valid values are the CHARSET_ constants. Any other value is treated as {@link CHARSET_ALL}.*

Returns

Type	Description
string \| array	The current charset. If $charsetType is {@link CHARSET_ALL}, the current values will be returned as an array with the types as keys, and charsets as values.

Details

See
See

getDefaultCharset(int $charsetType) : string | array

static

Gets the default charset(s).

Parameters

Name	Type	Description
$charsetType	int	Which charset to get. Valid values are the CHARSET_ constants. Any other value is treated as {@link CHARSET_ALL}.*

Returns

Type	Description
string \| array	The current charset. If $charsetType is {@link CHARSET_ALL}, the current values will be returned as an array with the types as keys, and charsets as values.

Details

See

getNextWord() : string

Get the next word in queue as a string.

Get the next word in queue as a string, after automatically decoding its length.

Returns

Type	Description
string	The word.

Details

See

getNextWordAsStream() : resource

Get the next word in queue as a stream.

Get the next word in queue as a stream, after automatically decoding its length.

Returns

Type	Description
resource	The word, as a stream.

Details

See

getTransmitter() : \PEAR2\Net\Transmitter\TcpClient

Gets the transmitter for this connection.

Returns

Type	Description
\PEAR2\Net\Transmitter\TcpClient	The transmitter for this connection.

iconvStream(string $in_charset, string $out_charset, resource $stream) : resource

static

Uses iconv to convert a stream from one charset to another.

Parameters

Name	Type	Description
$in_charset	string	The charset of the stream.
$out_charset	string	The desired resulting charset.
$stream	resource	The stream to convert.

Returns

Type	Description
resource	A new stream that uses the $out_charset. The stream is a subset from the original stream, from its current position to its end.

isSeekableStream(mixed $var) : bool

static

Checks whether a variable is a seekable stream resource.

Parameters

Name	Type	Description
$var	mixed	The value to check.

Returns

Type	Description
bool	TRUE if $var is a seekable stream, FALSE otherwise.

sendWord(string $word) : int

Sends a word.

Sends a word and automatically encodes its length when doing so.

Parameters

Name	Type	Description
$word	string	The word to send.

Returns

Type	Description
int	The number of bytes sent.

Details

See
See

sendWordFromStream(string $prefix, resource $stream) : int

Sends a word based on a stream.

Sends a word based on a stream and automatically encodes its length when doing so. The stream is read from its current position to its end, and then returned to its current position. Because of those operations, the supplied stream must be seekable.

Parameters

Name	Type	Description
$prefix	string	A string to prepend before the stream contents.
$stream	resource	The stream to send.

Returns

Type	Description
int	The number of bytes sent.

Details

See

setCharset(mixed $charset, int $charsetType = self::CHARSET_ALL) : string | array

Sets the charset(s) for this connection.

Sets the charset(s) for this connection. The specified charset(s) will be used for all future words. When sending, {@link CHARSET_LOCAL} is converted to {@link CHARSET_REMOTE}, and when receiving, {@link CHARSET_REMOTE} is converted to {@link CHARSET_LOCAL}. Setting NULL to either charset will disable charset convertion, and data will be both sent and received "as is".

Parameters

Name	Type	Description
$charset	mixed	The charset to set. If $charsetType is {@link CHARSET_ALL}, you can supply either a string to use for all charsets, or an array with the charset types as keys, and the charsets as values.
$charsetType	int	Which charset to set. Valid values are the Communicator::CHARSET_ constants. Any other value is treated as {@link CHARSET_ALL}.*

Returns

Type	Description
string \| array	The old charset. If $charsetType is {@link CHARSET_ALL}, the old values will be returned as an array with the types as keys, and charsets as values.

Details

See

setDefaultCharset(mixed $charset, int $charsetType = self::CHARSET_ALL) : string | array

static

Sets the default charset(s) for new connections.

Parameters

Name	Type	Description
$charset	mixed	The charset to set. If $charsetType is {@link CHARSET_ALL}, you can supply either a string to use for all charsets, or an array with the charset types as keys, and the charsets as values.
$charsetType	int	Which charset to set. Valid values are the CHARSET_ constants. Any other value is treated as {@link CHARSET_ALL}.*

Returns

Type	Description
string \| array	The old charset. If $charsetType is {@link CHARSET_ALL}, the old values will be returned as an array with the types as keys, and charsets as values.

Details

See

verifyLengthSupport(int $length) : void

static

Verifies that the length is supported.

Verifies if the specified length is supported by the API. Throws a {@link LengthException} if that's not the case. Currently, RouterOS supports words up to 0xFFFFFFF in length, so that's the only check performed.

Parameters

Name	Type	Description
$length	int	The length to verify.

Communicator.php

\PEAR2\Net\RouterOS\Communicatorjump to top

Constants

Properties

Methods

\PEAR2\Net\RouterOS\Communicator
jump to top