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

4
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.

138
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 |
+====================+====================+==========================================+
| 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 The Four Message Events (MessageReceived, Updated, Deleted, and Acknowledged) are raised when a message has been modified/created.
:language: csharp6
:tab-width: 2 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.

8
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.

14
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,19 +9,20 @@ 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
@@ -30,7 +31,6 @@ It is highly recommended that you always use the latest version and please repor
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)
void SetPermissionsChannelPerms(User u, Channel c) var userPerms = user.GetPermissions(channel);
{ userPerms.ReadMessageHistory = false;
ChannelPermissions allow = new ChannelPermissions(); userPerms.AttachFiles = null;
ChannelPermissions deny = new ChannelPermissions(); channel.AddPermissionsRule(user, userPerms);
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);
} }