Difference between revisions of "Exchanger class"

From Apibot
Jump to: navigation, search
(+ link to Mains)
m (moved Apibot 0.40 Exchanger class to Exchanger class: 0.40 is the stable version now - why numbering it?)
(No difference)

Revision as of 15:34, 13 April 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 common/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 api/mains/exchanger.php and Exchanger_Web (found in the file web/mains/exchanger.php). They are accessed identically, only the internal machinery is different.

The Mains 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 one currently supported by Apibot is "php")
  • 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