1// Copyright 2005-2019 The Mumble Developers. All rights reserved. 2// Use of this source code is governed by a BSD-style license 3// that can be found in the LICENSE file at the root of the 4// Mumble source tree or at <https://www.mumble.info/LICENSE>. 5 6/** 7 * 8 * Information and control of the murmur server. Each server has 9 * one {@link Meta} interface that controls global information, and 10 * each virtual server has a {@link Server} interface. 11 * 12 **/ 13 14#include <Ice/SliceChecksumDict.ice> 15 16module Murmur 17{ 18 19 /** A network address in IPv6 format. 20 **/ 21 ["python:seq:tuple"] sequence<byte> NetAddress; 22 23 /** A connected user. 24 **/ 25 struct User { 26 /** Session ID. This identifies the connection to the server. */ 27 int session; 28 /** User ID. -1 if the user is anonymous. */ 29 int userid; 30 /** Is user muted by the server? */ 31 bool mute; 32 /** Is user deafened by the server? If true, this implies mute. */ 33 bool deaf; 34 /** Is the user suppressed by the server? This means the user is not muted, but does not have speech privileges in the current channel. */ 35 bool suppress; 36 /** Is the user a priority speaker? */ 37 bool prioritySpeaker; 38 /** Is the user self-muted? */ 39 bool selfMute; 40 /** Is the user self-deafened? If true, this implies mute. */ 41 bool selfDeaf; 42 /** Is the User recording? (This flag is read-only and cannot be changed using setState().) **/ 43 bool recording; 44 /** Channel ID the user is in. Matches {@link Channel.id}. */ 45 int channel; 46 /** The name of the user. */ 47 string name; 48 /** Seconds user has been online. */ 49 int onlinesecs; 50 /** Average transmission rate in bytes per second over the last few seconds. */ 51 int bytespersec; 52 /** Client version. Major version in upper 16 bits, followed by 8 bits of minor version and 8 bits of patchlevel. Version 1.2.3 = 0x010203. */ 53 int version; 54 /** Client release. For official releases, this equals the version. For snapshots and git compiles, this will be something else. */ 55 string release; 56 /** Client OS. */ 57 string os; 58 /** Client OS Version. */ 59 string osversion; 60 /** Plugin Identity. This will be the user's unique ID inside the current game. */ 61 string identity; 62 /** 63 Base64-encoded Plugin context. This is a binary blob identifying the game and team the user is on. 64 65 The used Base64 alphabet is the one specified in RFC 2045. 66 67 Before Mumble 1.3.0, this string was not Base64-encoded. This could cause problems for some Ice 68 implementations, such as the .NET implementation. 69 70 If you need the exact string that is used by Mumble, you can get it by Base64-decoding this string. 71 72 If you simply need to detect whether two users are in the same game world, string comparisons will 73 continue to work as before. 74 */ 75 string context; 76 /** User comment. Shown as tooltip for this user. */ 77 string comment; 78 /** Client address. */ 79 NetAddress address; 80 /** TCP only. True until UDP connectivity is established. */ 81 bool tcponly; 82 /** Idle time. This is how many seconds it is since the user last spoke. Other activity is not counted. */ 83 int idlesecs; 84 /** UDP Ping Average. This is the average ping for the user via UDP over the duration of the connection. */ 85 float udpPing; 86 /** TCP Ping Average. This is the average ping for the user via TCP over the duration of the connection. */ 87 float tcpPing; 88 }; 89 90 sequence<int> IntList; 91 92 /** A text message between users. 93 **/ 94 struct TextMessage { 95 /** Sessions (connected users) who were sent this message. */ 96 IntList sessions; 97 /** Channels who were sent this message. */ 98 IntList channels; 99 /** Trees of channels who were sent this message. */ 100 IntList trees; 101 /** The contents of the message. */ 102 string text; 103 }; 104 105 /** A channel. 106 **/ 107 struct Channel { 108 /** Channel ID. This is unique per channel, and the root channel is always id 0. */ 109 int id; 110 /** Name of the channel. There can not be two channels with the same parent that has the same name. */ 111 string name; 112 /** ID of parent channel, or -1 if this is the root channel. */ 113 int parent; 114 /** List of id of linked channels. */ 115 IntList links; 116 /** Description of channel. Shown as tooltip for this channel. */ 117 string description; 118 /** Channel is temporary, and will be removed when the last user leaves it. */ 119 bool temporary; 120 /** Position of the channel which is used in Client for sorting. */ 121 int position; 122 }; 123 124 /** A group. Groups are defined per channel, and can inherit members from parent channels. 125 **/ 126 struct Group { 127 /** Group name */ 128 string name; 129 /** Is this group inherited from a parent channel? Read-only. */ 130 bool inherited; 131 /** Does this group inherit members from parent channels? */ 132 bool inherit; 133 /** Can subchannels inherit members from this group? */ 134 bool inheritable; 135 /** List of users to add to the group. */ 136 IntList add; 137 /** List of inherited users to remove from the group. */ 138 IntList remove; 139 /** Current members of the group, including inherited members. Read-only. */ 140 IntList members; 141 }; 142 143 /** Write access to channel control. Implies all other permissions (except Speak). */ 144 const int PermissionWrite = 0x01; 145 /** Traverse channel. Without this, a client cannot reach subchannels, no matter which privileges he has there. */ 146 const int PermissionTraverse = 0x02; 147 /** Enter channel. */ 148 const int PermissionEnter = 0x04; 149 /** Speak in channel. */ 150 const int PermissionSpeak = 0x08; 151 /** Whisper to channel. This is different from Speak, so you can set up different permissions. */ 152 const int PermissionWhisper = 0x100; 153 /** Mute and deafen other users in this channel. */ 154 const int PermissionMuteDeafen = 0x10; 155 /** Move users from channel. You need this permission in both the source and destination channel to move another user. */ 156 const int PermissionMove = 0x20; 157 /** Make new channel as a subchannel of this channel. */ 158 const int PermissionMakeChannel = 0x40; 159 /** Make new temporary channel as a subchannel of this channel. */ 160 const int PermissionMakeTempChannel = 0x400; 161 /** Link this channel. You need this permission in both the source and destination channel to link channels, or in either channel to unlink them. */ 162 const int PermissionLinkChannel = 0x80; 163 /** Send text message to channel. */ 164 const int PermissionTextMessage = 0x200; 165 /** Kick user from server. Only valid on root channel. */ 166 const int PermissionKick = 0x10000; 167 /** Ban user from server. Only valid on root channel. */ 168 const int PermissionBan = 0x20000; 169 /** Register and unregister users. Only valid on root channel. */ 170 const int PermissionRegister = 0x40000; 171 /** Register and unregister users. Only valid on root channel. */ 172 const int PermissionRegisterSelf = 0x80000; 173 174 175 /** Access Control List for a channel. ACLs are defined per channel, and can be inherited from parent channels. 176 **/ 177 struct ACL { 178 /** Does the ACL apply to this channel? */ 179 bool applyHere; 180 /** Does the ACL apply to subchannels? */ 181 bool applySubs; 182 /** Is this ACL inherited from a parent channel? Read-only. */ 183 bool inherited; 184 /** ID of user this ACL applies to. -1 if using a group name. */ 185 int userid; 186 /** Group this ACL applies to. Blank if using userid. */ 187 string group; 188 /** Binary mask of privileges to allow. */ 189 int allow; 190 /** Binary mask of privileges to deny. */ 191 int deny; 192 }; 193 194 /** A single ip mask for a ban. 195 **/ 196 struct Ban { 197 /** Address to ban. */ 198 NetAddress address; 199 /** Number of bits in ban to apply. */ 200 int bits; 201 /** Username associated with ban. */ 202 string name; 203 /** Hash of banned user. */ 204 string hash; 205 /** Reason for ban. */ 206 string reason; 207 /** Date ban was applied in unix time format. */ 208 int start; 209 /** Duration of ban. */ 210 int duration; 211 }; 212 213 /** A entry in the log. 214 **/ 215 struct LogEntry { 216 /** Timestamp in UNIX time_t */ 217 int timestamp; 218 /** The log message. */ 219 string txt; 220 }; 221 222 class Tree; 223 sequence<Tree> TreeList; 224 225 enum ChannelInfo { ChannelDescription, ChannelPosition }; 226 enum UserInfo { UserName, UserEmail, UserComment, UserHash, UserPassword, UserLastActive, UserKDFIterations }; 227 228 dictionary<int, User> UserMap; 229 dictionary<int, Channel> ChannelMap; 230 sequence<Channel> ChannelList; 231 sequence<User> UserList; 232 sequence<Group> GroupList; 233 sequence<ACL> ACLList; 234 sequence<LogEntry> LogList; 235 sequence<Ban> BanList; 236 sequence<int> IdList; 237 sequence<string> NameList; 238 dictionary<int, string> NameMap; 239 dictionary<string, int> IdMap; 240 sequence<byte> Texture; 241 dictionary<string, string> ConfigMap; 242 sequence<string> GroupNameList; 243 sequence<byte> CertificateDer; 244 sequence<CertificateDer> CertificateList; 245 246 /** User information map. 247 * Older versions of ice-php can't handle enums as keys. If you are using one of these, replace 'UserInfo' with 'byte'. 248 */ 249 250 dictionary<UserInfo, string> UserInfoMap; 251 252 /** User and subchannel state. Read-only. 253 **/ 254 class Tree { 255 /** Channel definition of current channel. */ 256 Channel c; 257 /** List of subchannels. */ 258 TreeList children; 259 /** Users in this channel. */ 260 UserList users; 261 }; 262 263 exception MurmurException {}; 264 /** This is thrown when you specify an invalid session. This may happen if the user has disconnected since your last call to {@link Server.getUsers}. See {@link User.session} */ 265 exception InvalidSessionException extends MurmurException {}; 266 /** This is thrown when you specify an invalid channel id. This may happen if the channel was removed by another provess. It can also be thrown if you try to add an invalid channel. */ 267 exception InvalidChannelException extends MurmurException {}; 268 /** This is thrown when you try to do an operation on a server that does not exist. This may happen if someone has removed the server. */ 269 exception InvalidServerException extends MurmurException {}; 270 /** This happens if you try to fetch user or channel state on a stopped server, if you try to stop an already stopped server or start an already started server. */ 271 exception ServerBootedException extends MurmurException {}; 272 /** This is thrown if {@link Server.start} fails, and should generally be the cause for some concern. */ 273 exception ServerFailureException extends MurmurException {}; 274 /** This is thrown when you specify an invalid userid. */ 275 exception InvalidUserException extends MurmurException {}; 276 /** This is thrown when you try to set an invalid texture. */ 277 exception InvalidTextureException extends MurmurException {}; 278 /** This is thrown when you supply an invalid callback. */ 279 exception InvalidCallbackException extends MurmurException {}; 280 /** This is thrown when you supply the wrong secret in the calling context. */ 281 exception InvalidSecretException extends MurmurException {}; 282 /** This is thrown when the channel operation would excede the channel nesting limit */ 283 exception NestingLimitException extends MurmurException {}; 284 /** This is thrown when you ask the server to disclose something that should be secret. */ 285 exception WriteOnlyException extends MurmurException {}; 286 /** This is thrown when invalid input data was specified. */ 287 exception InvalidInputDataException extends MurmurException {}; 288 289 /** Callback interface for servers. You can supply an implementation of this to receive notification 290 * messages from the server. 291 * If an added callback ever throws an exception or goes away, it will be automatically removed. 292 * Please note that all callbacks are done asynchronously; murmur does not wait for the callback to 293 * complete before continuing processing. 294 * Note that callbacks are removed when a server is stopped, so you should have a callback for 295 * {@link MetaCallback.started} which calls {@link Server.addCallback}. 296 * @see MetaCallback 297 * @see Server.addCallback 298 */ 299 interface ServerCallback { 300 /** Called when a user connects to the server. 301 * @param state State of connected user. 302 */ 303 idempotent void userConnected(User state); 304 /** Called when a user disconnects from the server. The user has already been removed, so you can no longer use methods like {@link Server.getState} 305 * to retrieve the user's state. 306 * @param state State of disconnected user. 307 */ 308 idempotent void userDisconnected(User state); 309 /** Called when a user state changes. This is called if the user moves, is renamed, is muted, deafened etc. 310 * @param state New state of user. 311 */ 312 idempotent void userStateChanged(User state); 313 /** Called when user writes a text message 314 * @param state the User sending the message 315 * @param message the TextMessage the user has sent 316 */ 317 idempotent void userTextMessage(User state, TextMessage message); 318 /** Called when a new channel is created. 319 * @param state State of new channel. 320 */ 321 idempotent void channelCreated(Channel state); 322 /** Called when a channel is removed. The channel has already been removed, you can no longer use methods like {@link Server.getChannelState} 323 * @param state State of removed channel. 324 */ 325 idempotent void channelRemoved(Channel state); 326 /** Called when a new channel state changes. This is called if the channel is moved, renamed or if new links are added. 327 * @param state New state of channel. 328 */ 329 idempotent void channelStateChanged(Channel state); 330 }; 331 332 /** Context for actions in the Server menu. */ 333 const int ContextServer = 0x01; 334 /** Context for actions in the Channel menu. */ 335 const int ContextChannel = 0x02; 336 /** Context for actions in the User menu. */ 337 const int ContextUser = 0x04; 338 339 /** Callback interface for context actions. You need to supply one of these for {@link Server.addContext}. 340 * If an added callback ever throws an exception or goes away, it will be automatically removed. 341 * Please note that all callbacks are done asynchronously; murmur does not wait for the callback to 342 * complete before continuing processing. 343 */ 344 interface ServerContextCallback { 345 /** Called when a context action is performed. 346 * @param action Action to be performed. 347 * @param usr User which initiated the action. 348 * @param session If nonzero, session of target user. 349 * @param channelid If not -1, id of target channel. 350 */ 351 idempotent void contextAction(string action, User usr, int session, int channelid); 352 }; 353 354 /** Callback interface for server authentication. You need to supply one of these for {@link Server.setAuthenticator}. 355 * If an added callback ever throws an exception or goes away, it will be automatically removed. 356 * Please note that unlike {@link ServerCallback} and {@link ServerContextCallback}, these methods are called 357 * synchronously. If the response lags, the entire murmur server will lag. 358 * Also note that, as the method calls are synchronous, making a call to {@link Server} or {@link Meta} will 359 * deadlock the server. 360 */ 361 interface ServerAuthenticator { 362 /** Called to authenticate a user. If you do not know the username in question, always return -2 from this 363 * method to fall through to normal database authentication. 364 * Note that if authentication succeeds, murmur will create a record of the user in it's database, reserving 365 * the username and id so it cannot be used for normal database authentication. 366 * The data in the certificate (name, email addresses etc), as well as the list of signing certificates, 367 * should only be trusted if certstrong is true. 368 * 369 * Internally, Murmur treats usernames as case-insensitive. It is recommended 370 * that authenticators do the same. Murmur checks if a username is in use when 371 * a user connects. If the connecting user is registered, the other username is 372 * kicked. If the connecting user is not registered, the connecting user is not 373 * allowed to join the server. 374 * 375 * @param name Username to authenticate. 376 * @param pw Password to authenticate with. 377 * @param certificates List of der encoded certificates the user connected with. 378 * @param certhash Hash of user certificate, as used by murmur internally when matching. 379 * @param certstrong True if certificate was valid and signed by a trusted CA. 380 * @param newname Set this to change the username from the supplied one. 381 * @param groups List of groups on the root channel that the user will be added to for the duration of the connection. 382 * @return UserID of authenticated user, -1 for authentication failures, -2 for unknown user (fallthrough), 383 * -3 for authentication failures where the data could (temporarily) not be verified. 384 */ 385 idempotent int authenticate(string name, string pw, CertificateList certificates, string certhash, bool certstrong, out string newname, out GroupNameList groups); 386 387 /** Fetch information about a user. This is used to retrieve information like email address, keyhash etc. If you 388 * want murmur to take care of this information itself, simply return false to fall through. 389 * @param id User id. 390 * @param info Information about user. This needs to include at least "name". 391 * @return true if information is present, false to fall through. 392 */ 393 idempotent bool getInfo(int id, out UserInfoMap info); 394 395 /** Map a name to a user id. 396 * @param name Username to map. 397 * @return User id or -2 for unknown name. 398 */ 399 idempotent int nameToId(string name); 400 401 /** Map a user id to a username. 402 * @param id User id to map. 403 * @return Name of user or empty string for unknown id. 404 */ 405 idempotent string idToName(int id); 406 407 /** Map a user to a custom Texture. 408 * @param id User id to map. 409 * @return User texture or an empty texture for unknwon users or users without textures. 410 */ 411 idempotent Texture idToTexture(int id); 412 }; 413 414 /** Callback interface for server authentication and registration. This allows you to support both authentication 415 * and account updating. 416 * You do not need to implement this if all you want is authentication, you only need this if other scripts 417 * connected to the same server calls e.g. {@link Server.setTexture}. 418 * Almost all of these methods support fall through, meaning murmur should continue the operation against its 419 * own database. 420 */ 421 interface ServerUpdatingAuthenticator extends ServerAuthenticator { 422 /** Register a new user. 423 * @param info Information about user to register. 424 * @return User id of new user, -1 for registration failure, or -2 to fall through. 425 */ 426 int registerUser(UserInfoMap info); 427 428 /** Unregister a user. 429 * @param id Userid to unregister. 430 * @return 1 for successfull unregistration, 0 for unsuccessfull unregistration, -1 to fall through. 431 */ 432 int unregisterUser(int id); 433 434 /** Get a list of registered users matching filter. 435 * @param filter Substring usernames must contain. If empty, return all registered users. 436 * @return List of matching registered users. 437 */ 438 idempotent NameMap getRegisteredUsers(string filter); 439 440 /** Set additional information for user registration. 441 * @param id Userid of registered user. 442 * @param info Information to set about user. This should be merged with existing information. 443 * @return 1 for successfull update, 0 for unsuccessfull update, -1 to fall through. 444 */ 445 idempotent int setInfo(int id, UserInfoMap info); 446 447 /** Set texture (now called avatar) of user registration. 448 * @param id registrationId of registered user. 449 * @param tex New texture. 450 * @return 1 for successfull update, 0 for unsuccessfull update, -1 to fall through. 451 */ 452 idempotent int setTexture(int id, Texture tex); 453 }; 454 455 /** Per-server interface. This includes all methods for configuring and altering 456 * the state of a single virtual server. You can retrieve a pointer to this interface 457 * from one of the methods in {@link Meta}. 458 **/ 459 ["amd"] interface Server { 460 /** Shows if the server currently running (accepting users). 461 * 462 * @return Run-state of server. 463 */ 464 idempotent bool isRunning() throws InvalidSecretException; 465 466 /** Start server. */ 467 void start() throws ServerBootedException, ServerFailureException, InvalidSecretException; 468 469 /** Stop server. 470 * Note: Server will be restarted on Murmur restart unless explicitly disabled 471 * with setConf("boot", false) 472 */ 473 void stop() throws ServerBootedException, InvalidSecretException; 474 475 /** Delete server and all it's configuration. */ 476 void delete() throws ServerBootedException, InvalidSecretException; 477 478 /** Fetch the server id. 479 * 480 * @return Unique server id. 481 */ 482 idempotent int id() throws InvalidSecretException; 483 484 /** Add a callback. The callback will receive notifications about changes to users and channels. 485 * 486 * @param cb Callback interface which will receive notifications. 487 * @see removeCallback 488 */ 489 void addCallback(ServerCallback *cb) throws ServerBootedException, InvalidCallbackException, InvalidSecretException; 490 491 /** Remove a callback. 492 * 493 * @param cb Callback interface to be removed. 494 * @see addCallback 495 */ 496 void removeCallback(ServerCallback *cb) throws ServerBootedException, InvalidCallbackException, InvalidSecretException; 497 498 /** Set external authenticator. If set, all authentications from clients are forwarded to this 499 * proxy. 500 * 501 * @param auth Authenticator object to perform subsequent authentications. 502 */ 503 void setAuthenticator(ServerAuthenticator *auth) throws ServerBootedException, InvalidCallbackException, InvalidSecretException; 504 505 /** Retrieve configuration item. 506 * @param key Configuration key. 507 * @return Configuration value. If this is empty, see {@link Meta.getDefaultConf} 508 */ 509 idempotent string getConf(string key) throws InvalidSecretException, WriteOnlyException; 510 511 /** Retrieve all configuration items. 512 * @return All configured values. If a value isn't set here, the value from {@link Meta.getDefaultConf} is used. 513 */ 514 idempotent ConfigMap getAllConf() throws InvalidSecretException; 515 516 /** Set a configuration item. 517 * @param key Configuration key. 518 * @param value Configuration value. 519 */ 520 idempotent void setConf(string key, string value) throws InvalidSecretException; 521 522 /** Set superuser password. This is just a convenience for using {@link updateRegistration} on user id 0. 523 * @param pw Password. 524 */ 525 idempotent void setSuperuserPassword(string pw) throws InvalidSecretException; 526 527 /** Fetch log entries. 528 * @param first Lowest numbered entry to fetch. 0 is the most recent item. 529 * @param last Last entry to fetch. 530 * @return List of log entries. 531 */ 532 idempotent LogList getLog(int first, int last) throws InvalidSecretException; 533 534 /** Fetch length of log 535 * @return Number of entries in log 536 */ 537 idempotent int getLogLen() throws InvalidSecretException; 538 539 /** Fetch all users. This returns all currently connected users on the server. 540 * @return List of connected users. 541 * @see getState 542 */ 543 idempotent UserMap getUsers() throws ServerBootedException, InvalidSecretException; 544 545 /** Fetch all channels. This returns all defined channels on the server. The root channel is always channel 0. 546 * @return List of defined channels. 547 * @see getChannelState 548 */ 549 idempotent ChannelMap getChannels() throws ServerBootedException, InvalidSecretException; 550 551 /** Fetch certificate of user. This returns the complete certificate chain of a user. 552 * @param session Connection ID of user. See {@link User.session}. 553 * @return Certificate list of user. 554 */ 555 idempotent CertificateList getCertificateList(int session) throws ServerBootedException, InvalidSessionException, InvalidSecretException; 556 557 /** Fetch all channels and connected users as a tree. This retrieves an easy-to-use representation of the server 558 * as a tree. This is primarily used for viewing the state of the server on a webpage. 559 * @return Recursive tree of all channels and connected users. 560 */ 561 idempotent Tree getTree() throws ServerBootedException, InvalidSecretException; 562 563 /** Fetch all current IP bans on the server. 564 * @return List of bans. 565 */ 566 idempotent BanList getBans() throws ServerBootedException, InvalidSecretException; 567 568 /** 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 569 * append to the returned list before calling this method. 570 * @param bans List of bans. 571 */ 572 idempotent void setBans(BanList bans) throws ServerBootedException, InvalidSecretException; 573 574 /** Kick a user. The user is not banned, and is free to rejoin the server. 575 * @param session Connection ID of user. See {@link User.session}. 576 * @param reason Text message to show when user is kicked. 577 */ 578 void kickUser(int session, string reason) throws ServerBootedException, InvalidSessionException, InvalidSecretException; 579 580 /** Get state of a single connected user. 581 * @param session Connection ID of user. See {@link User.session}. 582 * @return State of connected user. 583 * @see setState 584 * @see getUsers 585 */ 586 idempotent User getState(int session) throws ServerBootedException, InvalidSessionException, InvalidSecretException; 587 588 /** Set user state. You can use this to move, mute and deafen users. 589 * @param state User state to set. 590 * @see getState 591 */ 592 idempotent void setState(User state) throws ServerBootedException, InvalidSessionException, InvalidChannelException, InvalidSecretException; 593 594 /** Send text message to a single user. 595 * @param session Connection ID of user. See {@link User.session}. 596 * @param text Message to send. 597 * @see sendMessageChannel 598 */ 599 void sendMessage(int session, string text) throws ServerBootedException, InvalidSessionException, InvalidSecretException; 600 601 /** Check if user is permitted to perform action. 602 * @param session Connection ID of user. See {@link User.session}. 603 * @param channelid ID of Channel. See {@link Channel.id}. 604 * @param perm Permission bits to check. 605 * @return true if any of the permissions in perm were set for the user. 606 */ 607 bool hasPermission(int session, int channelid, int perm) throws ServerBootedException, InvalidSessionException, InvalidChannelException, InvalidSecretException; 608 609 /** Return users effective permissions 610 * @param session Connection ID of user. See {@link User.session}. 611 * @param channelid ID of Channel. See {@link Channel.id}. 612 * @return bitfield of allowed actions 613 */ 614 idempotent int effectivePermissions(int session, int channelid) throws ServerBootedException, InvalidSessionException, InvalidChannelException, InvalidSecretException; 615 616 /** Add a context callback. This is done per user, and will add a context menu action for the user. 617 * 618 * @param session Session of user which should receive context entry. 619 * @param action Action string, a unique name to associate with the action. 620 * @param text Name of action shown to user. 621 * @param cb Callback interface which will receive notifications. 622 * @param ctx Context this should be used in. Needs to be one or a combination of {@link ContextServer}, {@link ContextChannel} and {@link ContextUser}. 623 * @see removeContextCallback 624 */ 625 void addContextCallback(int session, string action, string text, ServerContextCallback *cb, int ctx) throws ServerBootedException, InvalidCallbackException, InvalidSecretException; 626 627 /** Remove a callback. 628 * 629 * @param cb Callback interface to be removed. This callback will be removed from all from all users. 630 * @see addContextCallback 631 */ 632 void removeContextCallback(ServerContextCallback *cb) throws ServerBootedException, InvalidCallbackException, InvalidSecretException; 633 634 /** Get state of single channel. 635 * @param channelid ID of Channel. See {@link Channel.id}. 636 * @return State of channel. 637 * @see setChannelState 638 * @see getChannels 639 */ 640 idempotent Channel getChannelState(int channelid) throws ServerBootedException, InvalidChannelException, InvalidSecretException; 641 642 /** Set state of a single channel. You can use this to move or relink channels. 643 * @param state Channel state to set. 644 * @see getChannelState 645 */ 646 idempotent void setChannelState(Channel state) throws ServerBootedException, InvalidChannelException, InvalidSecretException, NestingLimitException; 647 648 /** Remove a channel and all its subchannels. 649 * @param channelid ID of Channel. See {@link Channel.id}. 650 */ 651 void removeChannel(int channelid) throws ServerBootedException, InvalidChannelException, InvalidSecretException; 652 653 /** Add a new channel. 654 * @param name Name of new channel. 655 * @param parent Channel ID of parent channel. See {@link Channel.id}. 656 * @return ID of newly created channel. 657 */ 658 int addChannel(string name, int parent) throws ServerBootedException, InvalidChannelException, InvalidSecretException, NestingLimitException; 659 660 /** Send text message to channel or a tree of channels. 661 * @param channelid Channel ID of channel to send to. See {@link Channel.id}. 662 * @param tree If true, the message will be sent to the channel and all its subchannels. 663 * @param text Message to send. 664 * @see sendMessage 665 */ 666 void sendMessageChannel(int channelid, bool tree, string text) throws ServerBootedException, InvalidChannelException, InvalidSecretException; 667 668 /** Retrieve ACLs and Groups on a channel. 669 * @param channelid Channel ID of channel to fetch from. See {@link Channel.id}. 670 * @param acls List of ACLs on the channel. This will include inherited ACLs. 671 * @param groups List of groups on the channel. This will include inherited groups. 672 * @param inherit Does this channel inherit ACLs from the parent channel? 673 */ 674 idempotent void getACL(int channelid, out ACLList acls, out GroupList groups, out bool inherit) throws ServerBootedException, InvalidChannelException, InvalidSecretException; 675 676 /** Set ACLs and Groups on a channel. Note that this will replace all existing ACLs and groups on the channel. 677 * @param channelid Channel ID of channel to fetch from. See {@link Channel.id}. 678 * @param acls List of ACLs on the channel. 679 * @param groups List of groups on the channel. 680 * @param inherit Should this channel inherit ACLs from the parent channel? 681 */ 682 idempotent void setACL(int channelid, ACLList acls, GroupList groups, bool inherit) throws ServerBootedException, InvalidChannelException, InvalidSecretException; 683 684 /** Temporarily add a user to a group on a channel. This state is not saved, and is intended for temporary memberships. 685 * @param channelid Channel ID of channel to add to. See {@link Channel.id}. 686 * @param session Connection ID of user. See {@link User.session}. 687 * @param group Group name to add to. 688 */ 689 idempotent void addUserToGroup(int channelid, int session, string group) throws ServerBootedException, InvalidChannelException, InvalidSessionException, InvalidSecretException; 690 691 /** Remove a user from a temporary group membership on a channel. This state is not saved, and is intended for temporary memberships. 692 * @param channelid Channel ID of channel to add to. See {@link Channel.id}. 693 * @param session Connection ID of user. See {@link User.session}. 694 * @param group Group name to remove from. 695 */ 696 idempotent void removeUserFromGroup(int channelid, int session, string group) throws ServerBootedException, InvalidChannelException, InvalidSessionException, InvalidSecretException; 697 698 /** Redirect whisper targets for user. If set, whenever a user tries to whisper to group "source", the whisper will be redirected to group "target". 699 * To remove a redirect pass an empty target string. This is intended for context groups. 700 * @param session Connection ID of user. See {@link User.session}. 701 * @param source Group name to redirect from. 702 * @param target Group name to redirect to. 703 */ 704 idempotent void redirectWhisperGroup(int session, string source, string target) throws ServerBootedException, InvalidSessionException, InvalidSecretException; 705 706 /** Map a list of {@link User.userid} to a matching name. 707 * @param List of ids. 708 * @return Matching list of names, with an empty string representing invalid or unknown ids. 709 */ 710 idempotent NameMap getUserNames(IdList ids) throws ServerBootedException, InvalidSecretException; 711 712 /** Map a list of user names to a matching id. 713 * @param List of names. 714 * @reuturn List of matching ids, with -1 representing invalid or unknown user names. 715 */ 716 idempotent IdMap getUserIds(NameList names) throws ServerBootedException, InvalidSecretException; 717 718 /** Register a new user. 719 * @param info Information about new user. Must include at least "name". 720 * @return The ID of the user. See {@link RegisteredUser.userid}. 721 */ 722 int registerUser(UserInfoMap info) throws ServerBootedException, InvalidUserException, InvalidSecretException; 723 724 /** Remove a user registration. 725 * @param userid ID of registered user. See {@link RegisteredUser.userid}. 726 */ 727 void unregisterUser(int userid) throws ServerBootedException, InvalidUserException, InvalidSecretException; 728 729 /** Update the registration for a user. You can use this to set the email or password of a user, 730 * and can also use it to change the user's name. 731 * @param registration Updated registration record. 732 */ 733 idempotent void updateRegistration(int userid, UserInfoMap info) throws ServerBootedException, InvalidUserException, InvalidSecretException; 734 735 /** Fetch registration for a single user. 736 * @param userid ID of registered user. See {@link RegisteredUser.userid}. 737 * @return Registration record. 738 */ 739 idempotent UserInfoMap getRegistration(int userid) throws ServerBootedException, InvalidUserException, InvalidSecretException; 740 741 /** Fetch a group of registered users. 742 * @param filter Substring of user name. If blank, will retrieve all registered users. 743 * @return List of registration records. 744 */ 745 idempotent NameMap getRegisteredUsers(string filter) throws ServerBootedException, InvalidSecretException; 746 747 /** Verify the password of a user. You can use this to verify a user's credentials. 748 * @param name User name. See {@link RegisteredUser.name}. 749 * @param pw User password. 750 * @return User ID of registered user (See {@link RegisteredUser.userid}), -1 for failed authentication or -2 for unknown usernames. 751 */ 752 idempotent int verifyPassword(string name, string pw) throws ServerBootedException, InvalidSecretException; 753 754 /** Fetch user texture. Textures are stored as zlib compress()ed 600x60 32-bit BGRA data. 755 * @param userid ID of registered user. See {@link RegisteredUser.userid}. 756 * @return Custom texture associated with user or an empty texture. 757 */ 758 idempotent Texture getTexture(int userid) throws ServerBootedException, InvalidUserException, InvalidSecretException; 759 760 /** Set a user texture (now called avatar). 761 * @param userid ID of registered user. See {@link RegisteredUser.userid}. 762 * @param tex Texture (as a Byte-Array) to set for the user, or an empty texture to remove the existing texture. 763 */ 764 idempotent void setTexture(int userid, Texture tex) throws ServerBootedException, InvalidUserException, InvalidTextureException, InvalidSecretException; 765 766 /** Get virtual server uptime. 767 * @return Uptime of the virtual server in seconds 768 */ 769 idempotent int getUptime() throws ServerBootedException, InvalidSecretException; 770 771 /** 772 * Update the server's certificate information. 773 * 774 * Reconfigure the running server's TLS socket with the given 775 * certificate and private key. 776 * 777 * The certificate and and private key must be PEM formatted. 778 * 779 * New clients will see the new certificate. 780 * Existing clients will continue to see the certificate the server 781 * was using when they connected to it. 782 * 783 * This method throws InvalidInputDataException if any of the 784 * following errors happen: 785 * - Unable to decode the PEM certificate and/or private key. 786 * - Unable to decrypt the private key with the given passphrase. 787 * - The certificate and/or private key do not contain RSA keys. 788 * - The certificate is not usable with the given private key. 789 */ 790 idempotent void updateCertificate(string certificate, string privateKey, string passphrase) throws ServerBootedException, InvalidSecretException, InvalidInputDataException; 791 }; 792 793 /** Callback interface for Meta. You can supply an implementation of this to receive notifications 794 * when servers are stopped or started. 795 * If an added callback ever throws an exception or goes away, it will be automatically removed. 796 * Please note that all callbacks are done asynchronously; murmur does not wait for the callback to 797 * complete before continuing processing. 798 * @see ServerCallback 799 * @see Meta.addCallback 800 */ 801 interface MetaCallback { 802 /** Called when a server is started. The server is up and running when this event is sent, so all methods that 803 * need a running server will work. 804 * @param srv Interface for started server. 805 */ 806 void started(Server *srv); 807 808 /** Called when a server is stopped. The server is already stopped when this event is sent, so no methods that 809 * need a running server will work. 810 * @param srv Interface for started server. 811 */ 812 void stopped(Server *srv); 813 }; 814 815 sequence<Server *> ServerList; 816 817 /** This is the meta interface. It is primarily used for retrieving the {@link Server} interfaces for each individual server. 818 **/ 819 ["amd"] interface Meta { 820 /** Fetch interface to specific server. 821 * @param id Server ID. See {@link Server.getId}. 822 * @return Interface for specified server, or a null proxy if id is invalid. 823 */ 824 idempotent Server *getServer(int id) throws InvalidSecretException; 825 826 /** Create a new server. Call {@link Server.getId} on the returned interface to find it's ID. 827 * @return Interface for new server. 828 */ 829 Server *newServer() throws InvalidSecretException; 830 831 /** Fetch list of all currently running servers. 832 * @return List of interfaces for running servers. 833 */ 834 idempotent ServerList getBootedServers() throws InvalidSecretException; 835 836 /** Fetch list of all defined servers. 837 * @return List of interfaces for all servers. 838 */ 839 idempotent ServerList getAllServers() throws InvalidSecretException; 840 841 /** Fetch default configuraion. This returns the configuration items that were set in the configuration file, or 842 * the built-in default. The individual servers will use these values unless they have been overridden in the 843 * server specific configuration. The only special case is the port, which defaults to the value defined here + 844 * the servers ID - 1 (so that virtual server #1 uses the defined port, server #2 uses port+1 etc). 845 * @return Default configuration of the servers. 846 */ 847 idempotent ConfigMap getDefaultConf() throws InvalidSecretException; 848 849 /** Fetch version of Murmur. 850 * @param major Major version. 851 * @param minor Minor version. 852 * @param patch Patchlevel. 853 * @param text Textual representation of version. Note that this may not match the {@link major}, {@link minor} and {@link patch} levels, as it 854 * may be simply the compile date or the SVN revision. This is usually the text you want to present to users. 855 */ 856 idempotent void getVersion(out int major, out int minor, out int patch, out string text); 857 858 /** Add a callback. The callback will receive notifications when servers are started or stopped. 859 * 860 * @param cb Callback interface which will receive notifications. 861 */ 862 void addCallback(MetaCallback *cb) throws InvalidCallbackException, InvalidSecretException; 863 864 /** Remove a callback. 865 * 866 * @param cb Callback interface to be removed. 867 */ 868 void removeCallback(MetaCallback *cb) throws InvalidCallbackException, InvalidSecretException; 869 870 /** Get murmur uptime. 871 * @return Uptime of murmur in seconds 872 */ 873 idempotent int getUptime(); 874 875 /** Get slice file. 876 * @return Contents of the slice file server compiled with. 877 */ 878 idempotent string getSlice(); 879 880 /** Returns a checksum dict for the slice file. 881 * @return Checksum dict 882 */ 883 idempotent Ice::SliceChecksumDict getSliceChecksums(); 884 }; 885}; 886