ApiMain Class Reference
[API]

This is the main API class, used for both external and internal processing. More...

Inherits ApiBase.

List of all members.

Public Member Functions

 __construct ($request, $enableWrite=false)
 Constructs an instance of ApiMain that utilizes the module and format specified by $request.
 isInternalMode ()
 Return true if the API was started by other PHP code using FauxRequest.
 getRequest ()
 Return the request object that contains client's request.
 getResult ()
 Get the ApiResult object asscosiated with current request.
 requestWriteMode ()
 Only kept for backwards compatibility.
 setCacheMaxAge ($maxage)
 Set how long the response should be cached.
 createPrinterByName ($format)
 Create an instance of an output formatter by its name.
 execute ()
 Execute api request.
 isReadMode ()
 Indicates whether this module requires read rights.
 getAllowedParams ()
 See ApiBase for description.
 getParamDescription ()
 See ApiBase for description.
 getDescription ()
 See ApiBase for description.
 makeHelpMsg ()
 Override the parent to generate help messages for all available modules.
 isBot ()
 Returns true if the currently logged in user is a bot, false otherwise OBSOLETE, use canApiHighLimits() instead.
 isSysop ()
 Similar to isBot(), this method returns true if the logged in user is a sysop, and false if not.
 canApiHighLimits ()
 Check whether the current user is allowed to use high limits.
 getShowVersions ()
 Check whether the user wants us to show version information in the API help.
 getVersion ()
 Returns the version information of this file, plus it includes the versions for all files that are not callable proper API modules.
 getModules ()
 Get the array mapping module names to class names.

Static Public Member Functions

static makeHelpMsgHeader ($module, $paramName)

Public Attributes

const API_DEFAULT_FORMAT = 'xmlfm'
 When no format parameter is given, this format will be used.

Protected Member Functions

 executeActionWithErrorHandling ()
 Execute an action, and in case of an error, erase whatever partial results have been accumulated, and replace it with an error message and a help screen.
 substituteResultWithError ($e)
 Replace the result data with the information about an exception.
 executeAction ()
 Execute the actual module, without any error handling.
 printResult ($isError)
 Print results using the current printer.
 getCredits ()
 Returns an array of strings with credits for the API.
 addModule ($mdlName, $mdlClass)
 Add or overwrite a module in this ApiMain instance.
 addFormat ($fmtName, $fmtClass)
 Add or overwrite an output format for this ApiMain.

Private Attributes

 $mPrinter
 $mModules
 $mModuleNames
 $mFormats
 $mFormatNames
 $mResult
 $mAction
 $mShowVersions
 $mEnableWrite
 $mRequest
 $mInternalMode
 $mSquidMaxage
 $mIsBot = null
 $mIsSysop = null
 $mCanApiHighLimits = null

Static Private Attributes

static $Modules
 List of available modules: action name => module class.
static $Formats
 List of available formats: format name => format class.
static $mRights
 List of user roles that are specifically relevant to the API.


Detailed Description

This is the main API class, used for both external and internal processing.

When executed, it will create the requested formatter object, instantiate and execute an object associated with the needed action, and use formatter to print results. In case of an exception, an error message will be printed using the same formatter.

To use API from another application, run it using FauxRequest object, in which case any internal exceptions will not be handled but passed up to the caller. After successful execution, use getResult() for the resulting data.

Definition at line 48 of file ApiMain.php.


Constructor & Destructor Documentation

ApiMain::__construct ( request,
enableWrite = false 
)

Constructs an instance of ApiMain that utilizes the module and format specified by $request.

Parameters:
$request object - if this is an instance of FauxRequest, errors are thrown and no printing occurs
$enableWrite bool should be set to true if the api may modify data

Definition at line 132 of file ApiMain.php.

References $wgAPIModules, $wgUser, and wfDebug().


Member Function Documentation

ApiMain::addFormat ( fmtName,
fmtClass 
) [protected]

Add or overwrite an output format for this ApiMain.

Intended for use by extending classes who wish to add to or modify current formatters.

Access:
protected
Parameters:
$fmtName The identifier for this format.
$fmtClass The class implementing this format.

Definition at line 686 of file ApiMain.php.

ApiMain::addModule ( mdlName,
mdlClass 
) [protected]

Add or overwrite a module in this ApiMain instance.

Intended for use by extending classes who wish to add their own modules to their lexicon or override the behavior of inherent ones.

Access:
protected
Parameters:
$mdlName String The identifier for this module.
$mdlClass String The class where this module is implemented.

Definition at line 674 of file ApiMain.php.

ApiMain::canApiHighLimits (  ) 

Check whether the current user is allowed to use high limits.

Returns:
bool

Definition at line 633 of file ApiMain.php.

References $wgUser.

ApiMain::createPrinterByName ( format  ) 

Create an instance of an output formatter by its name.

Definition at line 208 of file ApiMain.php.

References ApiBase::dieUsage().

Referenced by executeAction(), makeHelpMsg(), and substituteResultWithError().

ApiMain::execute (  ) 

Execute api request.

Any errors will be handled if the API was called by the remote client.

Reimplemented from ApiBase.

Definition at line 217 of file ApiMain.php.

References executeAction(), executeActionWithErrorHandling(), ApiBase::profileIn(), and ApiBase::profileOut().

ApiMain::executeAction (  )  [protected]

ApiMain::executeActionWithErrorHandling (  )  [protected]

Execute an action, and in case of an error, erase whatever partial results have been accumulated, and replace it with an error message and a help screen.

Definition at line 231 of file ApiMain.php.

References executeAction(), ApiBase::getParameter(), printResult(), setCacheMaxAge(), substituteResultWithError(), wfDebugLog(), wfReportTime(), and wfTimestamp().

Referenced by execute().

ApiMain::getAllowedParams (  ) 

See ApiBase for description.

Reimplemented from ApiBase.

Definition at line 458 of file ApiMain.php.

References API_DEFAULT_FORMAT, ApiBase::PARAM_DFLT, and ApiBase::PARAM_TYPE.

ApiMain::getCredits (  )  [protected]

Returns an array of strings with credits for the API.

Definition at line 533 of file ApiMain.php.

Referenced by makeHelpMsg().

ApiMain::getDescription (  ) 

See ApiBase for description.

Reimplemented from ApiBase.

Definition at line 502 of file ApiMain.php.

ApiMain::getModules (  ) 

Get the array mapping module names to class names.

Definition at line 693 of file ApiMain.php.

ApiMain::getParamDescription (  ) 

See ApiBase for description.

Reimplemented from ApiBase.

Definition at line 487 of file ApiMain.php.

ApiMain::getRequest (  ) 

Return the request object that contains client's request.

Definition at line 181 of file ApiMain.php.

Referenced by substituteResultWithError().

ApiMain::getResult (  ) 

Get the ApiResult object asscosiated with current request.

Reimplemented from ApiBase.

Definition at line 188 of file ApiMain.php.

Referenced by executeAction(), printResult(), and substituteResultWithError().

ApiMain::getShowVersions (  ) 

Check whether the user wants us to show version information in the API help.

Returns:
bool

Definition at line 646 of file ApiMain.php.

ApiMain::getVersion (  ) 

Returns the version information of this file, plus it includes the versions for all files that are not callable proper API modules.

Reimplemented from ApiBase.

Definition at line 654 of file ApiMain.php.

References ApiBase::getBaseVersion().

ApiMain::isBot (  ) 

Returns true if the currently logged in user is a bot, false otherwise OBSOLETE, use canApiHighLimits() instead.

Definition at line 607 of file ApiMain.php.

References $wgUser.

ApiMain::isInternalMode (  ) 

Return true if the API was started by other PHP code using FauxRequest.

Definition at line 174 of file ApiMain.php.

ApiMain::isReadMode (  ) 

Indicates whether this module requires read rights.

Returns:
bool

Reimplemented from ApiBase.

Definition at line 451 of file ApiMain.php.

ApiMain::isSysop (  ) 

Similar to isBot(), this method returns true if the logged in user is a sysop, and false if not.

OBSOLETE, use canApiHighLimits() instead

Definition at line 620 of file ApiMain.php.

References $wgUser.

ApiMain::makeHelpMsg (  ) 

Override the parent to generate help messages for all available modules.

Reimplemented from ApiBase.

Definition at line 549 of file ApiMain.php.

References $msg, createPrinterByName(), getCredits(), User::getGroupsWithPermission(), makeHelpMsgHeader(), and wfMsgReplaceArgs().

Referenced by substituteResultWithError().

static ApiMain::makeHelpMsgHeader ( module,
paramName 
) [static]

Definition at line 591 of file ApiMain.php.

Referenced by makeHelpMsg(), and ApiQuery::makeHelpMsgHelper().

ApiMain::printResult ( isError  )  [protected]

Print results using the current printer.

Definition at line 433 of file ApiMain.php.

References getResult().

Referenced by executeAction(), and executeActionWithErrorHandling().

ApiMain::requestWriteMode (  ) 

Only kept for backwards compatibility.

Deprecated:
Use isWriteMode() instead

Definition at line 196 of file ApiMain.php.

ApiMain::setCacheMaxAge ( maxage  ) 

Set how long the response should be cached.

Definition at line 201 of file ApiMain.php.

Referenced by executeActionWithErrorHandling().

ApiMain::substituteResultWithError ( e  )  [protected]

Replace the result data with the information about an exception.

Returns the error code

Definition at line 296 of file ApiMain.php.

References $wgShowExceptionDetails, $wgShowSQLErrors, createPrinterByName(), ApiBase::getParameter(), getRequest(), getResult(), makeHelpMsg(), and ApiResult::setContent().

Referenced by executeActionWithErrorHandling().


Member Data Documentation

ApiMain::$Formats [static, private]

Initial value:

 array (
                'json' => 'ApiFormatJson',
                'jsonfm' => 'ApiFormatJson',
                'php' => 'ApiFormatPhp',
                'phpfm' => 'ApiFormatPhp',
                'wddx' => 'ApiFormatWddx',
                'wddxfm' => 'ApiFormatWddx',
                'xml' => 'ApiFormatXml',
                'xmlfm' => 'ApiFormatXml',
                'yaml' => 'ApiFormatYaml',
                'yamlfm' => 'ApiFormatYaml',
                'rawfm' => 'ApiFormatJson',
                'txt' => 'ApiFormatTxt',
                'txtfm' => 'ApiFormatTxt',
                'dbg' => 'ApiFormatDbg',
                'dbgfm' => 'ApiFormatDbg'
        )
List of available formats: format name => format class.

Definition at line 88 of file ApiMain.php.

ApiMain::$mAction [private]

Definition at line 124 of file ApiMain.php.

ApiMain::$mCanApiHighLimits = null [private]

Definition at line 601 of file ApiMain.php.

ApiMain::$mEnableWrite [private]

Definition at line 124 of file ApiMain.php.

ApiMain::$mFormatNames [private]

Definition at line 123 of file ApiMain.php.

ApiMain::$mFormats [private]

Definition at line 123 of file ApiMain.php.

ApiMain::$mInternalMode [private]

Definition at line 124 of file ApiMain.php.

ApiMain::$mIsBot = null [private]

Definition at line 599 of file ApiMain.php.

ApiMain::$mIsSysop = null [private]

Definition at line 600 of file ApiMain.php.

ApiMain::$mModuleNames [private]

Definition at line 123 of file ApiMain.php.

ApiMain::$mModules [private]

Definition at line 123 of file ApiMain.php.

ApiMain::$Modules [static, private]

Initial value:

 array (
                'login' => 'ApiLogin',
                'logout' => 'ApiLogout',
                'query' => 'ApiQuery',
                'expandtemplates' => 'ApiExpandTemplates',
                'parse' => 'ApiParse',
                'opensearch' => 'ApiOpenSearch',
                'feedwatchlist' => 'ApiFeedWatchlist',
                'help' => 'ApiHelp',
                'paraminfo' => 'ApiParamInfo',

                
                'purge' => 'ApiPurge',
                'rollback' => 'ApiRollback',
                'delete' => 'ApiDelete',
                'undelete' => 'ApiUndelete',
                'protect' => 'ApiProtect',
                'block' => 'ApiBlock',
                'unblock' => 'ApiUnblock',
                'move' => 'ApiMove',
                'edit' => 'ApiEditPage',
                'emailuser' => 'ApiEmailUser',
                'watch' => 'ApiWatch',
                'patrol' => 'ApiPatrol',
                'import' => 'ApiImport',
        )
List of available modules: action name => module class.

Definition at line 58 of file ApiMain.php.

ApiMain::$mPrinter [private]

Definition at line 123 of file ApiMain.php.

ApiMain::$mRequest [private]

Definition at line 124 of file ApiMain.php.

ApiMain::$mResult [private]

Definition at line 124 of file ApiMain.php.

ApiMain::$mRights [static, private]

Initial value:

 array('writeapi' => array(
                                                'msg' => 'Use of the write API',
                                                'params' => array()
                                        ),
                                        'apihighlimits' => array(
                                                'msg' => 'Use higher limits in API queries (Slow queries: $1 results; Fast queries: $2 results). The limits for slow queries also apply to multivalue parameters.',
                                                'params' => array (ApiMain::LIMIT_SML2, ApiMain::LIMIT_BIG2)
                                        )
        )
List of user roles that are specifically relevant to the API.

array( 'right' => array ( 'msg' => 'Some message with a $1', 'params' => array ( $someVarToSubst ) ), );

Definition at line 112 of file ApiMain.php.

ApiMain::$mShowVersions [private]

Definition at line 124 of file ApiMain.php.

ApiMain::$mSquidMaxage [private]

Definition at line 124 of file ApiMain.php.

const ApiMain::API_DEFAULT_FORMAT = 'xmlfm'

When no format parameter is given, this format will be used.

Definition at line 53 of file ApiMain.php.

Referenced by getAllowedParams().


The documentation for this class was generated from the following file:

Generated on Sat Sep 5 02:08:31 2009 for MediaWiki by  doxygen 1.5.9