From 2ff11b806aea2911822795b6328e14d825d6cd5f Mon Sep 17 00:00:00 2001 From: Christopher F Date: Wed, 23 Mar 2016 20:03:55 -0400 Subject: [PATCH] Made some fixes to Audio; Brought the Permissions Docs up to date --- docs/features/permissions.rst | 41 +++++++++++++++++++---------------- docs/features/voice.rst | 20 ++++++++++++----- docs/global.txt | 1 + docs/index.rst | 2 ++ docs/samples/permissions.cs | 15 ++++--------- 5 files changed, 44 insertions(+), 35 deletions(-) diff --git a/docs/features/permissions.rst b/docs/features/permissions.rst index d351e8159..aa3856807 100644 --- a/docs/features/permissions.rst +++ b/docs/features/permissions.rst @@ -1,10 +1,21 @@ -|stub| Permissions -================== +Permissions +=========== |outdated| There are two types of permissions: *Channel Permissions* and *Server Permissions*. +Permission Overrides +-------------------- + +Channel Permissions are expressed using an enum, ``PermValue``. + +The three states are fairly straightforward - + +``PermValue.Allow``: Allow the user to perform a permission. +``PermValue.Deny``: Deny the user to perform a permission. +``PermValue.Inherit``: The user will inherit the permission from its role. + Channel Permissions ------------------- Channel Permissions are controlled using a set of flags: @@ -31,27 +42,24 @@ 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. +Each flag is a PermValue; see the section above. Setting Channel Permissions --------------------------- -To set channel permissions, you may use either two ChannelPermissions, or one DualChannelPermissions. +To set channel permissions, create a new ``ChannelPermissionOverrides``, and specify the flags/values that you want to override. + +Then, update the user, by doing ``Channel.AddPermissionsRule(_user, _overwrites);`` -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. +Roles +----- + +Accessing/modifying permissions for roles is done the same way as user permissions, just using the overload for a Role. See above sections. Server Permissions ------------------ -Server Permissions can be accessed by ``Server.GetPermissions(User)``, and updated with ``Server.UpdatePermissions(User, ServerPermissions)`` +Server Permissions can be viewed with ``User.ServerPermissions``, but **at the time of this writing** cannot be set. 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: @@ -65,11 +73,6 @@ ManageChannels Server Manage channels that exist on the server (add, r 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 ------- diff --git a/docs/features/voice.rst b/docs/features/voice.rst index 1d1102bd7..a4dddeff5 100644 --- a/docs/features/voice.rst +++ b/docs/features/voice.rst @@ -1,6 +1,16 @@ Voice ===== +Installation +------------ + +Before setting up the AudioService, you must first install the package `from NuGet`_ or `GitHub`_. + +Add the package to your solution, and then import the namespace ``Discord.Audio``. + +.. _from NuGet: https://www.nuget.org/packages/Discord.Net.Audio/0.9.0-rc3 +.. _GitHub: https://github.com/RogueException/Discord.Net/tree/master/src/Discord.Net.Audio + Setup ----- @@ -12,7 +22,7 @@ To use audio, you must install the AudioService to your DiscordClient. _client.UsingAudio(x => // Opens an AudioConfigBuilder so we can configure our AudioService { - x.Mode == AudioMode.Outgoing; // Tells the AudioService that we will only be sending audio + x.Mode = AudioMode.Outgoing; // Tells the AudioService that we will only be sending audio }); Joining a Channel @@ -96,7 +106,7 @@ You can `download NAudio from NuGet`_. for (int i = byteCount; i < blockSize; i++) buffer[i] = 0; } - _vClient.Send(buffer, 0, blockSize) // Send the buffer to Discord + _vClient.Send(buffer, 0, blockSize); // Send the buffer to Discord } } @@ -130,12 +140,12 @@ Broadcasting with FFmpeg while (true) // Loop forever, so data will always be read { byteCount = process.StandardOutput.BaseStream // Access the underlying MemoryStream from the stdout of FFmpeg - .Read(buffer, 0, blockSize) // Read stdout into the buffer + .Read(buffer, 0, blockSize); // Read stdout into the buffer if (byteCount == 0) // FFmpeg did not output anything break; // Break out of the while(true) loop, since there was nothing to read. - _vClient.Send(buffer, 0, byteCount) // Send our data to Discord + _vClient.Send(buffer, 0, byteCount); // Send our data to Discord } _vClient.Wait(); // Wait for the Voice Client to finish sending data, as ffMPEG may have already finished buffering out a song, and it is unsafe to return now. } @@ -157,7 +167,7 @@ To prepare for Multi-Server Broadcasting, you must first enable it in your confi _client.UsingAudio(x => { - x.Mode == AudioMode.Outgoing; + x.Mode = AudioMode.Outgoing; x.EnableMultiserver = true; // Enable Multiserver }); diff --git a/docs/global.txt b/docs/global.txt index c7774b131..25b33510e 100644 --- a/docs/global.txt +++ b/docs/global.txt @@ -1,3 +1,4 @@ .. |stub| unicode:: U+1F527 .. |stub-desc| replace:: This page is a placeholder and has not been written yet. It should be coming soon! .. |outdated| replace:: **This page is currently out-of-date. The information below may be inaccurate.** +.. |incomplete| replace:: **This page is incomplete. While the information below is accurate, it should be noted that it is not thorough.** \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 85420ef85..bf5676406 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -23,6 +23,8 @@ It is highly recommended that you always use the latest version and please repor This Documentation is **currently undergoing a rewrite**. Some pages (marked with a wrench) are not updated, or are not completed yet. +**The documentation is currently being written to reflect ``0.9-rc4``, which can be accessed via the latest git-master.** + .. toctree:: :caption: Documentation :maxdepth: 2 diff --git a/docs/samples/permissions.cs b/docs/samples/permissions.cs index d4bb50fed..65681d0f9 100644 --- a/docs/samples/permissions.cs +++ b/docs/samples/permissions.cs @@ -1,15 +1,8 @@ -/* --- OUTDATED --- */ // Find a User's Channel Permissions -var userChannelPermissions = user.GetPermissions(channel); +var UserPerms = _channel.GetPermissionsRule(_user); -// Find a User's Server Permissions -var userServerPermissions = user.ServerPermissions(); -var userServerPermissions = server.GetPermissions(user); +// Set a User's Channel Permissions -// Set a User's Channel Permissions (using DualChannelPermissions) - -var userPerms = user.GetPermissions(channel); -userPerms.ReadMessageHistory = false; -userPerms.AttachFiles = null; -channel.AddPermissionsRule(user, userPerms); +var NewOverwrites = new ChannelPermissionOverrides(sendMessages: PermValue.Deny); +await channel.AddPermissionsRule(_user, NewOverwrites);