492 lines
13 KiB
HTML
492 lines
13 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<head>
|
|
<title>
|
|
Bugzilla::Webservice::User</title>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
|
<link rel="stylesheet" title="style" type="text/css" href="../.././../../../style.css" media="all" >
|
|
|
|
</head>
|
|
<body id="pod">
|
|
<p class="backlinktop"><b><a name="___top" href="../../index.html" accesskey="1" title="All Documents"><<</a></b></p>
|
|
<h1>Bugzilla::Webservice::User</h1>
|
|
<div class='indexgroup'>
|
|
<ul class='indexList indexList1'>
|
|
<li class='indexItem indexItem1'><a href='#NAME'>NAME</a>
|
|
<li class='indexItem indexItem1'><a href='#DESCRIPTION'>DESCRIPTION</a>
|
|
<li class='indexItem indexItem1'><a href='#METHODS'>METHODS</a>
|
|
<ul class='indexList indexList2'>
|
|
<li class='indexItem indexItem2'><a href='#Logging_In_and_Out'>Logging In and Out</a>
|
|
<li class='indexItem indexItem2'><a href='#Account_Creation'>Account Creation</a>
|
|
<li class='indexItem indexItem2'><a href='#User_Info'>User Info</a>
|
|
</ul>
|
|
</ul>
|
|
</div>
|
|
|
|
<h1><a class='u' href='#___top' title='click to go to top of document'
|
|
name="NAME"
|
|
>NAME</a></h1>
|
|
|
|
<p>Bugzilla::Webservice::User - The User Account and Login API</p>
|
|
|
|
<h1><a class='u' href='#___top' title='click to go to top of document'
|
|
name="DESCRIPTION"
|
|
>DESCRIPTION</a></h1>
|
|
|
|
<p>This part of the Bugzilla API allows you to create User Accounts and log in/out using an existing account.</p>
|
|
|
|
<h1><a class='u' href='#___top' title='click to go to top of document'
|
|
name="METHODS"
|
|
>METHODS</a></h1>
|
|
|
|
<p>See <a href="../../Bugzilla/WebService.html" class="podlinkpod"
|
|
>Bugzilla::WebService</a> for a description of how parameters are passed,
|
|
and what <b>STABLE</b>,
|
|
<b>UNSTABLE</b>,
|
|
and <b>EXPERIMENTAL</b> mean.</p>
|
|
|
|
<h2><a class='u' href='#___top' title='click to go to top of document'
|
|
name="Logging_In_and_Out"
|
|
>Logging In and Out</a></h2>
|
|
|
|
<dl>
|
|
<dt><a name="login"
|
|
><code class="code">login</code></a></dt>
|
|
|
|
<dd>
|
|
<p><b>STABLE</b></p>
|
|
|
|
<dl>
|
|
<dt><a name="Description"
|
|
><b>Description</b></a></dt>
|
|
|
|
<dd>
|
|
<p>Logging in,
|
|
with a username and password,
|
|
is required for many Bugzilla installations,
|
|
in order to search for bugs,
|
|
post new bugs,
|
|
etc.
|
|
This method logs in an user.</p>
|
|
|
|
<dt><a name="Params"
|
|
><b>Params</b></a></dt>
|
|
|
|
<dd>
|
|
<dl>
|
|
<dt><a name="login_(string)_-_The_user's_login_name."
|
|
><code class="code">login</code> (string) - The user's login name.</a></dt>
|
|
|
|
<dd>
|
|
<dt><a name="password_(string)_-_The_user's_password."
|
|
><code class="code">password</code> (string) - The user's password.</a></dt>
|
|
|
|
<dd>
|
|
<dt><a
|
|
><code class="code">remember</code> (bool) <b>Optional</b> - if the cookies returned by the call to login should expire with the session or not.
|
|
In order for this option to have effect the Bugzilla server must be configured to allow the user to set this option - the Bugzilla parameter <i>rememberlogin</i> must be set to "defaulton" or "defaultoff".
|
|
Addionally,
|
|
the client application must implement management of cookies across sessions.</a></dt>
|
|
</dl>
|
|
|
|
<dt><a name="Returns"
|
|
><b>Returns</b></a></dt>
|
|
|
|
<dd>
|
|
<p>On success,
|
|
a hash containing one item,
|
|
<code class="code">id</code>,
|
|
the numeric id of the user that was logged in.
|
|
A set of http cookies is also sent with the response.
|
|
These cookies must be sent along with any future requests to the webservice,
|
|
for the duration of the session.</p>
|
|
|
|
<dt><a name="Errors"
|
|
><b>Errors</b></a></dt>
|
|
|
|
<dd>
|
|
<dl>
|
|
<dt><a name="300_(Invalid_Username_or_Password)"
|
|
>300 (Invalid Username or Password)</a></dt>
|
|
|
|
<dd>
|
|
<p>The username does not exist,
|
|
or the password is wrong.</p>
|
|
|
|
<dt><a name="301_(Account_Disabled)"
|
|
>301 (Account Disabled)</a></dt>
|
|
|
|
<dd>
|
|
<p>The account has been disabled.
|
|
A reason may be specified with the error.</p>
|
|
|
|
<dt><a name="50_(Param_Required)"
|
|
>50 (Param Required)</a></dt>
|
|
|
|
<dd>
|
|
<p>A login or password parameter was not provided.</p>
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
|
|
<dt><a name="logout"
|
|
><code class="code">logout</code></a></dt>
|
|
|
|
<dd>
|
|
<p><b>STABLE</b></p>
|
|
|
|
<dl>
|
|
<dt><a name="Description"
|
|
><b>Description</b></a></dt>
|
|
|
|
<dd>
|
|
<p>Log out the user.
|
|
Does nothing if there is no user logged in.</p>
|
|
|
|
<dt><a name="Params_(none)"
|
|
><b>Params</b> (none)</a></dt>
|
|
|
|
<dd>
|
|
<dt><a name="Returns_(nothing)"
|
|
><b>Returns</b> (nothing)</a></dt>
|
|
|
|
<dd>
|
|
<dt><a name="Errors_(none)"
|
|
><b>Errors</b> (none)</a></dt>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
|
|
<h2><a class='u' href='#___top' title='click to go to top of document'
|
|
name="Account_Creation"
|
|
>Account Creation</a></h2>
|
|
|
|
<dl>
|
|
<dt><a name="offer_account_by_email"
|
|
><code class="code">offer_account_by_email</code></a></dt>
|
|
|
|
<dd>
|
|
<p><b>STABLE</b></p>
|
|
|
|
<dl>
|
|
<dt><a name="Description"
|
|
><b>Description</b></a></dt>
|
|
|
|
<dd>
|
|
<p>Sends an email to the user,
|
|
offering to create an account.
|
|
The user will have to click on a URL in the email,
|
|
and choose their password and real name.</p>
|
|
|
|
<p>This is the recommended way to create a Bugzilla account.</p>
|
|
|
|
<dt><a name="Param"
|
|
><b>Param</b></a></dt>
|
|
|
|
<dd>
|
|
<dl>
|
|
<dt><a name="email_(string)_-_the_email_to_send_the_offer_to."
|
|
><code class="code">email</code> (string) - the email to send the offer to.</a></dt>
|
|
</dl>
|
|
|
|
<dt><a name="Returns_(nothing)"
|
|
><b>Returns</b> (nothing)</a></dt>
|
|
|
|
<dd>
|
|
<dt><a name="Errors"
|
|
><b>Errors</b></a></dt>
|
|
|
|
<dd>
|
|
<dl>
|
|
<dt><a name="500_(Illegal_Email_Address)"
|
|
>500 (Illegal Email Address)</a></dt>
|
|
|
|
<dd>
|
|
<p>This Bugzilla does not allow you to create accounts with the format of email address you specified.
|
|
Account creation may be entirely disabled.</p>
|
|
|
|
<dt><a name="501_(Account_Already_Exists)"
|
|
>501 (Account Already Exists)</a></dt>
|
|
|
|
<dd>
|
|
<p>An account with that email address already exists in Bugzilla.</p>
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
|
|
<dt><a name="create"
|
|
><code class="code">create</code></a></dt>
|
|
|
|
<dd>
|
|
<p><b>EXPERIMENTAL</b></p>
|
|
|
|
<dl>
|
|
<dt><a name="Description"
|
|
><b>Description</b></a></dt>
|
|
|
|
<dd>
|
|
<p>Creates a user account directly in Bugzilla,
|
|
password and all.
|
|
Instead of this,
|
|
you should use <a href="#offer_account_by_email" class="podlinkpod"
|
|
>"offer_account_by_email"</a> when possible,
|
|
because that makes sure that the email address specified can actually receive an email.
|
|
This function does not check that.</p>
|
|
|
|
<p>You must be logged in and have the <code class="code">editusers</code> privilege in order to call this function.</p>
|
|
|
|
<dt><a name="Params"
|
|
><b>Params</b></a></dt>
|
|
|
|
<dd>
|
|
<dl>
|
|
<dt><a name="email_(string)_-_The_email_address_for_the_new_user."
|
|
><code class="code">email</code> (string) - The email address for the new user.</a></dt>
|
|
|
|
<dd>
|
|
<dt><a name="full_name_(string)_Optional_-_The_user's_full_name._Will_be_set_to_empty_if_not_specified."
|
|
><code class="code">full_name</code> (string) <b>Optional</b> - The user's full name.
|
|
Will be set to empty if not specified.</a></dt>
|
|
|
|
<dd>
|
|
<dt><a
|
|
><code class="code">password</code> (string) <b>Optional</b> - The password for the new user account,
|
|
in plain text.
|
|
It will be stripped of leading and trailing whitespace.
|
|
If blank or not specified,
|
|
the newly created account will exist in Bugzilla,
|
|
but will not be allowed to log in using DB authentication until a password is set either by the user (through resetting their password) or by the administrator.</a></dt>
|
|
</dl>
|
|
|
|
<dt><a name="Returns"
|
|
><b>Returns</b></a></dt>
|
|
|
|
<dd>
|
|
<p>A hash containing one item,
|
|
<code class="code">id</code>,
|
|
the numeric id of the user that was created.</p>
|
|
|
|
<dt><a name="Errors"
|
|
><b>Errors</b></a></dt>
|
|
|
|
<dd>
|
|
<p>The same as <a href="#offer_account_by_email" class="podlinkpod"
|
|
>"offer_account_by_email"</a>.
|
|
If a password is specified,
|
|
the function may also throw:</p>
|
|
|
|
<dl>
|
|
<dt><a name="502_(Password_Too_Short)"
|
|
>502 (Password Too Short)</a></dt>
|
|
|
|
<dd>
|
|
<p>The password specified is too short.
|
|
(Usually,
|
|
this means the password is under three characters.)</p>
|
|
|
|
<dt><a name="503_(Password_Too_Long)"
|
|
>503 (Password Too Long)</a></dt>
|
|
|
|
<dd>
|
|
<p>The password specified is too long.
|
|
(Usually,
|
|
this means the password is over ten characters.)</p>
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
|
|
<h2><a class='u' href='#___top' title='click to go to top of document'
|
|
name="User_Info"
|
|
>User Info</a></h2>
|
|
|
|
<dl>
|
|
<dt><a name="get"
|
|
><code class="code">get</code></a></dt>
|
|
|
|
<dd>
|
|
<p><b>UNSTABLE</b></p>
|
|
|
|
<dl>
|
|
<dt><a name="Description"
|
|
><b>Description</b></a></dt>
|
|
|
|
<dd>
|
|
<p>Gets information about user accounts in Bugzilla.</p>
|
|
|
|
<dt><a name="Params"
|
|
><b>Params</b></a></dt>
|
|
|
|
<dd>
|
|
<p><b>Note</b>: At least one of <code class="code">ids</code>,
|
|
<code class="code">names</code>,
|
|
or <code class="code">match</code> must be specified.</p>
|
|
|
|
<p><b>Note</b>: Users will not be returned more than once,
|
|
so even if a user is matched by more than one argument,
|
|
only one user will be returned.</p>
|
|
|
|
<p>In addition to the parameters below,
|
|
this method also accepts the standard <a href="../../Bugzilla/WebService.html#include_fields" class="podlinkpod"
|
|
>include_fields</a> and <a href="../../Bugzilla/WebService.html#exclude_fields" class="podlinkpod"
|
|
>exclude_fields</a> arguments.</p>
|
|
|
|
<dl>
|
|
<dt><a name="ids_(array)"
|
|
><code class="code">ids</code> (array)</a></dt>
|
|
|
|
<dd>
|
|
<p>An array of integers,
|
|
representing user ids.</p>
|
|
|
|
<p>Logged-out users cannot pass this parameter to this function.
|
|
If they try,
|
|
they will get an error.
|
|
Logged-in users will get an error if they specify the id of a user they cannot see.</p>
|
|
|
|
<dt><a name="names_(array)_-_An_array_of_login_names_(strings)."
|
|
><code class="code">names</code> (array) - An array of login names (strings).</a></dt>
|
|
|
|
<dd>
|
|
<dt><a name="match_(array)"
|
|
><code class="code">match</code> (array)</a></dt>
|
|
|
|
<dd>
|
|
<p>An array of strings.
|
|
This works just like "user matching" in Bugzilla itself.
|
|
Users will be returned whose real name or login name contains any one of the specified strings.
|
|
Users that you cannot see will not be included in the returned list.</p>
|
|
|
|
<p>Some Bugzilla installations have user-matching turned off,
|
|
in which case you will only be returned exact matches.</p>
|
|
|
|
<p>Most installations have a limit on how many matches are returned for each string,
|
|
which defaults to 1000 but can be changed by the Bugzilla administrator.</p>
|
|
|
|
<p>Logged-out users cannot use this argument,
|
|
and an error will be thrown if they try.
|
|
(This is to make it harder for spammers to harvest email addresses from Bugzilla,
|
|
and also to enforce the user visibility restrictions that are implemented on some Bugzillas.)</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<dt><a name="Returns"
|
|
><b>Returns</b></a></dt>
|
|
|
|
<dd>
|
|
<p>A hash containing one item,
|
|
<code class="code">users</code>,
|
|
that is an array of hashes.
|
|
Each hash describes a user,
|
|
and has the following items:</p>
|
|
|
|
<dl>
|
|
<dt><a name="id"
|
|
>id</a></dt>
|
|
|
|
<dd>
|
|
<p><code class="code">int</code> The unique integer ID that Bugzilla uses to represent this user.
|
|
Even if the user's login name changes,
|
|
this will not change.</p>
|
|
|
|
<dt><a name="real_name"
|
|
>real_name</a></dt>
|
|
|
|
<dd>
|
|
<p><code class="code">string</code> The actual name of the user.
|
|
May be blank.</p>
|
|
|
|
<dt><a name="email"
|
|
>email</a></dt>
|
|
|
|
<dd>
|
|
<p><code class="code">string</code> The email address of the user.</p>
|
|
|
|
<dt><a name="name"
|
|
>name</a></dt>
|
|
|
|
<dd>
|
|
<p><code class="code">string</code> The login name of the user.
|
|
Note that in some situations this is different than their email.</p>
|
|
|
|
<dt><a name="can_login"
|
|
>can_login</a></dt>
|
|
|
|
<dd>
|
|
<p><code class="code">boolean</code> A boolean value to indicate if the user can login into bugzilla.</p>
|
|
|
|
<dt><a name="email_enabled"
|
|
>email_enabled</a></dt>
|
|
|
|
<dd>
|
|
<p><code class="code">boolean</code> A boolean value to indicate if bug-related mail will be sent to the user or not.</p>
|
|
|
|
<dt><a name="login_denied_text"
|
|
>login_denied_text</a></dt>
|
|
|
|
<dd>
|
|
<p><code class="code">string</code> A text field that holds the reason for disabling a user from logging into bugzilla,
|
|
if empty then the user account is enabled.
|
|
Otherwise it is disabled/closed.</p>
|
|
|
|
<p><b>Note</b>: If you are not logged in to Bugzilla when you call this function,
|
|
you will only be returned the <code class="code">id</code>,
|
|
<code class="code">name</code>,
|
|
and <code class="code">real_name</code> items.
|
|
If you are logged in and not in editusers group,
|
|
you will only be returned the <code class="code">id</code>,
|
|
<code class="code">name</code>,
|
|
<code class="code">real_name</code>,
|
|
<code class="code">email</code>,
|
|
and <code class="code">can_login</code> items.</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<dt><a name="Errors"
|
|
><b>Errors</b></a></dt>
|
|
|
|
<dd>
|
|
<dl>
|
|
<dt><a name="51_(Bad_Login_Name)"
|
|
>51 (Bad Login Name)</a></dt>
|
|
|
|
<dd>
|
|
<p>You passed an invalid login name in the "names" array.</p>
|
|
|
|
<dt><a name="304_(Authorization_Required)"
|
|
>304 (Authorization Required)</a></dt>
|
|
|
|
<dd>
|
|
<p>You are logged in,
|
|
but you are not authorized to see one of the users you wanted to get information about by user id.</p>
|
|
|
|
<dt><a name="505_(User_Access_By_Id_or_User-Matching_Denied)"
|
|
>505 (User Access By Id or User-Matching Denied)</a></dt>
|
|
|
|
<dd>
|
|
<p>Logged-out users cannot use the "ids" or "match" arguments to this function.</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<dt><a name="History"
|
|
><b>History</b></a></dt>
|
|
|
|
<dd>
|
|
<dl>
|
|
<dt><a name="Added_in_Bugzilla_3.4."
|
|
>Added in Bugzilla <b>3.4</b>.</a></dt>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
<p class="backlinkbottom"><b><a name="___bottom" href="../../index.html" title="All Documents"><<</a></b></p>
|
|
|
|
<!-- end doc -->
|
|
|
|
</body></html>
|