All Downloads are FREE. Search and download functionalities are using the official Maven repository.

net.dv8tion.jda.api.entities.Invite Maven / Gradle / Ivy

Go to download

Java wrapper for the popular chat & VOIP service: Discord https://discord.com

There is a newer version: 5.1.0
Show newest version
/*
 * Copyright 2015 Austin Keener, Michael Ritter, Florian Spieß, and the JDA contributors
 *
 * 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.api.entities;

import net.dv8tion.jda.api.JDA;
import net.dv8tion.jda.api.entities.Guild.VerificationLevel;
import net.dv8tion.jda.api.entities.channel.ChannelType;
import net.dv8tion.jda.api.requests.RestAction;
import net.dv8tion.jda.api.requests.restaction.AuditableRestAction;
import net.dv8tion.jda.api.utils.ImageProxy;
import net.dv8tion.jda.internal.entities.InviteImpl;

import javax.annotation.CheckReturnValue;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import java.time.OffsetDateTime;
import java.util.List;
import java.util.Set;

/**
 * Representation of a Discord Invite.
 * This class is immutable.
 *
 * @since  3.0
 * @author Aljoscha Grebe
 *
 * @see    #resolve(JDA, String)
 * @see    #resolve(JDA, String, boolean)
 *
 * @see    net.dv8tion.jda.api.entities.Guild#retrieveInvites() Guild.retrieveInvites()
 * @see    net.dv8tion.jda.api.entities.channel.attribute.IInviteContainer#retrieveInvites()
 */
public interface Invite
{
    /**
     * Retrieves a new {@link Invite Invite} instance for the given invite code.
     * 
You cannot resolve invites if you were banned from the origin Guild! * *

Possible {@link net.dv8tion.jda.api.requests.ErrorResponse ErrorResponses} include: *

    *
  • {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_INVITE Unknown Invite} *
    The Invite did not exist (possibly deleted) or the account is banned in the guild.
  • *
* * @param api * The JDA instance * @param code * A valid invite code * * @return {@link net.dv8tion.jda.api.requests.RestAction RestAction} - Type: {@link Invite Invite} *
The Invite object */ @Nonnull static RestAction resolve(@Nonnull final JDA api, @Nonnull final String code) { return resolve(api, code, false); } /** * Retrieves a new {@link Invite Invite} instance for the given invite code. *
You cannot resolve invites if you were banned from the origin Guild! * *

Possible {@link net.dv8tion.jda.api.requests.ErrorResponse ErrorResponses} include: *

    *
  • {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_INVITE Unknown Invite} *
    The Invite did not exist (possibly deleted) or the account is banned in the guild.
  • *
* * @param api * The JDA instance * @param code * A valid invite code * @param withCounts * Whether or not to include online and member counts for guild invites or users for group invites * * @return {@link net.dv8tion.jda.api.requests.RestAction RestAction} - Type: {@link Invite Invite} *
The Invite object */ @Nonnull static RestAction resolve(@Nonnull final JDA api, @Nonnull final String code, final boolean withCounts) { return InviteImpl.resolve(api, code, withCounts); } /** * Deletes this invite. *
Requires {@link net.dv8tion.jda.api.Permission#MANAGE_CHANNEL MANAGE_CHANNEL} in the invite's channel. * Will throw an {@link net.dv8tion.jda.api.exceptions.InsufficientPermissionException InsufficientPermissionException} otherwise. * * @throws net.dv8tion.jda.api.exceptions.InsufficientPermissionException * if the account does not have {@link net.dv8tion.jda.api.Permission#MANAGE_SERVER MANAGE_SERVER} in the invite's channel * * @return {@link net.dv8tion.jda.api.requests.restaction.AuditableRestAction AuditableRestAction} */ @Nonnull @CheckReturnValue AuditableRestAction delete(); /** * Tries to retrieve a new expanded {@link Invite Invite} with more info. *
As bots can't be in groups this is only available for guild invites and will throw an {@link java.lang.IllegalStateException IllegalStateException} * for other types. *
Requires either {@link net.dv8tion.jda.api.Permission#MANAGE_SERVER MANAGE_SERVER} in the invite's guild or * {@link net.dv8tion.jda.api.Permission#MANAGE_CHANNEL MANAGE_CHANNEL} in the invite's channel. * Will throw an {@link net.dv8tion.jda.api.exceptions.InsufficientPermissionException InsufficientPermissionException} otherwise. * * @throws net.dv8tion.jda.api.exceptions.InsufficientPermissionException * if the account neither has {@link net.dv8tion.jda.api.Permission#MANAGE_SERVER MANAGE_SERVER} in the invite's guild nor * {@link net.dv8tion.jda.api.Permission#MANAGE_CHANNEL MANAGE_CHANNEL} in the invite's channel * @throws java.lang.IllegalStateException * If this is a group invite * * @return {@link net.dv8tion.jda.api.requests.RestAction RestAction} - Type: {@link Invite Invite} *
The expanded Invite object * * @see #getType() * @see #isExpanded() */ @Nonnull @CheckReturnValue RestAction expand(); /** * The type of this invite. * * @return The invite's type */ @Nonnull Invite.InviteType getType(); /** * The target type of this invite or {@link TargetType#NONE} if this invite does not have a {@link #getTarget() InviteTarget}. * * @return The invite's target type or {@link TargetType#NONE} * * @see Invite.TargetType */ @Nonnull Invite.TargetType getTargetType(); /** * An {@link Invite.Channel Invite.Channel} object * containing information about this invite's origin channel. * * @return Information about this invite's origin channel or null in case of a group invite * * @see Invite.Channel */ @Nullable Channel getChannel(); /** * An {@link Invite.Group Invite.Group} object * containing information about this invite's origin group. * * @return Information about this invite's origin group or null in case of a guild invite * * @see Invite.Group */ @Nullable Group getGroup(); /** * An {@link Invite.InviteTarget Invite.InviteTarget} object * containing information about this invite's target or {@code null} * if this invite does not have a target. * * @return Information about this invite's target or {@code null} * * @see Invite.InviteTarget */ @Nullable InviteTarget getTarget(); /** * The invite code * * @return the invite code */ @Nonnull String getCode(); /** * The invite URL for this invite in the format of: * {@code "https://discord.gg/" + getCode()} * * @return Invite URL for this Invite */ @Nonnull default String getUrl() { return "https://discord.gg/" + getCode(); } /** * An {@link Invite.Guild Invite.Guild} object * containing information about this invite's origin guild. * * @return Information about this invite's origin guild or null in case of a group invite * * @see Invite.Guild */ @Nullable Guild getGuild(); /** * The user who created this invite. For not expanded invites this may be null. * * @return The user who created this invite */ @Nullable User getInviter(); /** * The {@link net.dv8tion.jda.api.JDA JDA} instance used to create this Invite * * @return the corresponding JDA instance */ @Nonnull JDA getJDA(); /** * The max age of this invite in seconds. * *

This works only for expanded invites and will throw a {@link IllegalStateException} otherwise! * * @throws IllegalStateException * if this invite is not expanded * * @return The max age of this invite in seconds * * @see #expand() * @see #isExpanded() */ int getMaxAge(); /** * The max uses of this invite. If there is no limit thus will return {@code 0}. * *

This works only for expanded invites and will throw a {@link IllegalStateException} otherwise! * * @throws IllegalStateException * if this invite is not expanded * * @return The max uses of this invite or {@code 0} if there is no limit * * @see #expand() * @see #isExpanded() */ int getMaxUses(); /** * Returns creation date of this invite. * *

This works only for expanded invites and will throw a {@link IllegalStateException} otherwise! * * @throws IllegalStateException * if this invite is not expanded * * @return The creation date of this invite * * @see #expand() * @see #isExpanded() */ @Nonnull OffsetDateTime getTimeCreated(); /** * How often this invite has been used. * *

This works only for expanded invites and will throw a {@link IllegalStateException} otherwise! * * @throws IllegalStateException * if this invite is not expanded * * @return The uses of this invite * * @see #expand() * @see #isExpanded() */ int getUses(); /** * Whether this Invite is expanded or not. Expanded invites contain more information, but they can only be * obtained by {@link net.dv8tion.jda.api.entities.Guild#retrieveInvites() Guild#retrieveInvites()} (requires * {@link net.dv8tion.jda.api.Permission#MANAGE_SERVER Permission.MANAGE_SERVER}) or * {@link net.dv8tion.jda.api.entities.channel.attribute.IInviteContainer#retrieveInvites() IInviteContainer#retrieveInvites()} (requires * {@link net.dv8tion.jda.api.Permission#MANAGE_CHANNEL Permission.MANAGE_CHANNEL}). * *

There is a convenience method {@link #expand()} to get the expanded invite for an unexpanded one. * * @return Whether this invite is expanded or not * * @see #expand() */ boolean isExpanded(); /** * Whether this Invite grants only temporary access or not. * *

This works only for expanded invites and will throw a {@link IllegalStateException} otherwise! * * @throws IllegalStateException * if this invite is not expanded * * @return Whether this invite is temporary or not * * @see #expand() * @see #isExpanded() */ boolean isTemporary(); /** * POJO for the channel information provided by an invite. * * @see #getChannel() */ interface Channel extends ISnowflake { /** * The name of this channel. * * @return The channel's name */ @Nonnull String getName(); /** * The {@link ChannelType ChannelType} of this channel. *
Valid values are only {@link ChannelType#TEXT TEXT} or {@link ChannelType#VOICE VOICE} * * @return The channel's type */ @Nonnull ChannelType getType(); } /** * POJO for the guild information provided by an invite. * * @see #getGuild() */ interface Guild extends ISnowflake { /** * The icon id of this guild. * * @return The guild's icon id * * @see #getIconUrl() */ @Nullable String getIconId(); /** * The icon url of this guild. * * @return The guild's icon url * * @see #getIconId() */ @Nullable String getIconUrl(); /** * Returns an {@link ImageProxy} for this guild's icon * * @return Possibly-null {@link ImageProxy} of this guild's icon * * @see #getIconUrl() */ @Nullable default ImageProxy getIcon() { final String iconUrl = getIconUrl(); return iconUrl == null ? null : new ImageProxy(iconUrl); } /** * The name of this guild. * * @return The guild's name */ @Nonnull String getName(); /** * The splash image id of this guild. * * @return The guild's splash image id or {@code null} if the guild has no splash image * * @see #getSplashUrl() */ @Nullable String getSplashId(); /** * Returns the splash image url of this guild. * * @return The guild's splash image url or {@code null} if the guild has no splash image * * @see #getSplashId() */ @Nullable String getSplashUrl(); /** * Returns an {@link ImageProxy} for this invite guild's splash image. * * @return Possibly-null {@link ImageProxy} of this invite guild's splash image * * @see #getSplashUrl() */ @Nullable default ImageProxy getSplash() { final String splashUrl = getSplashUrl(); return splashUrl == null ? null : new ImageProxy(splashUrl); } /** * Returns the {@link net.dv8tion.jda.api.entities.Guild.VerificationLevel VerificationLevel} of this guild. * * @return the verification level of the guild */ @Nonnull VerificationLevel getVerificationLevel(); /** * Returns the approximate count of online members in the guild. If the online member count was not included in the * invite, this will return -1. Counts will usually only be returned when resolving the invite via the * {@link #resolve(net.dv8tion.jda.api.JDA, java.lang.String, boolean) Invite.resolve()} method with the * withCounts boolean set to {@code true} * * @return the approximate count of online members in the guild, or -1 if not present in the invite */ int getOnlineCount(); /** * Returns the approximate count of total members in the guild. If the total member count was not included in the * invite, this will return -1. Counts will usually only be returned when resolving the invite via the * {@link #resolve(net.dv8tion.jda.api.JDA, java.lang.String, boolean) Invite.resolve()} method with the * withCounts boolean set to {@code true} * * @return the approximate count of total members in the guild, or -1 if not present in the invite */ int getMemberCount(); /** * The Features of the {@link Invite.Guild Guild}. *

* Possible known features: *

    *
  • VIP_REGIONS - Guild has VIP voice regions
  • *
  • VANITY_URL - Guild a vanity URL (custom invite link)
  • *
  • INVITE_SPLASH - Guild has custom invite splash. See {@link #getSplashId()} and {@link #getSplashUrl()}
  • *
  • VERIFIED - Guild is "verified"
  • *
  • MORE_EMOJI - Guild is able to use more than 50 emoji
  • *
* * @return Never-null, unmodifiable Set containing all of the Guild's features. */ @Nonnull Set getFeatures(); /** * The welcome screen of the {@link Invite.Guild Guild}. *
This will be {@code null} if the Guild has no welcome screen, * or if the invite came from a {@link net.dv8tion.jda.api.events.guild.invite.GuildInviteCreateEvent GuildInviteCreateEvent}. * * @return The welcome screen of this Guild or {@code null} */ @Nullable GuildWelcomeScreen getWelcomeScreen(); } /** * POJO for the group information provided by an invite. * * @see #getChannel() */ interface Group extends ISnowflake { /** * The icon id of this group or {@code null} if the group has no icon. * * @return The group's icon id * * @see #getIconUrl() */ @Nullable String getIconId(); /** * The icon url of this group or {@code null} if the group has no icon. * * @return The group's icon url * * @see #getIconId() */ @Nullable String getIconUrl(); /** * Returns an {@link ImageProxy} for this group invite's icon. * * @return Possibly-null {@link ImageProxy} of this group invite's icon * * @see #getIconUrl() */ @Nullable default ImageProxy getIcon() { final String iconUrl = getIconUrl(); return iconUrl == null ? null : new ImageProxy(iconUrl); } /** * The name of this group or {@code null} if the group has no name. * * @return The group's name */ @Nullable String getName(); /** * The names of all users in this group. If the users were not included in the * invite, this will return {@code null}. Users will only be returned when resolving the invite via the * {@link #resolve(net.dv8tion.jda.api.JDA, java.lang.String, boolean) Invite.resolve()} method with the * {@code withCounts} boolean set to {@code true}. * * @return The names of the group's users or null if not preset in the invite */ @Nullable List getUsers(); } /** * POJO for the target of this invite. * * @see #getTarget() */ interface InviteTarget { /** * The type of this invite target. * * @return The type of this invite target */ @Nonnull TargetType getType(); /** * The Snowflake id of the target entity of this invite. * * @throws IllegalStateException * If there is no target entity, {@link #getType() TargetType} is {@link TargetType#UNKNOWN} * * @return The id of the target entity */ @Nonnull String getId(); /** * The Snowflake id of the target entity of this invite. * * @throws IllegalStateException * If there is no target entity, {@link #getType() TargetType} is {@link TargetType#UNKNOWN} * * @return The id of the target entity */ long getIdLong(); /** * The target {@link User} of this invite or {@code null} if the {@link #getType() TargeType} is not {@link TargetType#STREAM} * * @return The target user of this invite * * @see net.dv8tion.jda.api.entities.User */ @Nullable User getUser(); /** * The target {@link EmbeddedApplication} of this invite or {@code null} if the {@link #getType() TargeType} is not {@link TargetType#EMBEDDED_APPLICATION} * * @return The target application of this invite * * @see Invite.EmbeddedApplication */ @Nullable EmbeddedApplication getApplication(); } /** * POJO for the target application information provided by an invite. * * @see InviteTarget#getApplication() */ interface EmbeddedApplication extends ISnowflake { /** * The name of this application. * * @return The name of this application. */ @Nonnull String getName(); /** * The description of this application. * * @return The description of this application. */ @Nonnull String getDescription(); /** * The summary of this application or {@code null} if this application has no summary. * * @return The summary of this application. */ @Nullable String getSummary(); /** * The icon id of this application or {@code null} if the application has no icon. * * @return The application's icon id * * @see #getIconUrl() */ @Nullable String getIconId(); /** * The icon url of this application or {@code null} if the application has no icon. * * @return The application's icon url * * @see #getIconId() */ @Nullable String getIconUrl(); /** * Returns an {@link ImageProxy} for this application invite's icon. * * @return Possibly-null {@link ImageProxy} of this application invite's icon * * @see #getIconUrl() */ @Nullable default ImageProxy getIcon() { final String iconUrl = getIconUrl(); return iconUrl == null ? null : new ImageProxy(iconUrl); } /** * The max participant count of this application or {@code -1} if no max participant count is set * * @return {@code -1} if this application does not have a max participant count */ int getMaxParticipants(); } /** * Enum representing the type of an invite. * * @see #getType() */ enum InviteType { GUILD, GROUP, UNKNOWN } /** * A TargetType indicates additional action to be taken by the client on accepting the invite, * typically connecting external services or launching external applications depending on the specific TargetType. * *

Some actions might not be available or show up on certain devices. * * @see InviteTarget#getType() */ enum TargetType { /** * The invite does not have a target type, {@link Invite#getTarget()} will return {@code null}. */ NONE(0), /** * The invite points to a user's stream in a voice channel. * The user to whose stream the invite goes can be get with {@link InviteTarget#getUser() InviteTarget.getUser} and is not {@code null}. * * @see InviteTarget#getUser() */ STREAM(1), /** * The invite points to an application in a voice channel. * The application to which the invite goes can be get with {@link InviteTarget#getApplication() InviteTarget.getApplication} and is not {@code null}. * * @see InviteTarget#getApplication() */ EMBEDDED_APPLICATION(2), /** * The invite points to a role subscription listing in a guild. *
These cannot be created by bots. */ ROLE_SUBSCRIPTIONS_PURCHASE(3), /** * Unknown Discord invite target type. Should never happen and would only possibly happen if Discord implemented a new * target type and JDA had yet to implement support for it. */ UNKNOWN(-1); private final int id; TargetType(int id) { this.id = id; } /** * The Discord id key used to represent the target type. * * @return The id key used by discord for this channel type. */ public int getId() { return id; } /** * Static accessor for retrieving a target type based on its Discord id key. * * @param id * The id key of the requested target type. * * @return The TargetType that is referred to by the provided key. If the id key is unknown, {@link #UNKNOWN} is returned. */ @Nonnull public static TargetType fromId(int id) { for (TargetType type : values()) { if (type.id == id) return type; } return UNKNOWN; } } }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy