github/Discord.Net
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Began updating documentation; fixed features/permissions to use more up-to-date information; made features/events contain usable information (removed the table of events); marked commands as a stub due to it being outdated; modified samples; updated index page

Browse Source
This commit is contained in:
Christopher F
2016-01-23 21:58:29 -05:00
parent 1ae7c36d31
commit 4081f6ae18
6 changed files with 107 additions and 121 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/features/commands.rst
View File

@@ -1,5 +1,5 @@
Commands |stub| Commands
======== ===============
The `Discord.Net.Commands`_ package DiscordBotClient extends DiscordClient with support for commands. The `Discord.Net.Commands`_ package DiscordBotClient extends DiscordClient with support for commands.
@@ -11,10 +11,10 @@ Example (Simple)
.. literalinclude:: /samples/command.cs .. literalinclude:: /samples/command.cs
:language: csharp6 :language: csharp6
:tab-width: 2 :tab-width: 2
Example (Groups) Example (Groups)
---------------- ----------------
.. literalinclude:: /samples/command_group.cs .. literalinclude:: /samples/command_group.cs
:language: csharp6 :language: csharp6
:tab-width: 2 :tab-width: 2

140
docs/features/events.rst
View File

@@ -1,75 +1,75 @@
|stub| Events Events
============= ======
Usage Usage
----- -----
To take advantage of Events in Discord.Net, you need to hook into them. Events in Discord.NET are raised using the Event system in c#. Most events are raised on the ``DiscordClient`` class.
There are two ways of hooking into events. See the example for examples on using these events. Most events in Discord.NET explain theirselves by their name.
Usable Events Messages
------------- --------
+--------------------+--------------------+------------------------------------------+
| Event Name | EventArgs | Description | The Four Message Events (MessageReceived, Updated, Deleted, and Acknowledged) are raised when a message has been modified/created.
+====================+====================+==========================================+
| UserBanned | BanEventArgs | Called when a user is banned. | Example of MessageReceived:
+--------------------+--------------------+------------------------------------------+
| UserUnbanned | BanEventArgs | Called when a user is unbanned. | .. code-block:: c#
+--------------------+--------------------+------------------------------------------+
| ChannelCreated | ChannelEventArgs | Called when a channel is created. | // (Preface: Echo Bots are discouraged, make sure your bot is not running in a public server if you use them)
+--------------------+--------------------+------------------------------------------+
| ChannelDestroyed | ChannelEventArgs | Called when a channel is destroyed. | // Hook into the MessageReceived event using a Lambda
+--------------------+--------------------+------------------------------------------+ _client.MessageReceived += (s, e) => {
| ChannelUpdated | ChannelEventArgs | Called when a channel is updated. | // Check to make sure that the bot is not the author
+--------------------+--------------------+------------------------------------------+ if (!e.Message.IsAuthor)
| MessageReceived | MessageEventArgs | Called when a message is received. | // Echo the message back to the channel
+--------------------+--------------------+------------------------------------------+ e.Channel.SendMessage(e.Message);
| MessageSent | MessageEventArgs | Called when a message is sent. | };
+--------------------+--------------------+------------------------------------------+
| MessageDeleted | MessageEventArgs | Called when a message is deleted. | Users
+--------------------+--------------------+------------------------------------------+ -----
| MessageUpdated | MessageEventArgs | Called when a message is updated\\edited.|
+--------------------+--------------------+------------------------------------------+ There are Six User Events:
| MessageReadRemotely| MessageEventArgs | Called when a message is read. |
+--------------------+--------------------+------------------------------------------+ UserBanned: A user has been banned from a Server
| RoleCreated | RoleEventArgs | Called when a role is created. | UserUnbanned: A user was unbanned
+--------------------+--------------------+------------------------------------------+ UserJoined: A user joins a server
| RoleUpdated | RoleEventArgs | Called when a role is updated. | UserLeft: A user left (or was kicked) from a Server
+--------------------+--------------------+------------------------------------------+ UserIsTyping: A user in a channel starts typing
| RoleDeleted | RoleEventArgs | Called when a role is deleted. | UserUpdated: A user object was updated. (caused by a presence update, role/permission change, or a voice state update)
+--------------------+--------------------+------------------------------------------+
| JoinedServer | ServerEventArgs | Called when a member joins a server. | .. note::
+--------------------+--------------------+------------------------------------------+ UserUpdated Events include a ``User`` object for Before and After the change.
| LeftServer | ServerEventArgs | Called when a member leaves a server. | When accessing the User, you should only use ``e.Before`` if comparing changes, otherwise use ``e.After``
+--------------------+--------------------+------------------------------------------+
| ServerUpdated | ServerEventArgs | Called when a server is updated. | Examples:
+--------------------+--------------------+------------------------------------------+
| ServerUnavailable | ServerEventArgs | Called when a Discord server goes down. | .. code-block:: c#
+--------------------+--------------------+------------------------------------------+
| ServerAvailable | ServerEventArgs |Called when a Discord server goes back up.| // Register a Hook into the UserBanned event using a Lambda
+--------------------+--------------------+------------------------------------------+ _client.UserBanned += (s, e) => {
| UserJoined | UserEventArgs | Called when a user joins a Channel. | // 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();
| UserLeft | UserEventArgs | Called when a user leaves a Channel. | // Send a message to the server's log channel, stating that a user was banned.
+--------------------+--------------------+------------------------------------------+ logChannel.SendMessage($"User Banned: {e.User.Name}")
| UserUpdated | UserEventArgs | --- | };
+--------------------+--------------------+------------------------------------------+
| UserPresenceUpdated| UserEventArgs | Called when a user's presence changes. | // Register a Hook into the UserUpdated event using a Lambda
| | | (Here\\Away) | _client.UserUpdated += (s, e) => {
+--------------------+--------------------+------------------------------------------+ // Check that the user is in a Voice channel
| UserVoiceState | UserEventArgs | Called when a user's voice state changes.| if (e.After.VoiceChannel == null) return;
| Updated | | (Muted\\Unmuted) |
+--------------------+--------------------+------------------------------------------+ // See if they changed Voice channels
|UserIsTypingUpdated | UserEventArgs | Called when a user starts\\stops typing. | if (e.Before.VoiceChannel == e.After.VoiceChannel) return;
+--------------------+--------------------+------------------------------------------+
| UserIsSpeaking | UserEventArgs | Called when a user's voice state changes.| // do something...
| Updated | | (Speaking\\Not Speaking) | };
+--------------------+--------------------+------------------------------------------+
| ProfileUpdated | N/A | Called when a user's profile changes. | Connection States
+--------------------+--------------------+------------------------------------------+ -----------------
Example
------- Connection Events will be raised when the Connection State of your client changes.
.. literalinclude:: /samples/events.cs .. warning::
:language: csharp6 You should not use DiscordClient.Connected to run code when your client first connects to Discord.
:tab-width: 2 If you lose connection and automatically reconnect, this code will be ran again, which may lead to unexpected behavior.

12
docs/features/permissions.rst
View File

@@ -1,11 +1,11 @@
Permissions Permissions
================== ===========
There are two types of permissions: *Channel Permissions* and *Server Permissions*. There are two types of permissions: *Channel Permissions* and *Server Permissions*.
Channel Permissions Channel Permissions
------------------- -------------------
Channel Permissions have a set of bools behind them: Channel Permissions are controlled using a set of flags:
======================= ======= ============== ======================= ======= ==============
Flag Type Description Flag Type Description
@@ -49,7 +49,7 @@ Otherwise, you can use a single DualChannelPermissions.
Server Permissions 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: 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 Flag Type Description
======================= ======= ============== ======================= ======= ==============
BanMembers Server Ban users from the server. 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. ManageRoles Server Manage roles on the server, and their permissions.
ManageChannels Server Manage channels that exist on the server (add, remove them) ManageChannels Server Manage channels that exist on the server (add, remove them)
ManageServer Server Manage the server settings. 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 Example
------- -------
.. literalinclude:: /samples/permissions.cs .. literalinclude:: /samples/permissions.cs
:language: csharp6 :language: csharp6
:tab-width: 2 :tab-width: 2

24
docs/index.rst
View File

@@ -1,7 +1,7 @@
Discord.Net 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. It offers several methods to create automated operations, bots, or even custom clients.
Feel free to join us in the `Discord API chat`_. 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 chat service: https://discordapp.com
.. _Discord API chat: https://discord.gg/0SBTUU1wZTVjAMPx .. _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. 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. As the API is still unofficial, 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. 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`_. 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 .. _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:: .. toctree::
:caption: Documentation :caption: Documentation
:maxdepth: 2 :maxdepth: 2
getting_started getting_started
features/logging features/logging
features/management features/management
features/permissions features/permissions
features/profile
features/commands features/commands
features/voice features/voice
features/events features/events

6
docs/samples/getting_started.cs
View File

@@ -11,17 +11,17 @@ class Program
client.MessageReceived += async (s, e) => client.MessageReceived += async (s, e) =>
{ {
if (!e.Message.IsAuthor) 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 //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 //Connect to the Discord server using our email and password
await client.Connect("discordtest@email.com", "Password123"); 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 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")); await client.AcceptInvite(client.GetInvite("aaabbbcccdddeee"));
}); });
} }

38
docs/samples/permissions.cs
View File

@@ -1,28 +1,14 @@
// Finding User Permissions // Find a User's Channel Permissions
var userChannelPermissions = user.GetPermissions(channel);
void FindPermissions(User u, Channel c) // Find a User's Server Permissions
{ var userServerPermissions = user.ServerPermissions();
ChannelPermissions cperms = u.GetPermissions(c); var userServerPermissions = server.GetPermissions(user);
ServerPermissions sperms = u.GetServerPermissions();
// Set a User's Channel Permissions (using DualChannelPermissions)
var userPerms = user.GetPermissions(channel);
userPerms.ReadMessageHistory = false;
userPerms.AttachFiles = null;
channel.AddPermissionsRule(user, userPerms);
} }
void SetPermissionsChannelPerms(User u, Channel c)
{
ChannelPermissions allow = new ChannelPermissions();
ChannelPermissions deny = new ChannelPermissions();
allow.Connect = true;
deny.AttachFiles = true;
client.SetChannelPermissions(c, u, allow, deny)
}
void SetPermissionsDualPerms(User u, Channel c)
{
DualChannelPermissions dual = new DualChannelPermissions();
dual.ReadMessageHistory = false;
dual.Connect = true;
dual.AttachFiles = null;
client.SetChannelPermissions(c, u, dual);
}