Difference between revisions of "Exchanger class"

Latest revision as of 23:56, 10 November 2014

The exchange between a MediaWiki and a bot is far more specialized than the universal HTTP protocol. So, it makes sense to have optimized specific functionality for it. In Apibot, it is implemented in the Exchanger class, found in the file core/backends/_generic/_exchanger.php.

Most of the Apibot functionality works through the MediaWiki API. For some things, however, there are also backends that work through the human-oriented Web interface. The underlying mechanisms differ between these two. For this reason, from the base Exchanger class are derived two specific classes - Exchanger_API (found in the file core/backends/api/exchanger.php and Exchanger_Web (found in the file core/backends/web/exchanger.php). They are accessed identically, only the internal machinery is different.

The Core object contains two Exchanger objects - an API one and a Web one.

Creation

Creating an object of the Exchanger class (or its descendant) takes five parameters:

• URI to use for connecting to the MediaWiki
• settings for the exchanger
• params for the exchanger (and ultimately for the API mainmodule object)
• Log object
• Browser object

Public properties

• $data - the data received from the wiki (as a structured array)

Public methods

Basic exchanger methods

• log ( $message, $loglevel = LL_INFO, $preface = "exchanger: " ) - write a line to the bot log
• browse ( $uri, $vars = array(), $files = array(), $mustbeposted = false ) - an extended layer over the Browser xfer() function. Adds the exchanger params, retries on need, checks the result for correctness, throws exceptions on need.
• xfer ( $vars, $files = array, $mustbeposted = false ) - makes an exchanger-level transfer with the MediaWiki.

Exchanger parameters

• get_params() - returns the exchanger params
• set_params ( $params_array ) - sets exchanger params
• clear_params() - clears the exchanger params

Browser object exposure methods

• last_time() - returns the last xfer mean time
• bytecounters() - returns the browser bytecounters
• reset_bytecounters() - resets the browser bytecounters
• get_headers() - returns the headers received during the last browser transfer
• get_cookies() - returns the browser cookies
• get_cookie ( $cookie_name ) - returns the browser cookie ( array ( 'content' => cookie text, 'exp' => cookie expiration ) ), or false if no such cookie exists
• set_cookie ( $cookie_name, $cookie ) - sets a browser cookie (see above for the $cookie structure)
• del_cookie ( $cookie_name ) - delete the cookie with this name, if any
• set_cookie_expiration ( $cookie_name, $seconds ) - sets this cookie expiration, if it exists
• modify_cookie_expiration ( $cookie_name, $seconds ) - adds (or subtracts, if negative) to this cookie expiration, if it exists

Exchanger_API public methods

Currently Exchanger_Web has no other public methods outside these of the parent Exchanger class. Exchanger_API, however, has some additional ones.

Parameters

The parameters of Exchanger_API are also passed to, and used by the API Mainmodule parameters class. Also, in addition to the parent Exchanger class, it has the following methods:

• get_param ( $name ) - returns the param with this name
• set_param ( $name, $value = "" ) - sets the param with this name to this value
• clear_param ( $name, $value = NULL ) - clears this param (or some of its subparams, if $value is an array with the subparams names)

There are also methods setting some API-specific parameters:

• set_format ( $format ) - set exchange format (the only currently supported by Apibot is the default "php" and "json" - the first is supported by even the oldest MW version, and the second is the preferred one)
• set_maxlag ( $maxlag ) - set exchange maxlag
• set_version ( $version ) - set version
• set_smaxage ( $smaxage ) - set smaxage
• set_maxage ( $maxage ) - set maxage
• set_requestid ( $requestid ) - set requestid
• set_servedby ( $servedby ) - set servedby

Hooks

These Exchanger functions can be hooked to through the Hooks Core module:

The hook names differ for the Exchanger_API and Exchanger_Web classes, as follows: