diff --git a/docs/features/commands.rst b/docs/features/commands.rst index 31da73c65..8abfb18a9 100644 --- a/docs/features/commands.rst +++ b/docs/features/commands.rst @@ -1,5 +1,5 @@ -Commands -======== +|stub| Commands +=============== The `Discord.Net.Commands`_ package DiscordBotClient extends DiscordClient with support for commands. @@ -11,10 +11,10 @@ Example (Simple) .. literalinclude:: /samples/command.cs :language: csharp6 :tab-width: 2 - + Example (Groups) ---------------- .. literalinclude:: /samples/command_group.cs :language: csharp6 - :tab-width: 2 \ No newline at end of file + :tab-width: 2 diff --git a/docs/features/events.rst b/docs/features/events.rst index 862d28dd3..c3ab1e3b9 100644 --- a/docs/features/events.rst +++ b/docs/features/events.rst @@ -1,75 +1,75 @@ -|stub| Events -============= +Events +====== Usage ----- -To take advantage of Events in Discord.Net, you need to hook into them. - -There are two ways of hooking into events. See the example for examples on using these events. - -Usable Events -------------- -+--------------------+--------------------+------------------------------------------+ -| Event Name | EventArgs | Description | -+====================+====================+==========================================+ -| UserBanned | BanEventArgs | Called when a user is banned. | -+--------------------+--------------------+------------------------------------------+ -| UserUnbanned | BanEventArgs | Called when a user is unbanned. | -+--------------------+--------------------+------------------------------------------+ -| ChannelCreated | ChannelEventArgs | Called when a channel is created. | -+--------------------+--------------------+------------------------------------------+ -| ChannelDestroyed | ChannelEventArgs | Called when a channel is destroyed. | -+--------------------+--------------------+------------------------------------------+ -| ChannelUpdated | ChannelEventArgs | Called when a channel is updated. | -+--------------------+--------------------+------------------------------------------+ -| MessageReceived | MessageEventArgs | Called when a message is received. | -+--------------------+--------------------+------------------------------------------+ -| MessageSent | MessageEventArgs | Called when a message is sent. | -+--------------------+--------------------+------------------------------------------+ -| MessageDeleted | MessageEventArgs | Called when a message is deleted. | -+--------------------+--------------------+------------------------------------------+ -| MessageUpdated | MessageEventArgs | Called when a message is updated\\edited.| -+--------------------+--------------------+------------------------------------------+ -| MessageReadRemotely| MessageEventArgs | Called when a message is read. | -+--------------------+--------------------+------------------------------------------+ -| RoleCreated | RoleEventArgs | Called when a role is created. | -+--------------------+--------------------+------------------------------------------+ -| RoleUpdated | RoleEventArgs | Called when a role is updated. | -+--------------------+--------------------+------------------------------------------+ -| RoleDeleted | RoleEventArgs | Called when a role is deleted. | -+--------------------+--------------------+------------------------------------------+ -| JoinedServer | ServerEventArgs | Called when a member joins a server. | -+--------------------+--------------------+------------------------------------------+ -| LeftServer | ServerEventArgs | Called when a member leaves a server. | -+--------------------+--------------------+------------------------------------------+ -| ServerUpdated | ServerEventArgs | Called when a server is updated. | -+--------------------+--------------------+------------------------------------------+ -| ServerUnavailable | ServerEventArgs | Called when a Discord server goes down. | -+--------------------+--------------------+------------------------------------------+ -| ServerAvailable | ServerEventArgs |Called when a Discord server goes back up.| -+--------------------+--------------------+------------------------------------------+ -| UserJoined | UserEventArgs | Called when a user joins a Channel. | -+--------------------+--------------------+------------------------------------------+ -| UserLeft | UserEventArgs | Called when a user leaves a Channel. | -+--------------------+--------------------+------------------------------------------+ -| UserUpdated | UserEventArgs | --- | -+--------------------+--------------------+------------------------------------------+ -| UserPresenceUpdated| UserEventArgs | Called when a user's presence changes. | -| | | (Here\\Away) | -+--------------------+--------------------+------------------------------------------+ -| UserVoiceState | UserEventArgs | Called when a user's voice state changes.| -| Updated | | (Muted\\Unmuted) | -+--------------------+--------------------+------------------------------------------+ -|UserIsTypingUpdated | UserEventArgs | Called when a user starts\\stops typing. | -+--------------------+--------------------+------------------------------------------+ -| UserIsSpeaking | UserEventArgs | Called when a user's voice state changes.| -| Updated | | (Speaking\\Not Speaking) | -+--------------------+--------------------+------------------------------------------+ -| ProfileUpdated | N/A | Called when a user's profile changes. | -+--------------------+--------------------+------------------------------------------+ -Example -------- - -.. literalinclude:: /samples/events.cs - :language: csharp6 - :tab-width: 2 \ No newline at end of file +Events in Discord.NET are raised using the Event system in c#. Most events are raised on the ``DiscordClient`` class. + +Most events in Discord.NET explain theirselves by their name. + +Messages +-------- + +The Four Message Events (MessageReceived, Updated, Deleted, and Acknowledged) are raised when a message has been modified/created. + +Example of MessageReceived: + +.. code-block:: c# + + // (Preface: Echo Bots are discouraged, make sure your bot is not running in a public server if you use them) + + // Hook into the MessageReceived event using a Lambda + _client.MessageReceived += (s, e) => { + // Check to make sure that the bot is not the author + if (!e.Message.IsAuthor) + // Echo the message back to the channel + e.Channel.SendMessage(e.Message); + }; + +Users +----- + +There are Six User Events: + +UserBanned: A user has been banned from a Server +UserUnbanned: A user was unbanned +UserJoined: A user joins a server +UserLeft: A user left (or was kicked) from a Server +UserIsTyping: A user in a channel starts typing +UserUpdated: A user object was updated. (caused by a presence update, role/permission change, or a voice state update) + +.. note:: + UserUpdated Events include a ``User`` object for Before and After the change. + When accessing the User, you should only use ``e.Before`` if comparing changes, otherwise use ``e.After`` + +Examples: + +.. code-block:: c# + + // Register a Hook into the UserBanned event using a Lambda + _client.UserBanned += (s, e) => { + // Create a Channel object by searching for a channel named '#logs' on the server the ban occurred in. + var logChannel = e.Server.FindChannels("logs").FirstOrDefault(); + // Send a message to the server's log channel, stating that a user was banned. + logChannel.SendMessage($"User Banned: {e.User.Name}") + }; + + // Register a Hook into the UserUpdated event using a Lambda + _client.UserUpdated += (s, e) => { + // Check that the user is in a Voice channel + if (e.After.VoiceChannel == null) return; + + // See if they changed Voice channels + if (e.Before.VoiceChannel == e.After.VoiceChannel) return; + + // do something... + }; + +Connection States +----------------- + +Connection Events will be raised when the Connection State of your client changes. + +.. warning:: + You should not use DiscordClient.Connected to run code when your client first connects to Discord. + If you lose connection and automatically reconnect, this code will be ran again, which may lead to unexpected behavior. diff --git a/docs/features/permissions.rst b/docs/features/permissions.rst index b4922cb53..058fe07cf 100644 --- a/docs/features/permissions.rst +++ b/docs/features/permissions.rst @@ -1,11 +1,11 @@ Permissions -================== +=========== There are two types of permissions: *Channel Permissions* and *Server Permissions*. Channel Permissions ------------------- -Channel Permissions have a set of bools behind them: +Channel Permissions are controlled using a set of flags: ======================= ======= ============== Flag Type Description @@ -49,7 +49,7 @@ Otherwise, you can use a single DualChannelPermissions. Server Permissions ------------------ -Server permisisons are read-only, you cannot change them. You may still access them, however, using User.GetServerPermissions(); +Server Permissions can be accessed by ``Server.GetPermissions(User)``, and updated with ``Server.UpdatePermissions(User, ServerPermissions)`` A user's server permissions also contain the default values for it's channel permissions, so the channel permissions listed above are also valid flags for Server Permissions. There are also a few extra Server Permissions: @@ -57,7 +57,7 @@ A user's server permissions also contain the default values for it's channel per Flag Type Description ======================= ======= ============== BanMembers Server Ban users from the server. -KickMembers Server Kick users from the server. They can stil rejoin. +KickMembers Server Kick users from the server. They can still rejoin. ManageRoles Server Manage roles on the server, and their permissions. ManageChannels Server Manage channels that exist on the server (add, remove them) ManageServer Server Manage the server settings. @@ -69,7 +69,7 @@ Managing permissions for roles is much easier than for users in channels. For ro Example ------- - + .. literalinclude:: /samples/permissions.cs :language: csharp6 - :tab-width: 2 \ No newline at end of file + :tab-width: 2 diff --git a/docs/index.rst b/docs/index.rst index c90a2936b..c4469cd46 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,7 +1,7 @@ Discord.Net =========== -Discord.Net is an unofficial C# wrapper around the `Discord chat service`. +Discord.Net is an unofficial C# wrapper around the `Discord Chat Service`. It offers several methods to create automated operations, bots, or even custom clients. Feel free to join us in the `Discord API chat`_. @@ -9,28 +9,28 @@ Feel free to join us in the `Discord API chat`_. .. _Discord chat service: https://discordapp.com .. _Discord API chat: https://discord.gg/0SBTUU1wZTVjAMPx -Warning -------- +.. warn:: -This is an alpha! +This is a beta! -This library has been built thanks to a community effort reverse engineering the Discord client. -As Discord is still in alpha, it may change at any time without notice, breaking this library as well. -Discord.Net itself is also in early development and you will often encounter breaking changes until the official Discord API is released. +This library has been built thanks to a community effort reverse engineering the Discord client. +As the API is still unofficial, it may change at any time without notice, breaking this library as well. +Discord.Net itself is still in development (and is currently undergoing a rewrite) and you may encounter breaking changes throughout development until the official Discord API is released. It is highly recommended that you always use the latest version and please report any bugs you find to our `Discord chat`_. .. _Discord chat: https://discord.gg/0SBTUU1wZTVjAMPx +This Documentation is **currently undergoing a rewrite**. Some pages (marked with a wrench) are not updated, or are not completed yet. + .. toctree:: :caption: Documentation :maxdepth: 2 - - getting_started - features/logging + + getting_started + features/logging features/management features/permissions - features/profile features/commands features/voice - features/events \ No newline at end of file + features/events diff --git a/docs/samples/getting_started.cs b/docs/samples/getting_started.cs index 228ef234e..55f7923a4 100644 --- a/docs/samples/getting_started.cs +++ b/docs/samples/getting_started.cs @@ -11,17 +11,17 @@ class Program client.MessageReceived += async (s, e) => { if (!e.Message.IsAuthor) - await client.SendMessage(e.Channel, e.Message.Text); + await e.Channel.SendMessage(e.Message.Text); }; //Convert our sync method to an async one and block the Main function until the bot disconnects - client.Run(async () => + client.ExecuteAndWait(async () => { //Connect to the Discord server using our email and password await client.Connect("discordtest@email.com", "Password123"); //If we are not a member of any server, use our invite code (made beforehand in the official Discord Client) - if (!client.AllServers.Any()) + if (!client.Servers.Any()) await client.AcceptInvite(client.GetInvite("aaabbbcccdddeee")); }); } diff --git a/docs/samples/permissions.cs b/docs/samples/permissions.cs index c09a151d6..419026714 100644 --- a/docs/samples/permissions.cs +++ b/docs/samples/permissions.cs @@ -1,28 +1,14 @@ -// Finding User Permissions +// Find a User's Channel Permissions +var userChannelPermissions = user.GetPermissions(channel); -void FindPermissions(User u, Channel c) -{ - ChannelPermissions cperms = u.GetPermissions(c); - ServerPermissions sperms = u.GetServerPermissions(); -} - -void SetPermissionsChannelPerms(User u, Channel c) -{ - ChannelPermissions allow = new ChannelPermissions(); - ChannelPermissions deny = new ChannelPermissions(); +// Find a User's Server Permissions +var userServerPermissions = user.ServerPermissions(); +var userServerPermissions = server.GetPermissions(user); - allow.Connect = true; - deny.AttachFiles = true; +// Set a User's Channel Permissions (using DualChannelPermissions) - client.SetChannelPermissions(c, u, allow, deny) +var userPerms = user.GetPermissions(channel); +userPerms.ReadMessageHistory = false; +userPerms.AttachFiles = null; +channel.AddPermissionsRule(user, userPerms); } - -void SetPermissionsDualPerms(User u, Channel c) -{ - DualChannelPermissions dual = new DualChannelPermissions(); - dual.ReadMessageHistory = false; - dual.Connect = true; - dual.AttachFiles = null; - - client.SetChannelPermissions(c, u, dual); -} \ No newline at end of file