$this->mModulePrefix = $modulePrefix;
}
- /**
- * Executes this module
+ /*****************************************************************************
+ * ABSTRACT METHODS *
+ *****************************************************************************/
+
+ /**
+ * Evaluates the parameters, performs the requested query, and sets up the
+ * result. Concrete implementations of ApiBase must override this method to
+ * provide whatever functionality their module offers. Implementations must
+ * not produce any output on their own and are not expected to handle any
+ * errors.
+ *
+ * The execute method will be invoked directly by ApiMain immediately before
+ * the result of the module is output. Aside from the constructor, implementations
+ * should assume that no other methods will be called externally on the module
+ * before the result is processed.
+ *
+ * The result data should be stored in the result object referred to by
+ * "getResult()". Refer to ApiResult.php for details on populating a result
+ * object.
*/
public abstract function execute();
+ /**
+ * Returns a String that identifies the version of the extending class. Typically
+ * includes the class name, the svn revision, timestamp, and last author. May
+ * be severely incorrect in many implementations!
+ */
+ public abstract function getVersion();
+
/**
* Get the name of the module being executed by this instance
*/
}
/**
- * If this module's $this is the same as $this->mMainModule, its the root, otherwise no
+ * Returns true if this module is the main module ($this === $this->mMainModule),
+ * false otherwise.
*/
public function isMain() {
return $this === $this->mMainModule;
}
/**
- * Get result object
+ * Get the result object. Please refer to the documentation in ApiResult.php
+ * for details on populating and accessing data in a result object.
*/
public function getResult() {
// Main module has getResult() method overriden
}
/**
- * Set warning section for this module. Users should monitor this section to notice any changes in API.
+ * Set warning section for this module. Users should monitor this section to
+ * notice any changes in API.
*/
public function setWarning($warning) {
$msg = array();
return $msg;
}
+ /**
+ * Generates the parameter descriptions for this module, to be displayed in the
+ * module's help.
+ */
public function makeHelpMsgParameters() {
$params = $this->getAllowedParams();
if ($params !== false) {
if (is_array($desc))
$desc = implode($paramPrefix, $desc);
- @ $type = $paramSettings[self :: PARAM_TYPE];
+ $type = $paramSettings[self :: PARAM_TYPE];
if (isset ($type)) {
if (isset ($paramSettings[self :: PARAM_ISMULTI]))
$prompt = 'Values (separate with \'|\'): ';
return $this->getParameterFromSettings($paramName, $paramSettings);
}
+ /**
+ * Returns an array of the namespaces (by integer id) that exist on the
+ * wiki. Used primarily in help documentation.
+ */
public static function getValidNamespaces() {
static $mValidNamespaces = null;
if (is_null($mValidNamespaces)) {
/**
* Using the settings determine the value for the given parameter
+ *
* @param $paramName String: parameter name
* @param $paramSettings Mixed: default value or an array of settings using PARAM_* constants.
* @param $parseMaxLimit Boolean: parse limit when max is given?
print "\n</pre>\n";
}
- public abstract function getVersion();
+ /**
+ * Returns a String that identifies the version of this class.
+ */
public static function getBaseVersion() {
return __CLASS__ . ': $Id$';
}
}
/**
+* API module that facilitates the blocking of users. Requires API write mode
+* to be enabled.
+*
* @addtogroup API
*/
class ApiBlock extends ApiBase {
+ /**
+ * Std ctor.
+ */
public function __construct($main, $action) {
parent :: __construct($main, $action);
}
+ /**
+ * Blocks the user specified in the parameters for the given expiry, with the
+ * given reason, and with all other settings provided in the params. If the block
+ * succeeds, produces a result containing the details of the block and notice
+ * of success. If it fails, the result will specify the nature of the error.
+ */
public function execute() {
global $wgUser;
$this->getMain()->requestWriteMode();
'nocreate' => 'Prevent account creation',
'autoblock' => 'Automatically block the last used IP address, and any subsequent IP addresses they try to login from',
'noemail' => 'Prevent user from sending e-mail through the wiki',
- 'hidename' => 'Hide the username from the block log.'
+ 'hidename' => 'Hide the username from the block log. (Requires the "hideuser" right.)'
);
}
require_once ("ApiBase.php");
}
-/**
+/**
+ * API module that facilitates the changing of user rights. The API eqivalent of
+ * Special:Userrights. Requires API write mode to be enabled.
+ *
* @addtogroup API
*/
class ApiChangeRights extends ApiBase {
/**
+ * API module that facilitates deleting pages. The API eqivalent of action=delete.
+ * Requires API write mode to be enabled.
+ *
* @addtogroup API
*/
class ApiDelete extends ApiBase {
parent :: __construct($main, $action);
}
+ /* Return values for the delete function. */
+ const DELETE_SUCCESS = 0;
+ const DELETE_PERM = 1;
+ const DELETE_BLOCKED = 2;
+ const DELETE_READONLY = 3;
+ const DELETE_BADTOKEN = 4;
+ const DELETE_BADARTICLE = 5;
+
/**
- * We have our own delete() function, since Article.php's implementation is split in two phases
- * @param Article $article - Article object to work on
- * @param string $token - Delete token (same as edit token)
- * @param string $reason - Reason for the deletion. Autogenerated if NULL
- * @return DELETE_SUCCESS on success, DELETE_* on failure
+ * Extracts the title, token, and reason from the request parameters and invokes
+ * the local delete() function with these as arguments. It does not make use of
+ * the delete function specified by Article.php. If the deletion succeeds, the
+ * details of the article deleted and the reason for deletion are added to the
+ * result object.
*/
-
- const DELETE_SUCCESS = 0;
- const DELETE_PERM = 1;
- const DELETE_BLOCKED = 2;
- const DELETE_READONLY = 3;
- const DELETE_BADTOKEN = 4;
- const DELETE_BADARTICLE = 5;
-
- public static function delete(&$article, $token, &$reason = NULL)
- {
- global $wgUser;
-
- // Check permissions first
- if(!$article->mTitle->userCan('delete'))
- return self::DELETE_PERM;
- if($wgUser->isBlocked())
- return self::DELETE_BLOCKED;
- if(wfReadOnly())
- return self::DELETE_READONLY;
-
- // Check token
- if(!$wgUser->matchEditToken($token))
- return self::DELETE_BADTOKEN;
-
- // Auto-generate a summary, if necessary
- if(is_null($reason))
- {
- $reason = $article->generateReason($hasHistory);
- if($reason === false)
- return self::DELETE_BADARTICLE;
- }
-
- // Luckily, Article.php provides a reusable delete function that does the hard work for us
- if($article->doDeleteArticle($reason))
- return self::DELETE_SUCCESS;
- return self::DELETE_BADARTICLE;
- }
-
public function execute() {
global $wgUser;
$this->getMain()->requestWriteMode();
$r = array('title' => $titleObj->getPrefixedText(), 'reason' => $reason);
$this->getResult()->addValue(null, $this->getModuleName(), $r);
}
+
+ /**
+ * We have our own delete() function, since Article.php's implementation is split in two phases
+ *
+ * @param Article $article - Article object to work on
+ * @param string $token - Delete token (same as edit token)
+ * @param string $reason - Reason for the deletion. Autogenerated if NULL
+ * @return DELETE_SUCCESS on success, DELETE_* on failure
+ */
+ public static function delete(&$article, $token, &$reason = NULL)
+ {
+ global $wgUser;
+
+ // Check permissions first
+ if(!$article->mTitle->userCan('delete'))
+ return self::DELETE_PERM;
+ if($wgUser->isBlocked())
+ return self::DELETE_BLOCKED;
+ if(wfReadOnly())
+ return self::DELETE_READONLY;
+
+ // Check token
+ if(!$wgUser->matchEditToken($token))
+ return self::DELETE_BADTOKEN;
+
+ // Auto-generate a summary, if necessary
+ if(is_null($reason))
+ {
+ $reason = $article->generateReason($hasHistory);
+ if($reason === false)
+ return self::DELETE_BADARTICLE;
+ }
+
+ // Luckily, Article.php provides a reusable delete function that does the hard work for us
+ if($article->doDeleteArticle($reason))
+ return self::DELETE_SUCCESS;
+ return self::DELETE_BADARTICLE;
+ }
protected function getAllowedParams() {
return array (
}
/**
+ * API module that functions as a shortcut to the wikitext preprocessor. Expands
+ * any templates in a provided string, and returns the result of this expansion
+ * to the caller.
+ *
* @addtogroup API
*/
class ApiExpandTemplates extends ApiBase {
require_once ('ApiBase.php');
}
+/**
+ * API module to allow users to log out of the wiki. API equivalent of
+ * Special:Userlogout.
+ *
+ * @addtogroup API
+ */
class ApiLogout extends ApiBase {
public function __construct($main, $action) {
public function getVersion() {
return __CLASS__ . ': $Id$';
}
-}
\ No newline at end of file
+}
}
/**
+ * API module that facilitates the unblocking of users. Requires API write mode
+ * to be enabled.
+ *
* @addtogroup API
*/
class ApiUnblock extends ApiBase {
parent :: __construct($main, $action);
}
+ /**
+ * Unblocks the specified user or provides the reason the unblock failed.
+ */
public function execute() {
global $wgUser;
$this->getMain()->requestWriteMode();