// // MailStore.cs // // Author: Jeffrey Stedfast // // Copyright (c) 2013-2020 .NET Foundation and Contributors // // Permission is hereby granted, free of charge, to any person obtaining a copy // of this software and associated documentation files (the "Software"), to deal // in the Software without restriction, including without limitation the rights // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell // copies of the Software, and to permit persons to whom the Software is // furnished to do so, subject to the following conditions: // // The above copyright notice and this permission notice shall be included in // all copies or substantial portions of the Software. // // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN // THE SOFTWARE. // using System; using System.Threading; using System.Threading.Tasks; using System.Collections.Generic; namespace MailKit { /// /// An abstract mail store implementation. /// /// /// An abstract mail store implementation. /// public abstract class MailStore : MailService, IMailStore { /// /// Initializes a new instance of the class. /// /// /// Initializes a new instance of the class. /// /// The protocol logger. /// /// is null. /// protected MailStore (IProtocolLogger protocolLogger) : base (protocolLogger) { } /// /// Gets the personal namespaces. /// /// /// The personal folder namespaces contain a user's personal mailbox folders. /// /// The personal namespaces. public abstract FolderNamespaceCollection PersonalNamespaces { get; } /// /// Gets the shared namespaces. /// /// /// The shared folder namespaces contain mailbox folders that are shared with the user. /// /// The shared namespaces. public abstract FolderNamespaceCollection SharedNamespaces { get; } /// /// Gets the other namespaces. /// /// /// The other folder namespaces contain other mailbox folders. /// /// The other namespaces. public abstract FolderNamespaceCollection OtherNamespaces { get; } /// /// Get whether or not the mail store supports quotas. /// /// /// Gets whether or not the mail store supports quotas. /// /// true if the mail store supports quotas; otherwise, false. public abstract bool SupportsQuotas { get; } /// /// Get the threading algorithms supported by the mail store. /// /// /// The threading algorithms are queried as part of the /// Connect /// and Authenticate methods. /// /// /// /// /// The supported threading algorithms. public abstract HashSet ThreadingAlgorithms { get; } /// /// Get the Inbox folder. /// /// /// The Inbox folder is the default folder and always exists on the mail store. /// This property will only be available after the client has been authenticated. /// /// The Inbox folder. public abstract IMailFolder Inbox { get; } /// /// Enable the quick resynchronization feature. /// /// /// Enables quick resynchronization when a folder is opened using the /// /// method. /// If this feature is enabled, the event is replaced /// with the event. /// This method needs to be called immediately after calling one of the /// Authenticate methods, before /// opening any folders. /// /// The cancellation token. /// /// The has been disposed. /// /// /// The is not connected. /// /// /// The is not authenticated. /// /// /// Quick resynchronization needs to be enabled before selecting a folder. /// /// /// The mail store does not support quick resynchronization. /// /// /// The operation was canceled via the cancellation token. /// /// /// An I/O error occurred. /// /// /// A protocol error occurred. /// /// /// The command failed. /// public abstract void EnableQuickResync (CancellationToken cancellationToken = default (CancellationToken)); /// /// Asynchronously enable the quick resynchronization feature. /// /// /// Enables quick resynchronization when a folder is opened using the /// /// method. /// If this feature is enabled, the event is replaced /// with the event. /// This method needs to be called immediately after calling one of the /// Authenticate methods, before /// opening any folders. /// /// An asynchronous task context. /// The cancellation token. /// /// The has been disposed. /// /// /// The is not connected. /// /// /// The is not authenticated. /// /// /// Quick resynchronization needs to be enabled before selecting a folder. /// /// /// The mail store does not support quick resynchronization. /// /// /// The operation was canceled via the cancellation token. /// /// /// An I/O error occurred. /// /// /// A protocol error occurred. /// /// /// The command failed. /// public abstract Task EnableQuickResyncAsync (CancellationToken cancellationToken = default (CancellationToken)); /// /// Get the specified special folder. /// /// /// Not all mail stores support special folders. Each implementation /// should provide a way to determine if special folders are supported. /// /// The folder if available; otherwise null. /// The type of special folder. /// /// is out of range. /// /// /// The has been disposed. /// /// /// The is not connected. /// /// /// The is not authenticated. /// public abstract IMailFolder GetFolder (SpecialFolder folder); /// /// Get the folder for the specified namespace. /// /// /// Gets the folder for the specified namespace. /// /// The folder. /// The namespace. /// /// is null. /// /// /// The has been disposed. /// /// /// The is not connected. /// /// /// The is not authenticated. /// /// /// The folder could not be found. /// public abstract IMailFolder GetFolder (FolderNamespace @namespace); /// /// Get all of the folders within the specified namespace. /// /// /// Gets all of the folders within the specified namespace. /// /// The folders. /// The namespace. /// If set to true, only subscribed folders will be listed. /// The cancellation token. /// /// is null. /// /// /// The has been disposed. /// /// /// The is not connected. /// /// /// The is not authenticated. /// /// /// The operation was canceled via the cancellation token. /// /// /// An I/O error occurred. /// /// /// A protocol error occurred. /// /// /// The command failed. /// public virtual IList GetFolders (FolderNamespace @namespace, bool subscribedOnly, CancellationToken cancellationToken = default (CancellationToken)) { return GetFolders (@namespace, StatusItems.None, subscribedOnly, cancellationToken); } /// /// Asynchronously get all of the folders within the specified namespace. /// /// /// Asynchronously gets all of the folders within the specified namespace. /// /// The folders. /// The namespace. /// If set to true, only subscribed folders will be listed. /// The cancellation token. /// /// is null. /// /// /// The has been disposed. /// /// /// The is not connected. /// /// /// The is not authenticated. /// /// /// The operation was canceled via the cancellation token. /// /// /// An I/O error occurred. /// /// /// A protocol error occurred. /// /// /// The command failed. /// public virtual Task> GetFoldersAsync (FolderNamespace @namespace, bool subscribedOnly, CancellationToken cancellationToken = default (CancellationToken)) { return GetFoldersAsync (@namespace, StatusItems.None, subscribedOnly, cancellationToken); } /// /// Get all of the folders within the specified namespace. /// /// /// Gets all of the folders within the specified namespace. /// /// The folders. /// The namespace. /// The status items to pre-populate. /// If set to true, only subscribed folders will be listed. /// The cancellation token. /// /// is null. /// /// /// The has been disposed. /// /// /// The is not connected. /// /// /// The is not authenticated. /// /// /// The operation was canceled via the cancellation token. /// /// /// An I/O error occurred. /// /// /// A protocol error occurred. /// /// /// The command failed. /// public abstract IList GetFolders (FolderNamespace @namespace, StatusItems items = StatusItems.None, bool subscribedOnly = false, CancellationToken cancellationToken = default (CancellationToken)); /// /// Asynchronously get all of the folders within the specified namespace. /// /// /// Asynchronously gets all of the folders within the specified namespace. /// /// The folders. /// The namespace. /// The status items to pre-populate. /// If set to true, only subscribed folders will be listed. /// The cancellation token. /// /// is null. /// /// /// The has been disposed. /// /// /// The is not connected. /// /// /// The is not authenticated. /// /// /// The operation was canceled via the cancellation token. /// /// /// An I/O error occurred. /// /// /// A protocol error occurred. /// /// /// The command failed. /// public abstract Task> GetFoldersAsync (FolderNamespace @namespace, StatusItems items = StatusItems.None, bool subscribedOnly = false, CancellationToken cancellationToken = default (CancellationToken)); /// /// Get the folder for the specified path. /// /// /// Gets the folder for the specified path. /// /// The folder. /// The folder path. /// The cancellation token. /// /// is null. /// /// /// The has been disposed. /// /// /// The is not connected. /// /// /// The is not authenticated. /// /// /// The operation was canceled via the cancellation token. /// /// /// The folder could not be found. /// /// /// An I/O error occurred. /// /// /// A protocol error occurred. /// /// /// The command failed. /// public abstract IMailFolder GetFolder (string path, CancellationToken cancellationToken = default (CancellationToken)); /// /// Asynchronously get the folder for the specified path. /// /// /// Asynchronously gets the folder for the specified path. /// /// The folder. /// The folder path. /// The cancellation token. /// /// is null. /// /// /// The has been disposed. /// /// /// The is not connected. /// /// /// The is not authenticated. /// /// /// The operation was canceled via the cancellation token. /// /// /// The folder could not be found. /// /// /// An I/O error occurred. /// /// /// A protocol error occurred. /// /// /// The command failed. /// public abstract Task GetFolderAsync (string path, CancellationToken cancellationToken = default (CancellationToken)); /// /// Gets the specified metadata. /// /// /// Gets the specified metadata. /// /// The requested metadata value. /// The metadata tag. /// The cancellation token. /// /// The has been disposed. /// /// /// The is not connected. /// /// /// The is not authenticated. /// /// /// The folder does not support metadata. /// /// /// The operation was canceled via the cancellation token. /// /// /// An I/O error occurred. /// /// /// The server's response contained unexpected tokens. /// /// /// The command failed. /// public abstract string GetMetadata (MetadataTag tag, CancellationToken cancellationToken = default (CancellationToken)); /// /// Asynchronously gets the specified metadata. /// /// /// Asynchronously gets the specified metadata. /// /// The requested metadata value. /// The metadata tag. /// The cancellation token. /// /// The has been disposed. /// /// /// The is not connected. /// /// /// The is not authenticated. /// /// /// The folder does not support metadata. /// /// /// The operation was canceled via the cancellation token. /// /// /// An I/O error occurred. /// /// /// The server's response contained unexpected tokens. /// /// /// The command failed. /// public abstract Task GetMetadataAsync (MetadataTag tag, CancellationToken cancellationToken = default (CancellationToken)); /// /// Gets the specified metadata. /// /// /// Gets the specified metadata. /// /// The requested metadata. /// The metadata tags. /// The cancellation token. /// /// is null. /// /// /// The has been disposed. /// /// /// The is not connected. /// /// /// The is not authenticated. /// /// /// The folder does not support metadata. /// /// /// The operation was canceled via the cancellation token. /// /// /// An I/O error occurred. /// /// /// The server's response contained unexpected tokens. /// /// /// The command failed. /// public virtual MetadataCollection GetMetadata (IEnumerable tags, CancellationToken cancellationToken = default (CancellationToken)) { return GetMetadata (new MetadataOptions (), tags, cancellationToken); } /// /// Asynchronously gets the specified metadata. /// /// /// Asynchronously gets the specified metadata. /// /// The requested metadata. /// The metadata tags. /// The cancellation token. /// /// is null. /// /// /// The has been disposed. /// /// /// The is not connected. /// /// /// The is not authenticated. /// /// /// The folder does not support metadata. /// /// /// The operation was canceled via the cancellation token. /// /// /// An I/O error occurred. /// /// /// The server's response contained unexpected tokens. /// /// /// The command failed. /// public virtual Task GetMetadataAsync (IEnumerable tags, CancellationToken cancellationToken = default (CancellationToken)) { return GetMetadataAsync (new MetadataOptions (), tags, cancellationToken); } /// /// Gets the specified metadata. /// /// /// Gets the specified metadata. /// /// The requested metadata. /// The metadata options. /// The metadata tags. /// The cancellation token. /// /// is null. /// -or- /// is null. /// /// /// The has been disposed. /// /// /// The is not connected. /// /// /// The is not authenticated. /// /// /// The folder does not support metadata. /// /// /// The operation was canceled via the cancellation token. /// /// /// An I/O error occurred. /// /// /// The server's response contained unexpected tokens. /// /// /// The command failed. /// public abstract MetadataCollection GetMetadata (MetadataOptions options, IEnumerable tags, CancellationToken cancellationToken = default (CancellationToken)); /// /// Asynchronously gets the specified metadata. /// /// /// Asynchronously gets the specified metadata. /// /// The requested metadata. /// The metadata options. /// The metadata tags. /// The cancellation token. /// /// is null. /// -or- /// is null. /// /// /// The has been disposed. /// /// /// The is not connected. /// /// /// The is not authenticated. /// /// /// The folder does not support metadata. /// /// /// The operation was canceled via the cancellation token. /// /// /// An I/O error occurred. /// /// /// The server's response contained unexpected tokens. /// /// /// The command failed. /// public abstract Task GetMetadataAsync (MetadataOptions options, IEnumerable tags, CancellationToken cancellationToken = default (CancellationToken)); /// /// Sets the specified metadata. /// /// /// Sets the specified metadata. /// /// The metadata. /// The cancellation token. /// /// is null. /// /// /// The has been disposed. /// /// /// The is not connected. /// /// /// The is not authenticated. /// /// /// The folder does not support metadata. /// /// /// The operation was canceled via the cancellation token. /// /// /// An I/O error occurred. /// /// /// The server's response contained unexpected tokens. /// /// /// The command failed. /// public abstract void SetMetadata (MetadataCollection metadata, CancellationToken cancellationToken = default (CancellationToken)); /// /// Asynchronously sets the specified metadata. /// /// /// Asynchronously sets the specified metadata. /// /// An asynchronous task context. /// The metadata. /// The cancellation token. /// /// is null. /// /// /// The has been disposed. /// /// /// The is not connected. /// /// /// The is not authenticated. /// /// /// The folder does not support metadata. /// /// /// The operation was canceled via the cancellation token. /// /// /// An I/O error occurred. /// /// /// The server's response contained unexpected tokens. /// /// /// The command failed. /// public abstract Task SetMetadataAsync (MetadataCollection metadata, CancellationToken cancellationToken = default (CancellationToken)); /// /// Occurs when a remote message store receives an alert message from the server. /// /// /// The event is raised whenever the mail server sends an /// alert message. /// public event EventHandler Alert; /// /// Raise the alert event. /// /// /// Raises the alert event. /// /// The alert message. /// /// is null. /// protected virtual void OnAlert (string message) { var handler = Alert; if (handler != null) handler (this, new AlertEventArgs (message)); } /// /// Occurs when a folder is created. /// /// /// The event is emitted when a new folder is created. /// public event EventHandler FolderCreated; /// /// Raise the folder created event. /// /// /// Raises the folder created event. /// /// The folder that was just created. protected virtual void OnFolderCreated (IMailFolder folder) { var handler = FolderCreated; if (handler != null) handler (this, new FolderCreatedEventArgs (folder)); } /// /// Occurs when metadata changes. /// /// /// The event is emitted when metadata changes. /// public event EventHandler MetadataChanged; /// /// Raise the metadata changed event. /// /// /// Raises the metadata changed event. /// /// The metadata that changed. protected virtual void OnMetadataChanged (Metadata metadata) { var handler = MetadataChanged; if (handler != null) handler (this, new MetadataChangedEventArgs (metadata)); } } }