001package com.github.theholywaffle.teamspeak3.api.event;
002
003/*
004 * #%L
005 * TeamSpeak 3 Java API
006 * %%
007 * Copyright (C) 2014 - 2015 Bert De Geyter
008 * %%
009 * Permission is hereby granted, free of charge, to any person obtaining a copy
010 * of this software and associated documentation files (the "Software"), to deal
011 * in the Software without restriction, including without limitation the rights
012 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
013 * copies of the Software, and to permit persons to whom the Software is
014 * furnished to do so, subject to the following conditions:
015 * 
016 * The above copyright notice and this permission notice shall be included in
017 * all copies or substantial portions of the Software.
018 * 
019 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
020 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
021 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
022 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
023 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
024 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
025 * THE SOFTWARE.
026 * #L%
027 */
028
029import com.github.theholywaffle.teamspeak3.api.wrapper.Wrapper;
030
031import java.util.Collections;
032import java.util.Map;
033
034public abstract class BaseEvent extends Wrapper implements TS3Event {
035
036        protected BaseEvent(Map<String, String> map) {
037                super(Collections.unmodifiableMap(map));
038        }
039
040        /**
041         * Gets the ID of the client who caused this event to happen.
042         * <p>
043         * Because not all events are caused by clients, not all events have an invoker.<br>
044         * Most importantly, client events (i.e. {@link ClientJoinEvent}, {@link ClientLeaveEvent}
045         * {@link ClientMovedEvent}) do <b>not</b> have an invoker if a client joined,
046         * quit or changed channels themselves. These values are only present if another client
047         * caused the event to happen by moving, kicking or banning a client.
048         * </p><p>
049         * If the event response does not contain an invoker, this method will return {@code -1}.
050         * </p>
051         *
052         * @return the client ID of the invoker or {@code -1} if the event does not contain an invoker
053         */
054        public int getInvokerId() {
055                return getInt("invokerid");
056        }
057
058        /**
059         * Gets the nickname of the client who caused this event to happen.
060         * <p>
061         * Because not all events are caused by clients, not all events have an invoker.<br>
062         * Most importantly, client events (i.e. {@link ClientJoinEvent}, {@link ClientLeaveEvent}
063         * {@link ClientMovedEvent}) do <b>not</b> have an invoker if a client joined,
064         * quit or changed channels themselves. These values are only present if another client
065         * caused the event to happen by moving, kicking or banning a client.
066         * </p><p>
067         * If the event response does not contain an invoker, this method will return an empty string.
068         * </p>
069         *
070         * @return the nickname of the invoker or an empty string if the event does not contain an invoker
071         */
072        public String getInvokerName() {
073                return get("invokername");
074        }
075
076        /**
077         * Gets the unique identifier of the client who caused this event to happen.
078         * <p>
079         * Because not all events are caused by clients, not all events have an invoker.<br>
080         * Most importantly, client events (i.e. {@link ClientJoinEvent}, {@link ClientLeaveEvent}
081         * {@link ClientMovedEvent}) do <b>not</b> have an invoker if a client joined,
082         * quit or changed channels themselves. These values are only present if another client
083         * caused the event to happen by moving, kicking or banning a client.
084         * </p><p>
085         * If the event response does not contain an invoker, this method will return an empty string.
086         * </p>
087         *
088         * @return the unique ID the invoker or an empty string if the event does not contain an invoker
089         */
090        public String getInvokerUniqueId() {
091                return get("invokeruid");
092        }
093
094        /**
095         * Gets the reason ID of the cause of this event.
096         * <p>
097         * Here's an incomplete list of known reason IDs:
098         * </p>
099         * <table>
100         * <tr><th>ID</th><th>Description</th></tr>
101         * <tr><td>-1</td><td>No reason present</td></tr>
102         * <tr><td>0</td><td>No external cause</td></tr>
103         * <tr><td>1</td><td>Client was moved (by other client / by creating a new channel)</td></tr>
104         * <tr><td>3</td><td>Client timed out</td></tr>
105         * <tr><td>4</td><td>Client kicked from a channel or channel deleted</td></tr>
106         * <tr><td>5</td><td>Client kicked from the server</td></tr>
107         * <tr><td>6</td><td>Client banned from the server</td></tr>
108         * <tr><td>8</td><td>Client left the server (no external cause)</td></tr>
109         * <tr><td>10</td><td>Virtual server or channel edited</td></tr>
110         * <tr><td>11</td><td>Server shut down</td></tr>
111         * </table>
112         *
113         * @return the reason ID for this event
114         */
115        public int getReasonId() {
116                return getInt("reasonid");
117        }
118
119        /**
120         * Gets the reason for this event.
121         * This field is rarely present, even if the reason ID is non-zero.
122         * <p>
123         * In case of a client getting kicked or banned, this will return the user-provided reason.
124         * </p>
125         *
126         * @return the reason for this event or an empty string if no reason message is present
127         */
128        public String getReasonMessage() {
129                return get("reasonmsg");
130        }
131}