-
-
Notifications
You must be signed in to change notification settings - Fork 724
/
TextChannel.java
292 lines (277 loc) · 14.7 KB
/
TextChannel.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
/*
* Copyright 2015-2017 Austin Keener & Michael Ritter
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package net.dv8tion.jda.core.entities;
import net.dv8tion.jda.core.requests.RestAction;
import net.dv8tion.jda.core.utils.MiscUtil;
import java.util.Collection;
import java.util.FormattableFlags;
import java.util.Formatter;
import java.util.List;
/**
* Represents a Discord Text Channel. See {@link net.dv8tion.jda.core.entities.Channel Channel} and
* {@link net.dv8tion.jda.core.entities.MessageChannel MessageChannel} for more information.
*
* <p>Internal implementation of this class is available at
* {@link net.dv8tion.jda.core.entities.impl.TextChannelImpl TextChannelImpl}.
* <br>Note: Internal implementation should not be used directly.
*/
public interface TextChannel extends Channel, MessageChannel, Comparable<TextChannel>, IMentionable
{
/**
* The topic set for this TextChannel.
* <br>If no topic has been set, this returns null.
*
* @return Possibly-null String containing the topic of this TextChannel.
*/
String getTopic();
/**
* Whether or not this channel is considered as "NSFW" (Not-Safe-For-Work)
* <br>This will check whether the name of this TextChannel begins with {@code nsfw-} or is equal to {@code nsfw}!
*
* @return True, If this TextChannel is considered NSFW by the official Discord Client
*/
boolean isNSFW();
/**
* Bulk deletes a list of messages.
* <b>This is not the same as calling {@link net.dv8tion.jda.core.entities.Message#delete()} in a loop.</b>
* <br>This is much more efficient, but it has a different ratelimit. You may call this once per second per Guild.
*
* <p>Must be at least 2 messages and not be more than 100 messages at a time.
* <br>If you only have 1 message, use the {@link Message#delete()} method instead.
*
* <br><p>You must have the Permission {@link net.dv8tion.jda.core.Permission#MESSAGE_MANAGE MESSAGE_MANAGE} in this channel to use
* this function.
*
* <p>This method is best used when using {@link MessageHistory MessageHistory} to delete a large amount
* of messages. If you have a large amount of messages but only their message Ids, please use {@link #deleteMessagesByIds(Collection)}
*
* <p>Possible ErrorResponses include:
* <ul>
* <li>{@link net.dv8tion.jda.core.requests.ErrorResponse#UNKNOWN_CHANNEL UNKNOWN_CHANNEL}
* <br>if this channel was deleted</li>
*
* <li>{@link net.dv8tion.jda.core.requests.ErrorResponse#UNKNOWN_MESSAGE UNKNOWN_MESSAGE}
* <br>if any of the provided messages does not exist</li>
*
* <li>{@link net.dv8tion.jda.core.requests.ErrorResponse#MISSING_ACCESS MISSING_ACCESS}
* <br>if we were removed from the guild</li>
*
* <li>{@link net.dv8tion.jda.core.requests.ErrorResponse#MISSING_PERMISSIONS MISSING_PERMISSIONS}
* <br>The send request was attempted after the account lost
* {@link net.dv8tion.jda.core.Permission#MESSAGE_MANAGE Permission.MESSAGE_MANAGE} in the channel.</li>
* </ul>
*
* @param messages
* The collection of messages to delete.
*
* @throws IllegalArgumentException
* If the size of the list less than 2 or more than 100 messages.
* @throws net.dv8tion.jda.core.exceptions.PermissionException
* If this account does not have MANAGE_MESSAGES
*
* @return {@link net.dv8tion.jda.core.requests.RestAction RestAction} - Type: Void
*
* @see #deleteMessagesByIds(Collection)
*/
RestAction<Void> deleteMessages(Collection<Message> messages);
/**
* Bulk deletes a list of messages.
* <b>This is not the same as calling {@link net.dv8tion.jda.core.entities.MessageChannel#deleteMessageById(String)} in a loop.</b>
* <br>This is much more efficient, but it has a different ratelimit. You may call this once per second per Guild.
*
* <p>Must be at least 2 messages and not be more than 100 messages at a time.
* <br>If you only have 1 message, use the {@link net.dv8tion.jda.core.entities.Message#delete()} method instead.
*
* <br><p>You must have {@link net.dv8tion.jda.core.Permission#MESSAGE_MANAGE Permission.MESSAGE_MANAGE} in this channel to use
* this function.
*
* <p>This method is best used when you have a large amount of messages but only their message Ids. If you are using
* {@link MessageHistory MessageHistory} or have {@link net.dv8tion.jda.core.entities.Message Message}
* objects, it would be easier to use {@link #deleteMessages(java.util.Collection)}.
*
* <p>Possible ErrorResponses include:
* <ul>
* <li>{@link net.dv8tion.jda.core.requests.ErrorResponse#UNKNOWN_CHANNEL UNKNOWN_CHANNEL}
* <br>if this channel was deleted</li>
*
* <li>{@link net.dv8tion.jda.core.requests.ErrorResponse#UNKNOWN_MESSAGE UNKNOWN_MESSAGE}
* <br>if any of the provided messages does not exist</li>
*
* <li>{@link net.dv8tion.jda.core.requests.ErrorResponse#MISSING_ACCESS MISSING_ACCESS}
* <br>if we were removed from the guild</li>
*
* <li>{@link net.dv8tion.jda.core.requests.ErrorResponse#MISSING_PERMISSIONS MISSING_PERMISSIONS}
* <br>The send request was attempted after the account lost
* {@link net.dv8tion.jda.core.Permission#MESSAGE_MANAGE Permission.MESSAGE_MANAGE} in the channel.</li>
* </ul>
*
* @param messageIds
* The message ids for the messages to delete.
*
* @throws java.lang.IllegalArgumentException
* If the size of the list less than 2 or more than 100 messages.
* @throws java.lang.NumberFormatException
* If any of the provided ids cannot be parsed by {@link Long#parseLong(String)}
* @throws net.dv8tion.jda.core.exceptions.PermissionException
* If this account does not have MANAGE_MESSAGES
*
* @return {@link net.dv8tion.jda.core.requests.RestAction RestAction} - Type: Void
*
* @see #deleteMessages(Collection)
*/
RestAction<Void> deleteMessagesByIds(Collection<String> messageIds);
/**
* Retrieves the {@link net.dv8tion.jda.core.entities.Webhook Webhooks} attached to this TextChannel.
*
* <p>Possible ErrorResponses include:
* <ul>
* <li>{@link net.dv8tion.jda.core.requests.ErrorResponse#UNKNOWN_CHANNEL UNKNOWN_CHANNEL}
* <br>if this channel was deleted</li>
*
* <li>{@link net.dv8tion.jda.core.requests.ErrorResponse#MISSING_ACCESS MISSING_ACCESS}
* <br>if we were removed from the guild</li>
* </ul>
*
* @return {@link net.dv8tion.jda.core.requests.RestAction} - Type: List{@literal <}{@link net.dv8tion.jda.core.entities.Webhook Webhook}{@literal >}
* <br>An immutable list of Webhook attached to this channel
*/
RestAction<List<Webhook>> getWebhooks();
/**
* Deletes a {@link net.dv8tion.jda.core.entities.Webhook Webhook} attached to this channel
* by the {@code id} specified.
*
* <p>Possible ErrorResponses include:
* <ul>
* <li>{@link net.dv8tion.jda.core.requests.ErrorResponse#UNKNOWN_WEBHOOK}
* <br>The provided id does not refer to a WebHook present in this TextChannel, either due
* to it not existing or having already been deleted.</li>
*
* <li>{@link net.dv8tion.jda.core.requests.ErrorResponse#UNKNOWN_CHANNEL UNKNOWN_CHANNEL}
* <br>if this channel was deleted</li>
*
* <li>{@link net.dv8tion.jda.core.requests.ErrorResponse#MISSING_ACCESS MISSING_ACCESS}
* <br>if we were removed from the guild</li>
*
* <li>{@link net.dv8tion.jda.core.requests.ErrorResponse#MISSING_PERMISSIONS MISSING_PERMISSIONS}
* <br>The send request was attempted after the account lost
* {@link net.dv8tion.jda.core.Permission#MANAGE_WEBHOOKS Permission.MANAGE_WEBHOOKS} in the channel.</li>
* </ul>
*
* @param id
* The not-null id for the target Webhook.
*
* @throws java.lang.IllegalArgumentException
* If the provided {@code id} is {@code null} or empty.
* @throws net.dv8tion.jda.core.exceptions.PermissionException
* If the currently logged in account does not have
* {@link net.dv8tion.jda.core.Permission#MANAGE_WEBHOOKS Permission.MANAGE_WEBHOOKS} in this channel.
*
* @return {@link net.dv8tion.jda.core.requests.RestAction} - Type: Void
*/
RestAction<Void> deleteWebhookById(String id);
/**
* Attempts to remove all reactions from a message with the specified {@code messageId} in this TextChannel
* <br>This is useful for moderator commands that wish to remove all reactions at once from a specific message.
*
* <p>The following {@link net.dv8tion.jda.core.requests.ErrorResponse ErrorResponses} are possible:
* <ul>
* <li>{@link net.dv8tion.jda.core.requests.ErrorResponse#MISSING_ACCESS MISSING_ACCESS}
* <br>The clear-reactions request was attempted after the account lost access to the {@link net.dv8tion.jda.core.entities.TextChannel TextChannel}
* due to {@link net.dv8tion.jda.core.Permission#MESSAGE_READ Permission.MESSAGE_READ} being revoked, or the
* account lost access to the {@link net.dv8tion.jda.core.entities.Guild Guild} or {@link net.dv8tion.jda.client.entities.Group Group}
* typically due to being kicked or removed.</li>
*
* <li>{@link net.dv8tion.jda.core.requests.ErrorResponse#MISSING_PERMISSIONS MISSING_PERMISSIONS}
* <br>The clear-reactions request was attempted after the account lost {@link net.dv8tion.jda.core.Permission#MESSAGE_MANAGE Permission.MESSAGE_MANAGE}
* in the {@link net.dv8tion.jda.core.entities.TextChannel TextChannel} when adding the reaction.</li>
*
* <li>{@link net.dv8tion.jda.core.requests.ErrorResponse#UNKNOWN_MESSAGE UNKNOWN_MESSAGE}
* The clear-reactions request was attempted after the Message had been deleted.</li>
* </ul>
*
* @throws net.dv8tion.jda.core.exceptions.PermissionException
* If the currently logged in account does not have
* {@link net.dv8tion.jda.core.Permission#MESSAGE_MANAGE Permission.MESSAGE_MANAGE} in this channel.
* @throws java.lang.IllegalArgumentException
* If the provided {@code id} is {@code null} or empty.
*
* @return {@link net.dv8tion.jda.core.requests.RestAction RestAction} - Type: {@link java.lang.Void}
*/
RestAction<Void> clearReactionsById(String messageId);
/**
* Attempts to remove all reactions from a message with the specified {@code messageId} in this TextChannel
* <br>This is useful for moderator commands that wish to remove all reactions at once from a specific message.
*
* <p>The following {@link net.dv8tion.jda.core.requests.ErrorResponse ErrorResponses} are possible:
* <ul>
* <li>{@link net.dv8tion.jda.core.requests.ErrorResponse#MISSING_ACCESS MISSING_ACCESS}
* <br>The clear-reactions request was attempted after the account lost access to the {@link net.dv8tion.jda.core.entities.TextChannel TextChannel}
* due to {@link net.dv8tion.jda.core.Permission#MESSAGE_READ Permission.MESSAGE_READ} being revoked, or the
* account lost access to the {@link net.dv8tion.jda.core.entities.Guild Guild} or {@link net.dv8tion.jda.client.entities.Group Group}
* typically due to being kicked or removed.</li>
*
* <li>{@link net.dv8tion.jda.core.requests.ErrorResponse#MISSING_PERMISSIONS MISSING_PERMISSIONS}
* <br>The clear-reactions request was attempted after the account lost {@link net.dv8tion.jda.core.Permission#MESSAGE_MANAGE Permission.MESSAGE_MANAGE}
* in the {@link net.dv8tion.jda.core.entities.TextChannel TextChannel} when adding the reaction.</li>
*
* <li>{@link net.dv8tion.jda.core.requests.ErrorResponse#UNKNOWN_MESSAGE UNKNOWN_MESSAGE}
* The clear-reactions request was attempted after the Message had been deleted.</li>
* </ul>
*
* @throws net.dv8tion.jda.core.exceptions.PermissionException
* If the currently logged in account does not have
* {@link net.dv8tion.jda.core.Permission#MESSAGE_MANAGE Permission.MESSAGE_MANAGE} in this channel.
*
* @return {@link net.dv8tion.jda.core.requests.RestAction RestAction} - Type: {@link java.lang.Void}
*/
default RestAction<Void> clearReactionsById(long messageId) {
return clearReactionsById(Long.toUnsignedString(messageId));
}
/**
* Whether we can send messages in this channel.
* <br>This is an overload of {@link #canTalk(Member)} with the SelfMember.
* <br>Checks for both {@link net.dv8tion.jda.core.Permission#MESSAGE_READ Permission.MESSAGE_READ} and
* {@link net.dv8tion.jda.core.Permission#MESSAGE_WRITE Permission.MESSAGE_WRITE}.
*
* @return True, if we are able to read and send messages in this channel
*/
boolean canTalk();
/**
* Whether the specified {@link net.dv8tion.jda.core.entities.Member}
* can send messages in this channel.
* <br>Checks for both {@link net.dv8tion.jda.core.Permission#MESSAGE_READ Permission.MESSAGE_READ} and
* {@link net.dv8tion.jda.core.Permission#MESSAGE_WRITE Permission.MESSAGE_WRITE}.
*
* @param member
* The Member to check
*
* @return True, if the specified member is able to read and send messages in this channel
*/
boolean canTalk(Member member);
@Override
default void formatTo(Formatter formatter, int flags, int width, int precision)
{
boolean leftJustified = (flags & FormattableFlags.LEFT_JUSTIFY) == FormattableFlags.LEFT_JUSTIFY;
boolean upper = (flags & FormattableFlags.UPPERCASE) == FormattableFlags.UPPERCASE;
boolean alt = (flags & FormattableFlags.ALTERNATE) == FormattableFlags.ALTERNATE;
String out;
if (alt)
out = "#" + (upper ? getName().toUpperCase(formatter.locale()) : getName());
else
out = getAsMention();
MiscUtil.appendTo(formatter, width, precision, leftJustified, out);
}
}