diff --git a/docs/features/events.rst b/docs/features/events.rst index 6d0f8b1c2..862d28dd3 100644 --- a/docs/features/events.rst +++ b/docs/features/events.rst @@ -1,4 +1,75 @@ |stub| Events ============= -|stub-desc| \ No newline at end of file +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 diff --git a/docs/features/permissions.rst b/docs/features/permissions.rst index 087065aeb..b4922cb53 100644 --- a/docs/features/permissions.rst +++ b/docs/features/permissions.rst @@ -1,4 +1,75 @@ -|stub| Permissions +Permissions ================== -|stub-desc| \ No newline at end of file +There are two types of permissions: *Channel Permissions* and *Server Permissions*. + +Channel Permissions +------------------- +Channel Permissions have a set of bools behind them: + +======================= ======= ============== +Flag Type Description +======================= ======= ============== +AttachFiles Text Send files to a channel. +Connect Voice Connect to a voice channel. +CreateInstantInvite General Create an invite to the channel. +DeafenMembers Voice Prevent users of a voice channel from hearing other users (server-wide). +EmbedLinks Text Create embedded links. +ManageChannel General Manage a channel. +ManageMessages Text Remove messages in a channel. +ManagePermissions General Manage the permissions of a channel. +MentionEveryone Text Use @everyone in a channel. +MoveMembers Voice Move members around in voice channels. +MuteMembers Voice Mute users of a voice channel (server-wide). +ReadMessageHistory Text Read the chat history of a voice channel. +ReadMessages Text Read any messages in a text channel; exposes the text channel to users. +SendMessages Text Send messages in a text channel. +SendTTSMessages Text Send TTS messages in a text channel. +Speak Voice Speak in a voice channel. +UseVoiceActivation Voice Use Voice Activation in a text channel (for large channels where PTT is preferred) +======================= ======= ============== + +If a user has a permission, the value is true. Otherwise, it must be null. + +Dual Channel Permissions +------------------------ +You may also access a user's permissions in a channel with the DualChannelPermissions class. +Unlike normal ChannelPermissions, DualChannelPermissions hold three values: + +If a user has a permission, the value is true. If a user is denied a permission, it will be false. If the permission is not set, the value will return null. + +Setting Channel Permissions +--------------------------- + +To set channel permissions, you may use either two ChannelPermissions, or one DualChannelPermissions. + +In the case of using two Channel Permissions, you must create one list of allowed permissions, and one list of denied permissions. +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(); + +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: + +======================= ======= ============== +Flag Type Description +======================= ======= ============== +BanMembers Server Ban users from the server. +KickMembers Server Kick users from the server. They can stil 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. + +Roles +----- + +Managing permissions for roles is much easier than for users in channels. For roles, just access the flag under `Role.Permissions`. + +Example +------- + +.. literalinclude:: /samples/permissions.cs + :language: csharp6 + :tab-width: 2 \ No newline at end of file diff --git a/docs/global.txt b/docs/global.txt index 12c642540..e5b572c93 100644 --- a/docs/global.txt +++ b/docs/global.txt @@ -1,2 +1,2 @@ -.. |stub| unicode:: U+0D83D U+0DD27 +.. |stub| unicode:: U+1F527 .. |stub-desc| replace:: This page is a placeholder and has not been written yet. It should be coming soon! \ No newline at end of file diff --git a/docs/samples/events.cs b/docs/samples/events.cs new file mode 100644 index 000000000..7f68bf6cb --- /dev/null +++ b/docs/samples/events.cs @@ -0,0 +1,27 @@ +class Program +{ + private static DiscordBotClient _client; + static void Main(string[] args) + { + var client = new DiscordClient(); + + // Handle Events using Lambdas + client.MessageCreated += (s, e) => + { + if (!e.Message.IsAuthor) + await client.SendMessage(e.Message.ChannelId, "foo"); + } + + // Handle Events using Event Handlers + EventHandler handler = new EventHandler(HandleMessageCreated); + client.MessageCreated += handler; + } + + + // NOTE: When using this method, 'client' must be accessible from outside the Main function. + static void HandleMessageCreated(object sender, EventArgs e) + { + if (!e.Message.IsAuthor) + await client.SendMessage(e.Message.ChannelId, "foo"); + } +} \ No newline at end of file diff --git a/docs/samples/permissions.cs b/docs/samples/permissions.cs new file mode 100644 index 000000000..c09a151d6 --- /dev/null +++ b/docs/samples/permissions.cs @@ -0,0 +1,28 @@ +// Finding User Permissions + +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(); + + 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); +} \ No newline at end of file