From 8dc17d009f849b3e51c730cc48bc2c230da07eaa Mon Sep 17 00:00:00 2001 From: Cyberboss Date: Fri, 20 Oct 2017 15:22:59 -0400 Subject: [PATCH] Document ChatProviders --- TGServerService/ChatProviders/ChatProvider.cs | 26 +++--- .../ChatProviders/DiscordChatProvider.cs | 68 +++++++++++++-- .../ChatProviders/IRCChatProvider.cs | 82 +++++++++++++++---- 3 files changed, 141 insertions(+), 35 deletions(-) diff --git a/TGServerService/ChatProviders/ChatProvider.cs b/TGServerService/ChatProviders/ChatProvider.cs index c99f138a07..b1d8d9d19b 100644 --- a/TGServerService/ChatProviders/ChatProvider.cs +++ b/TGServerService/ChatProviders/ChatProvider.cs @@ -4,7 +4,7 @@ using TGServiceInterface; namespace TGServerService.ChatProviders { /// - /// Callback for the chat provider recieving a message + /// Callback for the chat provider recieving a /// /// The chat provider the message came from /// The username of the speaker @@ -20,16 +20,16 @@ namespace TGServerService.ChatProviders interface ITGChatProvider : IDisposable { /// - /// Sets info for the provider + /// Sets for the provider /// - /// The info to set + /// The to set /// null on success, error message on failure string SetProviderInfo(ChatSetupInfo info); /// /// Gets the info of the provider /// - /// The info for the chat provider + /// The for the chat provider ChatSetupInfo ProviderInfo(); /// @@ -40,18 +40,18 @@ namespace TGServerService.ChatProviders /// /// Connects the chat provider if it's enabled /// - /// null on success, error message on failure + /// on success, error message on failure string Connect(); /// /// Forces a reconnection of the chat provider if it's enabled /// - /// null on success, error message on failure + /// on success, error message on failure string Reconnect(); /// /// Checks if the chat provider is connected /// - /// true if the provider is connected, false otherwise + /// if the provider is connected, otherwise bool Connected(); /// @@ -60,18 +60,18 @@ namespace TGServerService.ChatProviders void Disconnect(); /// - /// Send a message to a channel + /// Send a to a /// /// The message to send /// The channel to send to - /// null on success, error message on failure + /// on success, error message on failure string SendMessageDirect(string message, string channel); /// - /// Broadcast a message to appropriate channels based on the message type + /// Broadcast a to appropriate channels based on the message type /// - /// The message to send - /// The message type - void SendMessage(string msg, MessageType mt); + /// The message to send + /// The + void SendMessage(string message, MessageType mt); } } diff --git a/TGServerService/ChatProviders/DiscordChatProvider.cs b/TGServerService/ChatProviders/DiscordChatProvider.cs index 313e5096ef..80fd6dcc16 100644 --- a/TGServerService/ChatProviders/DiscordChatProvider.cs +++ b/TGServerService/ChatProviders/DiscordChatProvider.cs @@ -8,25 +8,50 @@ using TGServiceInterface; namespace TGServerService.ChatProviders { + /// + /// for Discord: https://discordapp.com/ + /// class DiscordChatProvider : ITGChatProvider { + /// public event OnChatMessage OnChatMessage; + /// + /// The Discord API client + /// DiscordSocketClient client; + /// + /// The setup info for the provider + /// DiscordSetupInfo DiscordConfig; + /// + /// Used for multithreading safety + /// object DiscordLock = new object(); + /// + /// An of internal identifers => s we have seen + /// IDictionary SeenPrivateChannels = new Dictionary(); + /// + /// Construct a + /// + /// The public DiscordChatProvider(ChatSetupInfo info) { Init(info); } - + + /// public ChatSetupInfo ProviderInfo() { return DiscordConfig; } + /// + /// Sets up the Discord API and + /// + /// The to init with void Init(ChatSetupInfo info) { DiscordConfig = new DiscordSetupInfo(info); @@ -34,17 +59,27 @@ namespace TGServerService.ChatProviders client.MessageReceived += Client_MessageReceived; } - private bool CheckAdmin(SocketUser u) + /// + /// Checks if a is considered a chat admin + /// + /// The sender of a message + /// if is a chat admin, otherwise + private bool CheckAdmin(SocketUser user) { if (!DiscordConfig.AdminsAreSpecial) - return DiscordConfig.AdminList.Contains(u.Id.ToString()); - if(u is SocketGuildUser sgu) + return DiscordConfig.AdminList.Contains(user.Id.ToString()); + if(user is SocketGuildUser sgu) foreach (var I in sgu.Roles) if (DiscordConfig.AdminList.Contains(I.Id.ToString())) return true; return false; } + /// + /// Called when a channel the bot is in recieves a message or the bot is PM'd directly + /// + /// The event arguments + /// The task to run when this occurs private async Task Client_MessageReceived(SocketMessage e) { await Task.Run(() => @@ -81,6 +116,7 @@ namespace TGServerService.ChatProviders }); } + /// public string Connect() { try @@ -102,6 +138,7 @@ namespace TGServerService.ChatProviders } } + /// public bool Connected() { lock (DiscordLock) @@ -110,6 +147,7 @@ namespace TGServerService.ChatProviders } } + /// public void Disconnect() { try @@ -126,12 +164,14 @@ namespace TGServerService.ChatProviders catch { } } + /// public string Reconnect() { Disconnect(); return Connect(); } + /// public void SendMessage(string msg, MessageType mt) { if (!Connected()) @@ -158,6 +198,7 @@ namespace TGServerService.ChatProviders } } + /// public string SendMessageDirect(string message, string channelname) { if (!Connected()) @@ -185,6 +226,10 @@ namespace TGServerService.ChatProviders return e.ToString(); } } + + /// + /// Shutsdown and disposes + /// void DisconnectAndDispose() { try @@ -198,6 +243,7 @@ namespace TGServerService.ChatProviders client.Dispose(); } + /// public string SetProviderInfo(ChatSetupInfo info) { try @@ -228,8 +274,15 @@ namespace TGServerService.ChatProviders } #region IDisposable Support - private bool disposedValue = false; // To detect redundant calls + /// + /// To detect redundant calls + /// + private bool disposedValue = false; + /// + /// Implements the pattern + /// + /// if was called manually, if it was from the finalizer protected virtual void Dispose(bool disposing) { if (!disposedValue) @@ -252,8 +305,9 @@ namespace TGServerService.ChatProviders // // Do not change this code. Put cleanup code in Dispose(bool disposing) above. // Dispose(false); // } - - // This code added to correctly implement the disposable pattern. + /// + /// Implements the pattern + /// public void Dispose() { // Do not change this code. Put cleanup code in Dispose(bool disposing) above. diff --git a/TGServerService/ChatProviders/IRCChatProvider.cs b/TGServerService/ChatProviders/IRCChatProvider.cs index d79d236835..0609cf97ef 100644 --- a/TGServerService/ChatProviders/IRCChatProvider.cs +++ b/TGServerService/ChatProviders/IRCChatProvider.cs @@ -4,25 +4,44 @@ using System.Threading; using TGServiceInterface; using Meebey.SmartIrc4net; - namespace TGServerService.ChatProviders { + /// + /// for internet relay chat + /// class IRCChatProvider : ITGChatProvider { + /// + /// Header used to mark that a channel is actually a query message + /// const string PrivateMessageMarker = "---PRIVATE-MSG---"; + /// + /// The irc client + /// IrcFeatures irc; - + /// + /// Used for multithreading safety + /// object IRCLock = new object(); + /// + /// The setup info for the provider + /// IRCSetupInfo IRCConfig; + /// public event OnChatMessage OnChatMessage; - + + /// public ChatSetupInfo ProviderInfo() { return IRCConfig; } + /// + /// Construct a + /// + /// The public IRCChatProvider(ChatSetupInfo info) { IRCConfig = new IRCSetupInfo(info); @@ -41,8 +60,8 @@ namespace TGServerService.ChatProviders irc.OnChannelMessage += Irc_OnChannelMessage; irc.OnQueryMessage += Irc_OnQueryMessage; } - - //public api + + /// public string SendMessageDirect(string message, string channel) { try @@ -64,6 +83,7 @@ namespace TGServerService.ChatProviders } } + /// public string SetProviderInfo(ChatSetupInfo info) { var convertedInfo = (IRCSetupInfo)info; @@ -84,6 +104,11 @@ namespace TGServerService.ChatProviders return null; } + /// + /// Checks if a message is considered sent from a chat admin + /// + /// The + /// if was sent by a chat admin, otherwise private bool CheckAdmin(IrcMessageData e) { if (IRCConfig.AdminsAreSpecial) @@ -122,12 +147,21 @@ namespace TGServerService.ChatProviders return false; } - //private message + /// + /// Called when the bot recieves a query message + /// + /// The sender of the event (usually ) + /// The private void Irc_OnQueryMessage(object sender, IrcEventArgs e) { OnChatMessage(this, e.Data.Nick, e.Data.Nick + PrivateMessageMarker, e.Data.Message, CheckAdmin(e.Data), true); } + /// + /// Called when a channel the bot is in recieves a message + /// + /// The sender of the event (usually ) + /// The private void Irc_OnChannelMessage(object sender, IrcEventArgs e) { var formattedMessage = e.Data.Message.Trim(); @@ -144,7 +178,10 @@ namespace TGServerService.ChatProviders OnChatMessage(this, e.Data.Nick, e.Data.Channel, formattedMessage, CheckAdmin(e.Data), IRCConfig.AdminChannels.Contains(e.Data.Channel.ToLower())); } - //Joins configured channels + + /// + /// Joins all channels specified in + /// void JoinChannels() { var hs = new HashSet(); //for unique inserts @@ -165,7 +202,10 @@ namespace TGServerService.ChatProviders foreach (var I in hs) irc.RfcJoin(I); } - //runs the login command + + /// + /// Sends a login query to with message + /// void Login() { lock (IRCLock) @@ -174,7 +214,7 @@ namespace TGServerService.ChatProviders irc.SendMessage(SendType.Message, IRCConfig.AuthTarget, IRCConfig.AuthMessage); } } - //public api + /// public string Connect() { if (Connected() || !IRCConfig.Enabled) @@ -213,7 +253,9 @@ namespace TGServerService.ChatProviders } } - //This is the thread that listens for irc messages + /// + /// Runs the listener in a safe loop + /// void IRCListen() { while (irc != null && Connected()) @@ -224,14 +266,14 @@ namespace TGServerService.ChatProviders catch { } } - //public api + /// public string Reconnect() { Disconnect(); return Connect(); } - //public api + /// public void Disconnect() { try @@ -250,7 +292,7 @@ namespace TGServerService.ChatProviders Service.WriteError("IRC failed QnD: " + e.ToString(), EventID.ChatDisconnectFail); } } - //public api + /// public bool Connected() { lock (IRCLock) @@ -258,7 +300,7 @@ namespace TGServerService.ChatProviders return irc != null && irc.IsConnected; } } - //public api + /// public void SendMessage(string message, MessageType mt) { if (!Connected()) @@ -279,8 +321,15 @@ namespace TGServerService.ChatProviders #region IDisposable Support - private bool disposedValue = false; // To detect redundant calls + /// + /// To detect redundant calls + /// + private bool disposedValue = false; + /// + /// Implements the pattern + /// + /// if was called manually, if it was from the finalizer protected virtual void Dispose(bool disposing) { if (!disposedValue) @@ -306,6 +355,9 @@ namespace TGServerService.ChatProviders // } // This code added to correctly implement the disposable pattern. + /// + /// Implements the pattern + /// public void Dispose() { // Do not change this code. Put cleanup code in Dispose(bool disposing) above.