# MumbleServer::Server

## Overview

### [ "amd" ] interface Server

Per-server interface. This includes all methods for configuring and altering the state of a single virtual server. You can retrieve a pointer to this interface from one of the methods in Meta.

## Operation Index

isRunning
  Shows if the server currently running (accepting users).
start
  Start server.
stop
  Stop server.
delete
  Delete server and all it's configuration.
id
  Fetch the server id.
addCallback
  Add a callback.
removeCallback
  Remove a callback.
setAuthenticator
  Set external authenticator.
getConf
  Retrieve configuration item.
getAllConf
  Retrieve all configuration items.
setConf
  Set a configuration item.
setSuperuserPassword
  Set superuser password.
getLog
  Fetch log entries.
getLogLen
  Fetch length of log @return Number of entries in log
getUsers
  Fetch all users.
getChannels
  Fetch all channels.
getCertificateList
  Fetch certificate of user.
getTree
  Fetch all channels and connected users as a tree.
getBans
  Fetch all current IP bans on the server.
setBans
  Set all current IP bans on the server.
kickUser
  Kick a user.
getState
  Get state of a single connected user.
setState
  Set user state.
sendMessage
  Send text message to a single user.
hasPermission
  Check if user is permitted to perform action.
effectivePermissions
  Return users effective permissions @param session Connection ID of user.
addContextCallback
  Add a context callback.
removeContextCallback
  Remove a callback.
getChannelState
  Get state of single channel.
setChannelState
  Set state of a single channel.
removeChannel
  Remove a channel and all its subchannels.
addChannel
  Add a new channel.
sendMessageChannel
  Send text message to channel or a tree of channels.
getACL
  Retrieve ACLs and Groups on a channel.
setACL
  Set ACLs and Groups on a channel.
addUserToGroup
  Temporarily add a user to a group on a channel.
removeUserFromGroup
  Remove a user from a temporary group membership on a channel.
redirectWhisperGroup
  Redirect whisper targets for user.
getUserNames
  Map a list of User::userid to a matching name.
getUserIds
  Map a list of user names to a matching id.
registerUser
  Register a new user.
unregisterUser
  Remove a user registration.
updateRegistration
  Update the registration for a user.
getRegistration
  Fetch registration for a single user.
getRegisteredUsers
  Fetch a group of registered users.
verifyPassword
  Verify the password of a user.
getTexture
  Fetch user texture.
setTexture
  Set a user texture (now called avatar).
getUptime
  Get virtual server uptime.
updateCertificate
  Update the server's certificate information.
startListening
  Makes the given user start listening to the given channel.
stopListening
  Makes the given user stop listening to the given channel.
isListening
  @param userid The ID of the user @param channelid The ID of the channel @returns Whether the given user is currently listening to the given channel
getListeningChannels
  @param userid The ID of the user @returns An ID-list of channels the given user is listening to
getListeningUsers
  @param channelid The ID of the channel @returns An ID-list of users listening to the given channel
getListenerVolumeAdjustment
  @param channelid The ID of the channel @param userid The ID of the user @returns The volume adjustment set for a listener of the given user in the given channel
setListenerVolumeAdjustment
  Sets the volume adjustment set for a listener of the given user in the given channel @param channelid The ID of the channel @param userid The ID of the user
sendWelcomeMessage
  @param receiverUserIDs list of IDs of the users the message shall be sent to

## Operations

### bool isRunning() throws InvalidSecretException

Shows if the server currently running (accepting users).

#### Return Value

Run-state of server.

### void start() throws ServerBootedException, ServerFailureException, InvalidSecretException

Start server.

### void stop() throws ServerBootedException, InvalidSecretException

Stop server. Note: Server will be restarted on Murmur restart unless explicitly disabled with setConf("boot", false)

### void delete() throws ServerBootedException, InvalidSecretException

Delete server and all it's configuration.

### int id() throws InvalidSecretException

Fetch the server id.

#### Return Value

Unique server id.

### void addCallback(ServerCallback* cb) throws ServerBootedException, InvalidCallbackException, InvalidSecretException

Add a callback. The callback will receive notifications about changes to users and channels.

#### Parameters

cb
  Callback interface which will receive notifications.

#### See Also

removeCallback

### void removeCallback(ServerCallback* cb) throws ServerBootedException, InvalidCallbackException, InvalidSecretException

Remove a callback.

#### Parameters

cb
  Callback interface to be removed.

#### See Also

addCallback

### void setAuthenticator(ServerAuthenticator* auth) throws ServerBootedException, InvalidCallbackException, InvalidSecretException

Set external authenticator. If set, all authentications from clients are forwarded to this proxy.

#### Parameters

auth
  Authenticator object to perform subsequent authentications.

### string getConf(string key) throws InvalidSecretException, WriteOnlyException

Retrieve configuration item.

#### Parameters

key
  Configuration key.

#### Return Value

Configuration value. If this is empty, see Meta::getDefaultConf

### ConfigMap getAllConf() throws InvalidSecretException

Retrieve all configuration items.

#### Return Value

All configured values. If a value isn't set here, the value from Meta::getDefaultConf is used.

### void setConf(string key, string value) throws InvalidSecretException

Set a configuration item.

#### Parameters

key
  Configuration key.
value
  Configuration value.

### void setSuperuserPassword(string pw) throws InvalidSecretException

Set superuser password. This is just a convenience for using updateRegistration on user id 0.

#### Parameters

pw
  Password.

### LogList getLog(int first, int last) throws InvalidSecretException

Fetch log entries.

#### Parameters

first
  Lowest numbered entry to fetch. 0 is the most recent item.
last
  Last entry to fetch.

#### Return Value

List of log entries.

### int getLogLen() throws InvalidSecretException

Fetch length of log

#### Return Value

Number of entries in log

### UserMap getUsers() throws ServerBootedException, InvalidSecretException

Fetch all users. This returns all currently connected users on the server.

#### Return Value

List of connected users.

#### See Also

getState

### ChannelMap getChannels() throws ServerBootedException, InvalidSecretException

Fetch all channels. This returns all defined channels on the server. The root channel is always channel 0.

#### Return Value

List of defined channels.

#### See Also

getChannelState

### CertificateList getCertificateList(int session) throws ServerBootedException, InvalidSessionException, InvalidSecretException

Fetch certificate of user. This returns the complete certificate chain of a user.

#### Parameters

session
  Connection ID of user. See User::session.

#### Return Value

Certificate list of user.

### Tree getTree() throws ServerBootedException, InvalidSecretException

Fetch all channels and connected users as a tree. This retrieves an easy-to-use representation of the server as a tree. This is primarily used for viewing the state of the server on a webpage.

#### Return Value

Recursive tree of all channels and connected users.

### BanList getBans() throws ServerBootedException, InvalidSecretException

Fetch all current IP bans on the server.

#### Return Value

List of bans.

### void setBans(BanList bans) throws ServerBootedException, InvalidSecretException

Set all current IP bans on the server. This will replace any bans already present, so if you want to add a ban, be sure to call getBans and then append to the returned list before calling this method.

#### Parameters

bans
  List of bans.

### void kickUser(int session, string reason) throws ServerBootedException, InvalidSessionException, InvalidSecretException

Kick a user. The user is not banned, and is free to rejoin the server.

#### Parameters

session
  Connection ID of user. See User::session.
reason
  Text message to show when user is kicked.

### User getState(int session) throws ServerBootedException, InvalidSessionException, InvalidSecretException

Get state of a single connected user.

#### Parameters

session
  Connection ID of user. See User::session.

#### Return Value

State of connected user.

#### See Also

setState
getUsers

### void setState(User state) throws ServerBootedException, InvalidSessionException, InvalidChannelException, InvalidSecretException

Set user state. You can use this to move, mute and deafen users.

#### Parameters

state
  User state to set.

#### See Also

getState

### void sendMessage(int session, string text) throws ServerBootedException, InvalidSessionException, InvalidSecretException

Send text message to a single user.

#### Parameters

session
  Connection ID of user. See User::session.
text
  Message to send.

#### See Also

sendMessageChannel

### bool hasPermission(int session, int channelid, int perm) throws ServerBootedException, InvalidSessionException, InvalidChannelException, InvalidSecretException

Check if user is permitted to perform action.

#### Parameters

session
  Connection ID of user. See User::session.
channelid
  ID of Channel. See Channel::id.
perm
  Permission bits to check.

#### Return Value

true if any of the permissions in perm were set for the user.

### int effectivePermissions(int session, int channelid) throws ServerBootedException, InvalidSessionException, InvalidChannelException, InvalidSecretException

Return users effective permissions

#### Parameters

session
  Connection ID of user. See User::session.
channelid
  ID of Channel. See Channel::id.

#### Return Value

bitfield of allowed actions

### void addContextCallback(int session, string action, string text, ServerContextCallback* cb, int ctx) throws ServerBootedException, InvalidCallbackException, InvalidSecretException

Add a context callback. This is done per user, and will add a context menu action for the user.

#### Parameters

session
  Session of user which should receive context entry.
action
  Action string, a unique name to associate with the action.
text
  Name of action shown to user.
cb
  Callback interface which will receive notifications.
ctx
  Context this should be used in. Needs to be one or a combination of ContextServer, ContextChannel and ContextUser.

#### See Also

removeContextCallback

### void removeContextCallback(ServerContextCallback* cb) throws ServerBootedException, InvalidCallbackException, InvalidSecretException

Remove a callback.

#### Parameters

cb
  Callback interface to be removed. This callback will be removed from all from all users.

#### See Also

addContextCallback

### Channel getChannelState(int channelid) throws ServerBootedException, InvalidChannelException, InvalidSecretException

Get state of single channel.

#### Parameters

channelid
  ID of Channel. See Channel::id.

#### Return Value

State of channel.

#### See Also

setChannelState
getChannels

### void setChannelState(Channel state) throws ServerBootedException, InvalidChannelException, InvalidSecretException, NestingLimitException

Set state of a single channel. You can use this to move or relink channels.

#### Parameters

state
  Channel state to set.

#### See Also

getChannelState

### void removeChannel(int channelid) throws ServerBootedException, InvalidChannelException, InvalidSecretException

Remove a channel and all its subchannels.

#### Parameters

channelid
  ID of Channel. See Channel::id.

### int addChannel(string name, int parent) throws ServerBootedException, InvalidChannelException, InvalidSecretException, NestingLimitException

Add a new channel.

#### Parameters

name
  Name of new channel.
parent
  Channel ID of parent channel. See Channel::id.

#### Return Value

ID of newly created channel.

### void sendMessageChannel(int channelid, bool tree, string text) throws ServerBootedException, InvalidChannelException, InvalidSecretException

Send text message to channel or a tree of channels.

#### Parameters

channelid
  Channel ID of channel to send to. See Channel::id.
tree
  If true, the message will be sent to the channel and all its subchannels.
text
  Message to send.

#### See Also

sendMessage

### void getACL(int channelid, out ACLList acls, out GroupList groups, out bool inherit) throws ServerBootedException, InvalidChannelException, InvalidSecretException

Retrieve ACLs and Groups on a channel.

#### Parameters

channelid
  Channel ID of channel to fetch from. See Channel::id.
acls
  List of ACLs on the channel. This will include inherited ACLs.
groups
  List of groups on the channel. This will include inherited groups.
inherit
  Does this channel inherit ACLs from the parent channel?

### void setACL(int channelid, ACLList acls, GroupList groups, bool inherit) throws ServerBootedException, InvalidChannelException, InvalidSecretException

Set ACLs and Groups on a channel. Note that this will replace all existing ACLs and groups on the channel.

#### Parameters

channelid
  Channel ID of channel to fetch from. See Channel::id.
acls
  List of ACLs on the channel.
groups
  List of groups on the channel.
inherit
  Should this channel inherit ACLs from the parent channel?

### void addUserToGroup(int channelid, int session, string group) throws ServerBootedException, InvalidChannelException, InvalidSessionException, InvalidSecretException

Temporarily add a user to a group on a channel. This state is not saved, and is intended for temporary memberships.

#### Parameters

channelid
  Channel ID of channel to add to. See Channel::id.
session
  Connection ID of user. See User::session.
group
  Group name to add to.

### void removeUserFromGroup(int channelid, int session, string group) throws ServerBootedException, InvalidChannelException, InvalidSessionException, InvalidSecretException

Remove a user from a temporary group membership on a channel. This state is not saved, and is intended for temporary memberships.

#### Parameters

channelid
  Channel ID of channel to add to. See Channel::id.
session
  Connection ID of user. See User::session.
group
  Group name to remove from.

### void redirectWhisperGroup(int session, string source, string target) throws ServerBootedException, InvalidSessionException, InvalidSecretException

Redirect whisper targets for user. If set, whenever a user tries to whisper to group "source", the whisper will be redirected to group "target". To remove a redirect pass an empty target string. This is intended for context groups.

#### Parameters

session
  Connection ID of user. See User::session.
source
  Group name to redirect from.
target
  Group name to redirect to.

### NameMap getUserNames(IdList ids) throws ServerBootedException, InvalidSecretException

Map a list of User::userid to a matching name.

#### Parameters

List
  of ids.

#### Return Value

Matching list of names, with an empty string representing invalid or unknown ids.

### IdMap getUserIds(NameList names) throws ServerBootedException, InvalidSecretException

Map a list of user names to a matching id. @reuturn List of matching ids, with -1 representing invalid or unknown user names.

#### Parameters

List
  of names.

### int registerUser(UserInfoMap info) throws ServerBootedException, InvalidUserException, InvalidSecretException

Register a new user.

#### Parameters

info
  Information about new user. Must include at least "name".

#### Return Value

The ID of the user. See `RegisteredUser::userid`.

### void unregisterUser(int userid) throws ServerBootedException, InvalidUserException, InvalidSecretException

Remove a user registration.

#### Parameters

userid
  ID of registered user. See `RegisteredUser::userid`.

### void updateRegistration(int userid, UserInfoMap info) throws ServerBootedException, InvalidUserException, InvalidSecretException

Update the registration for a user. You can use this to set the email or password of a user, and can also use it to change the user's name.

#### Parameters

registration
  Updated registration record.

### UserInfoMap getRegistration(int userid) throws ServerBootedException, InvalidUserException, InvalidSecretException

Fetch registration for a single user.

#### Parameters

userid
  ID of registered user. See `RegisteredUser::userid`.

#### Return Value

Registration record.

### NameMap getRegisteredUsers(string filter) throws ServerBootedException, InvalidSecretException

Fetch a group of registered users.

#### Parameters

filter
  Substring of user name. If blank, will retrieve all registered users.

#### Return Value

List of registration records.

### int verifyPassword(string name, string pw) throws ServerBootedException, InvalidSecretException

Verify the password of a user. You can use this to verify a user's credentials.

#### Parameters

name
  User name. See `RegisteredUser::name`.
pw
  User password.

#### Return Value

User ID of registered user (See `RegisteredUser::userid`), -1 for failed authentication or -2 for unknown usernames.

### Texture getTexture(int userid) throws ServerBootedException, InvalidUserException, InvalidSecretException

Fetch user texture. Textures are stored as zlib compress()ed 600x60 32-bit BGRA data.

#### Parameters

userid
  ID of registered user. See `RegisteredUser::userid`.

#### Return Value

Custom texture associated with user or an empty texture.

### void setTexture(int userid, Texture tex) throws ServerBootedException, InvalidUserException, InvalidTextureException, InvalidSecretException

Set a user texture (now called avatar).

#### Parameters

userid
  ID of registered user. See `RegisteredUser::userid`.
tex
  Texture (as a Byte-Array) to set for the user, or an empty texture to remove the existing texture.

### int getUptime() throws ServerBootedException, InvalidSecretException

Get virtual server uptime.

#### Return Value

Uptime of the virtual server in seconds

### void updateCertificate(string certificate, string privateKey, string passphrase) throws ServerBootedException, InvalidSecretException, InvalidInputDataException

Update the server's certificate information. Reconfigure the running server's TLS socket with the given certificate and private key. The certificate and and private key must be PEM formatted. New clients will see the new certificate. Existing clients will continue to see the certificate the server was using when they connected to it. This method throws InvalidInputDataException if any of the following errors happen: - Unable to decode the PEM certificate and/or private key. - Unable to decrypt the private key with the given passphrase. - The certificate and/or private key do not contain RSA keys. - The certificate is not usable with the given private key.

### void startListening(int userid, int channelid)

Makes the given user start listening to the given channel.

#### Parameters

userid
  The ID of the user
channelid
  The ID of the channel

### void stopListening(int userid, int channelid)

Makes the given user stop listening to the given channel.

#### Parameters

userid
  The ID of the user
channelid
  The ID of the channel

### bool isListening(int userid, int channelid)

#### Parameters

userid
  The ID of the user
channelid
  The ID of the channel

#### Return Value

s Whether the given user is currently listening to the given channel

### IntList getListeningChannels(int userid)

#### Parameters

userid
  The ID of the user

#### Return Value

s An ID-list of channels the given user is listening to

### IntList getListeningUsers(int channelid)

#### Parameters

channelid
  The ID of the channel

#### Return Value

s An ID-list of users listening to the given channel

### float getListenerVolumeAdjustment(int channelid, int userid)

#### Parameters

channelid
  The ID of the channel
userid
  The ID of the user

#### Return Value

s The volume adjustment set for a listener of the given user in the given channel

### void setListenerVolumeAdjustment(int channelid, int userid, float volumeAdjustment)

Sets the volume adjustment set for a listener of the given user in the given channel

#### Parameters

channelid
  The ID of the channel
userid
  The ID of the user

### void sendWelcomeMessage(IdList receiverUserIDs)

#### Parameters

receiverUserIDs
  list of IDs of the users the message shall be sent to