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;
032
033public abstract class BaseEvent extends Wrapper implements TS3Event {
034
035        protected BaseEvent(Wrapper wrapper) {
036                super(Collections.unmodifiableMap(wrapper.getMap()));
037        }
038
039        /**
040         * Gets the ID of the client who caused this event to happen.
041         * <p>
042         * Because not all events are caused by clients, not all events have an invoker.<br>
043         * Most importantly, client events (i.e. {@link ClientJoinEvent}, {@link ClientLeaveEvent}
044         * {@link ClientMovedEvent}) do <b>not</b> have an invoker if a client joined,
045         * quit or changed channels themselves. These values are only present if another client
046         * caused the event to happen by moving, kicking or banning a client.
047         * </p><p>
048         * If the event response does not contain an invoker, this method will return {@code -1}.
049         * </p>
050         *
051         * @return the client ID of the invoker or {@code -1} if the event does not contain an invoker
052         */
053        public int getInvokerId() {
054                return getInt("invokerid");
055        }
056
057        /**
058         * Gets the nickname of the client who caused this event to happen.
059         * <p>
060         * Because not all events are caused by clients, not all events have an invoker.<br>
061         * Most importantly, client events (i.e. {@link ClientJoinEvent}, {@link ClientLeaveEvent}
062         * {@link ClientMovedEvent}) do <b>not</b> have an invoker if a client joined,
063         * quit or changed channels themselves. These values are only present if another client
064         * caused the event to happen by moving, kicking or banning a client.
065         * </p><p>
066         * If the event response does not contain an invoker, this method will return an empty string.
067         * </p>
068         *
069         * @return the nickname of the invoker or an empty string if the event does not contain an invoker
070         */
071        public String getInvokerName() {
072                return get("invokername");
073        }
074
075        /**
076         * Gets the unique identifier of the client who caused this event to happen.
077         * <p>
078         * Because not all events are caused by clients, not all events have an invoker.<br>
079         * Most importantly, client events (i.e. {@link ClientJoinEvent}, {@link ClientLeaveEvent}
080         * {@link ClientMovedEvent}) do <b>not</b> have an invoker if a client joined,
081         * quit or changed channels themselves. These values are only present if another client
082         * caused the event to happen by moving, kicking or banning a client.
083         * </p><p>
084         * If the event response does not contain an invoker, this method will return an empty string.
085         * </p>
086         *
087         * @return the unique ID the invoker or an empty string if the event does not contain an invoker
088         */
089        public String getInvokerUniqueId() {
090                return get("invokeruid");
091        }
092
093        /**
094         * Gets the reason ID of the cause of this event.
095         * <p>
096         * Here's an incomplete list of known reason IDs:
097         * </p>
098         * <table>
099         * <caption>Incomplete list of known reason IDs</caption>
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}