Add support for undocumented tokenused event notification

This event notification is sent when a client (or server query) uses a privilege key.

Existing classes implementing TS3Listener need to be changed. In cases where TS3EventAdapter was used, no changes to code are required.

- Add event type PRIVILEGE_KEY_USED
- Add class PrivilegeKeyUsedEvent corresponding to this event
- Add method onPrivilegeKeyUsed(PrivilegeKeyUsedEvent) to TS3Listener
- Cleaned up a couple of event classes

example/ChatBotExample.java

@@ -27,12 +27,10 @@
 import com.github.theholywaffle.teamspeak3.TS3Api;
 import com.github.theholywaffle.teamspeak3.TS3Config;
 import com.github.theholywaffle.teamspeak3.TS3Query;
-import com.github.theholywaffle.teamspeak3.api.reconnect.ConnectionHandler;
 import com.github.theholywaffle.teamspeak3.api.TextMessageTargetMode;
 import com.github.theholywaffle.teamspeak3.api.event.TS3EventAdapter;
 import com.github.theholywaffle.teamspeak3.api.event.TS3EventType;
 import com.github.theholywaffle.teamspeak3.api.event.TextMessageEvent;
-import com.github.theholywaffle.teamspeak3.api.reconnect.ReconnectingConnectionHandler;
 
 import java.util.logging.Level;
 

example/EventListenerExample.java

@@ -54,52 +54,65 @@ public static void main(String[] args) {
 		api.registerAllEvents();
 		api.addTS3Listeners(new TS3Listener() {
 
+			@Override
 			public void onTextMessage(TextMessageEvent e) {
 				System.out.println("Text message received in " + e.getTargetMode());
 			}
 
+			@Override
 			public void onServerEdit(ServerEditedEvent e) {
 				System.out.println("Server edited by " + e.getInvokerName());
 			}
 
+			@Override
 			public void onClientMoved(ClientMovedEvent e) {
 				System.out.println("Client has been moved " + e.getClientId());
 			}
 
+			@Override
 			public void onClientLeave(ClientLeaveEvent e) {
 				// ...
-
 			}
 
+			@Override
 			public void onClientJoin(ClientJoinEvent e) {
 				// ...
-
 			}
 
+			@Override
 			public void onChannelEdit(ChannelEditedEvent e) {
 				// ...
-
 			}
 
+			@Override
 			public void onChannelDescriptionChanged(ChannelDescriptionEditedEvent e) {
 				// ...
 			}
 
+			@Override
 			public void onChannelCreate(ChannelCreateEvent e) {
 				// ...
 			}
 
+			@Override
 			public void onChannelDeleted(ChannelDeletedEvent e) {
 				// ...
 			}
 
+			@Override
 			public void onChannelMoved(ChannelMovedEvent e) {
 				// ...
 			}
 
+			@Override
 			public void onChannelPasswordChanged(ChannelPasswordChangedEvent e) {
 				// ...
 			}
+
+			@Override
+			public void onPrivilegeKeyUsed(PrivilegeKeyUsedEvent e) {
+				// ...
+			}
 		});
 	}
 }

src/main/java/com/github/theholywaffle/teamspeak3/EventManager.java

@@ -85,6 +85,8 @@ private TS3Event createEvent(String notifyName, String notifyBody) {
 				return new ChannelMovedEvent(eventData);
 			case "notifychannelpasswordchanged":
 				return new ChannelPasswordChangedEvent(eventData);
+			case "notifytokenused":
+				return new PrivilegeKeyUsedEvent(eventData);
 			default:
 				throw new TS3UnknownEventException(notifyName + " " + notifyBody);
 		}

src/main/java/com/github/theholywaffle/teamspeak3/TS3Api.java

@@ -2952,7 +2952,7 @@ public boolean quit() {
 	 *
 	 * @return whether all commands succeeded or not
 	 *
-	 * @querycommands 5
+	 * @querycommands 6
 	 * @see #addTS3Listeners(TS3Listener...)
 	 */
 	public boolean registerAllEvents() {
@@ -2962,6 +2962,7 @@ public boolean registerAllEvents() {
 		success &= registerEvent(TS3EventType.CHANNEL, 0);
 		success &= registerEvent(TS3EventType.TEXT_CHANNEL, 0);
 		success &= registerEvent(TS3EventType.TEXT_PRIVATE);
+		success &= registerEvent(TS3EventType.PRIVILEGE_KEY_USED);
 
 		return success;
 	}

src/main/java/com/github/theholywaffle/teamspeak3/TS3ApiAsync.java

@@ -3237,7 +3237,7 @@ public CommandFuture<Boolean> quit() {
 	 *
 	 * @return whether all commands succeeded or not
 	 *
-	 * @querycommands 5
+	 * @querycommands 6
 	 * @see #addTS3Listeners(TS3Listener...)
 	 */
 	public CommandFuture<Boolean> registerAllEvents() {
@@ -3249,6 +3249,7 @@ public CommandFuture<Boolean> registerAllEvents() {
 		eventFutures.add(registerEvent(TS3EventType.CHANNEL, 0));
 		eventFutures.add(registerEvent(TS3EventType.TEXT_CHANNEL, 0));
 		eventFutures.add(registerEvent(TS3EventType.TEXT_PRIVATE));
+		eventFutures.add(registerEvent(TS3EventType.PRIVILEGE_KEY_USED));
 
 		CommandFuture.ofAll(eventFutures).onSuccess(new CommandFuture.SuccessListener<List<Boolean>>() {
 			@Override

src/main/java/com/github/theholywaffle/teamspeak3/api/event/PrivilegeKeyUsedEvent.java

@@ -0,0 +1,75 @@
+package com.github.theholywaffle.teamspeak3.api.event;
+
+/*
+ * #%L
+ * TeamSpeak 3 Java API
+ * %%
+ * Copyright (C) 2016 Bert De Geyter, Roger Baumgartner
+ * %%
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ * #L%
+ */
+
+import com.github.theholywaffle.teamspeak3.api.TokenType;
+
+import java.util.Map;
+
+public class PrivilegeKeyUsedEvent extends BaseEvent {
+
+	public PrivilegeKeyUsedEvent(Map<String, String> map) {
+		super(map);
+	}
+
+	public int getClientId() {
+		return getInt("clid");
+	}
+
+	public int getClientDatabaseId() {
+		return getInt("cldbid");
+	}
+
+	public String getClientUniqueIdentifier() {
+		return get("cluid");
+	}
+
+	public String getPrivilegeKey() {
+		return get("token");
+	}
+
+	public TokenType getPrivilegeKeyType() {
+		if (getPrivilegeKeyChannelId() == 0) {
+			return TokenType.SERVER_GROUP;
+		} else {
+			return TokenType.CHANNEL_GROUP;
+		}
+	}
+
+	public int getPrivilegeKeyGroupId() {
+		return getInt("token1");
+	}
+
+	public int getPrivilegeKeyChannelId() {
+		return getInt("token2");
+	}
+
+	@Override
+	public void fire(TS3Listener listener) {
+		listener.onPrivilegeKeyUsed(this);
+	}
+}

src/main/java/com/github/theholywaffle/teamspeak3/api/event/TS3EventAdapter.java

@@ -67,4 +67,7 @@ public void onChannelMoved(ChannelMovedEvent e) {}
 
 	@Override
 	public void onChannelPasswordChanged(ChannelPasswordChangedEvent e) {}
+
+	@Override
+	public void onPrivilegeKeyUsed(PrivilegeKeyUsedEvent e) {}
 }

src/main/java/com/github/theholywaffle/teamspeak3/api/event/TS3EventType.java

@@ -32,7 +32,8 @@ public enum TS3EventType {
 	CHANNEL("channel"),
 	TEXT_SERVER("textserver"),
 	TEXT_CHANNEL("textchannel"),
-	TEXT_PRIVATE("textprivate");
+	TEXT_PRIVATE("textprivate"),
+	PRIVILEGE_KEY_USED("tokenused");
 
 	private final String name;
 

src/main/java/com/github/theholywaffle/teamspeak3/api/event/TS3Listener.java

@@ -50,4 +50,5 @@ public interface TS3Listener {
 
 	void onChannelPasswordChanged(ChannelPasswordChangedEvent e);
 
+	void onPrivilegeKeyUsed(PrivilegeKeyUsedEvent e);
 }