// // IImapClient.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.Threading; using System.Threading.Tasks; using System.Collections.Generic; namespace MailKit.Net.Imap { ///

/// An interface for an IMAP client. ///

/// /// Implemented by . /// public interface IImapClient : IMailStore { ///

/// Get the capabilities supported by the IMAP server. ///

/// /// The capabilities will not be known until a successful connection has been made via one of /// the Connect methods and may /// change as a side-effect of calling one of the /// Authenticate /// methods. /// /// ///

///


		/// The capabilities.
		/// 
		/// Capabilities cannot be enabled, they may only be disabled.
		/// 
		ImapCapabilities Capabilities { get; set; }

		/// 
		/// Gets the maximum size of a message that can be appended to a folder.
		/// 
		/// 
		/// Gets the maximum size of a message, in bytes, that can be appended to a folder.
		/// If the value is not set, then the limit is unspecified.
		/// 
		/// The append limit.
		uint? AppendLimit { get; }

		/// 
		/// Gets the internationalization level supported by the IMAP server.
		/// 
		/// 
		/// Gets the internationalization level supported by the IMAP server.
		/// For more information, see
		/// section 4 of rfc5255.
		/// 
		/// The internationalization level.
		int InternationalizationLevel { get; }

		/// 
		/// Get the access rights supported by the IMAP server.
		/// 
		/// 
		/// These rights are additional rights supported by the IMAP server beyond the standard rights
		/// defined in section 2.1 of rfc4314
		/// and will not be populated until the client is successfully connected.
		/// 
		/// 
		/// 
		/// 
		/// The rights.
		AccessRights Rights { get; }

		/// 
		/// Get whether or not the client is currently in the IDLE state.
		/// 
		/// 
		/// Gets whether or not the client is currently in the IDLE state.
		/// 
		/// true if an IDLE command is active; otherwise, false.
		bool IsIdle { get; }

		/// 
		/// Enable compression over the IMAP connection.
		/// 
		/// 
		/// Enables compression over the IMAP connection.
		/// If the IMAP server supports the  extension,
		/// it is possible at any point after connecting to enable compression to reduce network
		/// bandwidth usage. Ideally, this method should be called before authenticating.
		/// 
		/// The cancellation token.
		/// 
		/// The  has been disposed.
		/// 
		/// 
		/// The  is not connected.
		/// 
		/// 
		/// Compression must be enabled before a folder has been selected.
		/// 
		/// 
		/// The IMAP server does not support the  extension.
		/// 
		/// 
		/// The operation was canceled via the cancellation token.
		/// 
		/// 
		/// An I/O error occurred.
		/// 
		/// 
		/// The server replied to the COMPRESS command with a NO or BAD response.
		/// 
		/// 
		/// An IMAP protocol error occurred.
		/// 
		void Compress (CancellationToken cancellationToken = default (CancellationToken));

		/// 
		/// Asynchronously enable compression over the IMAP connection.
		/// 
		/// 
		/// Asynchronously enables compression over the IMAP connection.
		/// If the IMAP server supports the  extension,
		/// it is possible at any point after connecting to enable compression to reduce network
		/// bandwidth usage. Ideally, this method should be called before authenticating.
		/// 
		/// An asynchronous task context.
		/// The cancellation token.
		/// 
		/// The  has been disposed.
		/// 
		/// 
		/// The  is not connected.
		/// 
		/// 
		/// Compression must be enabled before a folder has been selected.
		/// 
		/// 
		/// The IMAP server does not support the COMPRESS extension.
		/// 
		/// 
		/// The operation was canceled via the cancellation token.
		/// 
		/// 
		/// An I/O error occurred.
		/// 
		/// 
		/// The server replied to the COMPRESS command with a NO or BAD response.
		/// 
		/// 
		/// An IMAP protocol error occurred.
		/// 
		Task CompressAsync (CancellationToken cancellationToken = default (CancellationToken));

		/// 
		/// Enable the UTF8=ACCEPT extension.
		/// 
		/// 
		/// Enables the UTF8=ACCEPT extension.
		/// 
		/// The cancellation token.
		/// 
		/// The  has been disposed.
		/// 
		/// 
		/// The  is not connected.
		/// 
		/// 
		/// The  is not authenticated.
		/// 
		/// 
		/// UTF8=ACCEPT needs to be enabled before selecting a folder.
		/// 
		/// 
		/// The IMAP server does not support the UTF8=ACCEPT extension.
		/// 
		/// 
		/// The operation was canceled via the cancellation token.
		/// 
		/// 
		/// An I/O error occurred.
		/// 
		/// 
		/// The server replied to the ENABLE command with a NO or BAD response.
		/// 
		/// 
		/// An IMAP protocol error occurred.
		/// 
		void EnableUTF8 (CancellationToken cancellationToken = default (CancellationToken));

		/// 
		/// Asynchronously enable the UTF8=ACCEPT extension.
		/// 
		/// 
		/// Enables the UTF8=ACCEPT extension.
		/// 
		/// An asynchronous task context.
		/// The cancellation token.
		/// 
		/// The  has been disposed.
		/// 
		/// 
		/// The  is not connected.
		/// 
		/// 
		/// The  is not authenticated.
		/// 
		/// 
		/// UTF8=ACCEPT needs to be enabled before selecting a folder.
		/// 
		/// 
		/// The IMAP server does not support the UTF8=ACCEPT extension.
		/// 
		/// 
		/// The operation was canceled via the cancellation token.
		/// 
		/// 
		/// An I/O error occurred.
		/// 
		/// 
		/// The server replied to the ENABLE command with a NO or BAD response.
		/// 
		/// 
		/// An IMAP protocol error occurred.
		/// 
		Task EnableUTF8Async (CancellationToken cancellationToken = default (CancellationToken));

		/// 
		/// Identify the client implementation to the server and obtain the server implementation details.
		/// 
		/// 
		/// Passes along the client implementation details to the server while also obtaining implementation
		/// details from the server.
		/// If the  is null or no properties have been set, no
		/// identifying information will be sent to the server.
		/// 
		/// Security Implications
		/// This command has the danger of violating the privacy of users if misused. Clients should
		/// notify users that they send the ID command.
		/// It is highly desirable that implementations provide a method of disabling ID support, perhaps by
		/// not calling this method at all, or by passing null as the 
		/// argument.
		/// Implementors must exercise extreme care in adding properties to the .
		/// Some properties, such as a processor ID number, Ethernet address, or other unique (or mostly unique) identifier
		/// would allow tracking of users in ways that violate user privacy expectations and may also make it easier for
		/// attackers to exploit security holes in the client.
		/// 
		/// 
		/// 
		/// 
		/// 
		/// The implementation details of the server if available; otherwise, null.
		/// The client implementation.
		/// The cancellation token.
		/// 
		/// The  has been disposed.
		/// 
		/// 
		/// The  is not connected.
		/// 
		/// 
		/// The IMAP server does not support the ID extension.
		/// 
		/// 
		/// The operation was canceled via the cancellation token.
		/// 
		/// 
		/// An I/O error occurred.
		/// 
		/// 
		/// The server replied to the ID command with a NO or BAD response.
		/// 
		/// 
		/// An IMAP protocol error occurred.
		/// 
		ImapImplementation Identify (ImapImplementation clientImplementation, CancellationToken cancellationToken = default (CancellationToken));

		/// 
		/// Asynchronously identify the client implementation to the server and obtain the server implementation details.
		/// 
		/// 
		/// Passes along the client implementation details to the server while also obtaining implementation
		/// details from the server.
		/// If the  is null or no properties have been set, no
		/// identifying information will be sent to the server.
		/// 
		/// Security Implications
		/// This command has the danger of violating the privacy of users if misused. Clients should
		/// notify users that they send the ID command.
		/// It is highly desirable that implementations provide a method of disabling ID support, perhaps by
		/// not calling this method at all, or by passing null as the 
		/// argument.
		/// Implementors must exercise extreme care in adding properties to the .
		/// Some properties, such as a processor ID number, Ethernet address, or other unique (or mostly unique) identifier
		/// would allow tracking of users in ways that violate user privacy expectations and may also make it easier for
		/// attackers to exploit security holes in the client.
		/// 
		/// 
		/// The implementation details of the server if available; otherwise, null.
		/// The client implementation.
		/// The cancellation token.
		/// 
		/// The  has been disposed.
		/// 
		/// 
		/// The  is not connected.
		/// 
		/// 
		/// The IMAP server does not support the ID extension.
		/// 
		/// 
		/// The operation was canceled via the cancellation token.
		/// 
		/// 
		/// An I/O error occurred.
		/// 
		/// 
		/// The server replied to the ID command with a NO or BAD response.
		/// 
		/// 
		/// An IMAP protocol error occurred.
		/// 
		Task IdentifyAsync (ImapImplementation clientImplementation, CancellationToken cancellationToken = default (CancellationToken));

		/// 
		/// Toggle the  into the IDLE state.
		/// 
		/// 
		/// When a client enters the IDLE state, the IMAP server will send
		/// events to the client as they occur on the selected folder. These events
		/// may include notifications of new messages arriving, expunge notifications,
		/// flag changes, etc.
		/// Due to the nature of the IDLE command, a folder must be selected
		/// before a client can enter into the IDLE state. This can be done by
		/// opening a folder using
		/// 
		/// or any of the other variants.
		/// While the IDLE command is running, no other commands may be issued until the
		///  is cancelled.
		/// It is especially important to cancel the 
		/// before cancelling the  when using SSL or TLS due to
		/// the fact that  cannot be polled.
		/// 
		/// 
		/// 
		/// 
		/// The cancellation token used to return to the non-idle state.
		/// The cancellation token.
		/// 
		///  must be cancellable (i.e.  cannot be used).
		/// 
		/// 
		/// The  has been disposed.
		/// 
		/// 
		/// The  is not connected.
		/// 
		/// 
		/// The  is not authenticated.
		/// 
		/// 
		/// A  has not been opened.
		/// 
		/// 
		/// The IMAP server does not support the IDLE extension.
		/// 
		/// 
		/// The operation was canceled via the cancellation token.
		/// 
		/// 
		/// An I/O error occurred.
		/// 
		/// 
		/// The server replied to the IDLE command with a NO or BAD response.
		/// 
		/// 
		/// The server responded with an unexpected token.
		/// 
		void Idle (CancellationToken doneToken, CancellationToken cancellationToken = default (CancellationToken));

		/// 
		/// Asynchronously toggle the  into the IDLE state.
		/// 
		/// 
		/// When a client enters the IDLE state, the IMAP server will send
		/// events to the client as they occur on the selected folder. These events
		/// may include notifications of new messages arriving, expunge notifications,
		/// flag changes, etc.
		/// Due to the nature of the IDLE command, a folder must be selected
		/// before a client can enter into the IDLE state. This can be done by
		/// opening a folder using
		/// 
		/// or any of the other variants.
		/// While the IDLE command is running, no other commands may be issued until the
		///  is cancelled.
		/// It is especially important to cancel the 
		/// before cancelling the  when using SSL or TLS due to
		/// the fact that  cannot be polled.
		/// 
		/// An asynchronous task context.
		/// The cancellation token used to return to the non-idle state.
		/// The cancellation token.
		/// 
		///  must be cancellable (i.e.  cannot be used).
		/// 
		/// 
		/// The  has been disposed.
		/// 
		/// 
		/// The  is not connected.
		/// 
		/// 
		/// The  is not authenticated.
		/// 
		/// 
		/// A  has not been opened.
		/// 
		/// 
		/// The IMAP server does not support the IDLE extension.
		/// 
		/// 
		/// The operation was canceled via the cancellation token.
		/// 
		/// 
		/// An I/O error occurred.
		/// 
		/// 
		/// The server replied to the IDLE command with a NO or BAD response.
		/// 
		/// 
		/// The server responded with an unexpected token.
		/// 
		Task IdleAsync (CancellationToken doneToken, CancellationToken cancellationToken = default (CancellationToken));

		/// 
		/// Request the specified notification events from the IMAP server.
		/// 
		/// 
		/// The NOTIFY command is used to expand
		/// which notifications the client wishes to be notified about, including status notifications
		/// about folders other than the currently selected folder. It can also be used to automatically
		/// FETCH information about new messages that have arrived in the currently selected folder.
		/// This, combined with ,
		/// can be used to get instant notifications for changes to any of the specified folders.
		/// 
		/// true if the server should immediately notify the client of the
		/// selected folder's status; otherwise, false.
		/// The specific event groups that the client would like to receive notifications for.
		/// The cancellation token.
		/// 
		///  is null.
		/// 
		/// 
		///  is empty.
		/// 
		/// 
		/// The  has been disposed.
		/// 
		/// 
		/// The  is not connected.
		/// 
		/// 
		/// The  is not authenticated.
		/// 
		/// 
		/// One or more  is invalid.
		/// 
		/// 
		/// The IMAP server does not support the NOTIFY extension.
		/// 
		/// 
		/// The operation was canceled via the cancellation token.
		/// 
		/// 
		/// An I/O error occurred.
		/// 
		/// 
		/// The server replied to the NOTIFY command with a NO or BAD response.
		/// 
		/// 
		/// The server responded with an unexpected token.
		/// 
		void Notify (bool status, IList eventGroups, CancellationToken cancellationToken = default (CancellationToken));

		/// 
		/// Asynchronously request the specified notification events from the IMAP server.
		/// 
		/// 
		/// The NOTIFY command is used to expand
		/// which notifications the client wishes to be notified about, including status notifications
		/// about folders other than the currently selected folder. It can also be used to automatically
		/// FETCH information about new messages that have arrived in the currently selected folder.
		/// This, combined with ,
		/// can be used to get instant notifications for changes to any of the specified folders.
		/// 
		/// An asynchronous task context.
		/// true if the server should immediately notify the client of the
		/// selected folder's status; otherwise, false.
		/// The specific event groups that the client would like to receive notifications for.
		/// The cancellation token.
		/// 
		///  is null.
		/// 
		/// 
		///  is empty.
		/// 
		/// 
		/// The  has been disposed.
		/// 
		/// 
		/// The  is not connected.
		/// 
		/// 
		/// The  is not authenticated.
		/// 
		/// 
		/// One or more  is invalid.
		/// 
		/// 
		/// The IMAP server does not support the NOTIFY extension.
		/// 
		/// 
		/// The operation was canceled via the cancellation token.
		/// 
		/// 
		/// An I/O error occurred.
		/// 
		/// 
		/// The server replied to the NOTIFY command with a NO or BAD response.
		/// 
		/// 
		/// The server responded with an unexpected token.
		/// 
		Task NotifyAsync (bool status, IList eventGroups, CancellationToken cancellationToken = default (CancellationToken));

		/// 
		/// Disable any previously requested notification events from the IMAP server.
		/// 
		/// 
		/// Disables any notification events requested in a prior call to 
		/// .
		/// request.
		/// 
		/// The cancellation token.
		/// 
		/// The  has been disposed.
		/// 
		/// 
		/// The  is not connected.
		/// 
		/// 
		/// The  is not authenticated.
		/// 
		/// 
		/// The IMAP server does not support the NOTIFY extension.
		/// 
		/// 
		/// The operation was canceled via the cancellation token.
		/// 
		/// 
		/// An I/O error occurred.
		/// 
		/// 
		/// The server replied to the NOTIFY command with a NO or BAD response.
		/// 
		/// 
		/// The server responded with an unexpected token.
		/// 
		void DisableNotify (CancellationToken cancellationToken = default (CancellationToken));

		/// 
		/// Asynchronously disable any previously requested notification events from the IMAP server.
		/// 
		/// 
		/// Disables any notification events requested in a prior call to 
		/// .
		/// request.
		/// 
		/// An asynchronous task context.
		/// The cancellation token.
		/// 
		/// The  has been disposed.
		/// 
		/// 
		/// The  is not connected.
		/// 
		/// 
		/// The  is not authenticated.
		/// 
		/// 
		/// The IMAP server does not support the NOTIFY extension.
		/// 
		/// 
		/// The operation was canceled via the cancellation token.
		/// 
		/// 
		/// An I/O error occurred.
		/// 
		/// 
		/// The server replied to the NOTIFY command with a NO or BAD response.
		/// 
		/// 
		/// The server responded with an unexpected token.
		/// 
		Task DisableNotifyAsync (CancellationToken cancellationToken = default (CancellationToken));
	}
}