Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
[[Category:XQuery]]
no edit summary
=Conventions=
All functions and errors in this module are assigned to the {{Code|<code><nowiki>http://basex.org/modules/user}} </nowiki></code> namespace, which is statically bound to the {{Code|user}} prefix.<br/>All errors are assigned to the {{Code|http://basex.org/errors}} namespace, which is statically bound to the {{Code|bxerr}} prefix.
=FunctionsRead Operations= ==user:current== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|user:current||xs:string}}<br/>|-| '''Summary'''|Returns the name of the currently logged in user.|-| '''Examples'''|* If the GUI or the standalone mode is used, {{Code|user:current()}} always returns {{Code|admin}}.|}
==user:list==
|-
| '''Summary'''
|Returns the names of all registered usersthat are visible to the current user.
|-
| '''Examples'''
|
* After a fresh installation, {{Code|adminuser:list()}} returns all registered userswill only return {{Code|admin}}.
|}
|-
| width='120' | '''Signatures'''
|{{Func|user:list-details||element(user)*}}<br/>{{Func|user:list-details|$name as xs:string|element(user)*}}<br/>
|-
| '''Summary'''
|Returns an element sequence, containing all registered users, their permissions, and their encoded password stringsthat are visible to the current user.<br/>The In addition to the [[Commands#SHOW_USERS|SHOW USERS]] command yields similar , encoded password strings and database permissions will be output. A user {{Code|$name}} can be specified to filter the results in advance.
|-
| '''Examples'''
|
* After a fresh installation, {{Code|adminuser:list-details()}} returns information on all registered users. By default, it returns output similar to the following outputone:<br/>
<pre class="brush:xml">
<user name="admin" permission="admin">
</password>
</user>
</pre>
|-
| '''Errors'''
|{{Error|unknown|#Errors}} The specified user name is unknown.
|}
==user:exists==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|user:exists|$name as xs:string|xs:boolean}}<br/>
|-
| '''Summary'''
|Checks if a user with the specified {{Code|$name}} exists.
|-
| '''Examples'''
|
* {{Code|user:exists('admin')}} will always yield true.
|-
| '''Errors'''
|{{Error|name|#Errors}} The specified user name is invalid.
|}
==user:check==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|user:check|$name as xs:string, $password as xs:string|xs:empty-sequence()}}<br/>
|-
| '''Summary'''
|Checks if the specified user and password is correct. Raises errors otherwise.
|-
| '''Examples'''
|
* {{Code|user:check('admin', 'admin')}} will raise an error if the admin password was changed.
|-
| '''Errors'''
|{{Error|name|#Errors}} The specified user name is invalid.<br/>{{Error|unknown|#Errors}} The specified user does not exist.<br/>{{Error|password|#Errors}} The specified password is wrong.<br/>
|}
==user:info==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|user:info||element(info)}}
|-
| '''Summary'''
|Returns an <code>info</code> element, which can be used to organize application-specific data. By default, the element has no contents. It can be modified via [[#user:update-info|user:update-info]].
|-
| '''Examples'''
|
* After a fresh installation, {{Code|user:info()}} returns <code><info/></code>.
|}
=Updates=
'''Important note:''' All functions in this section are ''updating functions'': they will not be immediately executed, but queued on the [[XQuery Update#Pending Update List|Pending Update List]], which will be processed after the actual query has been evaluated. This means that the order in which the functions are specified in the query does usually not reflect the order in which the code will be evaluated.
==user:create==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|user:create|$name as xs:string, $password as xs:string|empty-sequence()}}<br/>{{Func|user:create|$name as xs:string, $password as xs:string, $permissions as xs:string*|empty-sequence()}}<br/>{{Func|user:create|$name as xs:string, $password as xs:string, $permissions as xs:string*, $patterns as xs:string*|empty-sequence()}}
|-
| '''Summary'''
|Creates a new user with the specified {{Code|$name}}, {{Code|$password}}, and {{Code|$permissions}}. Local permissions are granted with non-empty glob {{Code|$patterns}}. The default global permission (''none'') can be overwritten with an empty pattern or by omitting the last argument. Existing users will be overwritten.
|-
| '''Examples'''
|
* {{Code|user:create('John', '7e$j#!1', 'admin')}} creates a new user 'John' with admin permissions.
* {{Code|user:create('Jack', 'top!secret', 'read', 'index*')}} creates a new user 'Jack' with no permissions, but write permissions for databases starting with the letters 'index'.
|-
| '''Errors'''
|{{Error|name|#Errors}} The specified user name is invalid.<br/>{{Error|permission|#Errors}} The specified permission is invalid.<br/>{{Error|admin|#Errors}} The "admin" user cannot be modified.<br/>{{Error|logged-in|#Errors}} The specified user is currently logged in.<br/>{{Error|update|#Errors}} The operation can only be performed once per user or database pattern.
|}
==user:grant==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|user:grant|$name as xs:string, $permissions as xs:string*|empty-sequence()}}<br/>{{Func|user:grant|$name as xs:string, $permissions as xs:string*, $patterns as xs:string*|empty-sequence()}}
|-
| '''Summary'''
|Grants global or local {{Code|$permissions}} to a user with the specified {{Code|$name}}. Local permissions are granted with non-empty glob {{Code|$patterns}}.
|-
| '''Examples'''
|
* {{Code|user:grant('John', 'create')}} grants create permissions to the user 'John'.
* {{Code|user:grant('John', ('read','write'), ('index*','unit*'))}} allows John to read all databases starting with the letters 'index', and to write to all databases starting with 'unit'.
|-
| '''Errors'''
|{{Error|unknown|#Errors}} The specified user name is unknown.<br/>{{Error|name|#Errors}} The specified user name is invalid.<br/>{{Error|pattern|#Errors}} The specified database pattern is invalid.<br/>{{Error|permission|#Errors}} The specified permission is invalid.<br/>{{Error|admin|#Errors}} The "admin" user cannot be modified.<br/>{{Error|local|#Errors}} A local permission can only be 'none', 'read' or 'write'.<br/>{{Error|logged-in|#Errors}} The specified user is currently logged in.<br/>{{Error|update|#Errors}} The operation can only be performed once per user or database pattern.
|}
==user:drop==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|user:drop|$name as xs:string|empty-sequence()}}<br/>{{Func|user:drop|$name as xs:string, $patterns as xs:string*|empty-sequence()}}
|-
| '''Summary'''
|Drops a user with the specified {{Code|$name}}. If non-empty glob {{Code|$patterns}} are specified, only the database patterns will be dropped.
|-
| '''Examples'''
|
* {{Code|user:drop('John')}} drops the user 'John'.
* {{Code|user:grant('John', 'unit*')}} removes the 'unit*' database pattern. If John accesses any of these database, his global permission will be checked again.
|-
| '''Errors'''
|{{Error|unknown|#Errors}} The specified user name is unknown.<br/>{{Error|name|#Errors}} The specified user name is invalid.<br/>{{Error|pattern|#Errors}} The specified database pattern is invalid.<br/>{{Error|admin|#Errors}} The "admin" user cannot be modified.<br/>{{Error|logged-in|#Errors}} The specified user is currently logged in.<br/>{{Error|update|#Errors}} The operation can only be performed once per user or database pattern.<br/>{{Error|conflict|#Errors}} A user cannot be both altered and dropped.
|}
==user:alter==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|user:alter|$name as xs:string, $newname as xs:string|empty-sequence()}}
|-
| '''Summary'''
|Renames a user with the specified {{Code|$name}} to {{Code|$newname}}.
|-
| '''Examples'''
|
* {{Code|user:rename('John', 'Jack')}} renames the user 'John' to 'Jack'.
|-
| '''Errors'''
|{{Error|unknown|#Errors}} The specified user name is unknown.<br/>{{Error|name|#Errors}} The specified user name is invalid.<br/>{{Error|admin|#Errors}} The "admin" user cannot be modified.<br/>{{Error|logged-in|#Errors}} The specified user is currently logged in.<br/>{{Error|update|#Errors}} The operation can only be performed once per user or database pattern.<br/>{{Error|conflict|#Errors}} A user cannot be both altered and dropped.
|}
==user:password==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|user:password|$name as xs:string, $password as xs:string|empty-sequence()}}
|-
| '''Summary'''
|Changes the {{Code|password}} of a user with the specified {{Code|$name}}.
|-
| '''Examples'''
|
* {{Code|user:password('John', '')}} assigns user 'John' an empty password string.
|-
| '''Errors'''
|{{Error|unknown|#Errors}} The specified user name is unknown.<br/>{{Error|name|#Errors}} The specified user name is invalid.<br/>{{Error|update|#Errors}} The operation can only be performed once per user or database pattern.
|}
==user:update-info==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|user:update-info|$info as element(info)|empty-sequence()}}
|-
| '''Summary'''
|Updates the <code>info</code> element with {{Code|$info}}. This node can be used to organize application-specific data (groups, enhanced user info, etc.).
|-
| '''Examples'''
|
* Store initial groups information:
<pre class="brush:xquery">
user:update-info(element info {
for $group in ('editor', 'author', 'writer')
return element group { $group }
})
</pre>
* Assign a group to a new user:
<pre class="brush:xquery">
let $user := 'john', $pw := '8hKJ@%.c/!0O', $group := 'editor'
return (
user:create($user, $pw),
user:update-info(user:info() update
insert node <user name='{ $user }' group='{ $group }'/> into .
)
)
</pre>
|}
|Description
|-
|{{Code|BXUS0001admin}}|The specified "admin" user name is invalidcannot be modified.|-|{{Code|conflict}}|A user cannot be both altered and dropped.
|-
|{{Code|BXUS0002equal}}|The specified database name Name of old and new user is invalidequal.
|-
|{{Code|BXUS0003local}}|The specified A local permission is invalidcan only be 'none', 'read' or 'write'.
|-
|{{Code|BXUS0004logged-in}}|The specified user does not existis currently logged in.
|-
|{{Code|BXUS0005name}}|The "admin" specified user cannot be modifiedname is invalid.
|-
|{{Code|BXUS0006password}}|Name of old and new user The specified password is equalwrong.
|-
|{{Code|BXUS0007pattern}}|A local permission can only be 'none', 'read' or 'write'The specified database name is invalid.
|-
|{{Code|BXUS0008permission}}|A The specified user permission is currently logged ininvalid.
|-
|{{Code|BXUS0009unknown}}|A The specified user, or its associated permission, can only be created, modified or dropped oncedoes not exist.
|-
|{{Code|BXUS0010update}}|A The operation can only be performed once per user cannot be both altered and droppedor database pattern.
|}
=Changelog=
;Version 8.6
* Added: [[#user:check|user:check]], [[#user:info|user:info]], [[#user:update-info|user:update-info]].
* Updated: [[#user:list|user:list]], [[#user:list-details|user:list-details]]: If called by non-admins, will only return the current user.
;Version 8.4
* Updated: [[#user:create|user:create]], [[#user:grant|user:grant]], [[#user:drop|user:drop]]: extended support for database patterns.
;Version 8.1
* Added: [[#user:current|user:current]].
The Module was introduced with Version 8.0.
