Client.php

Show:

inherited

Classes
- \PEAR2\Net\RouterOS\Client

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\Client
jump to top

Package: PEAR2_Net_RouterOS

A RouterOS client.

Provides functionality for easily communicating with a RouterOS host.

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

Constants

 
                FILTER_CALLBACK
                = 1

Used in {@link isRequestActive()} to limit search only to requests that have a callback.

 
                FILTER_BUFFER
                = 2

Used in {@link isRequestActive()} to limit search only to requests that use the buffer.

 
                FILTER_ALL
                = 3

Used in {@link isRequestActive()} to indicate no limit in search.

Properties

bool $_streamingResponses = false

Whether to stream future responses.

Default valuefalseDetails

Type: bool

array $callbacks = array()

An array of callbacks to be executed as responses come. Key is the tag of the request, and the value is the callback for it.

Default valuearray()Details

Type: array

\PEAR2\Net\RouterOS\Communicator $com

The communicator for this client.

Details

Type: \PEAR2\Net\RouterOS\Communicator

int $pendingRequestsCount = 0

The number of currently pending requests.

Default value0Details

Type: int

\PEAR2\Net\RouterOS\Registry $registry = null

A registry for the operations. Particularly helpful at persistent connections.

Default valuenullDetails

Type: \PEAR2\Net\RouterOS\Registry

array $responseBuffer = array()

An array of responses that have not yet been extracted or passed to a callback. Key is the tag of the request, and the value is an array of associated responses.

Default valuearray()Details

Type: array

Methods

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

Creates a new instance of a RouterOS API client.

Creates a new instance of a RouterOS API client with the specified settings.

Parameters

Name	Type	Description
$host	string	Hostname (IP or domain) of the RouterOS server.
$username	string	The RouterOS username.
$password	string	The RouterOS password.
$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.
$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
See

__destruct() : void

Closes the connection, unless it's a persistent one.

__invoke(mixed $arg = null) : mixed

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
$arg	mixed	Value can be either a {@link Request} to send, which would be sent asynchoniously if it has a tag, and synchroniously if not, a number to loop with or NULL to complete all pending requests. Any other value is converted to string and treated as the tag of a request to complete.

Returns

Type	Description
mixed	Whatever the long form function would have returned.

_login(\PEAR2\Net\RouterOS\Communicator $com, string $username, string $password = '', int | null $timeout = null) : bool

static

This is the actual login procedure, applied regardless of persistence and charset settings.

Parameters

Name	Type	Description
$com	\PEAR2\Net\RouterOS\Communicator	The communicator to attempt to login to.
$username	string	The RouterOS username.
$password	string	The RouterOS password. Potentially parsed already by iconv.
$timeout	int \| null	The time to wait for each response. NULL waits indefinetly.

Returns

Type	Description
bool	TRUE on success, FALSE on failure.

cancelRequest(string $tag = null) : \PEAR2\Net\RouterOS\Client | \PEAR2\Net\RouterOS\Client

Cancels a request.

Cancels an active request. Using this function in favor of a plain call to the "/cancel" command is highly reccomended, as it also updates the counter of pending requests properly. Note that canceling a request also removes any responses for it that were not previously extracted with {@link extractNewResponses()}.

Parameters

Name	Type	Description
$tag	string	Tag of the request to cancel. Setting NULL will cancel all requests.

Returns

Type	Description
\PEAR2\Net\RouterOS\Client \| \PEAR2\Net\RouterOS\Client	The client object.

Details

Fluent: This method is part of a fluent interface and will return the same instance
See
See

close() : bool

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

Closes the opened connection, even if it is a persistent one. Note that {@link extractNewResponses()} can still be used to extract responses collected prior to the closing.

Returns

Type	Description
bool	TRUE on success, FALSE on failure.

completeRequest(string $tag = null) : \PEAR2\Net\RouterOS\ResponseCollection

Completes a specified request.

Starts an event loop for the RouterOS callbacks and finishes when a specified request is completed.

Parameters

Name	Type	Description
$tag	string	The tag of the request to complete. Setting NULL completes all requests.

Returns

Type	Description
\PEAR2\Net\RouterOS\ResponseCollection	A collection of {@link Response} objects that haven't been passed to a callback function or previously extracted with {@link extractNewResponses()}. Returns an empty collection when $tag is set to NULL (responses can still be extracted).

dispatchNextResponse(int $timeout_s = 0, int $timeout_us = 0) : \PEAR2\Net\RouterOS\Response

Dispatches the next response in queue.

Dispatches the next response in queue, i.e. it executes the associated callback if there is one, or places the response in the response buffer.

Parameters

Name	Type	Description
$timeout_s	int	If a response is not immediatly available, wait this many seconds. If NULL, wait indefinetly.
$timeout_us	int	Microseconds to add to the waiting time.

Returns

Type	Description
\PEAR2\Net\RouterOS\Response	The dispatched response.

Throws

Exception	Description
\PEAR2\Net\RouterOS\SocketException	When there's no response within the time limit.

extractNewResponses(string $tag = null) : \PEAR2\Net\RouterOS\ResponseCollection

Extracts responses for a request.

Gets all new responses for a request that haven't been passed to a callback and clears the buffer from them.

Parameters

Name	Type	Description
$tag	string	The tag of the request to extract new responses for. Specifying NULL with extract new responses for all requests.

Returns

Type	Description
\PEAR2\Net\RouterOS\ResponseCollection	A collection of {@link Response} objects for the specified request.

Details

See

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 Communicator::CHARSET_ constants. Any other value is treated as {@link Communicator::CHARSET_ALL}.*

Returns

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

Details

See

getPendingRequestsCount() : int

Gets the number of pending requests.

Returns

Type	Description
int	The number of pending requests.

Details

See

isRequestActive(string $tag, int $filter = self::FILTER_ALL) : bool

Checks if a request is active.

Checks if a request is active. A request is considered active if it's a pending request and/or has responses that are not yet extracted.

Parameters

Name	Type	Description
$tag	string	The tag of the request to look for.
$filter	int	One of the FILTER_ consntants. Limits the search to the specified places.*

Returns

Type	Description
bool	TRUE if the request is active, FALSE otherwise.

Details

See
See

isStreamingResponses() : bool

Gets response streaming setting.

Gets whether future responses are streamed.

Returns

Type	Description
bool	The value of the setting.

Details

See

login(\PEAR2\Net\RouterOS\Communicator $com, string $username, string $password = '', int | null $timeout = null) : bool

static

Parameters

Name	Type	Description
$com	\PEAR2\Net\RouterOS\Communicator	The communicator to attempt to login to.
$username	string	The RouterOS username.
$password	string	The RouterOS password.
$timeout	int \| null	The time to wait for each response. NULL waits indefinetly.

Returns

Type	Description
bool	TRUE on success, FALSE on failure.

loop(int $timeout_s = null, int $timeout_us = 0) : bool

Starts an event loop for the RouterOS callbacks.

Starts an event loop for the RouterOS callbacks and finishes when there are no more pending requests or when a specified timeout has passed (whichever comes first).

Parameters

Name	Type	Description
$timeout_s	int	Timeout for the loop. If NULL, there is no time limit.
$timeout_us	int	Microseconds to add to the time limit.

Returns

Type	Description
bool	TRUE when there are any more pending requests, FALSE otherwise.

Details

See
See

send(\PEAR2\Net\RouterOS\Request $request) : \PEAR2\Net\RouterOS\Client | \PEAR2\Net\RouterOS\Client

Sends a request to RouterOS.

Parameters

Name	Type	Description
$request	\PEAR2\Net\RouterOS\Request	The request to send.

Returns

Type	Description
\PEAR2\Net\RouterOS\Client \| \PEAR2\Net\RouterOS\Client	The client object.

Details

Fluent: This method is part of a fluent interface and will return the same instance
See
See

sendAsync(\PEAR2\Net\RouterOS\Request $request, callback $callback = null) : \PEAR2\Net\RouterOS\Client | \PEAR2\Net\RouterOS\Client

Sends a request and waits for responses.

Parameters

Name	Type	Description
$request	\PEAR2\Net\RouterOS\Request	The request to send.
$callback	callback	Optional. A function that is to be executed when new responses for this request are available. The callback takes two parameters. The {@link Response} object as the first, and the {@link Client} object as the second one. If the function returns TRUE, the request is canceled. Note that the callback may be executed one last time after that with a response that notifies about the canceling.

Returns

Type	Description
\PEAR2\Net\RouterOS\Client \| \PEAR2\Net\RouterOS\Client	The client object.

Details

Fluent: This method is part of a fluent interface and will return the same instance
See
See
See

sendSync(\PEAR2\Net\RouterOS\Request $request) : \PEAR2\Net\RouterOS\ResponseCollection

Sends a request and gets the full response.

Parameters

Name	Type	Description
$request	\PEAR2\Net\RouterOS\Request	The request to send.

Returns

Type	Description
\PEAR2\Net\RouterOS\ResponseCollection	The received responses as a collection.

Details

See
See

setCharset(mixed $charset, int $charsetType = \PEAR2\Net\RouterOS\Communicator::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 requests and responses. When sending, {@link Communicator::CHARSET_LOCAL} is converted to {@link Communicator::CHARSET_REMOTE}, and when receiving, {@link Communicator::CHARSET_REMOTE} is converted to {@link Communicator::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 Communicator::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 Communicator::CHARSET_ALL}.*

Returns

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

Details

See

setStreamingResponses(bool $streamingResponses) : bool

Sets response streaming setting.

Sets whether future responses are streamed. If responses are streamed, the argument values are returned as streams instead of strings. This is particularly useful if you expect a response that may contain one or more very large words.

Parameters

Name	Type	Description
$streamingResponses	bool	Whether to stream future responses.

Returns

Type	Description
bool	The previous value of the setting.

Details

See

Client.php

\PEAR2\Net\RouterOS\Clientjump to top

Constants

Properties

Methods

\PEAR2\Net\RouterOS\Client
jump to top