Home Previous Up Next Index

Murmur::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 {@link 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 {@link 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.

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

Retrieve configuration item. {@link Meta.getDefaultConf}

Parameters

key
Configuration key.

Return Value

Configuration value. If this is empty, see {

ConfigMap getAllConf() throws InvalidSecretException

Retrieve all configuration items. {@link Meta.getDefaultConf} is used.

Return Value

All configured values. If a value isn't set here, the value from {

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 {@link 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. {@link User.session}.

Parameters

session
Connection ID of user. See {

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 {@link 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. {@link User.session}.

Parameters

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

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

Get state of a single connected user. {@link User.session}.

Parameters

session
Connection ID of user. See {

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. {@link User.session}.

Parameters

session
Connection ID of user. See {
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. {@link User.session}. {@link Channel.id}.

Parameters

session
Connection ID of user. See {
channelid
ID of Channel. See {
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 {@link User.session}. {@link Channel.id}.

Parameters

session
Connection ID of user. See {
channelid
ID of Channel. See {

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. {@link ContextServer}, {@link ContextChannel} and {@link ContextUser}.

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 {

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. {@link Channel.id}.

Parameters

channelid
ID of Channel. See {

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. {@link Channel.id}.

Parameters

channelid
ID of Channel. See {

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

Add a new channel. {@link Channel.id}.

Parameters

name
Name of new channel.
parent
Channel ID of parent channel. See {

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. {@link Channel.id}.

Parameters

channelid
Channel ID of channel to send to. See {
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. {@link Channel.id}.

Parameters

channelid
Channel ID of channel to fetch from. See {
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. {@link Channel.id}.

Parameters

channelid
Channel ID of channel to fetch from. See {
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. {@link Channel.id}. {@link User.session}.

Parameters

channelid
Channel ID of channel to add to. See {
session
Connection ID of user. See {
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. {@link Channel.id}. {@link User.session}.

Parameters

channelid
Channel ID of channel to add to. See {
session
Connection ID of user. See {
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. {@link User.session}.

Parameters

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

NameMap getUserNames(IdList ids) throws ServerBootedException, InvalidSecretException

Map a list of {@link 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. {@link RegisteredUser.userid}.

Parameters

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

Return Value

The ID of the user. See {

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

Remove a user registration. {@link RegisteredUser.userid}.

Parameters

userid
ID of registered user. See {

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. {@link RegisteredUser.userid}.

Parameters

userid
ID of registered user. See {

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. {@link RegisteredUser.name}. {@link RegisteredUser.userid}), -1 for failed authentication or -2 for unknown usernames.

Parameters

name
User name. See {
pw
User password.

Return Value

User ID of registered user (See {

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

Fetch user texture. Textures are stored as zlib compress()ed 600x60 32-bit BGRA data. {@link RegisteredUser.userid}.

Parameters

userid
ID of registered user. See {

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). {@link RegisteredUser.userid}.

Parameters

userid
ID of registered user. See {
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


Home Previous Up Next Index