\Client.php

Global
Classes
- \PEAR2\Net\RouterOS\Client

Show:

inherited

RouterOS API client implementation.

This package allows you to read and write information from a RouterOS host using MikroTik's RouterOS API.

PHP version 5

Author: Vasil Rangelov
Category: Net
Copyright: 2011 Vasil Rangelov
License: LGPL License 2.1
Link: http://netrouteros.sourceforge.net/
Package: PEAR2_Net_RouterOS
Version: 1.0.0b1

\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://netrouteros.sourceforge.net/

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
                 $_streamResponses= '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

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 $port
              =
              8728, bool $persist
              =
              false, float $timeout
              =
              null, resource $context
              =
              null
          )
        
        :
          void

Opens a new instance of a RouterOS API client.

Opens 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	The port on which the RouterOS server provides the API service.
$persist	bool	Whether or not the connection should be a persistent one.
$timeout	float	The timeout for the connection.
$context	resource	A context for the socket.

Details

See: \PEAR2\Net\RouterOS\sendSync()
See: \PEAR2\Net\RouterOS\sendAsync()

cancelRequest(
          string $tag
              =
              null
          )
        
        :
          \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	The client object.

Details

See: \PEAR2\Net\RouterOS\sendAsync()
See: \PEAR2\Net\RouterOS\close()

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(
          
          )
        
        :
          \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.

Returns

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

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: \PEAR2\Net\RouterOS\loop()

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: \PEAR2\Net\RouterOS\setCharset()

getPendingRequestsCount(
          
          )
        
        :
          int

Gets the number of pending requests.

Returns

Type	Description
int	The number of pending requests.

Details

See: \PEAR2\Net\RouterOS\isRequestActive()

getStreamResponses(
          
          )
        
        :
          bool

Gets response streaming setting.

Gets whether future responses are streamed.

Returns

Type	Description
bool	The value of the setting.

Details

See: \PEAR2\Net\RouterOS\setStreamResponses()

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: \PEAR2\Net\RouterOS\getPendingRequestsCount()
See: \PEAR2\Net\RouterOS\completeRequest()

login(
          \PEAR2\Net\RouterOS\Communicator $com, string $username, string $password
              =
              ''
          )
        
        :
          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.

Returns

Type	Description
bool	TRUE on success, FALSE on failure.

loop(
          float $timeout
              =
              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	float	Timeout for the loop. If 0, there is no time limit.

Returns

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

Details

See: \PEAR2\Net\RouterOS\extractNewResponses()
See: \PEAR2\Net\RouterOS\getPendingRequestsCount()

send(
          \PEAR2\Net\RouterOS\Request $request
          )
        
        :
          \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	The client object.

Details

See: \PEAR2\Net\RouterOS\sendSync()
See: \PEAR2\Net\RouterOS\sendAsync()

sendAsync(
          \PEAR2\Net\RouterOS\Request $request, callback $callback
              =
              null
          )
        
        :
          \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	The client object.

Details

See: \PEAR2\Net\RouterOS\completeRequest()
See: \PEAR2\Net\RouterOS\loop()
See: \PEAR2\Net\RouterOS\cancelRequest()

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: \PEAR2\Net\RouterOS\sendAsync()
See: \PEAR2\Net\RouterOS\close()

setCharset(
          mixed $charset, int $charsetType
              =
              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::HARSET_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: \PEAR2\Net\RouterOS\Communicator::setDefaultCharset()

setStreamResponses(
          bool $streamResponses
          )
        
        :
          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
$streamResponses	bool	Whether to stream future responses.

Returns

Type	Description
bool	The previous value of the setting.

Details

See: \PEAR2\Net\RouterOS\getStreamResponses()

\Client.php

\PEAR2\Net\RouterOS\Clientjump to top

Constants

Properties

Methods

\PEAR2\Net\RouterOS\Client
jump to top