Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
{{Mark|Updated with Version 8.4}}: Support for multiple database patterns.
{{Mark|Updated with Version 8.4}}: Support for multiple database patterns.
{{Mark|Updated with Version 8.4}}: Support for multiple database patterns.
|-
|{{Code|admin}}
|The "admin" user cannot be modified.
|-
|{{Code|equal}}
|Name of old and new user is equal.
|-
|{{Code|local}}
|A local permission can only be 'none', 'read' or 'write'.
|-
|{{Code|logged-in}}
|The specified user is currently logged in.
|-
|{{Code|conflict}}
|A user cannot be both altered and dropped.
no edit summary
=Conventions=
All functions and errors in this module and errors are assigned to the <code><nowiki>http://basex.org/modules/user</nowiki></code> namespace, which is statically bound to the {{Code|user}} prefix.<br/>
=Read Operations=
|-
| '''Examples'''
|* If the GUI or the standalone mode is used, {{Code|user:current()}} always returns {{Code|admin}}.
|}
|-
| '''Summary'''
|Returns the names of all registered usersthat are visible to the current user.
|-
| '''Examples'''
|
* After a fresh installation, {{Code|user:list()}} returns all registered userswill only return {{Code|admin}}.
|}
|-
| '''Summary'''
|Returns an element sequence, containing all registered users and their permissionsthat are visible to the current user.<br/>In addition to the [[Commands#SHOW_USERS|SHOW USERS]] command, encoded password strings and database permissions will be output. A user {{Code|$name}} can be specified to filter the results in advance.
|-
| '''Examples'''
|
* By defaultAfter a fresh installation, {{Code|user:list-details()}} returns output similar to the following outputone:<pre classsyntaxhighlight lang="brush:xml">
<user name="admin" permission="admin">
<password algorithm="digest">
</password>
</user>
</presyntaxhighlight>
|-
| '''Errors'''
| '''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|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)}}<br/>{{Func|user:info|$name as xs:string|element(info)}}
|-
| '''Summary'''
|Returns an <code>info</code> element, which may contain application-specific data. If a user {{Code|$name}} is supplied, a user-specific element is returned. By default, the returned 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>.
|}
==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()}}<br/>{{Func|user:create|$name as xs:string, $password as xs:string, $permissions as xs:string*, $patterns as xs:string*, $info as element(info)|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 (.* An {{Code|none$info}}element with application-specific information can be supplied.* 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 read permissions for databases starting with the letters 'index'.
|-
| '''Errors'''
==user:grant==
{| width='100%'
==user:drop==
{| width='100%'
|-
| '''Summary'''
|Drops a user with the specified {{Code|$name}}. If non-empty glob {{Code|$patterns}} are specified, only the database patterns will be droppedremoved.
|-
| '''Examples'''
| '''Examples'''
|
* {{Code|user:renamealter('John', 'Jack')}} renames the user 'John' to 'Jack'.
|-
| '''Errors'''
| '''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()}}<br/>{{Func|user:update-info|$info as element(info), $name as xs:string|empty-sequence()}}
|-
| '''Summary'''
|Assigns the specified {{Code|$info}} element to the user management or, if {{Code|$name}} is supplied, to a specific user. This function can be used to manage application-specific data (groups, enhanced user info, etc.).
|-
| '''Examples'''
|
* Store initial groups information:
<syntaxhighlight lang="xquery">
user:update-info(element info {
for $group in ('editor', 'author', 'writer')
return element group { $group }
})
</syntaxhighlight>
* Add a group to a specific user:
<syntaxhighlight lang="xquery">
user:update-info(<info group='editor'/>, 'john')
</syntaxhighlight>
|}
! width="110"|Code
|Description
|-
|{{Code|admin}}
|The "admin" user cannot be modified.
|-
|{{Code|conflict}}
|A user cannot be both altered and dropped.
|-
|{{Code|equal}}
|Name of old and new user is equal.
|-
|{{Code|local}}
|A local permission can only be 'none', 'read' or 'write'.
|-
|{{Code|logged-in}}
|The specified user is currently logged in.
|-
|{{Code|name}}
|The specified user name is invalid.
|-
|{{Code|password}}
|The specified password is wrong.
|-
|{{Code|pattern}}
|{{Code|unknown}}
|The specified user does not exist.
|-
|{{Code|update}}
|The operation can only be performed once per user or database pattern.
|}
=Changelog=
;Version 8.6
* Updated: [[#user:create|user:create]], [[#user:info|user:info]], [[#user:update-info|user:update-info]]: {{Code|$name}} parameter added.
;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 multiple database patterns.
;Version 8.1
